# WIDGET class

The Widget class is the generic or base class for the window system toolkit widgets supported by the object manager. The Widget class supports a number of different Xt widget classes using a table driven approach to describe each widget. Any widget may be created, destroyed, and manipulated in various ways using only the generic Widget class procedures and Widget-specific resources. The Widget class may be subclassed to support complex Widgets that require custom class-specific commands for use by the GUI code.

Generic Widget-class commands:

                     set <resource-name> <value>
                     get <resource-name>

             addCallback <procedure-name> []
          deleteCallback <procedure-name>
            setSensitive <sensitive>
             isSensitive

                 realize
               unrealize
             isRealizeed
                     map
                   unmap
                  manage child [child ...]
                unmanage child [child ...]
                   popup [grab-kind]
                 popdown
       popupSpringLoaded

                    move <x> <y>
                  resize <width> <height> <border-width>
               configure <x> <y> <width> <height> <border-width>

The most important Widget commands are set/get resource, and the callbacks. The widget sensitivity can be set and queried using set/get resource, but special procedures are provided to make this common operation more convenient.

Class specific functions:

                     append text                         # text widget
                    setList list [resize]                # list widget
            value = getItem itemno
                  highlight itemno
                unhighlight

Ideally the widget class should be subclassed for widgets that require class-specific functions, but in simple cases involving standard widgets the support is built into the widget class code as a special case.

Special actions (used in translations):

                    call (proc [,arg, ...])
                   popup (menu-name [xoffset [yoffset]])
                 popdown (menu-name)

The "call" action is a very general mechanism which allows any GUI procedure to be registered with any translation using the X translation table mechanism. The popup and popdown actions are used for popup menus. The menu will be popped up at the event coordinates plus the optional offsets if given.

Event handling:

         addEventHandler <procname> <event-mask> [<event-mask>...]

Event callback:

        userEventHandler widget event-type time wx wy rx ry other

In most cases translations are preferable to events, but a GUI can capture raw events if it wishes by adding event handlers. Nearly all of the X event types are supported. The callback syntax employs a number of standard arguments, followed by a number of event-specific arguments.

# addCallback

Add a callback procedure to the callback list for a widget. If no callback name is given, "callback" is assumed.

Usage:

            addCallback  [<callback-name>]

Specific widgets only support certain types of callbacks. There is no checking that the callback type specified is supported by a widget; the wrong type of callback can be registered, but it will never be called.

# deleteCallback

Delete a callback procedure previously registered for a widget.

Usage:

            deleteCallback <procedure-name>

# do_userproc (call)

Translation action procedure used to call general user action procedures in the interpreter. The name of the user procedure to be called is given as the first argument in the translation. For example, the translation "call(foo,a,b,c)" would cause procedure foo to be called with the arguments (a,b,c). The following arguments are special:

            Argument        Replaced by

            $name             object name of widget
            $time             event->time
            $x                event->x
            $y                event->y
            $x_root           event->x_root
            $y_root           event->y_root

The "user procedure" can be any server procedure.

# do_popup

Popup a menu (or other spring loaded popup) at the location of the event which triggered this action.

Usage:

            popup(menu-name [xoffset [yoffset]])

# do_popdown

Pop down a menu.

Usage:

            popdown(menu-name)

# set

Set a widget resource.

Usage:

            set <resource-name> <value>

# get

Get a widget resource value as a string.

Usage:

            get <resource-name>

# append

Append data to a text widget.

Usage:

            append <text>

# setList

Set the item list of a list widget.

Usage:

            setList list [resize]

The list is a simple list of strings, passed as a single string argument to setList (quotes, braces, etc. may be used to quote strings containing special characters).

# getItem

Get an item in a list widget.

Usage:

            value = getItem itemno

If ITEMNO is a number the indicated list item is returned, or the string "EOF" if the requested item is beyond the end of the list. Otherwise the currently selected item is returned, and the index of the item is returned in the output variable ITEMNO. If no item is currently selected ITEMNO will be set to "none" on output.

# highlight

Highlight an item in a list widget.

Usage:

            highlight itemno

The indicated item of the list is highlighted as if the item had been selected by the user. Any previously highlighted item is unhighlighted.

# unhighlight

Unhighlight the currently highlighted item in a list widget.

Usage:

            unhighlight

Any currently highlighted item in the list widget is unhighlighted.

# realize

Realize a widget. This activates and assigns windows for a widget and all of its descendants. Realizing a widget does not in itself cause it to appear on the screen.

Usage:

            realize

# unrealize

Unrealize a widget. This destroys the windows assigned to a widget and all of its descendants.

Usage:

            unrealize

# isRealized

Test whether a widget is realized.

Usage:

            isRealized

# map

Map a widget.

Usage:

            map

# unmap

Unmap a widget.

Usage:

            unmap

# manage

Manage a list of child widgets. These should share the same common parent, a geometry widget of some sort. Managing the children makes them appear in the window, possibly causing the other children to be rearranged in the window.

Usage:

            manage child [child ...]

This message should be sent to the geometry widget which is the parent of the children.

# unmanage

Unmanage a list of child widgets. These should share the same common parent, a geometry widget of some sort. Unmanaging the children makes them disappear from the window and be removed from geometry management, possibly causing the other children to be rearranged in the window.

Usage:

            unmanage child [child ...]

This message should be sent to the geometry widget which is the parent of the children.

# popup

Popup a shell widget. If no grab is indicated the popup can remain up while other windows accept input.

Usage:

            popup [grab-kind]

# popdown

Popdown a shell widget.

Usage:

            popdown

# popupSpringLoaded

Popup a shell widget, e.g., a popup menu. This implies an exclusive grab.

Usage:

            popupSpringLoaded

# move

Move a widget to the given window relative coordinates.

Usage:

            move <x> <y>

# resize

Resize a widget.

Usage:

            resize <width> <height> <border-width>

# configure

Configure a widget, i.e., execute a simultaneous move and resize.

Usage:

            configure <x> <y> <width> <height> <border-width>

# setSensitive

Set the sensitivity of a widget.

Usage:

            setSensitive <sensitive>

# isSensitive

Test the sensitivity of a widget.

Usage:

            isSensitive

# addEventHandler

Add a custom event handler to a widget. A list of event masks is given to define the classes of events the user supplied event handling procedure is to receive.

Usage:

            addEventHandler <procname> <event-mask> [<event-mask>...]

# removeEventHandler

Remove an event handler previously posted with addEventHandler, above.

Usage:

            removeEventHandler procname

# event

Generic event handler called when a widget event handler posted by addEventHandler is called.

The user event handler is called as

            userEventHandler widget event-type time wx wy rx ry other

where "other" is an event-type specific list of fields describing the the event.