Mud Client Protocol - GUI Package

A GUI package designed by Revar & Triggur
April 8, 2001: v0.990

1. Why?

It's become increasingly apparent that having a smooth graphic user interface for MUD-based interactions is the next step for online worlds. This proposal aims to solve the problem by creating a secure, open protocol, allowing server-side programmers to request a user's client to create a GUI interface.

2. Security Concerns

The protocol presented here answers these concerns by creating a high-level GUI protocol on top of the MCP transport protocol. Since no executable code is sent, we can guarentee the following:

3. What options are available to the Server-side coder wanting a GUI interface?

All interface dialogs are non-modal, meaning that the user is free to interact with the text window without having to dismiss the dialog.

3.1 How do I specify the look of my interface?

Glad you asked. You provide a proplist of commands to be sent to the client. These commands specify the layout of your dialog:

3.1.1 Dialog Management Commands

S->C ORG-FUZZBALL-GUI-DLOG-CREATE(DLOGID, TITLE, [TYPE], [PANES*], [NAMES*], [WIDTH], [HEIGHT], [RESIZABLE], [MINWIDTH], [MAXWIDTH], [MINHEIGHT], [MAXHEIGHT])
DLOGID
The dialog identifier, later used to specify what dialog you are working with. A DLOGID is composed of a string of one or more letters, numbers, or underscore characters.
TITLE
The window title of this dialog.
TYPE
The type of the dialog. Can be any of: "SIMPLE", "HELPER" or "TABBED". Defaults to "SIMPLE".
PANES
The reference ids of the tabs (tabbed dlog), or screens (helper dlog). This argument is only sent if the dialog type is Helper or Tabbed.
NAMES
The tab captions (tabbed dlog) or screen titles (helper dlog). This argument is only sent if the dialog type is Helper or Tabbed.
WIDTH
The requested width of the dialog, in pixels.
HEIGHT
The requested height of the dialog, in pixels.
RESIZABLE
Specifies whether the dialog can be resized by the user in the "x", "y", or "both" dimensions.
MINWIDTH
Specifies the minimum width of the dialog in pixels.  The dialog can't be resized to be smaller than this.
MAXWIDTH
Specifies the maximum width of the dialog in pixels.  The dialog can't be resized to be larger than this.
MINHEIGHT
Specifies the minimum height of the dialog in pixels.  The dialog can't be resized to be smaller than this.
MAXHEIGHT
Specifies the maximum height of the dialog in pixels.  The dialog can't be resized to be larger than this.
The DIALOG command is always the first command you send. It creates a dialog within which you can add controls. The TYPE tag lets you specify whether the dialog is to be a simple dialog, a Tabbed dialog, or a Helper dialog. A Simple dialog is just a window within which you can add controls.

A Helper dialog is similar to Windows95 Wizard dialogs, in that it provides a linear path through a series of controls. You may specify multiple panes in which you can create controls. Each pane will be a single Helper screen. The user will be led through the screens one by one until they have reached the last one. A Helper dialog has two buttons by default that can send buttonpress messages to the server. Their IDs are "_finish" and "_cancel".

A Tabbed dialog is like a Windows95 Property Sheet, or a window with a tabbed notebook control. You are provided with multiple panes within which you can add controls, each pane being a tab on the notebook. The user will be able to randomly access any page they wish. By default, a Tabbed dialog comes with three buttons that can send buttonpress events to the server. Their IDs are "_ok", "_apply", and "_cancel". The Apply button won't dismiss the dialog, but any changed values should be committed. The Okay button should commit changes, similar to the Apply button, but it also dismisses the dialog.

