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