serverReset

The "reset-server" command is implemented as a special case in ServerEvaluate. After doing a true reset ServerEvaluate calls Tcl_Eval to evaluate the full message which still contains the reset-server command. We want to ignore this the second time, so we treat the command here as a no-op.

Usage:

        reset-server

Note: for reset-server to be recognized by ServerEvaluate and really reset things, it must be the first command in a message to the server.

createObjects

TCL command to create the tree of UI objects comprising the user interface. The object tree is defined by a string valued resource. If no resource is named the default "objects" resource will be used.

Usage:

        createObjects [resource-name]

destroyObject

Destroy an object and all of its children.

Usage:

        destroyObject object-name

activate

Activate the user interface. When called the first time the user interface is created and activated, thereafter the UI is merely reactivated (e.g. mapped if unmapped).

Usage:

        activate

deactivate

Deactivate the user interface. Optionally unmaps the UI and calls the Obm client back to let it know that the UI has been deactivated.

Usage:

        deactivate [unmap]

getResource

Get the string value of the specified application resource (window system parameter). This allows use of the resource mechanism to supply default values for GUI parameters.

Usage:

        value = getResource resource-name [class [default-value]]

In the simplest case one merely requests a resource by name and the string value is returned as the function value. If the resource has an entry in the fallback resources for the application (appInitialize resource list) then a value is guaranteed to be returned.

If the Class name for the resource is given then a class default value will be returned if no entry is found for the name resource instance. This is useful when there are a number of resources of the same type (same class). If most or all resources in the same class have the same default value one need only make one entry for the Class in the application defaults resource list. It is up to the application developer to define the class name of a resource - the class name can be any string. Examples are "Font", "Cursor", etc. By convention the first character of a class name is capitalized, while instance names begin with a lower case letter.

If there is an entry for the named resource in the resource list passed to appInitialize then a value string is guaranteed to be returned. This will be either the appInitialize default, or a value specified by the system or the user in an X resources file. If one is not certain a default value is defined somewhere, a default value should be specified in the getResource call as shown above.

See also getResources, used to get multiple resources in one call.

getResources

Get the string values of a list of resources.

Usage:

        getResources resource-list

e.g.

        getResources {
            { resource [variable class [default-value]]] }
            { resource [variable class [default-value]]] }
            (etc.)
        }

createMenu, editMenu

Create or modify a menu. The editMenu function is an alias for createMenu.

Usage:

        createMenu menu-name parent item-list

e.g.,

        createMenu menu-name parent {
            { label function data [options...] }
            { label function data [options...] }
            (etc.)
        }

where

        menu-name is the object name for the menu popup shell
        parent    is the parent widget of the menu shell
        label     is a menu item label
        function  is the function to be performed when the menu
        item      is selected, e.g., f.exec, f.data, f.space, or f.line.
        data      is function dependent data
        options   are option-name option-value pairs, as specified
                  below.

In the item list the fields label and option-value may be any Tcl expression. Expressions are evaluated in the server context. The data field is a Tcl script to be executed when the menu item is selected.

Options are specified as "option option-value". The menu item options are as follows.

        bitmap       A bitmap to be displayed left justified in the label field
                     (e.g. to indicate a parameter setting).
        sensitive    Specifies whether the menu item is active (sensitive=true)
                     or inactive (sensitive=false, item grayed out).
        accelerator  Specifies an input translation (accelerator, e.g.,
                     keyboard event) which can be used to execute the
                     menu item.

The option-value field may be any Tcl expression.

Example:

        createMenu fileMenu toplevel {
            { "File Menu" f.title}
            { Open f.exec openFile}
            { Save f.exec saveFile}
            { Load f.menu loadMenu}
            { no-label f.line }
            { Quit f.exec "send client Quit" }
        }

