STUB WIDGET(3W) — OLIT

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

Table 1 Stub Widget Resource Set
   Stub Resource Set
                Name            Type       Default Access XtNancestorSensitive         Boolean          TRUE       G
       XtNbackground           Pixel         White     SGI
XtNbackgroundPixmap          Pixmap        (none)     SGI
      XtNborderColor           Pixel         Black     SGI
      XtNborderWidth       Dimension             0     SGI
            XtNdepth             int    (parent’s)      GI
          XtNdestroy        Function          NULL     SGI
XtNdestroyCallback XtCallbackList          NULL       I
           XtNexpose        Function          NULL     SGI
    XtNgetValuesHook        Function          NULL     SGI
           XtNheight       Dimension             0     SGI
       XtNinitialize        Function     (private)      GI
   XtNinitializeHook        Function          NULL      GI XtNmappedWhenManaged         Boolean          TRUE     SGI
    XtNqueryGeometry        Function          NULL     SGI
          XtNrealize        Function     (private)     SGI
    XtNreferenceStub          Widget          NULL      GI
           XtNresize        Function          NULL     SGI
        XtNsensitive         Boolean          TRUE      GI
        XtNsetValues        Function          NULL     SGI
XtNsetValuesAlmost        Function (superclass)     SGI
    XtNsetValuesHook        Function          NULL     SGI
         XtNuserData       XtPointer          NULL     SGI
            XtNwidth       Dimension             0     SGI
           XtNwindow          Window          NULL      GI
                XtNx        Position             0     SGI
                XtNy        Position             0     SGI
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. 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 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

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

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

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