S->C ORG-FUZZBALL-GUI-DLOG-SHOW(DLOGID)
DLOGID
The dialog identifier, used to specify what dialog you are causing to be shown.
Causes the given dialog to be displayed. This must be sent after the dialog is created or the dialog will not be displayed to the user. This exists mainly to keep the user from having to see dialogs get constructed while the GUI messages keep streaming in.
S->C ORG-FUZZBALL-GUI-DLOG-CLOSE(DLOGID)
DLOGID
The dialog identifier, used to specify what dialog you are closing.
This is used to dismiss the given dialog, from the server-side. This is useful for persistent or automatically dismissed dialogs. (Progress meters, for example.)
C->S ORG-FUZZBALL-GUI-CTRL-VALUE(DLOGID, ID, VALUE)
DLOGID
The dialog identifier, used to specify what dialog you are returning a value from.
ID
The identifier of the control that you are returning the value of.
VALUE
The value of the control.
This updates the server's knowledge of what values have changed in the given dialog. These messages should be sent before any event messages, for all changed values. These messages should also be sent immediately on any value change for controls that have a true REPORT argument. Note that since only changed values are sent, that the server needs to maintain state information for the dialog. If the user disconnects, this state information should be discarded. If an event message is received by the server and the DISMISSED argument is true, the state info should be discarded after being returned to the calling program.
C->S ORG-FUZZBALL-GUI-CTRL-EVENT(DLOGID, ID, DISMISSED, EVENT)
DLOGID
The the dialog identifier, used to specify what dialog you are working with.
ID
The identifier of the control that initiated the event.
DISMISSED
A true value if the dialog was dismissed by the event.
EVENT
The specific event type that occurred.  Currently either "BUTTONPRESS" or "VALCHANGED".
This is used to notify the server that an event occurred that the server should know about or handle.  It is expected that this message will be sent after a series of GUI-CTRL-VALUE messages that update the server's knowledge of current control values.  Currently, the supported event types are:
BUTTONPRESS
A button was pressed. The ID is that of the button that was pressed.  If the user clicked on the close button in the window's titlebar, then a buttonpress event is sent with an ID of "_closed".
VALCHANGED
A value changed in a control that was configured to "REPORT" when the user changed its value.  The new value is not included in this message, as the value should mave been reported in a previous GUI-CTRL-VALUE message.
C->S ORG-FUZZBALL-GUI-CTRL-COMMAND(DLOGID, ID, COMMAND, ...)
DLOGID
The dialog identifier, used to specify what dialog you are working with.
ID
The identifier of the control that you want to issue a command to.
COMMAND
The command that you want to issue to the specified control.
...
Each command will take 0 or more other arguments.  These may be named anything but the three above given args, and they should not starts with an underscore ('_') character.
This is used to send a command to the given control.  The currently supported control commands are:
INSERT(VALUES, [BEFORE])
DELETE(ITEMS|FIRST, LAST)
SELECT(ITEMS|FIRST, LAST)
SHOW(POSITION)
CURSOR(POSITION)
C<->S ORG-FUZZBALL-GUI-ERROR(DLOGID, TEXT, ERR)
DLOGID
The the dialog identifier, used to specify what dialog you are working with.
ERRTEXT
The human readable error message.
ERRCODE
The computer readable error code.

3.1.2 Dialog Layout

The client arranges controls in a manner similar to how HTML tables are laid out, but with only one control per cell. By default, when a control is added, it is placed in the first unused cell in the row below the previously added control. When any control is created, you can modify its placement with a variety of optional arguments.
NEWLINE
If "true" or "1", specifies that this control is to be placed relative to the first unused cell of the next row. If "false" or "0", specifies that this control is to be placed relative to the next unused cell in the current row. Defaults to "true".
COLSKIP
Specifies how many unused horizontal cells to skip past to get to the cell you want to place the control in. Defaults to 0.
COLSPAN
Specifies how many horizontal cells to span this control across. These cells are all considered used, for purposes of future layout commands. If you have a wide dialog due to wide controls in different rows, using this argument may help solve the problem. Defaults to 1.
ROWSPAN
Specifies how many vertical cells to span this control across. These cells are all considered used, for purposes of future layout commands. If you have a tall dialog due to tall controls in different rows, using this argument may help solve the problem. Defaults to 1.
STICKY
Specifies the side(s) of the cell to stick against. This contains any or all of the letters N, S, E, or W for north, south, east, or west, respectively. If you specify both N and S, then the control will stretch out vertically to stick to both north and south sides. If you specify both E and W, the control will stretch horizontally to stick to both east and west sides. If the value is "" (null) then the control will be centered in the cell both horizontally and vertically. Defaults to "W" to stick to the west side.
MINWIDTH
Specifies the minimum width in pixels that the control will occupy.
MINHEIGHT
Specifies the minimum height in pixels that the control will occupy.
HWEIGHT
How much the starting column of this control should expand.  When filling unused space, if there are two columns, one with hweight 2 and the other with hweight 1, then the column with hweight 2 will be expanded twice as much as the other column.  The default hweight is 0.  Note that the last control in the given column sets the hweight for the column.  If no hweights are given in a pane, then if the pane is forced to be wider than the contained controls, the empty space will be placed in the right side of the pane.
VWEIGHT
How much the starting row of this control should expand. When filling unused space, if there are two rows, one with vweight 2 and the other with vweight 1, then the row with vweight 2 will be expanded twice as much as the other row. The default hweight is 0.  Note that the last control in the given row sets the vweight for the row.  If no vweights are given in a pane, then if the pane is forced to be taller than the contained controls, the empty space will be placed in the bottom of the pane.
LEFTPAD
The number of pixels of spacing that should be to the left of this control.
TOPPAD
The number of pixels of spacing that should be above this control.
ROW
The specific row that this control should start in.  You should only need to specify this in rare circumstances, if you properly use the other layout options.
COLUMN
The specific column that this control should start in.  You should only need to specify this in rare circumstances, if you properly use the other layout options.
PANE
Specifies the screen or frame that this control will be created within. Defaults to the dialog window.

