Mud Client Protocol - Fuzzball GUI Package
Author: Revar Desmera
Description: A definition of the MCP messages used by the Fuzzball MCP GUI package.

# Mud Client Protocol - GUI Package (MCP-GUI)

## A package to provide GUI dialogs for server-side MU* programs.

## by Revar Desmera <revar@belfry.com>

## June 8, 2005: v1.0

### 1. Why?

It's become increasingly apparent that having a smooth graphical 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

- A sever-side program may not send anything that will be destructive to the client machine.
- Unauthorized programs may not trick the user into entering private information, including their password.
- The client may not invoke any unauthorized or destructive commands on the server.

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:

- We ensure that unsafe scripts cannot be uploaded to the client
- We don't force the server-side programmers to master TCL/Tk or some other GUI extension language
- The protocol can specify the same functional GUI, regardless of the implementation of the client.

### 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 list of commands to be sent to the client. These commands specify the layout of your dialog.

But first, some notation notes:

- S→C Means the message is sent from Server to Client.
- C→S Means the message is sent from Client to Server.
- C↔S Means either Client or Server can send it.

Also, a value is considered true if it's value is "1" or "true". A value of "" or "0" or "false" is considered false. Matching is case insensitive.

Now, on to the messages:

### 3.1.1 Dialog Management Commands

