Using tkMOO-light

Word completion

The client supports dabbrevs, which are a little like the TAB completion available on some UNIX shells. Typing a partial word followed by TAB makes the client search the Output window for matching word candidates, if a matching word is found then the remainder of its text is appended to the Input box, completing the word. If you keep pressing TAB then alternative matches are used to complete the word.

For example, suppose the output window contained the following text:

    January, February, March, April, May, Janet, Mary...
If you type the word 'Jan' into the Input window and then press the TAB key then the letters 'uary' are appended, to form the complete word 'January'. Typing TAB again changes the completed word to 'Janet'.

Accessing Search engines

The client lets you perform searches on many of the popular internet search engines. When you type '?' into the client's input window and follow it with a search term the client will open a webbrowser onto a search engine. By default the Google engine is chosen. For example, you should get a list of stuff about cars by typing:
    ?honda automobiles 
This searching behaviour is controlled by the 'Use Search Engines' checkbox under the Special Forces category of the Preferences Editor. Uncheck to stop the '?' from causing searches. Or pick another search engine from the 'Preferred search-engine' list.

Accessing the Server home page

The client can display the server's Home Page or Help Page, if these exist. Just select the Help->'Server Home Page' menu option. If the server has defined a home-page then it will be displayed by using your machine's web-browser. To define a home-page, the server needs to support the
dns-com-awns-serverinfo package.

The Preferences Editor

The versatile Preferences Editor is used to control the many settings which allow you to customise your client. The client can be set up to use different fonts and colours and text-formatting styles for each world in your list of connections.

Related preference settings are are grouped into different categories. You can access different categories in the editor by selecting a category from the menu-button at the top of the preferences editor window.

General Settings

The following settings control the client's behaviour when connecting to or disconnecting from a world.
The name of the world (or MUD) for which all the following settings pertain. The string is used to identify the site in the 'Connect' menu. This string is also matched against by the -world regular expression parameter in triggers, macros and gags.

The host name, or IP address of the MUD.

The port number for the MUD.

User name
Your user-id or character name for this MUD. Occurrences of the token %u in the Connection Script setting are replaced by this value.

The password for this MUD. Occurrences of the token %p in the Connection Script setting are replaced by this value. The password you enter will be displayed as '********'.

On short list
If the on short list checkbox is on, then this world will appear as an entry in the Connect menu.

Local echo
If the local-echo checkbox is on, then a copy of what you type into the input window will be displayed on the output window in highlighted text, usually in red. If local-echo is off then none of the text you type will appear on the output window.

Input window size
Sets the number of lines to display in the client's input window.

Always resize window
If the always resize window checkbox is on, then the client will resize and move to the screen position it occupied the last time you connected to this world.

Client mode
Sets the client's input mode. In line mode the client expects an end-of-line character, one of CR, LF, or CRLF to terminate each line of input from the server.

Line mode is required if you wish to make use of line mode protocols like MCP/2.1 or XMCP/1.1. MOO servers are usually line-mode in nature. Cold servers can be either line mode or character mode. To force your connection to a cold server to be in line mode you need to use a command like @set terminated-tell=no to set your connection's output characteristics.

Write to log file
Determines whether or not data sent to and from this MUD will be logged.

Log file name
The full path and file name of a text file. If the Write to log file checkbox is set then the client will write a copy of each line received from the mud as well as each line you type, into the file. You can type-in a file-path or use the Choose button to open a file-chooser dialog.

Connection script
One or more lines of text which are sent to the MUD immediately after a connection has been made. Some tokens take on a special meaning in a connection script; %u and %p are replaced by the values of the User name and Password settings respectively.

When no Connection Script is given the typical MUD login string 'connect %u %p' is assummed.

When a Connection Script is given it is assumed to contain *all* the information required to connect to a site as well as additional commands which are sent after the connection is made. This means that so long as there are other lines in the script then the first line should read 'connect %u %p'. For example, here's a suitable connection script for a MOO, that logs you in and then displays the latest news items:

    connect %u %p
    news new
Disconnection script
One or more lines of text which are sent to the MUD immediately before the connection is dropped by the client, eg. after the 'Connect->Close' or 'Connect->Quit' menu options have been selected.

Key bindings
The client can emulate the keybindings from several popular clients and platforms.

Colours and Fonts

You're able to define the background and foreground text colours of the main window. The colours you choose can be different for each world, which can help when you have several client windows open at the same time.
Normal text colour
Background colour
Local echo colour
Each setting determines foreground (text) and background (screen) colours for the client's Output window. The current setting is displayed as a bar of colour. You can change the setting by selecting the Choose button which opens a colour-chooser dialog.

Default font type
This setting determines which font style will be used when displaying normal text. Possible are fixedwidth and proportional. The actual font used is defined in the fixedwidth font and proportional font settings.

