2.4. Realizing Widgets   

To realize a widget instance, use XtRealizeWidget.

    void XtRealizeWidget(w)

          Widget w;

         w Specifies the widget.  Must be of class Core or any subclass thereof.

Binds all action names in the widget's translation table to procedures.

Makes a postorder traversal of the widget tree rooted at the specified widget and calls each non-NULL change_managed procedure of all composite widgets that have one or more managed children.

Constructs an XSetWindowAttributes structure filled in with information derived from the Core widget fields and calls the realize procedure for the widget, which adds any widget-specific attributes and creates the X window.

If the widget is not a subclass of compositeWidgetClass, XtRealizeWidget returns; otherwise it continues and performs the following:

             Descends recursively to  each  of  the  widget's

          managed  children and calls the realize procedures.

          Primitive widgets that instantiate children are re- 

          sponsible  for realizing those children themselves.

             Maps all of the managed  children  windows  that

          have mapped_when_managed True.  If a widget is man- 

          aged but mapped_when_managed is False , the  widget

          is allocated visual space but is not displayed.

If the widget is a top-level shell widget (that is, it has no parent), and mapped_when_managed is True , XtRealizeWidget maps the widget window.

XtCreateWidget, XtVaCreateWidget, XtRealizeWidget, XtManageChildren, XtUnmanageChildren, XtUnrealizeWidget, XtSetMappedWhenManaged, and XtDestroyWidget maintain the following invariants:

If a composite widget is realized, then all its managed children are realized.

If a composite widget is realized, then all its managed children that have mapped_when_managed True are mapped.

All Intrinsics functions and all widget routines should accept either realized or unrealized widgets. When calling the realize or change_managed procedures for children of a composite widget, XtRealizeWidget calls the procedures in reverse order of appearance in the CompositePart children list. By default, this ordering of the realize procedures will result in the stacking order of any newly created subwindows being top-to-bottom in the order of appearance on the list, and the most recently created child will be at the bottom.

To check whether or not a widget has been realized, use XtIsRealized.

    Boolean XtIsRealized(w)

          Widget w;

         w Specifies the widget.  Must be of class Object or any subclass thereof.

Some widget procedures (for example, set_values) might wish to operate differently after the widget has been realized.

2.4.1. Widget Instance Window Creation: the realize Procedure   

The realize procedure pointer in a widget class is of type XtRealizeProc.

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

          Widget w;

          XtValueMask *value_mask;

          XSetWindowAttributes *attributes;

         w Specifies the widget.

         value_mask Specifies which fields in the attributes structure are used.

         attributes Specifies the window attributes to use in the XCreateWindow call.

Before calling the class realize procedure, the generic XtRealizeWidget function fills in a mask and a corresponding XSetWindowAttributes structure. It sets the following fields in attributes and corresponding bits in value_mask based on information in the widget core structure:

The background_pixmap (or background_pixel if background_pixmap is XtUnspecifiedPixmap) is filled in from the corresponding field.

The border_pixmap (or border_pixel if border_pixmap is XtUnspecifiedPixmap) is filled in from the corresponding field.

The colormap is filled in from the corresponding field.

The event_mask is filled in based on the event handlers registered, the event translations specified, whether the expose field is non-NULL, and whether visible_interest is True.

The bit_gravity is set to NorthWestGravity if the expose field is NULL.

These or any other fields in attributes and the corresponding bits in value_mask can be set by the realize procedure.

Note that because realize is not a chained operation, the widget class realize procedure must update the XSetWindowAttributes structure with all the appropriate fields from non-Core superclasses.

A widget class can inherit its realize procedure from its superclass during class initialization. The realize procedure defined for coreWidgetClass calls XtCreateWindow with the passed value_mask and attributes and with window_class and visual set to CopyFromParent. Both compositeWidgetClass and constraintWidgetClass inherit this realize procedure, and most new widget subclasses can do the same.

The most common noninherited realize procedures set bit_gravity in the mask and attributes to the appropriate value and then create the window. For example, depending on its justification, Label might set bit_gravity to WestGravity, CenterGravity, or EastGravity. Consequently, shrinking it would just move the bits appropriately, and no exposure event is needed for repainting.

If a composite widget's children should be realized in an order other than that specified (to control the stacking order, for example), it should call XtRealizeWidget on its children itself in the appropriate order from within its own realize procedure.

Widgets that have children and whose class is not a subclass of compositeWidgetClass are responsible for calling XtRealizeWidget on their children, usually from within the realize procedure.

2.4.2. Window Creation Convenience Routine   

Rather than call the Xlib XCreateWindow function explicitly, a realize procedure should normally call the Intrinsics analog XtCreateWindow, which simplifies the creation of windows for widgets.

    void XtCreateWindow(w, window_class, visual, value_mask, attributes)

          Widget w;

          unsigned int window_class;

          Visual *visual;

          XtValueMask value_mask;

          XSetWindowAttributes *attributes;

         w Specifies the widget that defines the additional window attributed.

              Must be of class Core or any subclass thereof.

         window_class Specifies the Xlib window class (for example,

              InputOutput, InputOnly, or CopyFromParent).

         visual Specifies the visual type (usually CopyFromParent).

         value_mask Specifies which fields in the attributes structure are used.

         attributes Specifies the window attributes to use in the XCreateWindow call.

XtCreateWindow evaluates the following fields of the widget core structure: depth, screen, parent->core.window, x, y, width, height, and border_width.