Stub(3W) UNIX System V Stub(3W)
NAME
Stub - used for widget prototyping
SYNOPSIS
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <Stub.h>
Widget parent, stub;
stub = XtCreateWidget(name, stubWidgetClass, ...);
DESCRIPTION
The Stub widget is essentially a method-driven widget that allows the
application to specify procedures at creation and/or XtSetValues() time
which normally are 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.
Build Unique Widgets within an application
By allowing the application to specify procedures outside the widget
class structure, applications can use the stub widget to build local
widgets without having to go 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 an existing Window
The Stub widget also allows the application to give widget functionality
to existing X windows. For example, if the application wanted to track
10/89 Page 1
Stub(3W) UNIX System V Stub(3W)
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 VIRTUAL KEYS/BUTTONS that apply to the particular use of
the Stub.
Display of Keyboard Mnemonic
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.
Display of Keyboard Accelerators
The Stub does not display the keyboard accelerator. If the Stub is the
child of a Caption widget, the Caption widget can be used 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 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.
____________________________________________________________________________________________
| Stub Resource Set |
|_______________________|_________________________|________________|______________|________|
|Name | Class | Type | Default | Access|
|_______________________|_________________________|________________|______________|________|
____________________________________________________________________________________________
XtNacceptFocusFunc XtCAcceptFocus XtRFunction NULL SGI
____________________________________________________________________________________________
XtNaccelerator XtCAccelerator String NULL SGI
____________________________________________________________________________________________
XtNacceleratorText XtCAcceleratorText String Dynamic SGI
____________________________________________________________________________________________
XtNactivatefunc XtCActivateFunc Function NULL SGI
____________________________________________________________________________________________
XtNancestorSensitive XtCSensitive Boolean TRUE G
____________________________________________________________________________________________
XtNbackground XtCBackground Pixel White SGI
____________________________________________________________________________________________
XtNbackgroundPixmap XtCBackgroundPixmap Pixmap (none) SGI
____________________________________________________________________________________________
XtNborderColor XtCBorderColor Pixel Black SGI
Page 2 10/89
Stub(3W) UNIX System V Stub(3W)
____________________________________________________________________________________________
| Stub Resource Set |
|_______________________|_________________________|________________|______________|________|
|Name | Class | Type | Default | Access|
|_______________________|_________________________|________________|______________|________|
____________________________________________________________________________________________
XtNborderWidth XtCBorderWidth Dimension 0 SGI
____________________________________________________________________________________________
XtNconsumeEvent XtCConsumeEvent XtCallbackList NULL SGI
____________________________________________________________________________________________
XtNdepth XtCDepth Cardinal (parent's) GI
____________________________________________________________________________________________
XtNdestroy XtCDestroy Function NULL SGI
____________________________________________________________________________________________
XtNdestroyCallback XtCDestroyCallback XtCallbackList NULL I
____________________________________________________________________________________________
XtNexpose XtCExpose Function NULL SGI
____________________________________________________________________________________________
XtNgetValuesHook XtCGetValuesHook Function NULL SGI
____________________________________________________________________________________________
XtNhighlightHandlerProc XtCHighlightHandler XtRFunction NULL SGI
____________________________________________________________________________________________
XtNinputFocusColor XtCInputFocusColor Pixel Black SGI
____________________________________________________________________________________________
XtNheight XtCHeight Dimension 0 SGI
____________________________________________________________________________________________
XtNinitialize XtCInitialize Function (private) GI
____________________________________________________________________________________________
XtNinitializeHook XtCInitializeHook Function NULL GI
____________________________________________________________________________________________
XtNmappedWhenManaged XtCMappedWhenManaged Boolean TRUE SGI
____________________________________________________________________________________________
XtNmnemonic XtCMnemonic unsigned char NULL SGI
____________________________________________________________________________________________
XtNqueryGeometry XtCQueryGeometry Function NULL SGI
____________________________________________________________________________________________
XtNrealize XtCRealize Function (private) SGI
____________________________________________________________________________________________
XtNreferenceName XtCReferenceName String NULL SGI
____________________________________________________________________________________________
XtNreferenceStub XtCReferenceStub Widget NULL GI
____________________________________________________________________________________________
XtNreferenceWidget XtCReferenceWidget Widget NULL SGI
____________________________________________________________________________________________
XtNregisterFocusFunc XtCRegisterFocus XtRFunction Null SGI
____________________________________________________________________________________________
XtNresize XtCResize Function NULL SGI
____________________________________________________________________________________________
XtNsensitive XtCSensitive Boolean TRUE GI
____________________________________________________________________________________________
XtNsetValues XtCSetValues Function NULL SGI
____________________________________________________________________________________________
10/89 Page 3
Stub(3W) UNIX System V Stub(3W)
____________________________________________________________________________________________
| Stub Resource Set |
|_______________________|_________________________|________________|______________|________|
|Name | Class | Type | Default | Access|
|_______________________|_________________________|________________|______________|________|
|XtNsetValuesAlmost | XtCSetValuesAlmost | Function | (superclass)| SGI |
|_______________________|_________________________|________________|______________|________|
|XtNsetValuesHook | XtCSetValuesHook | Function | NULL | SGI |
|_______________________|_________________________|________________|______________|________|
|XtNtraversalHandlerFunc| XtCTraversalHandlerFunc| Function | NULL | SGI |
|_______________________|_________________________|________________|______________|________|
|XtNtraversalOn | XtCTraversalOn | Boolean | FALSE | SGI |
|_______________________|_________________________|________________|______________|________|
|XtNuserData | XtCUserData | XtPointer | NULL | SGI |
|_______________________|_________________________|________________|______________|________|
|XtNwidth | XtCWidth | Dimension | 0 | SGI |
|_______________________|_________________________|________________|______________|________|
|XtNwindow | XtCWindow | Window | NULL | GI |
|_______________________|_________________________|________________|______________|________|
|XtNx | XtCPosition | Position | 0 | SGI |
|_______________________|_________________________|________________|______________|________|
|XtNy | XtCPosition | Position | 0 | SGI |
|_______________________|_________________________|________________|______________|________|
XtNacceptFocusFunc
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. Applications that want to override the default
accept focus procedure should use this function. 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
void activateProc(w, activation_type, data)
Widget w;
OlVirtualName activation_type;
XtPointer data;
This procedure is called whenever OlActivateWidget() is called with the
stub widget id for which this routine was assigned. The procedure has
the following declaration:
Boolean (*OlActivateFunc)(w, activationtype, data)
Widget w;
OlVirtualName activationtype;
XtPointer data;
Page 4 10/89
Stub(3W) UNIX System V Stub(3W)
If the activationtype is valid, the routine should take the appropriate
action and return TRUE; otherwise, the routine should return FALSE.
XtNdestroy
void destroy(w)
Widget w;
Specifies the procedure called when this stub instance is destroyed.
XtNexpose
void expose(w, xevent, region)
Widget w;
XEvent * xevent;
Region region;
Procedure called whenever the a stub instance receives an exposure event.
Since the Stub Widget class has requested exposure compression, the
region field is valid.
XtNgetValuesHook
void getValuesHook(w, args, num_args)
Widget w;
ArgList args;
Cardinal * num_args;
Procedure called whenever the application does an XtGetValues() call on a
stub widget instance.
XtNhighlightHandlerProc
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
void initialize(request, new)
Widget request;
Widget new;
Procedure called by XtCreateWidget() for a stub widget instance. 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
10/89 Page 5
Stub(3W) UNIX System V Stub(3W)
by the XtNwindow id.
XtNinitializeHook
void initializeHook(w, args, numargs)
Widget w;
ArgList args;
Cardinal * numargs;
This procedure is called by XtCreateWidget() for a stub widget instance
after the initialize procedure has been called. 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
void queryGeometry(w, request, preferred_return)
Widget w;
XtWidgetGeometry * request;
XtWidgetGeometry * preferred_return;
Procedure called whenever the application does an XtQueryGeometry()
request on a stub widget instance.
XtNrealize
void realize(w, valuemask, attributes)
Widget w;
XtValueMask * valuemask;
XSetWindowAttributes * attributes;
Procedure called to realize a stub widget instance. 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
This is a pointer 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.
Page 6 10/89
Stub(3W) UNIX System V Stub(3W)
XtNresize
void resize(w)
Widget w;
Procedure called whenever a stub widget instance is resized.
XtNregisterFocusFunc
This is a Stub Widget resource that points to a function of type
void (*OlRegisterFocusFunc)(w)
Widget w;
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, returning a widget id other than the stub widget's will not
move the focus away from the stub widget.
XtNsetValues
Boolean setValues(current, request, new)
Widget current;
Widget request;
Widget new;
Procedure called whenever the application does an XtSetValues() call on a
stub widget instance.
XtNsetValuesAlmost
void setValuesAlmost(w, newwidget, request, reply)
Widget w;
Widget newwidget;
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
Boolean setValuesHook(w, args, numargs)
Widget w;
ArgList args;
Cardinal * numargs;
This procedure is called whenever the application does an XtSetValues()
10/89 Page 7
Stub(3W) UNIX System V Stub(3W)
on a stub widget instance. 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
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 traveral 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.)
XtNwindow
This resource 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.
If the Stub widget is managed, the window ID supplied with
XtNwindow will be included in the geometry calculation
causing undesireable reconfiguration. This is an anomoly
that exists only with this resource.
Page 8 10/89
Stub(3W) UNIX System V Stub(3W)
XtNwidth
XtNheight
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 are NULL when the application attempts to realize the stub
widget, an error will result.
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() */
SEE ALSO
Input Focus for a discussion on keyboard focus manipulation
10/89 Page 9