NAME

Stub − widget for widget prototyping

SYNOPSIS

#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/Stub.h>
 . . .
Widget my_stub, my_parent;
String my_name;
ArgList args;
Cardinal num_args;

my_stub =  XtCreate( my_name, stubWidgetClass,

my_parent, args, num_args);

DESCRIPTION

The Stub widget is a method-driven widget that allows the application to specify procedures at creation and/or XtSetValues() time which are normally restricted to a widget’s class part. 

Most class part procedures have been attached to the instance part.  For example, with the stub widget, it’s possible to set the procedure that’s called whenever an exposure occurs.  It’s also possible to set the SetValues and Initialize procedures. 

Local Widgets

By allowing the application to specify procedures outside the widget class structure, applications can use the Stub widget to build local widgets without having going through the formal steps.  For example, suppose an application wanted to create a menu separator widget that inherits its parent’s background color at creation time.  It would be wasteful to create a new widget to perform these trivial tasks.  Instead, the application would use a Stub widget and specify an Initialize procedure for it. 

Graphics Applications

The stub widget also implements graphics applications.  Since the application has direct access to the widget’s internal expose procedure, the application can take advantage of the exposure compression provided with the region argument.  This field is not accessible if the application used an Event Handler to trap exposures.  Also, since the application has access to the SetValues and SetValuesHook procedures, the application can programmatically modify graphic-related resources of the stub widget. 

Inheriting Procedures from Existing Widgets

Once a stub widget is created, other stub widgets can inherit its methods without the application having to specify them again.  All the application has to do is specify a reference stub widget in the creation Arg list and the new stub widget will inherit all instance methods from the referenced stub widget. 

Wrapping Widgets Around existing Windows

The Stub widget also allows the application to give widget functionality to existing X windows.  For example, if the application wanted to track button presses on the root window, the application would create a Stub widget using the RootWindow id as the XtNwindow resource.  Once this has been done, the application can monitor events on the root window by attaching event handlers to the Stub widget. 

Keyboard Traversal

The Stub is a Primitive widget and it inherits the translations for traversal actions from the Primitive class.  The user of a Stub widget should add translations for dealing with the navigation events listed in the section of virtualevents(3w) that apply to the particular use of the Stub. 

Keyboard Mnemonic Display

The Stub does not display the mnemonic accelerator.  If the Stub is the child of a Caption widget, the Caption widget can be used to display the Stub’s
 mnemonic.

Keyboard Accelerators Display

The Stub does not display the keyboard accelerator.  If the Stub is the child of a Caption widget, to display the Stub’s accelerator as part of the label. 

Coloration

The Stub widget should display a state which indicates that it has input focus.  The general heuristic used for this display in OPEN LOOK widgets is that the background color is replaced with the input focus color found in the resource XtNinputFocusColor. 

RESOURCES

The following table lists the resources available to the stub widget. 

  Table 1 Stub Widget Resource Set

Stub                    Resource       Set
Name                    Type           Default             Access
 
