'\"!  tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | tbl | tbl | tbl | tbl | mmdoc
'\"macro stdmacro
.if n .pH g3w.olStub @(#)olStub	40.2 of 1/8/90
.ig
Modified 10/23/89 by lmh
..
.nr X
.if \nX=0 .ds x} ""STUB WIDGET" 3W "\&"
.if \nX=1 .ds x} ""STUB WIDGET" 3W
.if \nX=2 .ds x} ""STUB WIDGET" "" "\&"
.if \nX=3 .ds x} ""STUB "" "" "\&"
.TH \*(x}
.SH "WIDGET CLASS NAME"
.PP
\fBStub\fP
.SH SYNOPSIS
.DS 
.nf
\fB#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <Stub.h>
.fi
.DE

.DS L N
.ft CW
Widget parent;
Widget stub;

stub = XtCreateWidget(\fIname\fP, stubWidgetClass, ...);
.ft P
.DE
.SH DESCRIPTION
.sp
The \fBStub\fP widget is essentially a method-driven widget that allows
the application to specify procedures at creation and/or \f4XtSetValues()\f1 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.
.sp
\fBBuild Unique Widgets within an application\fP
.PP
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.
.sp
\fBGraphics Applications\fP
.P
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 \f4region\fP 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.
.sp
\fBInheriting Procedures from Existing Widgets\fP
.P
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.
.bp
\fBWrapping Widgets around an existing Window\fP
.P
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.
.SH RESOURCES
.sp
The following table lists the resources available to the stub widget.
.sp
.TS H
expand center allbox;
cb s s s s
lbp-2|lbp-2|lbp-2|lbp-2|lbp-2
lp-2|lp-2|lp-2|lp-2|lp-2.
Stub Resource Set
Name	Class	Type	Default	Access
_
.TH
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
.TE
.bp 
\fBXtNdestroy\fP
.sp
.ft CW
void \fIdestroy\fP(w)
Widget w;\f1
.sp
Specifies the procedure called when this stub instance is destroyed.
.sp
\fBXtNexpose\fP
.DS
.ft CW
.nf

void \fIexpose\fP(w, xevent, region)
Widget w;
XEvent * xevent;
Region region; \f1
.fi
.DE
.sp
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.
.sp
\fBXtNgetValuesHook\fP
.DS
.ft CW
.nf

void \fIgetValuesHook\fP(w, args, num_args)
Widget w;
ArgList args;
Cardinal * num_args; \f1
.fi
.DE
.sp
Procedure called whenever the application does an 
\f4XtGetValues()\f1 call on a stub widget instance.
.sp
\fBXtNinitialize\fP
.DS
.ft CW
.nf

void \fIinitialize\fP(request, new)
Widget request;
Widget new; \f1
.fi
.DE
.sp
Procedure called by \f4XtCreateWidget()\f1 for a 
stub widget instance.  The
default initialize procedure knows how to deal with the \f4XtNwindow\f1
resource (see the section on \f4XtNwindow\f1).  If the application 
supplies its own
initialize procedure, it's the application's responsibility to deal with
the \f4XtNwindow\f1 resource.
.P
When the \f4XtNwindow\f1 resource is non-NULL, the default initialize
procedure fills in \f4XtNx, XtNy, XtNwidth\f1 and\f4 XtNheight\f1 with the
attributes specified by the \f4XtNwindow\f1 id.
.sp
\fBXtNinitializeHook\fP
.DS
.ft CW
.nf

void \fIinitializeHook\fP(w, args, num_args)
Widget w;
ArgList args;
Cardinal * num_args; \f1
.fi
.DE
.sp
This procedure is called by \f4XtCreateWidget()\f1 for a stub widget instance after
the \fIinitialize\fP procedure has been called.  The application can access the
creation arg list through this routine.  The widget specified with the
\f4w\f1 argument
is the \fBnew\fP widget from the \fIinitialize\fP procedure.
.sp
\fBXtNqueryGeometry\fP
.DS
.ft CW
.nf

