8 Commands: SMM++

This chapter explains commands specially designed for mudding and mudding with SMM++.

8.1 Miscellenous Commands

These commands are used for various purposes.

8.1.1 ::smm::option

This command turns on/off various options and returns the value of the option after setting it.

Syntax:

::smm::option parse action
::smm::option output action
::smm::option error action
::smm::option devmode action
Description:
action
The action argument may be one of the following values.
0Turns off the option
1Turns on the option
!Toggles the option
?Does nothing. Use it for quering the option.
::smm::option parse action
When parsing is off, everything send to the mud is send exactly as typed in. No aliases are invoked, no variables are substituted, no commands are executed, nothing. The only command still understood is "::smm::option parse 1", to turn on parsing again. It must be typed in exactly as shown above.
::smm::option output action
If turned off output from SMM commands is suppressed.
::smm::option error action
If turned off error output from SMM commands is suppressed.
::smm::option devmode action
Turns on or off map development mode. The effect will be the same as switching the development mode from the menu -> map -> development mode.

Example:
    ::smm::option parse 0

8.1.2 ::smm::tick

SMM++ has a clock: the ticker. It counts down the seconds starting from a startvalue and it does it over and over again, ticking at each second. You can assign each second a command, which will be executed when its time to do so.

Syntax:

::smm::tick on
::smm::tick off
::smm::tick reset
::smm::tick clear
::smm::tick size size
::smm::tick add seconds command
::smm::tick remove second
::smm::tick show second
::smm::tick list
Description:
::smm::tick on
Starts the ticker.
::smm::tick off
Stops the ticker.
::smm::tick reset
Resets the ticker; sets the actual count to the ticker size.
::smm::tick clear
Removes all tick commands.
::smm::tick size size
Sets the ticker size (maximum count/start value).
::smm::tick add second command
Adds (or changes) the command at the given second.
::smm::tick remove second
Removes the command from the given second.
::smm::tick show second
Shows the command at the given second.
::smm::tick list
Lists all tick commands.

Example:
    ::smm::tick size 10
    ::smm::tick add 0 {::smm::showme "10 seconds over,.."}
    ::smm::tick on

8.1.3 ::smm::tab

These commands build up the tab-list, which is used for tab-completition. Please follow this link for more information about tab-completition.

Syntax:

::smm::tab add string
::smm::tab rem string
::smm::tab list
Description:
::smm::tab add string
Adds string to the tab-list.
::smm::tab rem string
Removes string from the tab-list.
::smm::tab list
Shows the tab-list.

Example:
    ::smm::tab add Grogump
    ::smm::tab add phalanx
    ::smm::tab add "I was here!"
    ::smm::tab rem phalanx
    ::smm::tab list

8.1.4 ::smm::log

Used for logging a session to a file. If the file doesn't exist, it is created. If it exists, the mud output is appended.

Syntax:

::smm::log file
::smm::log 1
::smm::log 0
::smm::log !
Description:
::smm::log file
Sets the name of the file, in which the session will be logged. You can change the logfile even during logging.
::smm::log 1
Starts logging. You must have defined a log file before you can turn on logging.
::smm::log 0
Stops logging.
::smm::log !
Toggles logging.

Example:
    ::smm::log file bla.log
    ::smm::log 1

8.1.5 ::smm::showme

Prints a message on the screen.

Syntax:

::smm::showme string ?tags?
Description:
::smm::showme string ?tags?
Prints string on the screen. If tags are given, you can set its properties. tags is a space separated list of the following items:
Foreground color: FGdef, FGblack, FGred, FGgreen, FGyellow, FGblue, FGred2, FGblue2, FGwhite.
Background color: BGdef, BGblack, BGred, BGgreen, BGyellow, BGblue, BGred2, BGblue2, BGwhite.
Fonts: FNdef, FNbold
Blinking: BLon, BLoff

Example:
    ::smm::showme "This is a message."
    ::smm::showme "This is a message." FGred
    ::smm::showme "This is a message." "FGred BGblue BLon"

8.1.6 ::smm::keycom

Defines keys, combinations of keys or any sequence of those to invoke actions.

Syntax:

::smm::keycom sequence code
Description:
::smm::keycom sequence code
Defines sequence to invoke code. Please read the following five step explanation what a sequence and code is:

