UI PARAMETER class


The UI parameter class is used for client-UI communications. The client does not control the user interface directly, rather the UI defines a set of abstract UI parameters, and during execution the client application assigns values to these parameters. These UI parameters should be thought of as describing the runtime state of the client as viewed by the GUI. The GUI is free to interpret this state information in any way, including ignoring it. Many GUIs can be written which use the same client state as described by the UI parameters.

Assigning a value to a UI parameter causes the new value to be stored, and any parameter action procedures registered by the UI to be called. The action or actions [if any] taken when a parameter value changes are arbitrary, e.g. the action might be something as simple as changing a displayed value of a UI widget, or something more complex like displaying a popup.

UI Parameter class commands:

            getValue
            setValue  <new-value>
         addCallback  <procedure-name>
      deleteCallback  <procedure-name>
              notify

The most common usage is for the GUI to post one or more callbacks for each UI parameter. When the UI parameter value is changed [with setValue, e.g. by the client] the GUI callback procedures are called with the old and new UI parameter values on the command line. addCallback is used to add a callback procedure, and deleteCallback to delete one. Multiple callbacks may be registered for a single UI parameter. notify is used to simulate a parameter value change, causing any callback procedures to be invoked.

The callback procedure is called as follows:

	user-procedure param-name {old-value} {new-value}

The important thing to note here is that the old and new value strings are quoted with braces. This prevents any interpretation of the string by Tcl when the callback is executed, which is necessary because the strings can contain arbitrary data. When Tcl calls the callback the first level of braces will be stripped off, leaving old-value and new-value each as a single string argument.

setValue

Set the value of a parameter, and notify all clients via the posted callback procedures that the parameter value has changed.

Usage:

        setValue <new-value>

getValue

Get the value of a parameter.

Usage:

        getValue

notify

Notify the registered clients of a parameter as if the value had changed.

Usage:

        notify

addCallback

Add a callback procedure to the callback list for a parameter.

Usage:

        addCallback <procedure-name>

deleteCallback

Delete a callback procedure previously registered for a parameter.

Usage:

        deleteCallback <procedure-name>