3.1.3 Control Creation/Configuration Commands

These commands are all Server to Client messages. To create a new control, use one of these messages with a new ID. If you send one of these messages with an existing ID, you will just modify the existing control already bound to that ID. An ID is composed of a string of one or more letters, numbers, or underscore characters. 
ORG-FUZZBALL-GUI-CTRL-DATUM(DLOGID, ID, VALUE)
DLOGID
The dialog identifier, used to specify what dialog you are creating the control in.
ID
The control identifier, used to reference this item in later commands, and for returning this item's value.
VALUE
The value of this item.
Creates a hidden named data item, useful for storing various state information. This doesn't have a user-visible control associated with it. It just holds data that the user never has to see.
ORG-FUZZBALL-GUI-CTRL-HRULE(DLOGID, [ID], [HEIGHT])
DLOGID
The dialog identifier, used to specify what dialog you are creating the control in.
ID
The control identifier, used to reference this control in later commands,
HEIGHT
The thickness of the horizontal rule, in pixels.
The HRULE command draws a horizontal rule (line) across the cell as a separator.
If the PANE given for this control is a MENU control, then this will instead add a separator line to the given menu.  In this case, the HEIGHT argument is completely ignored.
ORG-FUZZBALL-GUI-CTRL-VRULE(DLOGID, [ID], [WIDTH])
DLOGID
The dialog identifier, used to specify what dialog you are creating the control in.
ID
The control identifier, used to reference this control in later commands,
WIDTH
The thickness of the vertical rule, in pixels.
The VRULE command draws a vertical rule (line) across the cell as a separator.
ORG-FUZZBALL-GUI-CTRL-BUTTON(DLOGID, ID, TEXT, [WIDTH], [DISMISS], [DEFAULT], [BINDKEY])
DLOGID
The dialog identifier, used to specify what dialog you are creating the control in.
ID
The control identifier, used to reference the control in later commands, and for returning control values.
TEXT
The text label to display within the button.
DISMISS
If set to "1", the dialog will be dismissed when this button is pushed.
DEFAULT
If set to "1", the given button will visually be indicated as the default button.
BINDKEY
Specifies a key combination that should trigger this button.  Format is that used by TCL/Tk.  ie: of the form: <Modifiers-Key-Keyname> where modifiers are "Alt-", "Control-", and "Shift-".  <Key-Return> would be the Return/Enter key.  <Alt-Shift-Key-numbersign> would specify the numbersign key, with the Alt and Shift keys held down.
WIDTH
The width of the button, in characters. This is based on the average character width of the font used for the button text.
A BUTTON is simply a pushbutton. Pressing it results in an immediate response back to the server, containing the VALUEs for all controls in the dialog. Though by default this dismisses the dialog, the programmer can specify that it does not, with the DISMISS option. The DISMISS argument defaults to "1".
If the PANE given for this control is a MENU control, then this will instead add a menu item to the given menu.  In this case, the DEFAULT and WIDTH arguments are completely ignored.  The menu item, when selected, will send a BUTTONPRESS event, just as if it were a button.
ORG-FUZZBALL-GUI-CTRL-TEXT(DLOGID, [ID], VALUE, [JUSTIFY], MAXWIDTH)
DLOGID
The dialog identifier, used to specify what dialog you are creating the control in.
ID
The control identifier, used to reference the control in later commands.
VALUE
The label text to display.
JUSTIFY
Specifies the justification for the text in the control, if it's multiline.  Must be one of "left", "right", or "center".
MAXWIDTH
The maximum width of the label, in characters.
The TEXT command draws a simple text label in the dialog. The ID tag specifies the ID of a control, for use in changing control options in persistent dialogs. If no ID tag is given, then an ID is automatically generated for it. The MAXWIDTH argument specifies the maximum width of the label, in character units. A character unit is the width of an average character for the given font. Text that is wider than MAXWIDTH is line-wrapped. Note that the actual number of characters you may fit into this width may vary according to the font, and the width of the characters in the entered text.
If the PANE given for this control is a MENU control, then this will only add a non-selectable comment to the given menu.  In this case, the JUSTIFY and MAXWIDTH arguments are completely ignored.
ORG-FUZZBALL-GUI-CTRL-IMAGE(DLOGID, [ID], VALUE, HEIGHT, WIDTH, [REPORT])
DLOGID
The dialog identifier, used to specify what dialog you are creating the control in.
ID
The control identifier, used to reference the control in later commands.
VALUE
The URL web address of the image to display. This image should be either a GIF or XBM file.
WIDTH
The width of the image in pixels.  This is a required argument.
HEIGHT
The height of the image in pixels.  This is a required argument.
REPORT
If set to "1" this image will send a buttonpress event when it is clicked on. Defaults to "0".
An image control lets the program display graphical images. It can be clicked like a button, if REPORT is set to "1".
ORG-FUZZBALL-GUI-CTRL-EDIT(DLOGID, ID, VALUE, [MAXLENGTH], [VALIDCHARS], [WIDTH])
DLOGID
The dialog identifier, used to specify what dialog you are creating the control in.
ID
The control identifier, used to reference the control in later commands.
TEXT
If given, a Text label control is inserted into the current row and column, then the edit control will be put in the column to the right of the label.  This may have unintended layout effects if you don't take this into account.
VALUE
The initial text contents of the control.
WIDTH
The width of the control, in character units.
HEIGHT
The height of the control, in lines. While you cannot enter more than one line of text, it will wrap to the next line if you enter a long string.  The height of the line varies depending on the fonts in use.
MAXLENGTH
The maximum number of characters to be entered.
VALIDCHARS
The characters that can be entered into this control.
An EDIT box lets the user enter a single line of text, containing no newlines. This text can optionally be filtered for content.  If the VALIDCHARS tag is specified, only characters matching the given Regular Expression pattern are allowed. If the LENGTH tag is given, no more than the given number of characters may be entered.
ORG-FUZZBALL-GUI-CTRL-MULTIEDIT(DLOGID, ID, VALUE*, [WIDTH], [HEIGHT])
DLOGID
The dialog identifier, used to specify what dialog you are creating the control in.
ID
The control identifier, used to reference the control in later commands.
VALUE
The initial contents of the edit control. This may be a multi-line value.
WIDTH
Width of the multiedit control, in Character units. Defaults to 40.
HEIGHT
Height of the multiedit control, in Line units. Defaults to 10.
FONT
Specifies whether the font in the control should be "variable" or "fixed" width.  Defaults to "fixed".
A MULTIEDIT control is a multi-line version of the edit control. However, it doesn't support length limits or content restrictions.
ORG-FUZZBALL-GUI-CTRL-CHECKBOX(DLOGID, ID, TEXT, VALUE, [VALNAME], [ONVAL], [OFFVAL], [REPORT])
DLOGID
The dialog identifier, used to specify what dialog you are creating the control in.
ID
The control identifier, used to reference the control in later commands.
TEXT
The text to display to the right of the checkbox.
VALUE
The initial state of the Checkbox. Should match ONVAL or OFFVAL's values.
VALNAME
Specifies the ID of the VALUE that will be selt back to the server.  Defaults to the ID of the control itself.
REPORT
If this is set to "1", then when this checkbutton is clicked on, a BUTTONPRESS event will be sent to the server for this control.
ONVAL
The value of the control when checked. Defaults to 1.
OFFVAL
The value of the control when unchecked. Defaults to 0.
A CHECKBOX is used to represent a boolean value.  When it is checked, it will return the given ONVAL.  When not checked, it will return the given OFFVAL.  If ONVAL and OFFVAL are not specified, they default to 1 and 0, respectively.
If the PANE given for this control is a MENU, then this will create a CHECKBOX item in the given menu.
ORG-FUZZBALL-GUI-CTRL-RADIO(DLOGID, ID, VALNAME, [VALUE], SELVALUE, TEXT, [REPORT])
DLOGID
The dialog identifier, used to specify what dialog you are creating the control in.
ID
The control identifier, used to reference the radio button group when returning values.
VALNAME
Specifies the ID of the VALUE that will be returned to the server.  All radio buttons in the same group share the same.
TEXT
The text to display to the right of the radio button.
VALUE
The initial state of the radio button group. Must match one of the SELVALUEs. If this argument is provided for multiple radio buttons in this group, the last one created will set the initial value. If this argument is never sent, the first radio button will be selected.
SELVALUE
What the value of the radio button group will be, when this button is selected.
REPORT
If this is set to "1", then when this radio button is clicked on, a BUTTONPRESS event will be sent to the server for this control.
A RADIO button lets the user select one of a set of discrete values. By creating multiple radio buttons with the same VALNAME, they are identified as being part of the same group. Each radio button within a group should have a unique SELVALUE. When the dialog results are sent back, the VALUE associated with the radio button group VALNAME is the SELVALUE of the selected radio button in that group.
If the PANE given for this control is a MENU control, then this will instead add a radio button menu item to the given menu. If REPORT is "1", then the radio button menu item, when selected, will send a BUTTONPRESS event, just as if it were a regular radiobutton.
ORG-FUZZBALL-GUI-CTRL-SPINNER(DLOGID, ID, [VALUE], [MINVAL], [MAXVAL], [WIDTH])
DLOGID
The dialog identifier, used to specify what dialog you are creating the control in.
ID
The control identifier, used to reference the control in later commands.
VALUE
The initial value of the spinner control. Defaults to 0.
MINVAL
The minimum allowed value of the spinner control. Defaults to 0.
MAXVAL
The maximum allowed value of the spinner control. Defaults to 100.
WIDTH
The number of digits the spinner control can contain.
A spinner is an integer-only control with an edit field and up/down buttons. It's used to let a user specify an integer number in a dialog.
ORG-FUZZBALL-GUI-CTRL-COMBOBOX(DLOGID, ID, VALUE, OPTIONS, [WIDTH], [EDITABLE], [REPORT], [SORTED])
DLOGID
The dialog identifier, used to specify what dialog you are creating the control in.
ID
The control identifier, used to reference the control in later commands.
VALUE
The initial value of the combobox control.
OPTIONS
The list of options selectable from the combobox.
EDITABLE
If set to "false" or "0", then the user cannot enter arbitrary values.
WIDTH
The width of the control in Character units.
REPORT
If set to "true" or "1", then this control informs the server of value changes.
REQUIRED
If "true" or "1", the dialog can't be dismissed if it the value wasn't changed. This only applies to Helper or Tabbed dialogs, or to buttons that also have the REQUIRED flag set.
SORTED
If set to "true" or "1", then the contents of the combobox list will be automatically sorted in dictionary order.
A combobox lets the user select one of a list of options. The resulting value of the control will be the actual text selected, not the index. If the REPORT argument is true, EDITABLE is assumed to be false, and selecting an item causes the dialog to immediately report the selected item.
ORG-FUZZBALL-GUI-CTRL-LISTBOX(DLOGID, ID, VALUE, OPTIONS, [WIDTH], [HEIGHT], [REPORT], [REQUIRED])
DLOGID
The dialog identifier, used to specify what dialog you are creating the control in.
ID
The control identifier, used to reference the control in later commands.
VALUE
The initially selected option. This should match one of OPTIONS.
OPTIONS
The list of options selectable from the listbox.
FONT
Specifies whether the text in the listbox should be "variable" or "fixed" width.  Defaults to "fixed" width.
WIDTH
The width of the control in Character units.
HEIGHT
The height of the control in Line units.
REPORT
If set to "true" or "1", then the this control informs the server of value changes.
SELECTMODE
Used to control the way list items can be selected. When set to "single" only a single list item can be selected at any one time. When set to "multiple", you can select more than one list item by clicking on each item to select or deselect it. When set to "extended", you can select more than one list item by control-clicking on the item, or by shift-clicking to extend the range. Clicking without a modifier key will deselect all other items, and select the item clicked.
A listbox lets the user select one of a list of items, but it takes up more than just a single line, unlike the COMBOBOX. If the REPORT tag is true, the server will be sent a VALCHANGED event whenever the user changes the selection.
ORG-FUZZBALL-GUI-CTRL-FRAME(DLOGID, ID, [TEXT], [VISIBLE], [RELIEF])
DLOGID
The dialog identifier, used to specify what dialog you are creating the control in.
ID
The control identifier, used to reference the control in later commands.
TEXT
The text label to display in the upper left border of the frame.
VISIBLE
If "true" or "1", specifies that the frame has a border.
RELIEF
Specifies the nature of the border, if it's visible.  Must be one of "raised", "sunken", "groove", "ridge", "flat", or "solid".  Defaults to "groove".
A frame lets the user specify control groupings for formatting purposes. The frame can be VISIBLE or invisible (default). Specifying TEXT implies VISIBLE. However, VISIBLE can be used without TEXT so as to provide an unbroken box around the controls. Frames can be nested arbitrarily deep. You place controls inside frames by using the FRAME layout argument.