detail
A detail is a "normal" key like 'a', 'b', 'c' or '1' or many others. Please refer to the list below (there may be more, I am not aware of?).
usual keys
a-z, A-Z, 0-9
F1, F2, ... for the functionkeys
'' = Escape'
' ' = 'space'
'!' = 'exclam'
'@' = 'at'
'#' = 'numbersign'
'$' = 'dollar'
'%' = 'percent'
'^' = 'asciicircum'
'&' = 'ampersand'
'*' = 'asterisk'
'(' = 'parenleft'
')' = 'parenright'
'_' = 'underscore'
'-' = 'minus'
'+' = 'plus'
'=' = 'equal'
''' = 'apostrophe'
'"' = 'quotedbl'
',' = 'comma'
'.' = 'period'
'/' = 'slash'
'<' = 'less'
'>' = 'greater'
'?' = 'question'
';' = 'semicolon'
':' = 'colon'
''' = 'apostrophe'
'"' = 'quotedbl'
'[' = 'bracketleft'
'{' = 'braceleft'
']' = 'bracketright'
'}' = 'braceright'
'\' = 'backslash'
'|' = 'bar'
'`' = 'grave'
'~' = 'asciitilde'
misc. keys:
' = 'BackSpace'
'' = 'Insert'
'' = 'Delete'
' ' = 'Tab'
'' = 'Home'
'' = 'Prior'
'' = 'Next'
'' = 'End'
'' = 'Pause'
'' = 'Scroll_Lock'
'' = 'Print'
'' = 'Num_Lock'
'' = 'Pause'

arrow keys:
'' = 'Up'
'' = 'Down'
'' = 'Left'
'' = 'Right'

keypad keys
'0-9' = 'KP_0 - KP_9'
'' = 'KP_Insert'
'' = 'KP_End'
'' = 'KP_Down'
'' = 'KP_Next'
'+' = 'KP_Add'
'' = 'KP_Left'
'' = 'KP_Begin'
'' = 'KP_Right'
'-' = 'KP_Subtract'
'' = 'KP_Home'
'' = 'KP_Up'
'' = 'KP_Prior'
'*' = 'KP_Multiply'
modifier
A modifier is one of the following strings:
Alt, Control, Shift, Lock, Meta (or M), Mod1 (or M1), Mod2 (or M2), Mod3 (or M3), Mod4 (or M4) or Mod5 (or M5).

It corresponds the the respective Key on your keyboard. Most of them can also be extended by a '_L' or '_R'. e.g. Alt_L is the left alternate key only.

key combinations
A key combination is any number of modifiers followed by one detail. They are separated by '-' characters. For recognition of the key combination you have to press all stated keys at once, all together.
sequence
A sequence is any number of key combinations, which are enclosed within '<' and '>'. For invocation of the command you have to press one key combination after the other in the given order.
code
code is anything that smm understands, e.g. "kill Dumbo" or "::set a 5"
A few examples will make everything easily clear:

Example:
    # One might want to send the string 'eat iron ration' 
    #  to the MUD on pressing the alternate-key and 
    #  f-key together:
    ::smm::keycom {<Alt-f>} {eat iron ration}
    
    # Or you prefer to bind the spell magic missle 
    #  to the sequence Alt-s (for spells), Alt-m (for missle):
    ::smm::keycom {<Alt-s><Alt-m>} {cast magic missle}

    # Or bind it to the sequence Control-Alternate-m
    ::smm::keycom {<Control-Alt-m>} {cast magic missle}

Note: I advise you not to bind the return key! And dont bind keys, which you need to enter your normal input, without modifiers,.. e.g. the 'a'-key, you don't really want that.
But maybe the following is a good idea:

Example:
    ::smm::keycom {<Escape>} {flee}

8.1.7 ::smm::bell

Beeps the system beeper or sets its parameters.

Syntax:

::smm::bell 0
::smm::bell 1
::smm::bell set volume herz milliseconds
::smm::bell ring
Description:
::smm::bell 0
Turns off the system beeper.
::smm::bell 1
Turns on the system beeper.
::smm::bell set volume herz milliseconds
Sets the volume, tone and duration of the bell. Might not work on all systems.
::smm::bell ring
Rings the bell.

Example:
    ::smm::bell ring

8.1.8 ::smm::file

Vorious file operations designed to be used for mudding. If you want to open/read/write files on your own, please refer to the tcl 'file' command.

Syntax:

::smm::file readasmud filename
::smm::file send filename
::smm::file eval filename
::smm::file usereval userscript
::smm::file syseval sysscript
Description:
::smm::file readasmud filename
Reads in the file filename, as if its content would have been send by the mud! So If you have a log file, or a file which you have written, you can offline tune and debug your scripts: test if actions, highlightnings, etc. work. filename can be a relative or absolute path.
::smm::file send filename
Sends the contents of a file as is to the MUD. Contrary to '::smm::file eval' (see below) the input wont be processed. That means no variable substitution, no alias substitution, etc.
::smm::file eval filename
Reads commands from a file and evaluates them, as if they were typed in. filename can be a relative or absolute path to an existing scriptfile. For information about scriptfiles please refer to the chapter Scriptfiles
::smm::file usereval userscript
Reads commands from a user script file with the name userscript and evaluates them, as if they were typed in. userscript can only be the name of a user script that exists; i. e. that you have written. For information about scriptfiles please refer to the chapter Scriptfiles
::smm::file syseval sysscript
Reads commands from a system script file with the name sysscript and evaluates them, as if they were typed in. sysscript can only be the name of a provided system file. For information about scriptfiles please refer to the chapter Scriptfiles