Fixedwidth font
Proportional font
Bold font
Italic font
Header font
Each setting determines the real font name to be used for this style of lettering, wherever it appears in the client. These font settings are also used in the client's Help windows and for rendering rich-text formats like jtext.

You can define fonts by hand, using for example an X-font definition:

Or you can select the Choose button which opens a font-chooser dialog.

Support ANSI codes
If this checkbox is on, then the client will display text which is rendered with ANSI colour codes.

ANSI blink
If this checkbox is on, then the ANSI blink code will be honoured, and relevant text will blink.

Out of Band

Many features of the client rely on coded information sent from the server. This information is sent across the same connection as regular chat text, but only the client is able to see it. We call such information 'out of band'.

The client supports several different Out of Band protocols, and these may be controlled individually by using the following settings.

XMCP/1.1 enabled
If the XMCP/1.1 enabled checkbox is on then the client will recognise XMCP/1.1 protocol messages if they are sent by the server.

XMCP/1.1 connection script
One or more lines of text containing commands which are sent to the server after an XMCP/1.1 protocol connection has been established.

XMCP/1.1 applications require the XMCP/1.1 Authentication Key to be sent before they can cooperate with the client. The simplest way to send the key is to place a command like:

in the client's
Connection Script.

Use MCP/2.1
If the Use MCP/2.1 checkbox is on then the client will recognise MCP/2.1 protocol messages.

Log MCP/2.1 messages
If the Log MCP/2.1 messages checkbox is on then MCP/2.1 protocol messages will be written to the client's active logfile.

Old-style local edit
Some servers support old-style local edit messages. If the old-style local edit checkbox is on then the client will recognise these messages.

Log MacMOOSE messages
The MacMOOSE object browser and editor uses the MacMOOSE out-of-band protocol to communicate with the server. If the Log MacMOOSE messages checkbox is on then these messages will be written to the client's active logfile.

You can find out more about MacMOOSE here:

Use MCP/1.0
MCP/1.0 is an older, now deprecated, version of MCP/2.1. If the Use MCP/1.0 checkbox is on then the client will recognise MCP/1.0 protocol messages.

Paragraph Layout

You can control the position of text on the client's main window. Settings allow you to control left and right margin indentation, as well as the amount of whitespace used between lines.
Display paragraphs
When the display paragraphs checkbox is on the following settings are used to format lines of text as they appear on the main window.

Distance units
The following distances are measured in pixels, millimeters or characters.

Left margin
The amount of space to leave between the left-hand side of the main window, and the text.

2nd line indent
If the line being displayed is wrapped to form a paragraph, then the 2nd and subsequent lines of that paragraph will be indented by this amount.

Right margin
The amount of space to leave between the right-hand side of the main window, and the text.

Space above
The amount of space to leave above each line of text.

Space below
The amount of space to leave below each line of text.

Statusbar Settings

The client's statusbars appear at the bottom of the client's main window.
Display elapsed time
If the display elapsed time checkbox is on then a status-bar window will display the number of hours and minutes that you've been connected to the current server.

Display seconds
If the display seconds checkbox is on then elapsed time is displayed in hours minutes and seconds.

Show statusbars
If the show statusbars chackbox is on then the client's status-bars will be displayed at the bottom of the client's main window. The statusbars can also hidden/exposed by using the Preferences->'Toggle Statusbars' menu-option.

Activity flash light
If the activity flash light checkbox is on then the activity indicator is displayed at the right-hand side of the statusbar. Normall the client will scroll automatically, so that new text appears at the bottom of the main window. If you've scrolled back a few lines to read older text then when new text arrives the indicator will flash in order to let you know.

Kiosk after seconds
If you don't type anything into the client then after this many secods it will go into kiosk-mode. Kiosk mode removes all widgets from the client's main window leaving only the output window, which remains abale to display text arriving from the server. A value of 0 (zero) seconds prevents the client from switching to kiosk-mode.

The client looks for the worlds.tkm file in each of the following locations:
Because the worlds.tkm files contains your valuable passwords you should keep the file hidden. On UNIX systems you can do this by using the chmod command to restrict read-access to the file to only yourself.

Triggers and Gags

In tkMOO-light version 0.2.51 support for user-programmable triggers and gags was introduced. The current implementation is very simple but will be improved in future releases of the client.

The client's Tools->Edit Triggers menu option opens the client's editor on the triggers.tkm file. The triggers file is stored in the following locations depending on which platform you are using.

    Platform    Location
    UNIX        $HOME/.tkMOO-lite/triggers.tkm
    MAC         triggers.tkm, in your Preferences Folder
    WINDOWS     $HOME\tkmoo\triggers.tkm