void \fIqueryGeometry\fP(w, request, preferred_return)
Widget w;
XtWidgetGeometry * request;
XtWidgetGeometry * preferred_return; \f1
.fi
.DE
.sp
Procedure called whenever the application does an 
\f4XtQueryGeometry()\f1 request on a stub widget instance.
.sp
\fBXtNrealize\fP
.DS
.ft CW
.nf

void \fIrealize\fP(w, value_mask, attributes)
Widget w;
XtValueMask * value_mask;
XSetWindowAttributes * attributes; \f1
.fi
.DE
.sp
Procedure called to realize a stub widget instance.  The default
realize procedure knows how to deal with the \f4XtNwindow\f1 resource (see
the section on \f4XtNwindow\f1).  If the application supplies its own
realize procedure, it's the application's responsibility to deal with
the \f4XtNwindow\f1 resource.
.PP
When \f4XtNwindow\f1 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.
.sp
\f3XtNreferenceStub\fP
.sp
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 \f4XtSetValues\f1 request on the 
new Stub widget
should be used to change any inherited methods.
.sp
\fBXtNresize\fP
.DS
.ft CW
.nf

void \fIresize\fP(w)
Widget w; \f1
.fi
.DE
.sp
Procedure called whenever a stub widget instance is resized.
.sp
\fBXtNsetValues\fP
.DS
.ft CW
.nf

Boolean \fIsetValues\fP(current, request, new)
Widget current;
Widget request;
Widget new; \f1
.fi
.DE
.sp
Procedure called whenever the application does an \f4XtSetValues()\f1 call
on a stub widget instance.
.sp
\fBXtNsetValuesAlmost\fP
.DS
.ft CW
.nf

void \fIsetValuesAlmost\fP(w, new_widget, request, reply)
Widget w;
Widget new_widget;
XtWidgetGeometry * request;
XtWidgetGeometry * reply; \f1
.fi
.DE
.sp
This procedure is called when the application attempts to set a stub
widget's geometry via an \f4XtSetValues()\f1 call and the stub widget's
parent did not accept the requested geometry.  The default
\f4setValuesAlmost\f1 procedure simply accepts the suggested compromise.
.sp
\fBXtNsetValuesHook\fP
.DS
.ft CW
.nf

Boolean \fIsetValuesHook\fP(w, args, num_args)
Widget w;
ArgList args;
Cardinal * num_args; \f1
.fi
.DE
.sp
This procedure is called whenever the application does an
\f4XtSetValues()\f1 on a stub widget instance.  Since this 
procedure is called after the \fIsetValues\fP procedure,
the widget specified by the \f4w\f1 argument
is the \fBnew\fP widget from the \fIsetValues\fP procedure.
.sp
\fBXtNwindow\fP
.PP
This resource specifies a window id that the Stub widget should
associate with its instance data at realization time.
The \f4XtNwindow\f1 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 \f4XtWindow()\f1 will
return this window id.
.PP
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 \f4XtMoveWidget\f1,
\f4XtResizeWidget\f1, \f4XtConfigureWidget\f1, 
or \f4XtSetValues\f1 can be used to
modify the window's attributes.
.IP "\f(HBWarning:\f1" 15
When the stub widget instance is destroyed, the window will be
destroyed along with it.
.in
.bp
\fBXtNwidth 
.br
XtNheight\fP
.PP
If \f4XtNwindow\f1 has a NULL value, the application
must insure that the dimensions of \f4XtNwidth\f1 and \f4XtNheight\f1 are non-NULL.
The application can specify the width and height with an Arg list
or specify an \fIinitialize\fP 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.
.SH EXAMPLE
The following example illustrates how an application can use the stub
widget to perform some particular type of exposure handling.  Since
an \fIinitialize\fP procedure was not specified and the \f4XtNwindow\f1 resource
was not used,
the initial Arg list includes non-NULL values for the widget's width and height.

.sp 2
.DS CB N
.nf
.ft CW
.ta 0.5i 1i 1.5i 2i
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() */
.fi
.ft P
.DT
.DE
