STUB WIDGET(3W) MISC. REFERENCE MANUAL PAGES STUB WIDGET(3W)
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 graph-
ics 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
STUB WIDGET(3W) MISC. REFERENCE MANUAL PAGES STUB WIDGET(3W)
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 applica-
tion 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 XtNwin-
dow). If the application supplies its own initialize pro-
cedure, 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 argu-
ment 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 XtQuer-
yGeometry() 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 XtNwin-
dow resource (see the section on XtNwindow). If the appli-
cation 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 mes-
sage 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 pro-
cedure 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 sup-
plied 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, XtConfi-
gureWidget, 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