hpux man page for realize

realize()																 realize()

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
  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:

  o  background_pixmap is set to the value of the widget's XtNbackgroundPixmap resource, or  if  this  resource  is  unspecified,  the	back-
     ground_pixel field is set to the value of the widget's XtNbackground resource.

  o  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.

  o  colormap is set to the value of the XtNcolormap resource of the widget.

  o  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.

  o  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 wid-
  get'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  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 real-
  ize() method.  (The Xaw Command widget does this.)  A composite widget can control the stacking order of its children by explicitly realiz-
  ing  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
  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 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 Also
  XtCreateWindow(1), XtRealizeWidget(1),
  Core(3).

Xt - Intrinsics Methods 														 realize()