The first createMenu is called for a given menu the menu is created, added to the menu list, and all window system widgets are created for the menu. Subsequent calls will result in only the changed parts of the menu being altered provided the changes are not great. Hence this routine can be called to efficiently modify a menu when minor runtime changes occur, e.g., an item label or action changes, the item value changes state, and so on, without need for the GUI code to know how to make the necessary detailed changes to the widgets used to implement the menu.

destroyMenu

Destroy a menu. This can be used to free up the resources used by a menu, e.g., if the menu is not expected to be needed again for a while.

Usage:

        destroyMenu menu-name

createBitmap

Create a named bitmap. This replaces any old bitmap of the same name. The new bitmap is cached in server memory; when a widget bitmap resource is set, the bitmap cache will be searched for the named bitmap before asking Xlib to find the bitmap.

Usage:

        createBitmap name width height data

e.g.,

        createBitmap foo 16 16 {
            0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xc0,0x01,
            0x60,0x03,0x20,0x02,0x60,0x03,0xc0,0x01,0x00,0x00,0x00,0x00,
            0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00 }

createCursor

Create a cursor from bitmap data. The cursor is entered into the server's cursor cache and will override any existing entry of the same name.

Usage:

        createCursor name source mask fg_color bg_color x_hot y_hot

e.g.,

        createCursor foo bitmap1 bitmap2 black white 8 8

The named bitmaps must be created first with createBitmap.

createPixmap

Create a named pixmap. This replaces any old pixmap of the same name. The new pixmap is cached in server memory; when a widget pixmap resource is set, the pixmap cache will be searched for the named pixmap before asking Xlib to find the pixmap.

Usage:

        createPixmap name width height depth fg_color bg_color data

e.g.,

        createPixmap foo 16 16 8 black white {
            0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xc0,0x01,
            0x60,0x03,0x20,0x02,0x60,0x03,0xc0,0x01,0x00,0x00,0x00,0x00,
            0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00 }

print

Print a string on the standard output. This is used mainly for debugging user interfaces.

Usage:

        print arg [arg ...]

send

Send a message to an object. The object interprets the message and returns a function value as the string result of the TCL command.

Usage

        send <object> <message>

postActivateCallback

Post a callback procedure to be called when the UI is activated. The UI is activated when it is first downloaded to server, but it may also be activated (reactivated) after the application has exited and is later restarted, or when the UI is deactivated and reactivated. Note that the UI state vis-a-vis the external world (client application) may no longer be accurate after it has been idle for a time and then reactivated.

Usage:

        postActivateCallback <procedure>

postTimedCallback

Post a callback to call the named procedure back after a specified delay in milliseconds.

Usage:

        id = postTimedCallback procedure msec [client-data]

After the specified delay the user callback procedure will be called with client_data (if given) as the single argument. Only one call will be made; the client must repost the callback in each call if the procedure is to be repeatedly executed.

An ID value is returned which may be passed to deleteTimedCallback to delete the timer.

deleteTimedCallback

Delete a timer callback procedure. This procedure is typically used to break a timer loop, where the timer procedure repeatedly reposts itself at the end of each interval.

Usage:

        deleteTimedCallback id

The ID string is returned by postTimedCallback when a timer is posted.

postWorkCallback

Post a callback for a procedure to be called when the server is idle. Work procedures are used to perform computations in the background while the user interface remains active and able to respond to input events. This works only if the user work procedure does its job in small increments, doing only a small amount of processing in each call. The work procedure will be called repeatedly until it returns a status indicating that it has finished its task.

Usage:

        id = postWorkCallback procedure [client-data]

When the server has nothing else to do the user work procedure will be called with client_data (if given) as the single argument. The work procedure should return the string "done" when all processing is finished, or any other string if the procedure is to be called again.

An ID value is returned which may be passed to deleteWorkCallback to delete the work procedure.

deleteWorkCallback

Delete a work callback procedure.

Usage:

        deleteWorkCallback id

The ID string is returned by postWorkCallback when a work procedure is posted.