path: root/vendor/x11iraf/obm/docs/gui.doc/servercom.html

<h1><A NAME="serverReset">serverReset</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        reset-server
</pre>
<p>
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.
<p>
<h1><A NAME="appInitialize>appInitialize</A></h1>
<p>
TCL command to initialize the server for a new application, setting the
application name and loading the application resources.
<p>
Usage:	
<p>
<pre>
        appInitialize appname, appclass, resources
</pre>
<p>
<h1><A NAME ="createObjects">createObjects</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        createObjects [resource-name]
</pre>
<h1><A NAME="destroyObject">destroyObject</A></h1>
<p>
Destroy an object and all of its children.
<p>
Usage:	
<pre>
        destroyObject object-name
</pre>
<p>
<h1><A NAME="activate">activate</A></h1>
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).
<p>
Usage:	
<p>
<pre>
        activate
</pre>
<p>
<h1><A NAME="deactivate">deactivate</A></h1>
<p>
Deactivate the user interface. Optionally unmaps the UI and calls the Obm
client back to let it know that the UI has been deactivated.
<p>
Usage:
<p>
<pre>
        deactivate [unmap]
</pre>
<p>
<h1><A NAME="getResource">getResource</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        value = getResource resource-name [class [default-value]]
</pre>
<p>
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.
<p>
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.
<p>
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.
<p>
See also getResources, used to get multiple resources in one call.
<p>
<h1><A NAME="getResources">getResources</A></h1>
<p>
Get the string values of a list of resources.
<p>
Usage:
<p>
<pre>
        getResources resource-list
</pre>
<p>
e.g.
<pre>
        getResources {
            { resource [variable class [default-value]]] }
            { resource [variable class [default-value]]] }
            (etc.)
        }
</pre>
<p>
<h1><A NAME="createMenu">createMenu, editMenu</A></h1>
<p>
Create or modify a menu. The editMenu function is an alias for createMenu.
<p>
Usage:
<pre>
        createMenu menu-name parent item-list
</pre>
<p>
e.g.,
<pre>
        createMenu menu-name parent {
            { label function data [options...] }
            { label function data [options...] }
            (etc.)
        }
</pre>
<p>
where
<p>
<pre>
        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.
</pre>
<p>
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.
<p>
Options are specified as "option option-value". The menu item options are
as follows.
<p>
<pre>
        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.
</pre>
<p>
The option-value field may be any Tcl expression.
<p>
Example:
<p>
<pre>
        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" }
        }
</pre>
<p>
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.
<p>
<h1><A NAME="destroyMenu">destroyMenu</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        destroyMenu menu-name
</pre>
<p>
<h1><A NAME="createBitmap">createBitmap</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        createBitmap name width height data
</pre>
<p>
e.g., 
<p>
<pre>
        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 }
<p>
<h1><A NAME="createCursor">createCursor</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        createCursor name source mask fg_color bg_color x_hot y_hot
</pre>
<p>
e.g., 
<p>
<pre>
        createCursor foo bitmap1 bitmap2 black white 8 8
</pre>
<p>
The named bitmaps must be created first with createBitmap.
<p>
<h1><A NAME="createPixmap">createPixmap</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        createPixmap name width height depth fg_color bg_color data
</pre>
<p>
e.g., 
<p>
<pre>
        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 }
</pre>
<p>
<h1><A NAME="print">print</A></h1>
<p>
Print a string on the standard output. This is used mainly for debugging
user interfaces.
<p>
Usage:
<p>
<pre>
        print arg [arg ...]
</pre>
<p>
<h1><A NAME="send">send</A></h1>
<p>
Send a message to an object. The object interprets the message and returns
a function value as the string result of the TCL command.
<p>
Usage
<p>
<pre>
        send &lt;object&gt; &lt;message&gt;
</pre>
<p>
<h1><A NAME="postActivateCallback">postActivateCallback</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        postActivateCallback &lt;procedure&gt;
</pre>
<p>
<p>
<h1><A NAME="postTimedCallback">postTimedCallback</A></h1>
<p>
Post a callback to call the named procedure back after a specified delay
in milliseconds.
<p>
Usage:
<p>
<pre>
        id = postTimedCallback procedure msec [client-data]
</pre>
<p>
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.
<p>
An ID value is returned which may be passed to deleteTimedCallback to delete
the timer.
<p>
<h1><A NAME="deleteTimedCallback">deleteTimedCallback</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        deleteTimedCallback id
</pre>
<p>
The ID string is returned by postTimedCallback when a timer is posted.
<p>
<h1><A NAME="postWorkCallback">postWorkCallback</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        id = postWorkCallback procedure [client-data]
</pre>
<p>
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.
<p>
An ID value is returned which may be passed to deleteWorkCallback to delete
the work procedure.
<p>
<h1><A NAME="deleteWorkCallback">deleteWorkCallback</A></h1>
<p>
Delete a work callback procedure.
<p>
Usage:
<p>
<pre>
        deleteWorkCallback id
</pre>
<p>
The ID string is returned by postWorkCallback when a work procedure is posted.