3.1.4 Control-Commands

These are the control-commands that can be sent via the ORG-FUZZBALL-GUI-CTRL-COMMAND message.  These are all Server to Client messages.  The hilighted command name is the value sent in the COMMAND argument. 
INSERT(DLOGID, ID, VALUES*, [BEFORE])
DLOGID
The dialog identifier, used to specify what dialog you are editing a control in.
ID
The control identifier of the control to add list items/characters to.
VALUES
The list of new items to add to the listbox or combobox.
BEFORE
The zero-based integer index of the list item which the new values will be inserted after. Defaults to "end". This will be ignored if the combobox is auto-sorted.
This command lets the programmer insert one or more items or characters into the contents of the control. For listboxes, edit, and combobox controls, the BEFORE argument is a zero-based index. If it is set to "end" then the new items will be added at the end.  For MULTIEDIT controls, the index is of the format 'line.character' where the line is a one-based line number, and the character is a zero-based index of the character in the line.  (1.0 is the first char of the first line.)
DELETE(DLOGID, ID, [ITEMS], [FIRST], [LAST])
DLOGID
The dialog identifier, used to specify what dialog you are editing a control in.
ID
The control identifier of the control to delete characters/items from.
ITEMS
The list of zero-based integer indexes of the list items to delete.  This is used with listboxes.
FIRST
The first position to delete from.  For MULTIEDIT controls, the index is of the format 'line.character' where the line is a one-based line number, and the character is a zero-based index of the character in the line.  (1.0 is the first char of the first line.) For other controls, this is the zero-based index of the first character/item to delete.
LAST
The last position to delete to.  For MULTIEDIT controls, the index is of the format 'line.character' where the line is a one-based line number, and the character is a zero-based index of the character in the line.  (1.0 is the first char of the first line.) For other controls, LAST is the zero-based index of the last character/item to delete to.
This command lets the programmer remove items or characters from the contents of a control. For listboxes, the ITEMS argument is a list of zero-based indexes into the list. For all other controls, the FIRST and LAST arguments are used to specify the start and ending positions of a range of text or items to delete.  If LAST is not given, then only the FIRST item/character is deleted.  If either FIRST or LAST are set to "end" then they are assumed to be the last character/item in the control.
SELECT(DLOGID, ID, [ITEMS], [FIRST], [LAST])
DLOGID
The dialog identifier, used to specify what dialog you are editing a control in.
ID
The control identifier of the lcontrol to select characters/items in.
ITEMS
The list of zero-based integer indexes of the list items to select.  This is used with listboxes.
FIRST
The first position to select.  For MULTIEDIT controls, the index is of the format 'line.character' where the line is a one-based line number, and the character is a zero-based index of the character in the line.  (1.0 is the first char of the first line.) For other controls, this is the zero-based index of the first character/item to select.
LAST
The last position to select to.  For MULTIEDIT controls, the index is of the format 'line.character' where the line is a one-based line number, and the character is a zero-based index of the character in the line.  (1.0 is the first char of the first line.) For other controls, LAST is the zero-based index of the last character/item to select to.
This command lets the programmer selected items or characters in the contents of a control. For listboxes, the ITEMS argument is a list of zero-based indexes into the list. For all other controls, the FIRST and LAST arguments are used to specify the start and ending positions of a range of text or items to select.  If LAST is not given, then only the FIRST item/character is selected.  If either FIRST or LAST are set to "end" then they are assumed to be the last character/item in the control.
SHOW(DLOGID, ID, VALUES*, [BEFORE])
DLOGID
The dialog identifier, used to specify what dialog you are editing a control in.
ID
The control identifier of the control to send this command to.
POSITION
The zero-based integer index of the list item or character which should be scrolled into view if it is not there already.
This command lets the programmer insure that the given list item or character is scrolled into view. For listboxes, edit, and combobox controls, the POSITION argument is a zero-based index. If it is set to "end" then the last item/character will be shown.  For MULTIEDIT controls, the index is of the format 'line.character' where the line is a one-based line number, and the character is a zero-based index of the character in the line.  (1.0 is the first char of the first line.)
CURSOR(DLOGID, ID, VALUES*, [BEFORE])
DLOGID
The dialog identifier, used to specify what dialog you are editing a control in.
ID
The control identifier of the control to send this command to.
POSITION
The zero-based integer index of the list item or character which the cursor should be placed before.
This command lets the programmer move the selection/insertion cursor, also known as the caret. For listboxes, edit, and combobox controls, the POSITION argument is a zero-based index. If it is set to "end" then the cursor will be placed at the last item, or after the last character.  For MULTIEDIT controls, the index is of the format 'line.character' where the line is a one-based line number, and the character is a zero-based index of the character in the line.  (1.0 is the first char of the first line.)