Example:
    # lets say you have logged a fight and noticed that
    #  your actions dont work as desired. You could now 
    #  (or later stop) the session and just load 
    #  (not connect, so your commands aren't send to the mud) 
    #  the session again. Now you can use your logfile and
    #  test your actions again:
    ::smm::file readasmud fight1.log

    # send a file (file is specified with an absolute path)
    ::smm::file send /home/doedel/bla.bla    

    # lets say for several sessions you have the same actions,
    #  highlights, procs, etc. and dont want to write them
    #  again and again in each session scriptfile. So write
    #  a separate user scriptfile and load it in each session
    #  scriptfile with a command like the followings:
    ::smm::file usereval dikuBase
    ::smm::file usereval elfBase
    ::smm::file usereval mageFight

8.1.9 ::smm::killall

Resets the session.

Syntax:

::smm::killall
Description:
::smm::killall
Clears all procs, variables, actions, etc.

Example:
    ::smm::killall

8.2 Action Commands

These commands build manipulate SMM++'s action system. SMM++ has a quite unique action system. For more information about SMM++'s action system, please read the section SMM++'s action system.

8.2.1 ::smm::action::set

Adds an action to the action list or changes its level.

Syntax:

::smm::action::set proc level
Description:
::smm::action::set proc level
If the procedure proc isnt in the action list, it is put into the list with the corresponding level. If it is already in the list, its position in the list is changed according to the value of level. level has to be a real number. The list of actions is an ordered list: actions are listed decreasingly according their level. When a new line of text is received from the mud, all actions in the list are called. Action with the same level have no defined relativ order, which even can change during running.

Example:
    ::smm::action::set flee    1000
    ::smm::action::set collect 1

8.2.2 ::smm::action::get

Returns the level of an action.

Syntax:

::smm::action::get proc
Description:
::smm::action::get proc
Returns the level of an action procedure or prints an error message.

Example:
    ::smm::showme "flee: [::smm::action::get flee]\n"

8.2.3 ::smm::action::unset

Removes an action.

Syntax:

::smm::action::unset proc
Description:
::smm::action::unset proc
If proc is in the action list it is removed from there; if not, this command does nothing.

Example:
    ::smm::action::unset flee

8.2.4 ::smm::action::exists

Tests if an action is in the action list.

Syntax:

::smm::action::exists proc
Description:
::smm::action::exists proc
If proc is in the action list this command returns 1, otherwise 0.

Example:
    ::if {[::smm::action::exists flee]} {
      ::smm::showme "flee is in the list.\n"
    }

8.2.5 ::smm::action::names

Returns all actions matching a glob-pattern.

Syntax:

::smm::action::names glob-pattern
Description:
::smm::action::names glob-pattern
Returns all actions matching a glob-pattern.

Example:
    ::smm::action::set fightGeneral 10
    ::smm::action::set fightMagic   10
    ::smm::action::set fightElf     10
    ::smm::action::set utilCollect   1
    ::smm::action::set utilColorize -3
    ::smm::showme "[::smm::action::names *]\n"
    ::smm::showme "[::smm::action::names fight*]\n"

8.2.6 ::smm::action::list

Returns the action list.

Syntax:

::smm::action::list
Description:
::smm::action::list
Returns the names of all actions in the order they called.

Example:
    ::smm::action::set utilCollect  -3
    ::smm::action::set utilCollect   1
    ::smm::action::set fightGeneral 10
    ::smm::action::set fightMagic   10
    ::smm::action::set fightElf     10
    ::smm::showme "[::smm::action::list]\n"

8.3 Text Commands

These procedures operate on the last from the mud received line. They change the text or its appereance (colors, fonts). Usually you would use these commands only from within actions.

Any text change is a real change, in the sense, that following actions are invoked with the changed line as its argument.

8.3.1 ::smm::text::delete

Deletes the last received line.

Syntax:

::smm::text::delete
Description:
::smm::text::delete
Deletes the last received line; also known as "gag"ing.

Example:
    ::smm::text::delete

8.3.2 ::smm::text::deleterange

Deletes a part of the last received line.

Syntax:

::smm::text::deleterange start-index end-index
Description:
::smm::text::deleterange start-index end-index
Deletes a part of the last received line from start-index to end-index inclusively. Indices must be integer numbers; 0 corresponds to the first character in the line.

Example:
    # the following command deletes the first 5 characters of
    #  the received line.
    ::smm::text::deleterange 0 4

8.3.3 ::smm::text::subst

Replaces the text of the last line.

