realize()realize()Namerealize - Core class method to create a widget's window.
Synopsis
typedef void (*XtRealizeProc)(Widget, XtValueMask *,
XSetWindowAttributes *);
Widget w;
XtValueMask *value_mask;
XSetWindowAttributes *attributes;
Inputs
w Specifies the widget that is to have its window created.
value_mask
Specifies which fields in the attributes structure are set.
attributes
Specifies the window attributes derived from the widget
instance structure.
Description
The realize() method is registered on the realize field of the Core
class part structure. It is called when a widget is realized (gener‐
ally because an ancestor was realized with XtRealizeWidget()) and is
responsible for creating an X window for the widget.
The attributes argument points to an XSetWindowAttributes structure
that has been initialized by the Intrinsics, and value_mask points to a
set of flags that specify which fields have been initialized. The
XSetWindowAttributes structure is shown in the "Structures" section
below. The fields are initialized as follows:
· background_pixmap is set to the value of the widget's XtNbackground‐
Pixmap resource, or if this resource is unspecified, the back‐
ground_pixel field is set to the value of the widget's XtNbackground
resource.
· border_pixmap is set to the value of the widget's XtNborderPixmap
resource, or, if this resource is unspecified, the border_pixel
field is set to the value of the XtNborderColor resource.
· colormap is set to the value of the XtNcolormap resource of the wid‐
get.
· event_mask is set based on the event handlers registered for the
widget, the translations that are specified for the widget, whether
the widget has an expose() method, and whether the widget's visi‐
ble_interest field is True.
· bit_gravity is set to NorthWestGravity if the widget does not have
an expose() method.
The realize() method may set any other field in attributes as appropri‐
ate for the particular widget class (and its superclasses), and then
should create the widget's window by
calling XtCreateWindow(). This is a convenient procedure that automat‐
ically uses the correct parent, position, size, etc., from the widget's
instance record, and sets the created window in the widget's window
field. See XtCreateWindow(1) for more information.
The realize() method is not chained. A widget class that does not need
any special window attributes set should inherit the realize method
from its superclass by specifying XtInheritRealize on the realize field
of the Core class part structure. No widget should have a NULL real‐
ize() method.
Usage
Note that the value_mask argument to this method is a pointer to the
value mask, not the value mask itself. This is unusual, and you should
be careful to correctly de-reference this argument when using it.
The realize() method defined for Core calls XtCreateWindow() with the
passed value_mask and attributes and with the windowClass and visual
arguments set to CopyFromParent. This is sufficient for most widgets;
both Composite and Constraint inherit it, and most new widget sub‐
classes can do the same.
A common reason to write a custom realize() method is to set the
bit_gravity window attribute to something other than its default value.
A label widget might set bit gravity depending on the justification of
the label, for example, and thereby avoid some expose events when the
widget was resized. If a widget uses the Shape extension to obtain a
non-rectangular window, the window should be re-shaped in the realize()
method. (The Xaw Command widget does this.) A composite widget can
control the stacking order of its children by explicitly realizing them
in the desired order from within its own realize() method. Also, a
non-composite widget that creates its own private children widgets must
explicitly realize them from the realize() method.
Custom realize() methods usually explicitly call the realize() method
of their superclass. The superclass's method may have inherited the
Core realize() method and create the window, or it may set its own
fields in attributes and invoke the method of its superclass. Eventu‐
ally a method will be called that actually creates the window and
returns. "Enveloping" the realize() method in this way creates a kind
of subclass-to-superclass chaining. When you envelop a method of your
superclass, use the superclass pointer directly, do not use XtSuper‐
class() to obtain the superclass of the supplied widget instance. If B
is a subclass of A, for example, then the widget passed to B's real‐
ize() method may be of class B, or may be of some subclass C of B. If
you call XtSuperclass() on this widget, you will get class B rather
than class A, and the realize() method will recursively call itself and
loop until it runs out of stack space and crashes.
Example
The following procedures are the realize() methods from the X11R5 Xaw
Command and Panner widgets. The first simply calls its superclass's
method to create the window, and then uses the Shape extension to
change the window's shape. The second procedure sets a background
pixmap for the window, even if the core XtNbackgroundPixmap resource is
unspecified, and then calls its superclass's method.
Note that the first procedure finds its superclass's method by going
through its own class pointer directly. The second procedure envelops
the superclass method incorrectly, using the instance pointer. A sub‐
class of this widget that inherited this method would crash when real‐
ized, as described in the section above.
static void Realize(w, valueMask, attributes)
Widget w;
Mask *valueMask;
XSetWindowAttributes *attributes;
{
(*commandWidgetClass->core_class.superclass->core_class.realize)
(w, valueMask, attributes);
ShapeButton( (CommandWidget) w, FALSE);
}
static void Realize (gw, valuemaskp, attr)
Widget gw;
XtValueMask *valuemaskp;
XSetWindowAttributes *attr;
{
PannerWidget pw = (PannerWidget) gw;
Pixmap pm = XtUnspecifiedPixmap;
Boolean gotpm = FALSE;
if (pw->core.background_pixmap == XtUnspecifiedPixmap) {
if (pw->panner.stipple_name) pm = BACKGROUND_STIPPLE (pw);
if (PIXMAP_OKAY(pm)) {
attr->background_pixmap = pm;
*valuemaskp = CWBackPixmap;
*valuemaskp &= ~CWBackPixel;
gotpm = TRUE;
}
}
(*gw->core.widget_class->core_class.superclass->core_class.realize)
(gw, valuemaskp, attr);
if (gotpm) XFreePixmap (XtDisplay(gw), pm);
}
Structures
The XSetWindowAttributes structure, the XtValueMask type, and the flags
that can be set in this type are defined as follows:
typedef struct {
Pixmap background_pixmap;/* background or None or ParentRelative * /
unsigned long background_pixel;/* background pixel */
Pixmap border_pixmap;/* border of the window */
unsigned long border_pixel;/* border pixel value */
int bit_gravity; /* one of bit gravity values */
int win_gravity; /* one of the window gravity values */
int backing_store; /* NotUseful, WhenMapped, Always */
unsigned long backing_planes;/* planes to be preserved if possible */
unsigned long backing_pixel;/* value to use in restoring planes */
Bool save_under; /* should bits under be saved (popups) */
long event_mask; /* set of events that should be saved */
long do_not_propagate_mask;/* set of events that shouldn't propagate */
Bool override_redirect;/* boolean value for override-redirect */
Colormap colormap; /* colormap to be associated with window */
Cursor cursor; /* cursor to be displayed (or None) */
} XSetWindowAttributes;
typedef unsigned long XtValueMask;
#define CWBackPixmap (1L<<0)
#define CWBackPixel (1L<<1)
#define CWBorderPixmap (1L<<2)
#define CWBorderPixel (1L<<3)
#define CWBitGravity (1L<<4)
#define CWWinGravity (1L<<5)
#define CWBackingStore (1L<<6)
#define CWBackingPlanes (1L<<7)
#define CWBackingPixel (1L<<8)
#define CWOverrideRedirect (1L<<9)
#define CWSaveUnder (1L<<10)
#define CWEventMask (1L<<11)
#define CWDontPropagate (1L<<12)
#define CWColormap (1L<<13)
#define CWCursor (1L<<14)
See AlsoXtCreateWindow(1), XtRealizeWidget(1),
Core(3).
Xt - Intrinsics Methods realize()