The gag command is a special form of the trigger command which does nothing, and prevents matching lines of input from appearing on the client's main window. Gags are used to clean up your client's input, filtering out information that you don't want to see. All defined gags are processed before any defined triggers are processed.

The gag command is defined like as follows. Optional command flags are shown inside square brackets '[', ']'. The '\' character is used to break lines of text up and to make the definitions more readable.

    gag -regexp {some regular expression} \
	    [ -world {world name} ] \
	    [ -type {world type} ]
Here's an example of the gag command which suppresses a MOO server's *** Connected *** message, normally received each time you connect to a MOO:
    gag -regexp {^\*\*\* .* \*\*\*$}

The trigger command is defined as follows. Optional command flags are shown inside square brackets '[', ']'. The '\' character is used to break lines of text up and to make the definitions more readable.

    trigger -regexp {some regular expression} \
            -command {some tcl procedure} \
	    [ -world {world name} ] \
	    [ -type {world type} ] \
	    [ -priority <priority> ] \
	    [ -continue ]
A trigger is a small program which runs each time the server sends the client a line of text that the user has decided is interesting. Each time a line of text arrives from the server a list is created of all the triggers that match the line. Each trigger defined is processed to see if it will be activated by the line. When all the activated triggers have been identified they are sorted according to their priority and processed so that matching triggers with a higher priority are processed before those with a lower priority. Each time a trigger is processed it's command is executed and then, if the -continue flag is present, the next matching trigger is processed until either all the available triggers have been processed. If a trigger that did not define the -continue flag is processed then further processing of triggers stops.

matched against each line received by the client from the server and if the regular expression matches the incoming line then the command is executed.

can contain any valid Tcl program fragment in addition to several specially defined commands which allow your program to interface with the rest of the client. In this way commands can be used to print information on the client's output window or send information back to the client. In addition the different matching parts of the the regular expression are captured in special variables which can be referred to in the command program.

a regular expression which is matched against the World: of the worlds.tkm file. If the regular expression does not match against the currently connected world then the trigger is not activated. If no -world command flag is present then the trigger is processed as if the flag was present and matched successfully.

a regular expression which is matched against the Type: field of the worlds.tkm file. If the regular expression does not match against the currently connected world's type then the trigger is not activated. If no -type command flag is present then the trigger is processed as if the flag was present and matched successfully.

an integer value, usually between 0 and 100. If no priority flag is defined then a default value of 50 is used.

after processing this trigger's command proceed to the next active trigger. If the -continue flag is not present then no further processing of the line is performed.
The macro command is defined as follows. Optional command flags are shown inside square brackets '[', ']'. The '\' character is used to break lines of text up and to make the definitions more readable.
     macro -regexp {some regular expression} \
           -command {come Tcl command} \
           [ -world {regexp} ] \
           [ -type {regexp} ]
The macro command behaves like 'trigger' but operates on outgoing data typed into the client's input window. Macro commands have access to the same range of Tcl commands that triggers do.

All your triggers, gags and macros are stored in a special file named triggers.tkm. The file can be editied using ordinary editing tools or by using the client's built-in editor. When you save the file using the built in editor the definitions are read and the client is immediately reconfigured.

Several procedures are predefined to allow the triggers to interract with the client's internal routines. Here's a list of the available commands:

Some Examples

Greet your friends