Syntax:

::smm::text::subst text
Description:
::smm::text::subst text
Replaces the text of the last line with text.

Example:
    ::smm::text::subst "This line had some other content."

8.3.4 ::smm::text::substrange

Replaces a part of the last line.

Syntax:

::smm::text::substrange start-index end-index text
Description:
::smm::text::substrange start-index end-index text
Replaces the text of the last line between start-index and end-index inclusively with text. Indices must be integer numbers; 0 corresponds to the first character in the line.

Example:
    # change all 'kill' to '!!! KILL !!!'.

    # first define the proc that will be added to the action list
    #  remember: action procs must exactly take one argument.
    ::proc substKill {line} {
      # regexp returns 1, if it matches; 0 otherwise
      #                +-- regexp should return indices
      #                |         +-- this is what we are looking for
      #                |         |     +-- this is the string to
      #                |         |     |   be searched
      #                |         |     |     +-- here the start and 
      #                v         v     v     v   end index will be stored
      ::if {[::regexp -indices {kill} $line range]} {
        # if regexp could match, the variable range will be a list
        #  containing the start and end index.
        ::smm::text::subst [lindex $range 0] [lindex $range 1] "!!! KILL !!!"
      }
    }
    # now add the proc to the action list
    ::smm::action::set substKill 10

8.3.5 ::smm::text::tag

Changes color and/or font of the last received line.

Syntax:

::smm::text::tag tags
Description:
::smm::text::tag tags
Changes color and/or font of the last received line. tags must be a space separated list of foreground-color, background-color, font and/or blink tags:
Foreground color:
FGdef, FGblack, FGred, FGgreen, FGyellow, FGblue, FGred2, FGblue2, FGwhite.
Background color:
BGdef, BGblack, BGred, BGgreen, BGyellow, BGblue, BGred2, BGblue2, BGwhite.
Fonts:
FNdef, FNbold
Blinking:
BLon, BLoff

Example:
    # if you want to change the foregroundcolor of the last line to red:
    ::smm::text::tag FGred 
    # also set bg-color to blue
    ::smm::text::tag {FGred BGblue}
    # and bold font
    ::smm::text::tag {FGred BGblue FNbold}
    # or just blinking and bold
    ::smm::text::tag {BLon FNbold}

8.3.6 ::smm::text::tagrange

Changes the colors and font of the text for a part of the last received line.

Syntax:

::smm::text::tagrange start-index end-index tags
Description:
::smm::text::tagrange start-index end-index tags
Changes color and/or font of the last received line between start-index and end-index inclusively. Indices must be integer numbers; 0 corresponds to the first character in the line. tags must be a space separated list of foreground-color, background-color, font and/or blink tags:
Foreground color:
FGdef, FGblack, FGred, FGgreen, FGyellow, FGblue, FGred2, FGblue2, FGwhite.
Background color:
BGdef, BGblack, BGred, BGgreen, BGyellow, BGblue, BGred2, BGblue2, BGwhite.
Fonts:
FNdef, FNbold
Blinking:
BLon, BLoff

Example:
    # have all 'kill' words in blinking red.
    ::proc substKill {line} {
      ::if {[::regexp -indices {kill} $line range]} {
        ::smm::text::tagrange [lindex $range 0] [lindex $range 1] {FGred BLon}
      }
    }
    ::smm::action::set substKill 10

8.3.7 ::smm::text::substtag

Changes the text and properties of the last received line.

Syntax:

::smm::text::substtag text tags
Description:
::smm::text::substtag text tags
Replaces the text of the last line with text and sets its properties according to tags. tags must be a space separated list of foreground-color, background-color, font and/or blink tags:
Foreground color:
FGdef, FGblack, FGred, FGgreen, FGyellow, FGblue, FGred2, FGblue2, FGwhite.
Background color:
BGdef, BGblack, BGred, BGgreen, BGyellow, BGblue, BGred2, BGblue2, BGwhite.
Fonts:
FNdef, FNbold
Blinking:
BLon, BLoff

Example:
    ::smm::text::substtag {hmm,...} {BLon FNbold}

8.3.8 ::smm::text::substtagrange

Changes the text and its properties for a part of the last received line.

Syntax:

::smm::text::substtagrange start-index end-index text tags
Description:
::smm::text::substtagrange start-index end-index text tags
Changes the text and its properties of the last received line between start-index and end-index inclusively to text. Indices must be integer numbers; 0 corresponds to the first character in the line. tags must be a space separated list of foreground-color, background-color, font and/or blink tags:
Foreground color:
FGdef, FGblack, FGred, FGgreen, FGyellow, FGblue, FGred2, FGblue2, FGwhite.
Background color:
BGdef, BGblack, BGred, BGgreen, BGyellow, BGblue, BGred2, BGblue2, BGwhite.
Fonts:
FNdef, FNbold
Blinking:
BLon, BLoff

