realize(3x) — HPUX 9.05

NAME

realize − Core class method to create a widget’s window.

Synopsis

typedef void (*XtRealizeProc)(Widget, XtValueMask *, XSetWindowAttributes *);

    Widget w;
    XtValueMask *value_mask;
    XSetWindowAttributes *attributes;

Inputs

wSpecifies 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 (generally 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 XtNbackgroundPixmap resource, or if this resource is unspecified, the background_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 widget.

•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 visible_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 appropriate 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 automatically 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 realize() 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 subclasses 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. Eventually 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. Note that when you envelop a method of your superclass, use the superclass pointer directly, do not use XtSuperclass() 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 realize() 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 subclass of this widget that inherited this method would crash when realized, 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 should not 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)

Museum

Related Articles