XtNacceptFocusFunc      XtRFunction    NULL                SGI
XtNaccelerator          String         NULL                SGI
XtNacceleratorText      String         Dynamic             SGI
XtNactivateFunc         Function       NULL                SGI
XtNancestorSensitive    Boolean        TRUE                G
XtNbackground           Pixel          XtDefaultBackground SGI
XtNbackgroundPixmap     Pixmap         (none)              SGI
XtNborderColor          Pixel          XtDefaultForeground SGI
XtNborderWidth          Dimension      0                   SGI
XtNconsumeEvent         XtCallbackList NULL                SGI
XtNdepth                Cardinal       (parent’s)          GI
XtNdestroy              Function       NULL                SGI
XtNdestroyCallback      XtCallbackList NULL                I
XtNexpose               Function       NULL                SGI
XtNgetValuesHook        Function       NULL                SGI
XtNheight               Dimension      0                   SGI
XtNhighlightHandlerProc XtRFunction    NULL                SGI
XtNinitialize           Function       (private)           GI
XtNinitializeHook       Function       NULL                GI
XtNinputFocusColor      Pixel          Red                 SGI
XtNmappedWhenManaged    Boolean        TRUE                SGI
XtNmnemonic             unsigned       char                NULL
XtNqueryGeometry        Function       NULL                SGI
XtNrealize              Function       (private)           SGI
XtNreferenceName        String         NULL                SGI
XtNreferenceStub        Widget         NULL                GI
XtNreferenceWidget      Widget         NULL                SGI
XtNregisterFocusFunc    XtRFunction    Null                SGI
XtNresize               Function       NULL                SGI
XtNsensitive            Boolean        TRUE                GI
XtNsetValues            Function       NULL                SGI
XtNsetValuesAlmost      Function       (superclass)        SGI
XtNsetValuesHook        Function       NULL                SGI
XtNtraversalHandlerFunc Function       NULL                SGI
XtNtraversalOn          Boolean        FALSE               SGI
XtNuserData             XtPointer      NULL                SGI
XtNwidth                Dimension      0                   SGI
XtNwindow               Window         NULL                GI
XtNx                    Position       0                   SGI
XtNy                    Position       0                   SGI

Stub                    Resource  Set
Name                    Type      Default Access
=
XtNsetValuesHook        Function  NULL    SGI
_
XtNtraversalHandlerFunc Function  NULL    SGI
_
XtNtraversalOn          Boolean   FALSE   SGI
_
XtNuserData             XtPointer NULL    SGI
_
XtNwidth                Dimension 0       SGI
_
XtNwindow               Window    NULL    GI
_
XtNx                    Position  0       SGI
_
XtNy                    Position  0       SGI

Access:S = XtSetValues G = XtGetValues
        I = init timeO = other access
† see resources(3W)

XtNacceptFocusFunc

class:XtCAcceptFocus type:XtRFunction default:NULLaccess:SGI

Action: allows applications to override the default accept focus procedure. 

This procedure has the same semantics as the XtAcceptFocusFunc Core Widget Class procedure and it’s called by the Stub Widget Class’s accept focus class procedure.  When overriding the default accept focus procedure, the convenience routine OlCanAcceptFocus() can be used to check the widget’s focus-taking eligibility.  OlSetInputFocus should be used instead of XSetInputFocus when explicitly setting focus to a window.  (See the section "Input Focus" for more on setting and accepting focus.) 

XtNactivateFunc