3.2 The Simple Dialog

The first and simplest form of interaction is with the simple dialog; everything in the dialog is specified by the server; no client-side controls are added as with the Helper Dialog (see section 3.3). The programmer is responsible for adding at least one button which can be used to dismiss the dialog. If the dialog is dismissed by the user by clicking on the titlebar's close button, the button ID "_closed" is returned in the buttonpress message.

3.3 The Helper Dialog

Sometimes the options for a program are best presented in a linear sequence. The "Helper" dialog, modeled after the Microsoft "Wizard" configuration interface, is the mechanism to do so. It is just like the simple dialog interface, except that it allows the programmer to string together multiple screens in a series. These screens are each represented by unique panes, into which the programmer can add controls. The client automatically adds "<<Back", "Next>>", "Cancel", and "Finish" buttons to the bottom as necessary. Only the Cancel and Finish buttons send a message to the server, and they report button IDs "_cancel" and "_finish" respectively. The values of all changed controls are reported before any event message. If the dialog is dismissed by the user clicking on the titlebar's close button, the button ID "_closed" is returned in the buttonpress event message.

3.4 The Tabbed Dialog

Sometimes there are more items to present to the user than a single dialog can present. The "Tabbed" dialog, modeled after the Microsoft "Property Sheet" interface, is the mechanism to do so. It presents the user with a dialog that contains several different pages of controls that they can randomly select from. The client program automatically adds "Cancel", "Apply", and "Okay" buttons to the bottom of the dialog. When the "Okay" button is pressed, the dialog is dismissed, the changed values are sent to the server as a series of ctrl-value messages, and a buttonpress event message is sent to the server with a button ID of "_ok". When the "Apply" button is pressed, the results are sent to the server without the dialog being dismissed, and a buttonpress event message is send with an ID of "_apply". When the Cancel button is pressed, the dialog is dismissed, changed values are sent to the server, and a buttonpress event message is sent to the server with an ID of "_cancel". If the dialog is dismissed by the user clicking on the titlebar's close button, the button ID "_closed" is returned in the buttonpress event message.

CHANGES TO THIS DOCUMENT

v0.902 - May 5, 1998 v0.903 - May 12, 1998 v0.904 - March 21, 1999 v0.905 - June 25, 1999 v0.906 - July 5, 1999 v0.990 - April 8, 2001