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.
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.
Delete a callback procedure previously registered for a widget.
Usage:
deleteCallback <procedure-name>
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.
Popup a menu (or other spring loaded popup) at the location of the event which triggered this action.
Usage:
popup(menu-name [xoffset [yoffset]])
Pop down a menu.
Usage:
popdown(menu-name)
Set a widget resource.
Usage:
set <resource-name> <value>
Get a widget resource value as a string.
Usage:
get <resource-name>
Append data to a text widget.
Usage:
append <text>
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).
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 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 the currently highlighted item in a list widget.
Usage:
unhighlight
Any currently highlighted item in the list widget is unhighlighted.
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 a widget. This destroys the windows assigned to a widget and all of its descendants.
Usage:
unrealize
Test whether a widget is realized.
Usage:
isRealized
Map a widget.
Usage:
map
Unmap a widget.
Usage:
unmap
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 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 a shell widget. If no grab is indicated the popup can remain up while other windows accept input.
Usage:
popup [grab-kind]
Popdown a shell widget.
Usage:
popdown
Popup a shell widget, e.g., a popup menu. This implies an exclusive grab.
Usage:
popupSpringLoaded
Move a widget to the given window relative coordinates.
Usage:
move <x> <y>
Resize a widget.
Usage:
resize <width> <height> <border-width>
Configure a widget, i.e., execute a simultaneous move and resize.
Usage:
configure <x> <y> <width> <height> <border-width>
Set the sensitivity of a widget.
Usage:
setSensitive <sensitive>
Test the sensitivity of a widget.
Usage:
isSensitive
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>...]
Remove an event handler previously posted with addEventHandler, above.
Usage:
removeEventHandler procname
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.