The following statements define a trigger which greets your friends if they wave to you:
    trigger -regexp {^(.*) waves\.$} \
	    -continue \
	    -command {
		io.outgoing ":waves to $m1."
Using this trigger, if your client sees the following line from the user 'Networker':
    Networker waves.
then your client (you're Andrew) will respond with:
    Andrew waves to Networker.

Colour friends' names

Here's a more advanced example that prints information on the client's screen in different colours. The tag command defines a tag Blue. Any text that gets printed on the client's output window which is marked with this tag will be displayed in blue, all other text is displayed in black. The regexp is similar to the previous example and assigns values to the special variables $m1 and $m2. The window.display and window.displayCR commands display text on the client's main window and marks the text with an optional tag.
    tag configure Blue -foreground [colour.get blue]
    trigger -regexp {^(Networker|Andrew) (.*)} \
            -command {
                window.display $m1 T_Blue
                window.displayCR " $m2"
If your client sees the following message from the server, then the name 'Networker' is displayed in blue text and the rest of the line is displayed in black text. This trigger has no -continue flag, so once it is processed all further processing of triggers ia stopped:
    Networker says, "My name should appear in blue letters..."
You can change the way a line of text is displayed on the client's output window according to the line's content. MOO usually emits 'Name''???' for say or emote messages. If the person making the noise in in our list of friends then print their name in blue, and the rest of the line in default black.

Different triggers for different Worlds

This example makes use of the predefined tag T_Blue. The trigger is only activated when you're connected to either SomeMOO or AnotherMOO, and when the message you've received comes from either Janet or John.
    trigger -world {SomeMOO|AnotherMOO} \
            -regexp {^(Janet|John) (.*)} \
            -command {
                window.display $m1 T_Blue
                window.displayCR " $m2"

Look at MOO object numbers

This example makes use of the predefined tag GoTo which gives text the look of a clickable hyperlink. Output from a standard MOO contains frequent references to objects, in the form #123, #9232, etc.

The GoTo tag makes these numbers appear in green and changes the shape of the mouse pointer whenever it's over the clickable text. If you have a 3-button mouse then clicking on button 3 will activate the link and send the message 'look #123' to the server.

The GoTo tag only defines what the text will look like. We need to use an additional tag which we create especially to call client.outgoing and sent the message to the server. The predefined routine unique_id is used to generate a new tag-name, returning a value of the form '12345t'.

The tag command creates a new tag using the new tag-name and defines a block of code to be executed each time the B3-ButtonRelease event ocurrs over any text marked with that tag. The GoTo tag is built-in, it colours text green and causes the mouse cursor to turn into a pointing finger when it's over the text.

    trigger -regexp {(.*)(#[0-9]+)(.*)} -command {
        set cmd_tag [unique_id t]
        tag bind $cmd_tag <B3-ButtonRelease> "client.outgoing {look $m2}"
        window.display $m1 
        window.display $m2 "GoTo T_$cmd_tag"
        window.displayCR $m3

Turn URLs into links and control a web browser

The next example displays any text that looks like a URL as a green clickable hyperlink. On UNIX machines clicking on the URL will cause tkMOO-light to request a local webbrowser to fetch the URL. The exec command is used to call the webbrowser passing it the URL to be displayed.
    trigger -regexp {(ftp|http)://([^\"\'\`\> ]+)} -command {
        set cmd_tag [unique_id t]
        tag bind $cmd_tag <B3-ButtonRelease> "exec netscape -remote openURL($m2://$m3) &"
        window.display $m1 
        window.display $m2://$m3 "GoTo T_$cmd_tag"
        window.displayCR $m4

Expand single-letter commands

The next example used a macro to save on typing. The macro expands the typed letter 'W' to the command '@who' and sends it to the server.
    macro -regexp {^W$} \
          -command { io.outgoing "@who" }

Using 'highlights'

New with version 0.2.59 of tkMOO-light, Highlights allow you to render a portion of a line in a different colour, with a different font, or with any other Tk 'tag'. Each time the client sees a new line of input it will check to see if any triggers have been activated and if any highlights have been set, by the triggers, for that line. If a highlight has been set then the client will display the line of input with the hilighting applied. If no highlights have been set then the client will display the line as normal. Here are some examples which use the highlight commands to perform some familiar tasks:

Colour friends' names

In this example the trigger command has preset a special variable $p1, which contains the positions of the start and end characters of the part of the input line that matches the first bracketed pattern in the regular expression.

If Janet were to say something:

    Janet says, "Hello!"
then $p1 would be a Tcl list with the value {0 4}, where 0 is the index of the first character in the line.

You don't need to use the values in $p1 if you don't want to. You can, instead use your own Tcl list containing a pair of integers.

    trigger -world {SomeMOO|AnotherMOO} \
            -continue \
            -regexp {^(Janet|John) (.*)} \
            -command {
                highlight T_Blue $p1

The Resources File

When the client is started it is able to read from an optional resources file which contains text entries defining some of the client's properties, like display colours and fonts. For the time being only a few colours are definable, but the number of configurable options will be improved in future versions of the client. The following entries define the client's default colour scheme:
    # off-white background for text screens
    *Text.background: #f0f0f0
    # pink background for input boxes
    *Entry.background: #f00000
    # grey desktops
    *desktopBackground: #d9d9d9
The same file can contain definitions for the fonts used by the client:
    *fontPlain: -*-times-medium-r-*-*-14-*-*-*-*-*-*-*
    *fontBold: -*-times-bold-r-*-*-14-*-*-*-*-*-*-*
    *fontItalic: -*-times-medium-i-*-*-14-*-*-*-*-*-*-*
    *fontHeader: -*-helvetica-medium-o-normal-*-18-*-*-*-*-*-*-*
    *fontFixedwidth: 7x14

Any settings in the preferences editor will override matching settings in the resource file.

The client looks for your resources file in the following places depending on which platform you're using:

    Platform	Location
    UNIX 	$HOME/.tkmoolightrc
    MAC 	tkMOO-light.RC, in your Preferences Folder
    WINDOWS 	$HOME\tkmoo\tkmoo.res