WIDGET CLASS NAME

Stub

SYNOPSIS

#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <Stub.h>

Widget parent; Widget 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 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 Set-ValuesHook 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.

Amiga Unix                Last change:                          1

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 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.

RESOURCES

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

______________________________________________________________________________________
__________________________________Stub_Resource_Set___________________________________
 Name                   Class                  Type             Default        Access
______________________________________________________________________________________

Amiga Unix                Last change:                          2
()                MISC. REFERENCE MANUAL PAGES                 ()

     ______________________________________________________________________________________
     _XtNancestorSensitive___XtCSensitive___________Boolean__________TRUE___________G______
      XtNbackground          XtCBackground          Pixel            White          SGI
     ______________________________________________________________________________________
     _XtNbackgroundPixmap____XtCBackgroundPixmap____Pixmap___________(none)_________SGI____
      XtNborderColor         XtCBorderColor         Pixel            Black          SGI
     ______________________________________________________________________________________
     _XtNborderWidth_________XtCBorderWidth_________Dimension________0______________SGI____
      XtNdepth               XtCDepth               int              (parent's)     GI
     ______________________________________________________________________________________
     _XtNdestroy_____________XtCDestroy_____________Function_________NULL___________SGI____
      XtNdestroyCallback     XtCDestroyCallback     XtCallbackList   NULL           I
     ______________________________________________________________________________________
     _XtNexpose______________XtCExpose______________Function_________NULL___________SGI____
    | XtNgetValuesHook       XtCGetValuesHook       Function         NULL           SGI   |
    |_____________________|______________________|________________|______________|________|
    |_XtNheight___________|__XtCHeight___________|__Dimension_____|__0___________|__SGI___|
    | XtNinitialize       |  XtCInitialize       |  Function      |  (private)   |  GI    |
    |_____________________|______________________|________________|______________|________|
    |_XtNinitializeHook___|__XtCInitializeHook___|__Function______|__NULL________|__GI____|
    | XtNmappedWhenManaged|  XtCMappedWhenManaged|  Boolean       |  TRUE        |  SGI   |
    |_____________________|______________________|________________|______________|________|
    |_XtNqueryGeometry____|__XtCQueryGeometry____|__Function______|__NULL________|__SGI___|
    | XtNrealize          |  XtCRealize          |  Function      |  (private)   |  SGI   |
    |_____________________|______________________|________________|______________|________|
    |_XtNreferenceStub____|__XtCReferenceStub____|__Widget________|__NULL________|__GI____|
    | XtNresize           |  XtCResize           |  Function      |  NULL        |  SGI   |
    |_____________________|______________________|________________|______________|________|
    |_XtNsensitive________|__XtCSensitive________|__Boolean_______|__TRUE________|__GI____|
    | XtNsetValues        |  XtCSetValues        |  Function      |  NULL        |  SGI   |
    |_____________________|______________________|________________|______________|________|
    |_XtNsetValuesAlmost__|__XtCSetValuesAlmost__|__Function______|__(superclass)|__SGI___|
    | XtNsetValuesHook    |  XtCSetValuesHook    |  Function      |  NULL        |  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___|

Amiga Unix                Last change:                          1
()                MISC. REFERENCE MANUAL PAGES                 ()

     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 XtGet-Values() call on a stub widget instance.

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 by the XtNwindow id.

     XtNinitializeHook

     void initializeHook(w, args, num_args)
     Widget w;
     ArgList args;
     Cardinal * num_args;

     This procedure is called  by  XtCreateWidget()  for  a  stub

Amiga Unix                Last change:                          2
()                MISC. REFERENCE MANUAL PAGES                 ()

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, value_mask, attributes)
Widget w;
XtValueMask * value_mask;
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.

XtNresize

void resize(w)
Widget w;

Procedure called whenever a stub widget instance is resized.

     XtNsetValues

Amiga Unix                Last change:                          3
()                MISC. REFERENCE MANUAL PAGES                 ()

     Boolean setValues(current, request, new)
     Widget current;
     Widget request;
     Widget new;

Procedure called whenever the application does an XtSet-Values() call on a stub widget instance.

XtNsetValuesAlmost

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

Boolean setValuesHook(w, args, num_args)
Widget w;
ArgList args;
Cardinal * num_args;

This procedure is called whenever the application does an XtSetValues() 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 set-Values procedure.

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.

Amiga Unix                Last change:                          4
()                MISC. REFERENCE MANUAL PAGES                 ()

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

Amiga Unix                Last change:                          5
()                MISC. REFERENCE MANUAL PAGES                 ()

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() */

Amiga Unix                Last change:                          6