Example:
    # have all 'kill' words in blinking red and changed to '!!! KILL !!!'.
    ::proc substKill {line} {
      ::if {[::regexp -indices {kill} $line range]} {
        ::smm::text::substtagrange [lindex $range 0] [lindex $range 1] \
           {!!! KILL !!!} {FGred BLon}
      }
    }
    ::smm::action::set substKill 10

8.4 Map Commands

These commands allow you to set and get map and room properties. Most probably you will use them from within automapper scripts.

I should mention that building up a map with SMM++-commands follows the same scheme as building it by hand; e.g. clicking in zoom interface.

8.4.1 ::smm::map::zoom

This command gives you access to the zoom interface.

Syntax:

::smm::map::zoom accept
::smm::map::zoom reset
::smm::map::zoom clear
::smm::map::zoom setbg bg-type bg-category bg-name
::smm::map::zoom setstuff stuff-pos stuff-type stuff-category stuff-name
::smm::map::zoom remstuff stuff-pos
::smm::map::zoom remtext
::smm::map::zoom settext text
::smm::map::zoom remexit exit-position
::smm::map::zoom setexit position command mapname maplevel connect-x connect-y draw-x draw-y door open-door-command close-door-command line-thickness line-color
Description:
::smm::map::zoom accept
Has the same effect as pressing the accept button in the zif.
::smm::map::zoom reset
Has the same effect as pressing the reset button in the zif.
::smm::map::zoom clear
Clears the whole zoom interface. This means the room is removed from the zoom interface (! only from the zoom interface!) If you want to permanently remove the room from the map, you need to accept the changes, too.
::smm::map::zoom setbg bg-type bg-category bg-name
Sets the bg image to the indicated image. The type, category and name of all the available images are shown in the background selector interface. If you move onto one of the background buttons its type, category and name are displayed in the label below.
::smm::map::zoom setstuff stuff-pos stuff-type stuff-category stuff-name
This works the same way as the command above. You just have to enter a stuff-pos too, as there are 9 possible positions where the stuff can be put to: nw, nc, ne, cw, cc, ce, sw, sc, se.
::smm::map::zoom remstuff stuff-pos
Removes the stuff at the indicated position.
::smm::map::zoom settext text
Sets the text, which is displayed for this room.
::smm::map::zoom remtext
Removes the text.
::smm::map::zoom setexit position command mapname maplevel connect-x connect-y draw-x draw-y door open-door-command close-door-command line-thickness line-color
Creates an exit with the given parameters. The parameters corospond to those, which are available in the exit configuration interface. Possible positions are: nw, nc, ne, cw, ce, sw, sc, se, uo, ux, do, dx. IF you want the exit to lead to the same map, mapname and maplevel should be empty strings.
::smm::map::zoom remexit exit-position
Removes the exit at the indicated position.

Example:
    # create a nothern exit.
    #  assume that the actual position are stored in the
    #  variables x and y.
    ::incr y 1
    ::smm::map::zoom setexit nc north {} {} $x $y $x $y 0 {} {} 2 black

8.4.2 ::smm::map::exists

Queries the existance of maps or rooms.

Syntax:

::smm::map::exists map map-name map-level
::smm::map::exists room map-name map-level x y
Description:
::smm::map::exists map map-name map-level
Returns 1, if the corresponding map exists; 0 otherwise.
::smm::map::exists room map-name map-level x y
Returns 1, if the corresponding room exists; 0 otherwise.

Example:
    # test, if the room doesnt exist.
    #  assume that the actual position are stored in the
    #  variables x and y; and the map name and level in
    #  the variable name and level.
    ::if {![::smm::map::exists room $name $level $x $y]} {
      # the room doesnt exist; you could create one now,..
    }

8.4.3 ::smm::map::set

Moves the zoom- or player-position on the map.

Syntax:

::smm::map::set zoompos map-name map-level x y
::smm::map::set playerpos map-name map-level x y
Description:
::smm::map::set zoompos map-name map-level x y
Moves the zoom postion to the indicated position.
::smm::map::set playerpos map-name map-level x y
Moves the player postion to the indicated position.

Example:
    ::smm::map::set playerpos $name $level $x $y

8.4.4 ::smm::map::get

Query map properties.

Syntax:

