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

<title>WIDGET class</title>
<h1><IMG SRC="/iraf/web/images/iraf.gif">  WIDGET class</h1>
<p>
<HR>
<p>
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.
<p>
Generic Widget-class commands:
<p>
<pre>
                 <a href="#set">set</a> &lt;resource-name&gt; &lt;value&gt;
                 <a href="#get">get</a> &lt;resource-name&gt;
<p>
         <a href="#addCallback">addCallback</a> &lt;procedure-name&gt; [<callback-name>]
      <a href="#deleteCallback">deleteCallback</a> &lt;procedure-name&gt;
        <a href="#setSensitive">setSensitive</a> &lt;sensitive&gt;
         <a href="#isSensitive">isSensitive</a>
<p>
             <a href="#realize">realize</a>
           <a href="#unrealize">unrealize</a>
         <a href="#isRealized">isRealizeed</a>
                 <a href="#map">map</a>
               <a href="#unmap">unmap</a>
              <a href="#manage">manage</a> child [child ...]
            <a href="#unmanage">unmanage</a> child [child ...]
               <a href="#popup">popup</a> [grab-kind]
             <a href="#popdown">popdown</a>
   <a href="#popupSpringLoaded">popupSpringLoaded</a>
<p>
                <a href="#move">move</a> &lt;x&gt; &lt;y&gt;
              <a href="#resize">resize</a> &lt;width&gt; &lt;height&gt; &lt;border-width&gt;
           <a href="#configure">configure</a> &lt;x&gt; &lt;y&gt; &lt;width&gt; &lt;height&gt; &lt;border-width&gt;
</pre>
<p>
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.
<p>
Class specific functions:
<p>
<pre>
                 <a href="#append">append</a> text                         # text widget
                <a href="#setList">setList</a> list [resize]                # list widget
        value = <a href="#getItem">getItem</a> itemno
              <a href="#highlight">highlight</a> itemno
            <a href="#unhighlight">unhighlight</a>
</pre>
<p>
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.
<p>
Special actions (used in translations):
<p>
<pre>
                <a href="#do_userproc">call</a> (proc [,arg, ...])
               <a href="#do_popup">popup</a> (menu-name [xoffset [yoffset]])
             <a href="#do_popdown">popdown</a> (menu-name)
</pre>
<p>
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.
<p>
Event handling:
<p>
<pre>
     <a href="#addEventHandler">addEventHandler</a> &lt;procname&gt; &lt;event-mask&gt; [&lt;event-mask&gt;...]
</pre>
<p>
Event callback:
<p>
<pre>
    <a href="#userEventHandler">userEventHandler</a> widget event-type time wx wy rx ry other
</pre>
<p>
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.
<p>
<h1><A NAME="addCallback">addCallback</A></h1>
<p>
Add a callback procedure to the callback list for
a widget.  If no callback name is given, "callback" is assumed.
<p>
Usage:
<p>
<pre>
        addCallback <procedure-name> [&lt;callback-name&gt;]
</pre>
<p>
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.
<p>
<h1><A NAME="deleteCallback">deleteCallback</A></h1>
<p>
Delete a callback procedure previously registered
for a widget.
<p>
Usage:
<p>
<pre>
        deleteCallback &lt;procedure-name&gt;
</pre>
<p>
<h1><A NAME="do_userproc">do_userproc (call)</A></h1>
<p>
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:
<p>
<pre>
        Argument        Replaced by
<p>
        $name             object name of widget
        $time             event->time
        $x                event->x
        $y                event->y
        $x_root           event->x_root
        $y_root           event->y_root
</pre>
<p>
The "user procedure" can be any server procedure.
<p>
<h1><A NAME="do_popup">do_popup</A></h1>
<p>
Popup a menu (or other spring loaded popup) at the location
of the event which triggered this action.
<p>
Usage:
<p>
<pre>
        popup(menu-name [xoffset [yoffset]])
</pre>
<p>
<h1><A NAME="do_popdown">do_popdown</A></h1>
<p>
Pop down a menu.
<p>
Usage:
<p>
<pre>
        popdown(menu-name)
</pre>
<p>
<h1><A NAME="set">set</A></h1>
<p>
Set a widget resource.
<p>
Usage:
<p>
<pre>
        set &lt;resource-name&gt; &lt;value&gt;
</pre>
<p>
<h1><A NAME="get">get</A></h1>
<p>
Get a widget resource value as a string.
<p>
Usage:
<p>
<pre>
        get &lt;resource-name&gt;
</pre>
<p>
<h1><A NAME="append">append</A></h1>
<p>
Append data to a text widget.
<p>
Usage:
<p>
<pre>
        append &lt;text&gt;
