[vJASS System]HelpFile

HelpFile ?!?

The HelpFile System allows you to create help messages that can be accessed via -help, -man or -h.
It does so by creating a tree of helpfiles and subcategories, allowing a player to easily follow the tree when he is searching for help on content of your map ( at least, if you don't link "Traderoute" to "Stats" and "Increase Stats" to "Trading" :P ).

How the tree is working

The HelpFile System allows you to create a new HelpFile that has a parent.
When parent is 0, it will default to the HELP command.
When you are pressing -h NAME, the HelpFile System will display you a message containing:
NAME(*¹):
(Sub Categories: *² )
Help message

(*¹): (PARENT), if any
(*²): Will display all the children of NAME
Help message will be NAME's help message.
An example:



( Image cut at the right side )
I recommend you to try out the testmap, and enter -help and -h index. Then you can just follow the tree.

API

// Create a helpfile with HELP as parent:
local helpfile N = helpfile.create( "NAME", "Name is a text refering to an object, a person or an animal.", HELP )
// Create one with N as parent:
local helpfile Serra = helpfile.create( "SERRAAVENGER", "Serra Avenger refers to the creator of the helpfile system.", N )
// Add a hotstring to Serra ( just enter -h serra to access to the SERRAAVENGER page ):
call Serra.addHotstring( "serra" )
// Also add Serra as children to HELP ( NOTE: HELP will not be listed as Serra's parent. N will. ):
call HELP.addSubclass( Serra )

These are all the functions you need to create the helpfile tree.


Built-in Commands:

-help // Displays to use -h help or -h index
-help help // Displays basic instructions on how to use the system
-help index // Toggles wether the HelpFile Index can be seen or not by the player who entered the message

The attached map uses ( apart from the systems ) only this initialization code: ( Strings are quite long, but they should actually help a bit, shouldn't they? )

library InitHelpFile initializer InitIHF needs HelpFile
function InitIHF takes nothing returns nothing
    local helpfile HELPFILE = helpfile.create( "HELPFILE", "A helpfile is a chat-triggered help-message, like this one. It can have multiple subfiles ( up to 40 ), that are listed under Sub Categories. It can also have a parent, which will be listed between Parenthesis in its name.", 0 )
    local helpfile SERRA = helpfile.create( "SERRAAVENGER", "SerraAvenger is a young crazy guy, who created many JASS-based systems and also created some maps. The most famous map he has been working on is the famous Battleships CrossFire\nSee also: BATTLESHIPS, CPT.DAVEYJONES", 0 )
    local helpfile DAVEY = helpfile.create( "CPT.DAVEYJONES", "Cpt.DaveyJones is SerraAvengers second account on Northrend. On other servers, there is no warranty that he actually is Serra.\nSee also: BATTLESHIPS, SERRAAVENGER", 0 )
    local helpfile BS = helpfile.create( "BATTLESHIPS", "Battleships is a map genre that is set up with most often 2 teams that are battling each other. While the Empire is supporting the players with creeps and money, the players buy Weapons that automatically target and fire in order to win.", 0 )
    local helpfile CF = helpfile.create( "BS CROSSFIRE", "Battleships Crossfire ( idea by TimberWolf, remodded and balanced by Say_No_To_War ) is one of the most played Battleships maps on Northrend. It is very specific in three points: It was one of the first Battleships maps using Auto-Doubling, there is a third empire on the right side of the map and 50% of all Systems were recoded by SerraAvenger.\nSee also: SERRAAVENGER / CPT.DAVEYJONES", BS )
    local helpfile ADV = helpfile.create( "BS ADVANCED", "Battleships Advanced ( by Trollkopp ) is one of the most important Tournament maps on Northrend. Many people critisize Trollkopp's balancing in some way or the other, although everything has been balanced using a complex formula ( also known as Trolli-Formula ).", BS )
    local helpfile ARC = helpfile.create( "BS ANTARCTICA", "Battleships Antarctica ( by SerraAvenger ) is set in northern regions. It is currently WIP, and not much has been released about it. Look for it on www.thehelper.net.", BS )
    local helpfile CREATE = helpfile.create( "CREATE HELPFILE", "In order to create a helpfile, the user of this system neeeds to enter call helpfile.create( string NAME, string HELPMESSAGE, helpfile PARENT). If PARENT is 0, it will be automatically set to HELP. When a helpfile is created, it will be automatically linked to the chat commands -help/-h/-man NAME, which will display the parent file, the sub files and HELPMESSAGE.\nSee also: CREATE SUBFILE", HELPFILE )
    local helpfile SUBMSG = helpfile.create( "CREATE SUBFILE", "Sub files are automatically created when you are creating a helpfile with a parent. You can alternatively use PARENT.addSubclass( SUBFILE ). The parent of SUBFILE will not be changed, though. \nSee also: CREATE HELPFILE", HELPFILE )
    local helpfile UTILITIES = helpfile.create( "UTILITIES", "Utilities is an infrastructure library created by SerraAvenger. Here, it is used to color the text, and it has many other cool features. Look for Utilities on [url]www.hiveworkshop.com[/url] when you want further explanations.", 0 )

    call DAVEY.addSubclass( ARC )
    call SERRA.addSubclass( ARC )
    call DAVEY.addSubclass( HELPFILE )
    call SERRA.addSubclass( HELPFILE )
    call DAVEY.addSubclass( UTILITIES )
    call SERRA.addSubclass( UTILITIES )

    call SERRA.addHotstring( "serra" )
    call DAVEY.addHotstring( "davey" )
    call DAVEY.addHotstring( "jones" )
    call ADV.addHotstring( "bs adv" )
    call CF.addHotstring( "bs cf" )
    call ARC.addHotstring( "bs arc" )
    call HELPFILE.addHotstring( "hf" )
    call HELPFILE.addHotstring( "hfile" )
    call CREATE.addHotstring( "create hf" )
    call SUBMSG.addHotstring( "create sub" )
    call BS.addHotstring( "bs" )


endfunction
endlibrary

Requirements
The system requires my Utilities library (V 08+) as well as ABC by Cohadar.
Please make sure you use the newest JassPack NewGen, too.

Please report bugs and suggestions here, Thanks.


Greetings, Davey Jones

Ver 00 - Just the basic system
Ver 01 - Added hotstrings for Helpfiles, like -h BS for -help Battleships
Ver 05 - Added a multiboard that shows all the helpfiles and their hotstrings, alphabetically sorted. Maximum amount of Helpfiles: 99. Hope that's enough, lol. Also Sub Topics are sorted now.

ToDo list:
-?Create an Indexing Multiboard that shows the HelpFile tree - Cons: Would grow rather big >_>
-Add a "see also" function that automatically creates a "See also: X, Y, Z" comment.

Code

//----------------------------------------------------------\\
// VER 05 \\
//----------------------------------------------------------\\

library HelpFile initializer InitHF needs Utilities
globals
    helpfile HELP
    helpfile INDEX
    helpfile BASE
private multiboard SortedIndex
    private helpfile array SortedFile
    private integer helpfiles = 0
    private constant integer MB_MAX_ROWS = 25
    private boolean array MbDisplay
endglobals

function S2Int takes string s returns integer
    return s
    return 0
endfunction

function UpdateMultiboard takes nothing returns nothing
    local integer row = 0
    local integer col = 0
    local integer index = 0
    local multiboarditem curItem
    local integer hotstringId
    local string hotstrings
    call MultiboardDisplay( SortedIndex, false )
    //call MultiboardClear( SortedIndex )
    call MultiboardSetRowCount( SortedIndex, IMinBJ( helpfiles, MB_MAX_ROWS ) + 2 )
    call MultiboardSetColumnCount( SortedIndex, R2I( helpfiles / MB_MAX_ROWS + 1 ) * 2 )
    call MultiboardSetItemsWidth( SortedIndex, .08 )
    call MultiboardSetTitleText( SortedIndex, "Help Index" )
    call MultiboardSetItemsStyle( SortedIndex, true, false )

    set curItem = MultiboardGetItem( SortedIndex, 0, col )
    call MultiboardSetItemValue( curItem, "Helpfile" )
    call MultiboardReleaseItem( curItem )

    set curItem = MultiboardGetItem( SortedIndex, 0, col + 1 )
    call MultiboardSetItemValue( curItem, "Hotstrings" )
    call MultiboardReleaseItem( curItem )


    loop
        exitwhen index == helpfiles
        set hotstringId = 0
        set hotstrings = GREY
        loop
            exitwhen hotstringId == SortedFile[ index ].hotstrings
            if hotstringId + 1 == SortedFile[ index ].hotstrings then
                set hotstrings = hotstrings + SortedFile[ index ].hotstring[ hotstringId ]
            else
                set hotstrings = hotstrings + SortedFile[ index ].hotstring[ hotstringId ] + " / "
            endif
            set hotstringId = hotstringId + 1
        endloop
        set curItem = MultiboardGetItem( SortedIndex, row+1, col )
        call MultiboardSetItemValue( curItem, SortedFile[ index ].name )
        call MultiboardReleaseItem( curItem )

        set curItem = MultiboardGetItem( SortedIndex , row+1, col+1 )
        call MultiboardSetItemValue( curItem, hotstrings )
        call MultiboardReleaseItem( curItem )

        set index = index + 1
        set row = row + 1
        if row >= MB_MAX_ROWS then
            set row = 0
set col = col + 2
            set curItem = MultiboardGetItem( SortedIndex, 0, col )
            call MultiboardSetItemValue( curItem, "Helpfile" )
            call MultiboardReleaseItem( curItem )

            set curItem = MultiboardGetItem( SortedIndex, 0, col + 1 )
            call MultiboardSetItemValue( curItem, "Hotstrings" )
            call MultiboardReleaseItem( curItem )
        endif
    endloop
endfunction

function ToggleMBView takes nothing returns nothing
    local player trigPlayer = GetTriggerPlayer()
    local integer trigPlayerId = GetPlayerId( trigPlayer )
    local player localPlayer = GetLocalPlayer()
    set MbDisplay[ trigPlayerId ] = not MbDisplay[ trigPlayerId ]
    if localPlayer == trigPlayer then
        call MultiboardDisplay( SortedIndex, MbDisplay[ trigPlayerId ] )
        call MultiboardMinimize( SortedIndex, not MbDisplay[ trigPlayerId ] )
    endif
endfunction

function Helper_Actions takes nothing returns nothing
    local player trigPlayer = GetTriggerPlayer()
    local helpfile trigFile = GetTriggerStructB( GetTriggeringTrigger() )
    local string subclassMsg = GREY + "Sub categories: "
    local integer index = 0
    local helpfile curSubfile
    if trigFile.parent != 0 then
        call DisplayTimedTextToPlayer( trigPlayer, 0, 0, 30, trigFile.name + " ( " + trigFile.parent.name + " ):" )
    else
        call DisplayTimedTextToPlayer( trigPlayer, 0, 0, 30, trigFile.name + ":" )
    endif
    if trigFile.subclasses > 0 then
        loop
            exitwhen index == trigFile.subclasses
            set curSubfile = trigFile.subclass[ index ]
            if index + 1 < trigFile.subclasses then
                set subclassMsg = subclassMsg + curSubfile.name + ", "
            else
                set subclassMsg = subclassMsg + curSubfile.name
            endif
            set index = index + 1
        endloop
        call DisplayTimedTextToPlayer( trigPlayer, 0, 0, 30, subclassMsg )
    endif
    call DisplayTimedTextToPlayer( trigPlayer, 0, 0, 30, trigFile.help )
endfunction

struct helpfile
    string name
    string help
    integer subclasses
    integer priority
    helpfile array subclass[ 40 ]
    helpfile parent
    trigger helper
    string array hotstring[ 40 ]
    integer array hotstringprio[ 40 ]
    integer hotstrings = 0

    static method create takes string name, string help, helpfile parent returns helpfile
        local helpfile new = helpfile.allocate()
        local integer index = 0
        local integer correctIndex
        set new.helper = CreateTrigger()
        set new.help = GREY + help
        set new.name = GREY + name
        set new.subclasses = 0
        set new.priority = Char2I( name )
        if parent > 0 then
            call parent.addSubclass( new )
            set new.parent = parent
        elseif parent != -1 then
            call HELP.addSubclass( new )
            set new.parent = HELP
        else
            call TriggerRegisterAnyPlayerChatEvent( new.helper, "-help", true )
            call TriggerRegisterAnyPlayerChatEvent( new.helper, "-man", true )
            call TriggerRegisterAnyPlayerChatEvent( new.helper, "-h", true )
            call TriggerRegisterAnyPlayerChatEvent( new.helper, "-manual", true )
            set new.name = GREY + "Help command"
            set new.parent = 0
        endif
        call TriggerRegisterAnyPlayerChatEvent( new.helper, "-help " + name, true )
        call TriggerRegisterAnyPlayerChatEvent( new.helper, "-man " + name, true )
        call TriggerRegisterAnyPlayerChatEvent( new.helper, "-h " + name, true )
        call TriggerRegisterAnyPlayerChatEvent( new.helper, "-manual " + name, true )

        call TriggerAddAction( new.helper, function Helper_Actions )
        call SetTriggerStructB( new.helper, new )
        loop
            if index >= helpfiles then
                set SortedFile[ helpfiles ] = new
                exitwhen true
            endif
            if SortedFile[ index ].priority > new.priority then
                set correctIndex = index
                set index = helpfiles - 1
                loop
                    exitwhen index < correctIndex
                    set SortedFile[ index + 1 ] = SortedFile[ index ]
                    set index = index - 1
                endloop
                set SortedFile[ correctIndex ] = new
                exitwhen true
            endif
            set index = index + 1
        endloop
        set helpfiles = helpfiles + 1
        return new
    endmethod

    method addSubclass takes helpfile subclass returns nothing
        local integer index = 0
        local integer correctIndex
        loop
            if index >= .subclasses then
                set .subclass[ .subclasses ] = subclass
                exitwhen true
            elseif .subclass[ index ].priority > subclass.priority then
                set correctIndex = index
                set index = .subclasses - 1
                loop
                    exitwhen index < correctIndex
                    set .subclass[ index + 1 ] = .subclass[ index ]
                    set index = index - 1
                endloop
                set .subclass[ correctIndex ] = subclass
                exitwhen true
            endif
            set index = index + 1
        endloop
        set .subclasses = .subclasses + 1
    endmethod

    method addHotstring takes string hotstring returns nothing
        local integer index = 0
        local integer correctIndex
        local integer prio = Char2I( hotstring )
        call TriggerRegisterAnyPlayerChatEvent( .helper, "-help " + hotstring, true )
        call TriggerRegisterAnyPlayerChatEvent( .helper, "-man " + hotstring, true )
        call TriggerRegisterAnyPlayerChatEvent( .helper, "-h " + hotstring, true )
        call TriggerRegisterAnyPlayerChatEvent( .helper, "-manual " + hotstring, true )
        loop
            if index >= .hotstrings then
                set .hotstring[ .hotstrings ] = hotstring
                set .hotstringprio[ .hotstrings ] = prio
                exitwhen true
            elseif .hotstringprio[ index ] > prio then
                set correctIndex = index
                set index = .hotstrings - 1
                loop
                    exitwhen index < correctIndex
                    set .hotstring[ index + 1 ] = .hotstring[ index ]
                    set .hotstringprio[ index + 1 ] = .hotstringprio[ index ]
                    set index = index - 1
                endloop
                set .hotstring[ correctIndex ] = hotstring
                set .hotstringprio[ correctIndex ] = prio
                exitwhen true
            endif
            set index = index + 1
        endloop
        set .hotstrings = .hotstrings + 1
    endmethod
endstruct

private function InitHF takes nothing returns nothing
    local integer playerId = 0
    set BASE = helpfile.create( "", "Enter -help HELP to get help on the help command, or use -help index to show all helpfiles. Case is ignored on all -help commands.", -1 )
    set HELP = helpfile.create( "HELP", "Enter -help NAME to recieve help on NAME. You can also use NAME's hotstring instead of NAME. Case is ignored on all -help commands.\nOther commands: -man , -h , -manual ", BASE )
    set INDEX = helpfile.create( "INDEX", "The index shows all helpfiles, their parent file and their hotstrings.", BASE )
    call TriggerAddAction( INDEX.helper, function ToggleMBView )
    set SortedIndex = CreateMultiboard()
    loop
        exitwhen playerId > MAX_PLAYER_SLOT
        set MbDisplay[ playerId ] = false
        set playerId = playerId + 1
    endloop
    call TimerStart( CreateTimer(), 0.04, false, function UpdateMultiboard )
endfunction
endlibrary