::smm::map::get zoomname
::smm::map::get zoomlevel
::smm::map::get zoomx
::smm::map::get zoomy
::smm::map::get playername
::smm::map::get playerlevel
::smm::map::get playerx
::smm::map::get playery
::smm::map::get exitwithcommand command map-name map-level x y
Description:
::smm::map::get zoomname
Returns the name of the map the zoom is located currently.
::smm::map::get zoomlevel
Returns the level of the map the zoom is located currently.
::smm::map::get zoomx
Returns the x position of the zoom.
::smm::map::get zoomy
Returns the y position of the zoom.
::smm::map::get playername
Returns the name of the map the player is located currently.
::smm::map::get playerlevel
Returns the level of the map the player is located currently.
::smm::map::get playerx
Returns the x position of the player.
::smm::map::get playery
Returns the y position of the player.
::smm::map::get exitwithcommand command map-name map-level x y
Looks for an exit with the command command in the room at map-name, map-level, x and y. If there is such an exit, its position (nw, nc, ne, cw, ce, sw, sc, se, uo, ux, do, dx) is returned; an empty string otherwise.

Example:
    # get current position
    ::set x [::smm::map::get playerx]
    ::set y [::smm::map::get playery]

8.4.5 ::smm::map::create

Creates a map.

Syntax:

::smm::map::create map-name map-level
Description:
::smm::map::create map-name map-level
Create a map with name map-name and level map-level.

Example:
    # create a new map for an upper exit.
    #  assume the current map name and level are stored
    #  in the variables name and level
    ::incr level
    ::smm::map::create $name $level

8.4.6 ::smm::map::switch

Show another map.

Syntax:

::smm::map::switch map-name map-level
Description:
::smm::map::switch map-name map-level
Shows the map with name map-name and level map-level in the map window.

Example:
    # an alias to have a look at the map on
    #  one upper level than the current one.
    ::proc lu {} {
      # get the current name and level of the map
      ::set name  [::smm::map::get playername]
      ::set level [::smm::map::get playerlevel]
      # increase the level
      ::incr level
      # switch the map
      ::smm::map::switch $name $level
    }

8.4.7 ::smm::map::move

Moves the payer on the map. These commands will consider the current player position as the starting coordinates.

Syntax:

::smm::map::move useexit exit-pos
::smm::map::move useexitwithcommand command
::smm::map::move followexit exit-pos
::smm::map::move followexitwithcommand command
::smm::map::move powerwalk map-name map-level x y
Description:
::smm::map::move useexit exit-pos
Will use the exit with the index exit-pos: sends the command to the map and will move the player on the map. This is just like pressing the corresponding button on the zif.
::smm::map::move useexitwithcommand command
Will first search for the index of an exit, that uses the command command and will then call ::smm::map::move useexit.
::smm::map::move followexit exit-pos
Will move the player thrue the exit with the index exit-pos. No command is send to the mud. This is useful, when following somebody or used in aliases, which just need to move the player on the map(, because the command is already sent).
::smm::map::move followexitwithcommand command
Will first search for the index of an exit, that uses the command command and will then call ::smm::map::move followexit.
::smm::map::move powerwalk map-name map-level x y
Will powerwalk to the requested destination. Work like powerwalking via mouse.

Example:
    # this alias will search the corresponding exit, send 
    #  the command to the mud AND move the player on the map.
    ::proc n {} {::smm::map::move useexitwithcommand north}
    
    #-- Just by the way,..
    #-- please note: if the command which the exit uses would 
    #-- be "n" instead of "north", you would end up in an 
    #-- endless loop, when you define an alias, which has the 
    #-- name 'n'!
    #-- this is the buggy implementation:
    ::proc n     {} {::smm::map::move useexitwithcommand n}
    # -- also buggy:
    ::proc north {} {::smm::map::move useexitwithcommand north}
    
    # another implementation
    ::proc n {} {
      north
      ::smm::map::move followexitwithcommand north
    }
    # ;) BUT, you might fool yourself!
    # => if there is a door, the open and close commands are not 
    #    send in this implementation!! they are send in the above
    #    implementation! Be sure, that you know what SMM++ does for
    #    you and what you want from SMM++ to do for you.

    # speedwalking to city center
    ::proc gocc {} {
      ::smm::map::move powerwalk "The City Of Hamburg" 0 254 29
    }

8.5 GUI Commands

Commands to build and access the user customizable interface.

8.5.1 ::smm::gui::set

Sets a GUI variable.

Syntax:

::smm::gui::set varName value
Description:
::smm::gui::set varName value
Contrary to the set command value must be specified. The value of varName is set to value, creating a new variable if one doesn't already exist, and returns its value. If varName contains an open parenthesis and ends with a close parenthesis, then it refers to an array element: the characters before the first open parenthesis are the name of the array, and the characters between the parentheses are the index within the array. Otherwise varName refers to a scalar variable.

You can use GUI variables just like normal ones. It's just that setting, getting values, etc. is more CPU intensiv and handling is a bit more unhandy.

Example:
    # scalar variable
    ::smm::gui::set target "elite guard"    
    # arrays variable
    ::smm::gui::set array(1) 5

8.5.2 ::smm::gui::unset

Delete a GUI variable.

Syntax:

::smm::gui::unset name
Description:
::smm::gui::unset name
This command works pretty much as the unset command and removes a GUI variable. name is a variable name, specified in any of the ways acceptable to the set command. If name refers to an element of an array then that element is removed without affecting the rest of the array. If a name consists of an array name with no parenthesized index, then the entire array is deleted. The unset command returns an empty string as result. An error occurs if the variables doesn't exist.

Example:
    # deletes one variable
    ::smm::gui::unset a
    # deletes the variables a, b and c
    ::smm::gui::unset a b c
    # deletes one element from the array
    ::smm::gui::unset array(index)
    # deletes the entire array
    ::smm::gui::unset array

8.5.3 ::smm::gui::get

Retrieve the value of a GUI variable.

Syntax:
Description:

::smm::gui::get name
You cannot use the $name syntax for GUI variables, but must retrieve their value by a function call: ::smm::gui::get name returns the value of the corresponding GUI variable.

Example:
    # non GUI variable
    ::set a 5
    ::set b [::expr $a + 1]
    # GUI variable
    ::smm::gui::set a 5
    ::smm::gui::set b [::expr [::smm::gui::get a] + 1]

8.5.4 ::smm::gui::list

Retrieve names of all GUI variables.

Syntax:

::smm::gui::list
Description:
::smm::gui::list
Returns a list containing the names of all GUI variables.

Example:
    # delete all GUI variables
    ::foreach gv [::smm::gui::list] {
      ::smm::gui::unset $gv
    }

8.5.5 ::smm::gui::array

Array operations.

Syntax:

::smm::gui::array option arrayname args
Description:
::smm::gui::array option arrayname args
Implements the array command for GUI variables.

Example:
    ::smm::gui::set A(1) 1
    ::smm::gui::set A(2) 2
    ::set size [::smm::gui::array size A]

8.5.6 ::smm::gui::addrow

Add a container to the user customizable widget area (UCWA). Other widgets must be placed into those containers. The row is not a usable widgets itself , but all other widgets must be placed within rows, thus rows are the starting point to your own GUI.

Syntax:

::smm::gui::addrow rowname
Description:
::smm::gui::addrow rowname
Adds a row with the name rowname to the UCWA. The rows are added from top to bottom in the order of their creation.

Example:
    ::smm::gui::addrow util

8.5.7 ::smm::gui::remrow

Remove a widget container/row.

Syntax:

::smm::gui::remrow rowname
Description:
::smm::gui::remrow rowname
Removes the row and all its widgets with the name rowname from the UCWA.

Example:
    ::smm::gui::remrow util

8.5.8 ::smm::gui::addbutton

Add a button to your own GUI. A button will invoke the assigned command when pressed. Of couse you can use it to send text/commands to the MUD.

Syntax:

::smm::gui::addbutton rowname buttonname text command
Description:
::smm::gui::addbutton rowname buttonname text command
Adds the button with its identifier pair rowname/buttonname into the row rowname. text is displayed as text on the button. command will be executed, when the button is pressed.

Example:
    # We need a row first.
    ::smm::gui::addrow    util
    # now we can add the button
    ::smm::gui::addbutton util getall "get all" {::tomud "get all"}

8.5.9 ::smm::gui::rembutton

Removes a button.

Syntax:

smm:gui::rembutton rowname buttonname

Description:
smm:gui::rembutton rowname buttonname
Removes the button with the identifier pair rowname/buttonname.

Example:
    ::smm::gui::rembutton util getall

8.5.10 ::smm::gui::addcheckbutton

Add a checkbutton to your GUI. Each check button has a corresponding variable, which has to have a value of 0 or 1. This value is displayed as the state of the button. Never the less on each buttonpress a command is/can be executed.

Syntax:

::smm::gui::addcheckbutton rowname buttonname text command variablename

Description:
::smm::gui::addcheckbutton rowname buttonname text command variablename
Adds a checkbutton with the identifierpair rowname/buttonname into the row rowname. text is displayed next to the button. command will be executed, when the button is pressed. variablename is the name of the gui-variable, which will have either a value of 0 or 1, depending on the state of the button.

Example:
    # We dont need a command to be executed on buttonpress.
    # Thus the argument is an empty string.
    ::smm::gui::addcheckbutton util bpclosed "backpack closed" {} bpclosed

8.5.11 ::smm::gui::remcheckbutton

Removes a checkbutton.

Syntax:

smm:gui::remcheckbutton rowname buttonname

Description:
smm:gui::remcheckbutton rowname buttonname
Removes the checkbutton with the identifier pair rowname/buttonname.

Example:
    ::smm::gui::remcheckbutton util bpclosed

8.5.12 ::smm::gui::addlabel

Add a label to your GUI; just displayes some text.

Syntax:

::smm::gui::addlabel rowname labelname text width
Description:
::smm::gui::addlabel rowname labelname text width
Adds a label with the identifierpair rowname/labelname. text is the displayed text. width is the width of the label.

Example:
    ::smm::gui::addlabel util title "Util: " 6

8.5.13 ::smm::gui::remlabel

Removes a label.

Syntax:

::smm::gui::remlabel rowname labelname
Description:
::smm::gui::remlabel rowname labelname
Removes the label with the identifierpair rowname/labelname

Example:
    ::smm::gui::remlabel util title

8.5.14 ::smm::gui::setlabeltext

Change the text of a label.

Syntax:

::smm::gui::setlabeltext rowname lablename text
Description:
::smm::gui::setlabeltext rowname lablename text
Changes the text of the label with the identifierpair rowname/labelname to text.

Example:
    ::smm::gui::setlabeltext util title "UTIL: "

8.5.15 ::smm::gui::addvarentry

Add a variableentry to your own GUI. A variableentry displays the value of a variable, which can be changed by editing the widget.

Syntax:

::smm::gui::addvarentry rowname entryname variablename width
Description:
::smm::gui::addvarentry rowname entryname variablename width
Adds a variableentry with the identifierpair rowname/entryname into the row rowname. variablename is the name of the variable, which is displayed in the widget. width is the width of the variableentry.

Example:
    ::smm::gui::addvarentry util stuff stuff 10
    # If you set the value of the corresponding gui-variable,
    # it is automatically displayed in the widget.
    ::smm::gui::set stuff torch

8.5.16 ::smm::gui::remvarentry

Removes a variableentry.

Syntax:

::smm::gui::remvarentry rowname entryname
Description:
::smm::gui::remvarentry rowname entryname
Removes the variableentry with the identifier pair rowname/entryname.

Example:
    ::smm::gui::remvarentry util stuff

8.5.17 ::smm::gui::addvarlabel

Add a variablelabel to your own GUI. A variablelabel is a mix between a label and a variableentry. On the one hand it just displays a text and doesn't offer editing; but on the other hand it displays the value of a gui-variable; so the displayed text is dynamic.

Syntax:

::smm::gui::addvarlabel rowname labelname variablename width
Description:
::smm::gui::addvarlabel rowname labelname variablename width
Adds a variablelabel with the identifierpair rowname/labelname into the row rowname. variablename is the name of the variable, whose value is displayed. width is the width of the label.

Example:
    ::smm::gui::addvarlabel util stuff stuff 10
    ::smm::gui::set stuff torch

8.5.18 ::smm::gui::remvarlabel

Removes a variablelabel.

Syntax:

::smm::gui::remvarlabel rowname labelname
Description:
::smm::gui::remvarlabel rowname labelname
Removes the variablelabel with the identifierpair rowname/labelname.

Example:
    ::smm::gui::remvarlabel util stuff

8.5.19 ::smm::gui::addvarchooser

Add a dropdownmenu to your own GUI.

Syntax:

::smm::gui::addvarchooser rowname vcname variablename width
Description:
::smm::gui::addvarchooser rowname vcname variablename width
Adds a dropdownmenu with the identifierpair rowname/vcname into the row rowname. variablename is the name of the variable, whose value is set and displayed in the dropdownmenu. width is the width of the dropdownmenu.

Example:
    ::smm::gui::addvarchooser util stuff stuff 10

8.5.20 ::smm::gui::remvarchooser

Removes a dropdownmenu.

Syntax:

::smm::gui::remvarchooser rowname vcname
Description:
::smm::gui::remvarchooser rowname vcname
Removes a dropdownmenu with the identifierpair rowname/vcname.

Example:
    ::smm::gui::remvarchooser util stuff

8.5.21 ::smm::gui::addvarchooseritem

Adds an entryitem to a dropdownmenu.

Syntax:

::smm::gui::addvarchooseritem rowname vcname item
Description:
::smm::gui::addvarchooseritem rowname vcname item
Adds entryitem item to the dropdownmenu with the identifierpair rowname/vcname. The first entryitem gets the index 0, the second gets the index 1 and so forth.

Example:
    ::smm::gui::addvarchooseritem util stuff torch
    ::smm::gui::addvarchooseritem util stuff sword
    ::smm::gui::addvarchooseritem util stuff armor
    ::smm::gui::addvarchooseritem util stuff "iron ration"
    ::smm::gui::addvarchooseritem util stuff skin

8.5.22 ::smm::gui::remvarchooseritem

Removes an entryitem from a dropdownmenu.

Syntax:

::smm::gui::remvarchooseritem rowname vcname itemindex
Description:
::smm::gui::remvarchooseritem rowname vcname itemindex
Removes the entryitem with the index itemindex from the dropdownmenu with the identifierpair rowname/vcname.

Example:
    ::smm::gui::remvarchooseritem util stuff 2