</pre>
<p>
<h1><A NAME="setList">setList</A></h1>
<p>
Set the item list of a list widget.
<p>
Usage:
<p>
<pre>
        setList list [resize]
</pre>
<p>
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).
<p>
<h1><A NAME="getItem">getItem</A></h1>
<p>
Get an item in a list widget.
<p>
Usage:
<p>
<pre>
        value = getItem itemno
</pre>
<p>
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.
<p>
<h1><A NAME="highlight">highlight</A></h1>
<p>
Highlight an item in a list widget.
<p>
Usage:
<p>
<pre>
        highlight itemno
</pre>
<p>
The indicated item of the list is highlighted as if the item had been
selected by the user.  Any previously highlighted item is unhighlighted.
<p>
<h1><A NAME="unhighlight">unhighlight</A></h1>
<p>
Unhighlight the currently highlighted item in a
list widget.
<p>
Usage:
<p>
<pre>
        unhighlight
</pre>
<p>
Any currently highlighted item in the list widget is unhighlighted.
<p>
<h1><A NAME="realize">realize</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        realize
</pre>
<p>
<h1><A NAME="unrealize">unrealize</A></h1>
<p>
Unrealize a widget.  This destroys the windows assigned
to a widget and all of its descendants.
<p>
Usage:
<p>
<pre>
        unrealize
</pre>
<p>
<h1><A NAME="isRealized">isRealized</A></h1>
<p>
Test whether a widget is realized.
<p>
Usage:
<p>
<pre>
        isRealized
</pre>
<p>
<h1><A NAME="map">map</A></h1>
<p>
Map a widget.
<p>
Usage:
<p>
<pre>
        map
</pre>
<p>
<h1><A NAME="unmap">unmap</A></h1>
<p>
Unmap a widget.
<p>
Usage:
<p>
<pre>
        unmap
</pre>
<p>
<h1><A NAME="manage">manage</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        manage child [child ...]
</pre>
<p>
This message should be sent to the geometry widget which is the parent
of the children.
<p>
<h1><A NAME="unmanage">unmanage</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        unmanage child [child ...]
</pre>
<p>
This message should be sent to the geometry widget which is the parent
of the children.
<p>
<h1><A NAME="popup">popup</A></h1>
<p>
Popup a shell widget.  If no grab is indicated the popup
can remain up while other windows accept input.
<p>
Usage:
<p>
<pre>
        popup [grab-kind]
</pre>
<p>
<h1><A NAME="popdown">popdown</A></h1>
<p>
Popdown a shell widget.
<p>
Usage:
<p>
<pre>
        popdown
</pre>
<p>
<h1><A NAME="popupSpringLoaded">popupSpringLoaded</A></h1>
<p>
Popup a shell widget, e.g., a popup menu.
This implies an exclusive grab.
<p>
Usage:
<p>
<pre>
        popupSpringLoaded
</pre>
<p>
<h1><A NAME="move">move</A></h1>
<p>
Move a widget to the given window relative coordinates.
<p>
Usage:
<p>
<pre>
        move &lt;x&gt; &lt;y&gt;
</pre>
<p>
<h1><A NAME="resize">resize</A></h1>
<p>
Resize a widget.
<p>
Usage:
<p>
<pre>
        resize &lt;width&gt; &lt;height&gt; &lt;border-width&gt;
</pre>
<p>
<h1><A NAME="configure">configure</A></h1>
<p>
Configure a widget, i.e., execute a simultaneous
move and resize.
<p>
Usage:
<p>
<pre>
        configure &lt;x&gt; &lt;y&gt; &lt;width&gt; &lt;height&gt; &lt;border-width&gt;
</pre>
<p>
<h1><A NAME="setSensitive">setSensitive</A></h1>
<p>
Set the sensitivity of a widget.
<p>
Usage:
<p>
<pre>
        setSensitive &lt;sensitive&gt;
</pre>
<p>
<h1><A NAME="isSensitive">isSensitive</A></h1>
<p>
Test the sensitivity of a widget.
<p>
Usage:
<p>
<pre>
        isSensitive
</pre>
<p>
<h1><A NAME="addEventHandler">addEventHandler</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        addEventHandler &lt;procname&gt; &lt;event-mask&gt; [&lt;event-mask&gt;...]
</pre>
<p>
<h1><A NAME="removeEventHandler">removeEventHandler</A></h1>
<p>
Remove an event handler previously posted
with addEventHandler, above.
<p>
Usage:
<p>
<pre>
        removeEventHandler procname
</pre>
<p>
<h1><A NAME="event">event</A></h1>
<p>
Generic event handler called when a widget event handler
posted by addEventHandler is called.
<p>
The user event handler is called as
<p>
<pre>
        userEventHandler widget event-type time wx wy rx ry other
</pre>
<p>
where "other" is an event-type specific list of fields describing the
the event.