Your manager widget must contain a class record. The first portion of the class record is a CoreClassPart structure. For example, following is the CoreClassPart structure of the ExmGrid widget:
externaldef(exmgridclassrec) ExmGridClassRec exmGridClassRec =
{
{ /* core_class */
/* superclass */ (WidgetClass)
&xmManagerClassRec,
/* class_name */ "ExmGrid",
/* widget_size */ sizeof(ExmGridRec),
/* class_initialize */ NULL,
/* class_part_initialize */ ClassPartInitialize,
/* class_inited */ FALSE,
/* initialize */ Initialize,
/* initialize_hook */ NULL,
/* realize */ XtInheritRealize,
/* actions */ NULL,
/* num_actions */ 0,
/* resources */ resources,
/* num_resources */ XtNumber(resources),
/* xrm_class */ NULLQUARK,
/* compress_motion */ TRUE,
/* compress_exposure */ XtExposeCompressMaximal,
/* compress_enterleave */ TRUE,
/* visible_interest */ FALSE,
/* destroy */ NULL,
/* resize */ Resize,
/* expose */ Redisplay,
/* set_values */ SetValues,
/* set_values_hook */ NULL,
/* set_values_almost */ XtInheritSetValuesAlmost,
/* get_values_hook */ NULL,
/* accept_focus */ NULL,
/* version */ XtVersion,
/* callback_private */ NULL,
/* tm_table */ XtInheritTranslations,
/* query_geometry */ QueryGeometry,
/* display_accelerator */ NULL,
/* extension */ NULL,
},
The following subsections explain what Motif widget writers need to know about these fields.
The first field of the CoreClassPart structure is the superclass field. For this field, you must specify the name of the class record of your widget's immediate superclass. For example, if your widget's immediate superclass is XmManager, the superclass field will look as follows:
/* superclass */ (WidgetClass) &xmManagerClassRec,
The class_name field holds a string representing the name of the class; for example:
/* class_name */ "ExmGrid",
Motif will not make any attempt to interpret the characters in the string. The string can be any length, and can be composed of alphanumeric character, hypens, and underbars.
The string should begin with some prefix that uniquely symbolizes the widget group you are creating. For example, all the sample widgets associated with this group start with the Exm prefix. Do not pick a prefix that is used by other groups. For example, Motif reserves the prefixes xm, Xm, _Xm, Xme, XmQT, and Exm. See Chapter 2 for more information on namespace.
The widget_size field of manager widgets holds the size of the full instance record. For example, the full instance record of the ExmGrid demonstration widget is named ExmGridRec; therefore, the Core class record of ExmGrid defines the widget_size field as follows:
/* widget_size */ sizeof(ExmGridRec);
The Intrinsics call the class_initialize method only once, at the first instantiation of a widget of this class. You can set the class_initialize field to one of the following:
Motif makes no requirements of the code in class_initialize methods. However, Motif recommends registering any new representation types inside the class_initialize method. (See Chapter 6 for details.)
The Intrinsics call the class_part_initialize method at the first instantiation of a widget of this class or of a subclass of this class. You can set the class_part_initialize field to one of the following:
The class_part_initialize method is chained; therefore, the Intrinsics call the class_part_initialize method of Core, Composite, Constraint, and XmManager before calling the class_part_initialize method of your own widget. (See documentation on the Intrinsics for information on the class_part_initialize methods of Core, Composite, and Constraint.) The class_part_initialize method of XmManager does the following:
Motif makes no requirements of the code in your widget's class_part_initialize method. However, most Motif widgets use this method to install traits. (See Chapter 5 for details on installing traits.)
Motif widgets must always set the value of the class_inited field to False.
The Intrinsics call your widget's initialize method when an application instantiates your widget. You must specify one of the following:
The initialize method is chained; therefore, the Intrinsics call the initialize method of the Core, Composite, Constraint, and XmManager widgets before calling the initialize method of your own widget. (See documentation on the Intrinsics for details on the initialize method of Core, Composite, and Constraint.) The initialize method of XmManager does the following:
The code in your own initialize method should check resource values and perform other start-up tasks relevant to your widget's creation. You can find a sample initialize method for a manager widget inside the Grid.c file.
The initialize_hook field is obsolete. Motif ignores the stored value of this field; set it to NULL.
The realize field holds the name of the method that is responsible for creating the widget's window. If you want a standard Motif manager window, you should inherit the realize method of the XmManager widget by setting the realize field to XtInheritRealize.
The realize method of XmManager calls XtCreateWindow to create a window. It is impossible for the width or height of the created window to be 0. Therefore, if the widget does not yet have a width or height, the realize method of XmManager forces the width or height to 1 pixel.
The window class of the created window will be InputOutput. The generated window will not propagate any button, key, or pointer motion events to its parent window(s).
The default windows for managers and primitives use bit gravity differently. Default manager windows set bit gravity to NorthWest, while default primitive windows take the default bit gravity, ForgetGravity.
The Motif Style Guide does not demand that all windows conform to a certain standard. For that matter, the Motif Style Guide does not even insist that all windows be rectangular. Therefore, you are free to create your own realize method.
Specify the name of the array that holds the actions methods defined by your widget. (See Chapter 7 for details on actions.)
The num_actions field holds the number of actions defined by the array in the actions field. If your widget does not provide an actions array, then you should specify 0 for the num_actions field. If your widget does provide an actions array, then you should use the XtNumber macro to count these actions. For example, the ExmCommandButton widget does provide an actions array, so its num_actions field looks as follows:
/* num_actions */ XtNumber(actions),
If your widget defines new resources, specify the name of the resources array. If your widget does not define new resources, specify NULL.
Your widget will automatically inherit the resources of its superclasses. (See Chapter 6 for more details on resources.)
The num_resources field holds the number of resources defined by the array in the resources field. If your widget does not provide a resources array, then you should specify 0 for the num_resources field. If your widget does provide a resources array, then your widget should use the XtNumber macro to count these resources. For example, the ExmGrid widget does provide a resources array, so its num_resources field looks as follows:
/* num_resources */ XtNumber(resources),
Your widget must always specify NULLQUARK as the value of the xrm_class field.
The compress_motion field requires a Boolean value. Setting this value to True eliminates certain redundant pointer motion events from the event queue. Setting this value to False imposes a slight performance penalty but produces more accurate pointer tracking. (See documentation on the Intrinsics for more details.)
Every standard Motif manager widget sets the compress_motion field to True.
The compress_exposure field requires a constant value. This value tells the Intrinsics how to respond to multiple exposure events. (See documentation on the Intrinsics for more complete details.)
Motif makes no recommendations on the value of the compress_exposure field. The XmManager widget sets this field to XtExposeCompressMaximal.
Managers that may have gadget children should not use the XtExposeNoRegion flag.
The compress_enterleave field requires a Boolean value. Setting this value to True means that the Intrinsics will ignore unimportant enter event/leave event pairs. (See documentation on the Intrinsics for more complete details.)
Motif makes no recommendations on the value of the compress_enterleave field. However, most standard Motif manager widgets, including the XmManager widget, set this field to True.
The visible_interest field requires a Boolean value. This value provides hints to the Intrinsics on the redisplay of partially exposed widgets. Motif does not layer any extra meaning on top of the standard Intrinsics use of this field.
Motif makes no recommendations on the value of this field. However, every standard Motif widget sets this field to False.
The Intrinsics automatically call the destroy method when the widget is explicitly destroyed. You must specify one of the following:
The destroy field is chained in subclass-to-superclass order; therefore, the destroy method of XmManager will be called after any destroy method that your own widget supplies. The destroy method of XmManager deallocates the following four graphics contexts:
In addition, the destroy method of XmManager deallocates all the widget traversal information held by this widget.
If your widget provides a destroy method, make sure it deallocates all strings, fonts, GCs, and so forth, allocated by your widget.
The Intrinsics automatically call the method specified in the resize field in response to a resize event. The XmManager widget does not provide a resize method, so your widget will not be able to inherit a resize method from XmManager. (See Chapter 12 for more information on geometry management.)
The Intrinsics automatically invoke the expose method upon receiving an exposure event. The interpretation of exposure events can be altered by the values of the compress_exposure and visible_interest fields. (See documentation on the Intrinsics for complete details.)
Your widget should set the expose field to one of the following:
All standard Motif manager widgets except XmManager provide their own expose method. Motif requires that your Redisplay method (or the Redisplay method your widget inherits) call XmeRedisplayGadgets in order to pass exposure events down to gadget children. (See Chapter 17 for syntactic details on XmeRedisplayGadgets.)
You can either specify the name of your widget's set_values method or you can specify NULL, which symbolizes the absence of a set_values method. Most of the widgets you write will specify a set_values method.
When an application calls XtSetValues to change any of the resource values in your widget, the Intrinsics automatically call the set_values method.
Your widget's set_values method is responsible for validating changes to resource values. Your widget can call XmRepTypeValidValue to validate changes to representation type resources. (See Chapter 6 for details.)
The code in a set_values method is usually quite similar to the code in an initialize method.
The set_values method returns a Boolean value. The Intrinsics monitor this returned value. If the returned value is True, the Intrinsics automatically invoke the widget's expose (Redisplay) method. There are many reasons why widget redisplay could benecessary. One subtle reason is that a widget GC has changed.
The set_values method is chained. Therefore, the Intrinsics will call the set_values method of XmManager prior to calling the set_values method of your own widget. The set_values method of XmManager does the following:
The set_values_hook field is obsolete. Motif ignores its value; set it to NULL.
The Intrinsics call the method named in the set_values_almost field when certain geometry requests cannot be fulfilled by the geometry manager. To inherit the set_values_almost method of your superclass, specify XtInheritSetValuesAlmost. The XmManager widget itself sets the set_values_almost field to XtInheritSetValuesAlmost, so it inherits this field from the Intrinsics widgets.
Motif makes no requirements for this method. However, all the standard Motif manager widgets set this field to XtInheritSetValuesAlmost. (See Chapter 12 for details on Motif geometry management.)
The get_values_hook field holds the name of a method responsible for returning resource values from any subparts of your widget. If your widget has no need to do this, it should set the get_values_hook field to NULL.
The get_values_hook field is chained; therefore, the Intrinsics will call the get_values_hook method of XmManager prior to the get_values_hook method of your widget. The get_values_hook method of XmManager implements synthetic resources on manager widgets.
Motif ignores the value of the accept_focus field; set it to NULL.
The version field holds an enumerated constant pertaining to the compatibility of the Intrinsics themselves. The version field does not express any information regarding Motif compatibility, nor does Motif seek to interpret the version field in any way.
Most widgets set this field to XtVersion. However, if you do not want your widget to check binary compatibility with future releases of the Intrinsics, set this field to XtVersionDontCheck. (See Chapter 15 for details on binary compatibility.)
Motif ignores the value of the callback_private field; set it to NULL.
You should specify one of the following three possible values for the tm_table field:
If your tm_table field is set to XtInheritTranslations and your widget's immediate superclass is XmManager, then your widget will inherit the following tm_table translations:
<BtnMotion> : ManagerGadgetButtonMotion()\n\ c<Btn1Down> : ManagerGadgetTraverseCurrent()\n\ ~c<Btn1Down> : ManagerGadgetArm()\n\ ~c<Btn1Down> ,~c<Btn1Up> : ManagerGadgetActivate()\n\ ~c<Btn1Up> : ManagerGadgetActivate()\n\ ~c<Btn1Down> (2+): ManagerGadgetMultiArm()\n\ ~c<Btn1Up> (2+): ManagerGadgetMultiActivate()\n\ <Btn2Down> : ManagerGadgetDrag()\n\ :<Key> osfActivate: ManagerParentActivate()\n\ :<Key> osfCancel: ManagerParentCancel()\n\ :<Key> osfSelect: ManagerGadgetSelect()\n\ :<Key> osfHelp: ManagerGadgetHelp()\n\ ~s ~m ~a <Key> Return: ManagerParentActivate()\n\ ~s ~m ~a <Key> space: ManagerGadgetSelect()\n\ <Key> : ManagerGadgetKeyInput()";
Suppose you provide your own tm_table string rather than inherit the tm_table string of XmManager. If you want your manager widget to handle the default button events correctly, then your tm_table string should be a superset of the activation translations of XmManager. That is, your tm_table string should contain the following:
:<Key> osfActivate: ManagerParentActivate()\n\ :<Key> osfCancel: ManagerParentCancel()\n\ ~s ~m ~a <Key> Return: ManagerParentActivate()\n\
If you want your manager widget to support gadgets properly, then the tm_table string should specify all of the translations used by XmManager.
(See Chapter 7 for more details on translations.)
When your manager is itself a child of another manager widget, the parent manager widget will call your widget's query_geometry method to request your widget's geometry preferences.
Your widget must specify one of the following for the query_geometry field:
The XmManager widget does not provide a query_geometry method. Therefore, your widget cannot inherit from it.
(See Chapter 12 for details on Motif geometry management.)
Motif ignores the value of the display_accelerator field; set it to NULL.
Motif strongly recommends that you set the value of the extension field to NULL. By doing so, Motif will install the correct extension record for you at runtime.