class:XtCActivateFunc type:Function default:NULLaccess:SGI void         Widget         w;        OlVirtualName  activation_type;        XtPointer      data;This procedure is called whenever with the stub widget id for which this routine was assigned.  Theprocedure has the following declaration:    Boolean (∗        Widget         w;        OlVirtualName  activation_type;        XtPointer      data;If the appropriate action and return TRUE; otherwise, the routine shouldreturn FALSE.class:XtCDestroy type:Function default:NULLaccess:SGI

Action: specifies the procedure called when this stub instance is destroyed. 

void destroy(Widget w)

XtNexpose

class:XtCExpose type:Function default:NULLaccess:SGI

Action: specifies the procedure called when the a stub instance receives an exposure event. 

void expose(w, xevent, region)

Widget w;
XEvent ∗ xevent;
Region region;

Since the Stub Widget class has requested exposure compression, the region field is valid. 

XtNgetValuesHook

class:XtCGetValuesHook type:Function default:NULLaccess:SGI

Action: specifies the procedure called whenever the application does an XtGetValues() call on a stub widget instance. 

void getValuesHook(w, args, num_args)

Widget w;
ArgList args;
Cardinal ∗ num_args;

XtNheight

class:XtCHeight type:Dimension default:0access:SGI

Action: specifies the height

If XtNwindow has a NULL value, the application must insure that the dimensions of XtNwidth and XtNheight are non-NULL.  The application can specify the width and height with an Arg list or specify an initialize procedure that sets them with non-NULL values. If either of these dimensions is NULL when the application attempts to realize the stub widget, an error will result.

XtNhighlightHandlerProc

class:XtCHighlightHandler type:XtRFunction default:NULLaccess:SGI

Action: allows Stub widget to display visual

This procedure has the same semantics as the OlHighlightProc class procedure and it is called by the Stub Widget Class’s HighlightProc class procedure.  Applications that have Stub widgets which accept focus should set this routine so that the Stub widget can display an appropriate visual whenever it gains or loses focus. 

XtNinitialize

class:XtCInitialize type:Function default:(private)access:GI

Action: specifies the procedure called by XtCreateWidget() for a stub widget instance. 

void initialize(request, new)

Widget request;
Widget new;

The default initialize procedure knows how to deal with the XtNwindow resource (see the section on XtNwindow).  If the application supplies its own initialize procedure, it’s the application’s responsibility to deal with the XtNwindow resource.  When the XtNwindow resource is non-NULL, the default initialize procedure fills in XtNx, XtNy, XtNwidth and XtNheight with the attributes specified by the XtNwindow id. 

XtNinitializeHook

class:XtCInitializeHook type:Function default:NULLaccess:GI

Action: specifies the procedure called by XtCreateWidget() for a stub widget instance after the initialize procedure has been called. 

void initializeHook(w, args, num_args)

Widget w;
ArgList args;
Cardinal ∗ num_args;

The application can access the creation arg list through this routine.  The widget specified with the w argument is the new widget from the initialize procedure. 

XtNqueryGeometry

class:XtCQueryGeometry type:Function default:NULLaccess:SGI

Action: specifies the procedure called whenever the application does an XtQueryGeometry() request on a stub widget instance. 

void queryGeometry(w, request, preferred_return)

Widget w;
XtWidgetGeometry ∗ request;
XtWidgetGeometry ∗ preferred_return;

XtNrealize

class:XtCRealize type:Function default:(private)access:SGI

Action: specifies procedure called to realize a stub widget instance. 

void realize(w, value_mask, attributes)

Widget w;
XtValueMask ∗ value_mask;
XSetWindowAttributes ∗ attributes;

The default realize procedure knows how to deal with the XtNwindow resource (see the section on XtNwindow). 

If the application supplies its own realize procedure, it’s the application’s responsibility to deal with the XtNwindow resource.  When XtNwindow is non-NULL, the realize procedure uses this window for the widget instance instead of creating a new window.  The default realize procedure gives an error message if another widget in its process space is referencing the window already.  Note, the default realize procedure does not reparent the specified window, if one is supplied. 

XtNreferenceStub

class:XtCReferenceStub type:Widget default:NULLaccess:GI

Action: points to an existing Stub widget. 

If this pointer is non-NULL, the new Stub will inherit all instance methods from the referenced stub widget.  An XtSetValues request on the new Stub widget should be used to change any inherited methods. 

XtNresize

class:XtCResize type:Function default:NULLaccess:SGI

Action: specifies the procedure called whenever a stub widget instance is resized. 

void resize(w)

Widget w;

XtNregisterFocusFunc

class:XtCRegisterFocus type:XtRFunction default:Nullaccess:SGI

Action: sets the current focus widget

Whenever a stub widget gains focus, this procedure is called and the stub’s shell sets the "current focus widget" (see OlGetCurrentFocusWidget) to the value returned by it.  If this function is NULL or returns NULL, the stub widget is set to the current focus widget.  This is the typical case.  If this procedure returns a widget id other than the stub widget’s, that id is used to update the current focus widget so that a subsequent call to OlGetCurrentFocusWidget would return it.  Note that returning a widget id other than the stub widgets’ will not move the focus away from the stub widget. 

XtNsetValues

class:XtCSetValues type:Function default:NULLaccess:SGI

Action: specifies the procedure called whenever the application does an XtSetValues() call on a stub widget instance. 

Boolean setValues(current, request, new)

Widget current;
Widget request;
Widget new;

XtNsetValuesAlmost

class:XtCSetValuesAlmost type:Function default:(superclass)access:SGI

Action: spefies procedure called when parent rejects requested geometry. 

void setValuesAlmost(w, new_widget, request, reply)

Widget w;
Widget new_widget;
XtWidgetGeometry ∗ request;
XtWidgetGeometry ∗ reply;

This procedure is called when the application attempts to set a stub widget’s geometry via an XtSetValues() call and the stub widget’s parent did not accept the requested geometry.  The default setValuesAlmost procedure simply accepts the suggested compromise. 

XtNsetValuesHook

class:XtCSetValuesHook type:Function default:NULLaccess:SGI

Action: specifies procedure called whenever the application does an XtSetValues() on a stub widget instance

Boolean setValuesHook(w, args, num_args)

Widget w;
ArgList args;
Cardinal ∗ num_args;

Since this procedure is called after the setValues procedure, the widget specified by the w argument is the new widget from the setValues procedure. 

XtNtraversalHandlerFunc

class:XtCTraversalHandlerFunc type:Function default:NULLaccess:SGI

Action: supplies traversal routine. 

If an application wants the stub widget to process traversal commands whenever the stub widget has focus, this resource is used to supply the traversal routine.  An example of a case when this is desirable is when a stub widget is used to implement a spread-sheet.  In this case, the stub widget would trap the OL_MOVERIGHT , OL_MOVELEFT , etc.  commands to move focus between the cells in the spread-sheet.  The traversal handling routine has the following declaration:

Widget (∗OLTraversalFunc)(w, start, direction, time)

Widget         w;          /∗ Stub widget id ∗/
Widget         start;      /∗ Stub widget id ∗/
OlVirtualName  direction;
Time           time;

If the traversal routine can process the traversal command, it returns the id of the widget which now has focus. 
Note: the widget id returned can be the stub widget’s id.  This is the case when the traversal command was processed, but focus did not leave the stub widget. 

If the traversal routine cannot process the given command, it should return NULL (see the section Input Focus for a discussion on valid direction values and focus movement). 

XtNwidth

class:XtCWidth type:Dimension default:0access:SGI

Action: specifies the width

If XtNwindow has a NULL value, the application must insure that the dimensions of XtNwidth and XtNheight are non-NULL.  The application can specify the width and height with an Arg list or specify an initialize procedure that sets them with non-NULL values. If either of these dimensions is NULL when the application attempts to realize the stub widget, an error will result.

XtNwindow

class:XtCWindow type:Window default:NULLaccess:GI

Action: specifies a window id that the Stub widget should associate with its instance data at realization time. 

The XtNwindow resource can be specified at initialization time only.  If a window id is supplied, that stub widget instance will trap events on the given window.  After the stub widget instance is realized, the function XtWindow() will return this window id.  If the stub widget is managed by its parent widget, the supplied window will be included in geometry calculations even though the stub widget (by default) does not reparent the supplied window to be a child of the parent widget’s window.  Explicit calls to XtMoveWidget, XtResizeWidget, XtConfigureWidget, or XtSetValues can be used to modify the window’s attributes. 

Warning: When the stub widget instance is destroyed, the window will be destroyed along with it. 

EXAMPLE

The following example illustrates how an application can use the stub widget to perform some particular type of exposure handling.  Since an initialize procedure was not specified and the XtNwindow resource was not used, the initial Arg list includes non-NULL values for the widget’s width and height. 

static void
Redisplay(w, xevent, region)
Widget    w;
XEvent ∗  xevent;
Region  region;
{
/∗
∗ do something interesting here
∗/
} /∗ END OF Redisplay() ∗/
 main(...)
{
Widget     base;
Widget     stub;
static Arg args[] = {
{ XtNexpose,   (XtArgVal) Redisplay },
{ XtNwidth,    (XtArgVal) 1 },
{ XtNheight,   (XtArgVal) 1 }
};
 base = OlInitialize(...);
 stub = XtCreateManagedWidget("graphics pane", stubWidgetClass,
base, args, XtNumber(args));
 .......
 } /∗ END OF main() ∗/

Version 3.0  —  Last change: 19 July 91  —  Last change: 19 July 91