S→C ORG-FUZZBALL-GUI-DLOG-CREATE ( DLOGID, TITLE, [TYPE], [PANES*], [NAMES*], [RESIZABLE], [WIDTH], [HEIGHT], [MINWIDTH], [MINHEIGHT], [MAXWIDTH], [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. Shown in the titlebar.
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. Items are newline separated.
NAMES
  The tab captions (tabbed dlog) or screen titles (helper dlog). This argument is only sent if the dialog type is Helper or Tabbed. Items are newline separated.
RESIZABLE
  Specifies whether the dialog can be resized by the user in the "x", "y", or "both" dimensions. Use the value "none" or don't supply this value, to make the dialog not be resizable.
WIDTH
  The requested width of the dialog, in pixels.
HEIGHT
  The requested height of the dialog, in pixels.
MINWIDTH
  Specifies the minimum width of the dialog in pixels. The dialog can't be resized to be smaller than this.
MINHEIGHT
  Specifies the minimum height 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.
MAXHEIGHT
  Specifies the maximum height of the dialog in pixels. The dialog can't be resized to be larger than this.

This command is always the first command you send. It creates a dialog within which you can add controls. The TYPE argument 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 simple empty window which you can add controls to.

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 must be sent to the server before the buttonpress notification. The Okay button must send changes, similar to the Apply button, but it also dismisses the dialog.

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".

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 this control value is for.
ID
  The control identifier, used to specify which control in the dialog this value is for.
VALUE
  The value of the control.

When sent by the server to the client, this message lets the server change the value shown in a control in the dialog managed by the client.

When sent by the client, 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 REPORT argument that is set true. 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, since the client closed the dialog.

C→S ORG-FUZZBALL-GUI-CTRL-EVENT ( DLOGID, ID, EVENT, [DISMISSED] [DATA] )

DLOGID
  The dialog identifier, used to specify what dialog this message refers to.
ID
  The identifier of the control that initiated the event.
EVENT
  The specific event type that occurred. Currently either "BUTTONPRESS" or "VALCHANGED".
DISMISSED
  A true value if the client closed the dialog due to this event.
DATA
  Extra event-specific data that may need to be sent back.

This message is used to notify the server that an event occurred that the server should know about or handle. Before an event is sent, the server must be updated with all changed control values via ORG-FUZZBALL-GUI-CTRL-VALUE messages. Currently, the supported event types are:

BUTTONPRESS
  A button was pressed, or an image or highlight was clicked on. The ID argument is that of the control that was clicked on. If the user clicked on the close button in the window's titlebar, then a buttonpress event is sent with an ID of "_closed". If the user clicked on highlighted text in a MULTIEDIT or EDIT widget, that was set to REPORT, then the DATA argument will contain a list, where the first line is the name of the highlight tag, and the second line will be the character position within the control, where the user clicked.
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 ORG-FUZZBALL-GUI-CTRL-VALUE message.

S→C ORG-FUZZBALL-GUI-CTRL-COMMAND ( DLOGID, ID, COMMAND, ... )

DLOGID
  The dialog identifier, used to specify what dialog this message refers to.
ID
  The control identifier, used to specify which control in the dialog this message refers to.
COMMAND
  The command that you want to issue to the specified control. Command matching is case insensitive.
...
  Each command may take 0 or more extra arguments. These may be named anything except the three above given arg names, and their name should not start with an underscore ('_') character.

This is used to send a command to the given control. The currently supported control commands, and their additional arguments are:

INSERT ( VALUES, [BEFORE] )
DELETE ( ITEMS | FIRST, LAST )
SELECT ( ITEMS | FIRST, LAST )
SHOW ( POSITION )
CURSOR ( POSITION )
HILITE-SET ( TAGNAME, START, END, ... too many optional args to list here. )
HILITE-CLEAR ( TAGNAME, START, END )
HILITE-DELETE ( TAGNAME )
ENABLE ( no args )
DISABLE ( no args )

C↔S ORG-FUZZBALL-GUI-ERROR ( DLOGID, ERRTEXT, ERRCODE )

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 multiple 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 row with vweight 1. 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.

S→C ORG-FUZZBALL-GUI-CTRL-DATUM ( DLOGID, ID, VALUE )

DLOGID
  The dialog identifier, used to specify what dialog this message refers to.
ID
  The control identifier, used to specify the name of the control to create/modify.
VALUE
  The initial value of the control.

Creates a hidden named data item, useful for storing various insecure state information. This doesn't have a user-visible control associated with it. It just holds data that the user never has to see. Since the user could have hacked their client, you should not consider this value to be secure.

S→C ORG-FUZZBALL-GUI-CTRL-HRULE ( DLOGID, ID, HEIGHT )

DLOGID
  The dialog identifier, used to specify what dialog this message refers to.
ID
  The control identifier, used to specify the name of the control to create/modify.
HEIGHT
  The thickness of the horizontal rule/line, in pixels.

This message 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 the menu case, the HEIGHT argument is completely ignored.

S→C ORG-FUZZBALL-GUI-CTRL-VRULE ( DLOGID, ID, WIDTH )

DLOGID
  The dialog identifier, used to specify what dialog this message refers to.
ID
  The control identifier, used to specify the name of the control to create/modify.
WIDTH
  The thickness of the vertical rule/line, in pixels.

This message draws a vertical rule (line) across the cell as a separator. This control cannot be used in a menu.

S→C ORG-FUZZBALL-GUI-CTRL-BUTTON ( DLOGID, ID, TEXT, [WIDTH], [DISMISS], [DEFAULT], [BINDKEY] )

DLOGID
  The dialog identifier, used to specify what dialog this message refers to.
ID
  The control identifier, used to specify the name of the control to create/modify.
TEXT
  The text label to be displayed on the button.
WIDTH
  The thickness of the vertical rule/line, in pixels.
DISMISS
  If true, when this button is pressed, automatically close the dialog.
DEFAULT
  If true, show this button as a Default style button.
BINDKEY
  Specifies a key binding that should also invoke this button. Format is that used by TCL/Tk. ie: of the form: <Modifiers-Key-Keyname> where modifiers are "Alt-", "Control-", and "Shift-". For example: "<Alt-Control-Key-u>" or "<Shift-Key-numbersign>".

A BUTTON is simply a pushbutton. Pressing it results in an immediate BUTTONPRESS event 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, by setting the DISMISS argument to "0". 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.

S→C ORG-FUZZBALL-GUI-CTRL-TEXT ( DLOGID, [ID], VALUE, [MAXWIDTH], [JUSTIFY] )

DLOGID
  The dialog identifier, used to specify what dialog this message refers to.
ID
  The control identifier, used to specify the name of the control to create/modify. If none is given, the server waives rights to refer to this widget in the future.
VALUE
  The text label string to be displayed.
MAXWIDTH
  If this is specified, the text will wrap if longer than this given number of pixels. Defaults to 80% of screen width.
JUSTIFY
  If the text wraps, then this determines how the text will be aligned. Can be "left", "right", or "center".

This message 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 the server doesn't wish to refer to this widget in the future. The MAXWIDTH argument specifies the maximum width of the label, in pixels. 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.

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.

S→C ORG-FUZZBALL-GUI-CTRL-IMAGE ( DLOGID, [ID], VALUE, WIDTH, HEIGHT, [REPORT] )

DLOGID
  The dialog identifier, used to specify what dialog this message refers to.
ID
  The control identifier, used to specify the name of the control to create/modify. If none is given, the server waives rights to refer to this widget in the future.
VALUE
  The URL of the image to be displayed. This image should be either a GIF, JPEG, or PNG file. GIFs and PNGs should support transparency if possible.
WIDTH
  The width of the image to be displayed, in pixels. (required)
HEIGHT
  The height of the image to be displayed, in pixels. (required)
REPORT
  If true, this image will send a BUTTONPRESS event when it is clicked on. Defaults to false.

An image control lets the program display graphical images. It can be clicked like a button, if REPORT is set to a true value. If the VALUE of the image is changed, the new image should be fetched and displayed. Image sizes up to 512x512 must be supported. The client may wish to impose restrictions on what sites images are allowed to be displayed from. URLs referring to the same IP address or domain as the server should almost certainly be allowed.

`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.
MAXLENGTH
  The maximum number of characters to be entered.
VALIDCHARS
  The characters that can be entered into this control.
REPORT
  If set to "1", then changes to the text content of this widget should be reported to the server periodically. This shouldn't be done more often than once every couple seconds, to prevent excessive bandwidth usage.

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 `MAXLENGTH` tag is given, no more than the given number of characters may be entered. `ORG-FUZZBALL-GUI-CTRL-PASSWORD(DLOGID, ID, VALUE, [MAXLENGTH], [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.
MAXLENGTH
  The maximum number of characters to be entered.

A `PASSWORD` box lets the user enter a single line of text, like the `EDIT` control, but the characters will not be shown visibly, so folks can't peek at your password over your shoulder. If the `MAXLENGTH` 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" width for a proportional font, "serif" for a proportional serif font, or "fixed" width. Defaults to "fixed". In general, "variable" should be Helvetica or Arial, "fixed" should be Courier or Monaco, and "serif" should be Times or Times New Roman.
MULTICOLOR
  Advises that the control is expected to be able to support color hilites, via the `HILITE-SET` control-command.
MULTISTYLE
  Advises that the control is expected to be able to support styles (bold, italics, underline, font, etc), set via the `HILITE-SET` control-command.

A MULTIEDIT control is a multi-line version of the edit control. However, it doesn't support length limits or content restrictions. To prevent excessive bandwidth usage, this control should not support REPORT-ing content changes, except when another event is about to be sent.
`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 valname.
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 created 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. Defaults to 12.
TEXT
  If given, a Text label control is inserted into the current row and column, then the spinner 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.

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.
TEXT
  If given, a Text label control is inserted into the current row and column, then the combobox 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.

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, and `EDITABLE` is false, then selecting an item causes the dialog to immediately report the selected item. REPORT is not required to be supported if `EDITABLE` is true.
`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, or if it should be a "serif" proportional font. Defaults to "variable" 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".
WIDTH
  Optionally specifies the width of the frame, in pixels.
HEIGHT
  Optionally specifies the height of the frame, in pixels.

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 `PANE` layout argument. `ORG-FUZZBALL-GUI-CTRL-NOTEBOOK(DLOGID, ID, ...)
`

DLOGID
ID
PANES {}
NAMES {}
HEIGHT 200
WIDTH 300

`ORG-FUZZBALL-GUI-CTRL-TREE(DLOGID, ID, ...)
`

DLOGID
ID
VALUE {}
OPTIONS {}
ICONS {}
HEIGHT 200
WIDTH 200
REPORT 0

`ORG-FUZZBALL-GUI-CTRL-MENU(DLOGID, ID, [TEXT])
`

DLOGID
ID
TEXT

`ORG-FUZZBALL-GUI-CTRL-SCALE(DLOGID, ID, ...)
`

dlogid
id
text {}
resolution 1.0
digits 0
length 100
report 0
width 15
value 0.0
valname
minval 0.0
maxval 100.0
orient horiz
interval 10.0
bigincrement 10%

### 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, combobox, and tree.
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.
ICONS
  When inserting an item into the tree widget, this specifies the icons that should be shown next to each value. The first item of the icons argument list corresponds to the first item of the values argument.
NAME
  The name of the pane to create when inserting a notebook tab.
PANE
  The pane name to give the pane created when inserting a notebook tab.

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.) For `TREE` controls, the `BEFORE` argument isn't given or used. The `ICONS` argument will specify what icons to show next to each VALUE inserted into the tree. For NOTEBOOK widgets, the NAME and `PANE` arguments are used, to specify the tab text and pane name of the tab to add, respectively.
`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 in tree controls, or as an alternative to/in addition to `FIRST`/`LAST` for 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.) For NOTEBOOK controls, this raises the given pane/tab.
`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

- Various formatting changes
- Added Changes section to end of document.
- Noted that REPORT works only in `PERSISTENT` dialogs for various controls.
- Added ONVAL and OFFVAL tags to CHECKBOX.
- Added VALUE tag to RADIO control, to allow specifying the value returned by that radio button group, if that particular radio button is selected.
- Added explanations for the `EDIT` control's `LENGTH` and `ALLOW` tags.
- Changed the names of several muf functions from all uppercase to all lowercase.
- Changed several references to integer `<serid>`'s to strings.

v0.903 - May 12, 1998

- Changed name of VALUE tag in RADIO button to be RETURN.
- Swapped TEXT and HRULE control explanations.
- Added ID tags for all controls.

v0.904 - March 21, 1999

- Stripped out any reference to MUF.
- Removed any reference to the transport protocol. That's handled by MCP now.
- Rewrote the higher-level GUI protocol as an MCP package.

v0.905 - June 25, 1999

- Removed the PERSISTENT dialog type.
- Added the TABBED dialog type.
- Removed the list CLEAR command.
- Added the 'all' option to the list DELETE command.
- Fleshed out a lot of various message usages and argument descriptions.

v0.906 - July 5, 1999

- Clarifications of Tabbed and Helper dialogs.
- Clarifications of REQUIRED tags.
- Removed SORTED from listbox.
- Added HEIGHT tag to HRULE
- Added WIDTH tag to VRULE
- various other small changes.

v0.990 - April 8, 2001

- Rewrote to reflect the way the MCP GUI protocol was actually implemented in Trebuchet, as that is the reference implementation.
- Removed REQUIRED tags.