diff options
Diffstat (limited to 'libXaw/spec/CH2')
| -rw-r--r-- | libXaw/spec/CH2 | 1103 |
1 files changed, 1103 insertions, 0 deletions
diff --git a/libXaw/spec/CH2 b/libXaw/spec/CH2 new file mode 100644 index 000000000..9e6c17a8a --- /dev/null +++ b/libXaw/spec/CH2 @@ -0,0 +1,1103 @@ +.\" $Xorg: CH2,v 1.3 2000/08/17 19:42:26 cpqbld Exp $ +.bp +\& +.sp 1 +.ce 3 +\s+1\fBChapter 2\fP\s-1 + +\s+1\fBUsing Widgets\fP\s-1 +.sp 2 +.nr H1 2 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 2 \- Using Widgets +.XE +.IN "using widgets" "" "@DEF@" +Widgets serve as the primary tools for building a user interface or +application environment. The Athena widget set consists of primitive +widgets that contain no children (for example, a command button) and +composite widgets which may contain one or more widget children (for +example, a Box widget). +.LP +The remaining chapters explain the widgets that are provided +by the Athena widget set. +These user-interface components serve as an interface for +application programmers who do not want to implement their own widgets. +In addition, they serve as a starting point +for those widget programmers who, using the \*(xI mechanisms, +want to implement alternative application programming interfaces. +.LP +This chapter is a brief introduction to widget programming. The +examples provided use the Athena widgets, though most of the concepts +will apply to all widget sets. Although there are several programming +interfaces to the \*(tk, only one is described here. A full +description of the programming interface is provided in the document +\fI\*(xT\fP. +.NH 2 +Setting the Locale +.LP +.XS + Setting the Locale +.XE +If it is desirable that the application take advantage of +internationalization (i18n), you must establish locale with +.PN XtSetLanguageProc +before \fBXtDisplayInitialize\fP or \fBXtAppInitialize\fP +is called. For full details, please refer to the document +\fI\*(xT\fP, section 2.2. However, the following simplest-case +call is sufficient in many or most applications. +.LP +.IN "internationalization" "" "" +.IN "XtSetLanguageProc" "" "@DEF@" +.IN "locale" "" "" +.Ds +.TA .5i 2i +.ta .5i 2i + XtSetLanguageProc(NULL, NULL, NULL); +.De +.LP +Most notably, this will affect the Standard C locale, determine which +resource files will be loaded, and what fonts will be required of FontSet +specifications. In many cases, the addition of this line is the only source change +required to internationalize Xaw programs, and will not disturb the function +of programs in the default "C" locale. +.NH 2 +Initializing the Toolkit +.LP +.XS + Initializing the Toolkit +.XE +You must call a toolkit initialization function before invoking any +other toolkit routines (besides locale setting, above). +.PN XtAppInitialize +opens the X server connection, parses the command line, +and creates an initial widget that will serve as the root of +a tree of widgets created by this application. +.IN "initialization" "" "@DEF@" +.IN "toolkit initialization" "" "@DEF@" +.IN "XtAppInitialize" "" "@DEF@" +.IN "fallback resources" "" "@DEF@" +.FD 0 +Widget XtAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \ +\fIoptions\fP, \fInum_options\fP, +.ta 2i + \fIargc_in_out\fP, \fIargv_in_out\fP, \fIfallback_resources\fP, \ +\fIargs\fP, \fInum_args\fP) +.br + XtAppContext *\fIapp_context_return\fP; +.br + String \fIapplication_class\fP; +.br + XrmOptionDescRec \fIoptions\fP[]; +.br + Cardinal \fInum_options\fP; +.br + int *\fIargc_in_out\fP; +.br + String *\fIargv_in_out\fP[]; +.br + String *\fIfallback_resources\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIapp_con_return\fP 1.5i +Returns the application context of this application, if non-NULL. +.IP \fIapplication_class\fP 1.5i +Specifies the class name of this application, +which is usually the generic name for all instances of this application. +A useful convention is to form the class name by capitalizing the +first letter of the application name. For example, the application named +``xman'' has a class name of ``Xman''. +.IP \fIoptions\fP 1.5i +Specifies how to parse the command line for any application-specific +resources. +The options argument is passed as a parameter to +.PN XrmParseCommand . +For further information, +see \fI\*(xL\fP. +.IP \fInum_options\fP 1.5i +Specifies the number of entries in the options list. +.IP \fIargc_in_out\fP 1.5i +Specifies a pointer to the number of command line parameters. +.IP \fIargv_in_out\fP 1.5i +Specifies the command line parameters. +.IP \fIfallback_resources\fP 1.5i +Specifies resource values to be used if the site-wide application class +defaults file cannot be opened, or NULL. +.IP \fIargs\fP 1.5i +Specifies the argument list to use when creating the Application shell. +.IP \fInum_args\fP 1.5i +Specifies the number of arguments in \fIargs\fP. +.LP +This function will remove the command line arguments that the toolkit +reads from \fIargc_in_out\fP, and \fIargv_in_out\fP. It will then +attempt to open the display. If the display cannot be opened, an error +message is issued and XtAppInitialize terminates the application. Once +the display is opened, all resources are read from the locations +specified by the \*(xI. This function returns an ApplicationShell +widget to be used as the root of the application's widget tree. +.NH 2 +Creating a Widget +.LP +.XS + Creating a Widget +.XE +.IN "widget creation" "" "@DEF@" +.IN "creating widgets" "" "@DEF@" +.IN "XtRealizeWidget" "" "" +Creating a widget is a three-step process. First, the widget instance +is allocated, and various instance-specific attributes are set by +using \fBXtCreateWidget\fP. Second, the widget's parent is informed +of the new child by using \fBXtManageChild\fP. Finally, X windows are +created for the parent and all its children by using \fBXtRealizeWidget\fP +and specifying the top-most widget. The first two steps can be +combined by using \fBXtCreateManagedWidget\fP. In addition, +\fBXtRealizeWidget\fP is automatically called when the child becomes +managed if the parent is already realized. +.LP +To allocate, initialize, and manage a widget, use +.PN XtCreateManagedWidget . +.IN "XtCreateManagedWidget" "" "@DEF@" +.FD 0 +Widget XtCreateManagedWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, \ +\fIargs\fP, \fInum_args\fP) +.br + String \fIname\fP; +.br + WidgetClass \fIwidget_class\fP; +.br + Widget \fIparent\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIname\fP 1i +Specifies the instance name for the created widget that is used for retrieving +widget resources. +.IP \fIwidget_class\fP 1i +Specifies the widget class pointer for the created widget. +.IP \fIparent\fP 1i +Specifies the parent widget ID. +.IP \fIargs\fP 1i +Specifies the argument list. The argument list is a variable-length +list composed of name and value pairs that contain information +pertaining to the specific widget instance being created. For further +information, see Section 2.7.2. +.IP \fInum_args\fP 1i +Specifies the number of arguments in the argument list. +If the num_args is zero, the argument list is never referenced. +.LP +When a widget instance is successfully created, the widget identifier +is returned to the application. If an error is encountered, the +.PN XtError +routine is invoked to inform the user of the error. +.IN "XtError" "" "" +.LP +For further information, see \fI\*(xT\fP. +.NH 2 +Common Resources +.XS + Common Resources +.XE +.IN "resource" "" +.LP +Although a widget can have unique arguments that it understands, all +widgets have common arguments that provide some regularity of operation. +The common arguments allow arbitrary widgets to be managed by +higher-level components without regard for the individual widget type. +Widgets will ignore any argument that they do not understand. +.LP +The following resources are retrieved from the argument list +or from the resource database by all of the Athena widgets: +.TS H +lw(1.5i) lw(1i) lw(1i) lw(2i). +_ +.sp 3p +.TB +Name Class Type Default Value +.sp 3p +_ +.TH +.R +.sp 3p +accelerators Accelerators AcceleratorTable NULL +ancestorSensitive AncestorSensitive Boolean True +background Background Pixel XtDefaultBackground +backgroundPixmap Pixmap Pixmap XtUnspecifiedPixmap +borderColor BorderColor Pixel XtDefaultForeground +borderPixmap Pixmap Pixmap XtUnspecifiedPixmap +borderWidth BorderWidth Dimension 1 +colormap Colormap Colormap Parent's Colormap +depth Depth int Parent's Depth +destroyCallback Callback XtCallbackList NULL +height Height Dimension \fIwidget dependent\fP +mappedWhenManaged MappedWhenManaged Boolean True +screen Screen Screen Parent's Screen +sensitive Sensitive Boolean True +translations Translations TranslationTable \fIwidget dependent\fP +width Width Dimension \fIwidget dependent\fP +x Position Position 0 +y Position Position 0 +.sp 3p +_ +.TE +.IN "XtDefaultForeground" "" "" +.IN "XtDefaultBackground" "" "" +.LP +The following additional resources are retrieved from the argument list +or from the resource database by many of the Athena widgets: +.TS H +lw(1.5i) lw(1i) lw(1i) lw(2i). +_ +.sp 3p +.TB +Name Class Type Default Value +.sp 3p +_ +.TH +.R +.sp 3p +callback Callback XtCallbackList NULL +cursor Cursor Cursor \fIwidget dependent\fP +foreground Foreground Pixel XtDefaultForeground +insensitiveBorder Insensitive Pixmap GreyPixmap +.sp 3p +_ +.TE +.IN "XtDefaultForeground" "" "" +.NH 2 +Resource Conversions +.XS + Resource Conversions +.XE +.IN "conversions" "" "@DEF@" +.IN "string conversions" "" "@DEF@" +.IN "type conversions" "" "@DEF@" +.LP +Most resources in the Athena widget set have a converter registered that +will translate the string in a resource file to the correct internal +representation. While some are obvious (string to integer, for example), +others need specific mention of the allowable values. Three general +converters are described here: +.IP \(bu 5 +Cursor +.IP \(bu 5 +Pixel +.IP \(bu 5 +Bitmap +.LP +Many widgets have defined special converters that apply only to that +widget. When these occur, the documentation section for that widget +will describe the converter. +.NH 3 +Cursor Conversion +.IN "conversions" "ColorCursor" "@DEF@" +.IN "conversions" "Cursor" "@DEF@" +.IN "cursor" "" "" +.LP +The value for the \fBcursorName\fP resource is specified in the resource +database as a string, and is of the following forms: +.IP \(bu 5 +A standard X cursor name from \fB< X11/cursorfont.h >\fP. +The names in \fBcursorfont.h\fP each describe a specific cursor. The +resource names for these cursors are exactly like the names in this file +except the \fBXC_\fP is not used. The cursor definition \fBXC_gumby\fP +has a resource name of \fBgumby\fP. +.IP \(bu 5 +Glyphs, as in \fIFONT font-name glyph-index [[ font-name ] glyph-index ]\fP. +The first font and glyph specify the cursor source pixmap. +The second font and glyph specify the cursor mask pixmap. +The mask font defaults to the source font, +and the mask glyph index defaults to the source glyph index. +.IP \(bu 5 +A relative or absolute file name. +If a relative or absolute file name is specified, that file is used to +create the source pixmap. Then the string "Mask" is appended to +locate the cursor mask pixmap. If the "Mask" file does not exist, the +suffix "msk" is tried. If "msk" fails, no cursor mask will be used. +If the filename does not start with '/' or './' the the bitmap +file path is used (see section 2.4.3). +.NH 3 +Pixel Conversion +.LP +.IN "conversions" "Pixel" "@DEF@" +.IN "pixel" "" "" +.IN "rgb.txt" "" "" +.IN "XtDefaultForeground" "" "" +.IN "XtDefaultBackground" "" "" +The string-to-pixel converter takes any name that is acceptable to +XParseColor (see \fI\*(xL\fP). In addition this routine understands +the special toolkit symbols `XtDefaultForeground' and +`XtDefaultBackground', described in \fI\*(xT\fP. In short the acceptable +pixel names are: +.IP \(bu 5 +Any color name for the rgb.txt file (typically in the directory +/usr/lib/X11 on POSIX systems). +.IP \(bu 5 +A numeric specification of the form #<red><green><blue> where these +numeric values are hexadecimal digits (both upper and lower case). +.IP \(bu 5 +The special strings `XtDefaultForeground' and `XtDefaultBackground' +.NH 3 +Bitmap Conversion +.IN "bitmap conversions" "" "@DEF@" +.IN "conversions" "Bitmap" "@DEF@" +.IN "bitmapFilePath" "" "@DEF@" +.IN "BitmapFilePath" "" "@DEF@" +.IN "/usr/include/X11/bitmaps" "" "" +.LP +The string-to-bitmap converter attempts to locate a file containing +bitmap data whose name is specified by the input string. If the file +name is relative (i.e. does not begin with / or ./), the directories to +be searched are specified in the \fBbitmapFilePath\fP resource--class +\fBBitmapFilePath\fP. This resource specifies a colon (:) separated +list of directories that will be searched for the named bitmap or +cursor glyph (see section 2.4.1). The \fBbitmapFilePath\fP resource is +global to the application, and may \fBnot\fP be specified differently +for each widget that wishes to convert a cursor to bitmap. In addition +to the directories specified in the \fBbitmapFilePath\fP resource a +default directory is searched. When using POSIX the default +directory is +.PN /usr/include/X11/bitmaps . +.NH 2 +Realizing a Widget +.LP +.XS + Realizing a Widget +.XE +.IN "realizing widgets" "" "@DEF@" +The +.PN XtRealizeWidget +function performs two tasks: +.IP \(bu 5 +Calculates the geometry constraints of all managed descendants +of this widget. The actual calculation is put off until realize time +for performance reasons. +.IP \(bu 5 +Creates an X window for the widget and, if it is a composite widget, +realizes each of its managed children. +.IN "XtRealizeWidget" "" "@DEF@" +.FD 0 +void XtRealizeWidget(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. +.LP +For further information about this function, +see the \fI\*(xT\fP. +.NH 2 +Processing Events +.LP +.XS + Processing Events +.XE +.IN "events" "" "" +.IN "XtAppInitialize" "" "" +Now that the application has created, managed and realized its +widgets, it is ready to process the events that will be delivered by the +X Server to this client. A function call that will process the +events is \fBXtAppMainLoop\fP. +.IN "XtAppMainLoop" "" "@DEF@" +.FD 0 +void XtAppMainLoop(\fIapp_context\fP) +.br + XtAppContext \fIapp_context\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context of this application. The value is +normally returned by \fBXtAppInitialize\fP. +.LP +This function never returns: it is an infinite loop that processes the +X events. User input can be handled through callback procedures and +application defined action routines. More details are provided in +\fI\*(xT\fP. +.NH 2 +Standard Widget Manipulation Functions +.XS + Standard Widget Manipulation Functions +.XE +.LP +After a widget has been created, a client can interact with that +widget by calling one of the standard widget manipulation routines +provided by the \*(xI, or a widget class-specific manipulation routine. +.LP +The \*(xI provide generic routines to give the application programmer +access to a set of standard widget functions. The common widget +routines let an application or composite widget perform the following +operations on widgets without requiring explicit knowledge of the widget +type. +.IP \(bu 5 +Control the mapping of widget windows +.IP \(bu 5 +Destroy a widget instance +.IP \(bu 5 +Obtain an argument value +.IP \(bu 5 +Set an argument value +.NH 3 +Mapping Widgets +.LP +By default, +widget windows are mapped (made viewable) automatically by +\fBXtRealizeWidget\fP. This behavior can be disabled by using +\fBXtSetMappedWhenManaged\fP, making the client responsible for calling +\fBXtMapWidget\fP to make the widget viewable. +.IN "XtSetMappedWhenManaged" "" "@DEF@" +.IN "XtMapWidget" "" "" +.IN "XtRealizeWidget" "" "" +.FD 0 +void XtSetMappedWhenManaged(\fIw\fP, \fImap_when_managed\fP) +.br + Widget \fIw\fP; +.br + Boolean \fImap_when_managed\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. +.IP \fImap_when_managed\fP 1i +Specifies the new value. +If map_when_managed is \fBTrue\fP, the widget is mapped automatically +when it is realized. If map_when_managed is \fBFalse\fP, the client +must call +.PN XtMapWidget +or make a second call to +.PN XtSetMappedWhenManaged +to cause the child window to be mapped. +.LP +.sp +The definition for +.PN XtMapWidget +is: +.IN "XtMapWidget" "" "@DEF@" +.FD 0 +void XtMapWidget(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. +.LP +When you are creating several children in sequence for a previously +realized common parent it is generally more efficient to construct a +list of children as they are created (using \fBXtCreateWidget\fP) and +then use \fBXtManageChildren\fP to request that their parent managed +them all at once. By managing a list of children at one time, the +parent can avoid wasteful duplication of geometry processing and the +associated ``screen flash''. +.IN "XtManageChildren" "" "@DEF@" +.IN "XtCreateWidget" "" "" +.FD 0 +void XtManageChildren(\fIchildren\fP, \fInum_children\fP) +.br + WidgetList \fIchildren\fP; +.br + Cardinal \fInum_children\fP; +.FN +.IP \fIchildren\fP 1i +Specifies a list of children to add. +.IP \fInum_children\fP 1i +Specifies the number of children to add. +.LP +If the parent is already visible on the screen, it is especially +important to batch updates so that the minimum amount of visible window +reconfiguration is performed. +.LP +For further information about these functions, +see the \fI\*(xT\fP. +.NH 3 +Destroying Widgets +.LP +To destroy a widget instance of any type, use +.PN XtDestroyWidget . +.IN "XtDestroyWidget" "" "@DEF@" +.FD 0 +void XtDestroyWidget(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. +.LP +.PN XtDestroyWidget +destroys the widget and recursively destroys any children that it may have, +including the windows created by its children. +After calling +.PN XtDestroyWidget , +no further references should be made to the widget or any children +that the destroyed widget may have had. +.NH 3 +Retrieving Widget Resource Values +.LP +To retrieve the current value of a resource attribute associated +with a widget instance, use +.PN XtGetValues . +.IN "XtGetValues" "" "@DEF@" +.FD 0 +void XtGetValues(\fIw\fP, \fIargs\fP, \fInum_args\fP) +.br + Widget \fIw\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. +.IP \fIargs\fP 1i +Specifies a variable-length argument list of name and \fBaddress\fP +pairs that contain the resource name and the address into which the +resource value is stored. +.IP \fInum_args\fP 1i +Specifies the number of arguments in the argument list. +.LP +The arguments and values passed in the argument list are dependent on +the widget. Note that the caller is responsible for providing space +into which the returned resource value is copied; the \fBArgList\fP +contains a pointer to this storage (e.g. x and y must be +allocated as Position). For further information, see the \fI\*(xT\fP. +.NH 3 +Modifying Widget Resource Values +.LP +To modify the current value of a resource attribute associated with a +widget instance, use +.PN XtSetValues . +.IN "XtSetValues" "" "@DEF@" +.FD 0 +void XtSetValues(\fIw\fP, \fIargs\fP, \fInum_args\fP) +.br + Widget \fIw\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. +.IP \fIargs\fP 1i +Specifies an array of name and \fBvalue\fP pairs that contain the +arguments to be modified and their new values. +.IP \fInum_args\fP 1i +Specifies the number of arguments in the argument list. +.LP +The arguments and values that are passed will depend on the widget +being modified. Some widgets may not allow certain resources to be +modified after the widget instance has been created or realized. +No notification is given if any part of a \fBXtSetValues\fP request is +ignored. +.LP +For further information about these functions, see the \fI\*(xT\fP. +.IN "XtGetValues" "" "" +.IN "XtSetValues" "" "" +.NT +The argument list entry for +.PN XtGetValues +specifies the address to which the caller wants the value copied. The +argument list entry for +.PN XtSetValues , +however, contains the new value itself, if the size of value is less than +sizeof(XtArgVal) (architecture dependent, but at least sizeof(long)); +otherwise, it is a pointer to the value. String resources are always +passed as pointers, regardless of the length of the string. +.NE +.NH 2 +Using the Client Callback Interface +.LP +.XS + Using the Client Callback Interface +.XE +.IN "callbacks" "" "" +Widgets can communicate changes in their state to their clients +by means of a callback facility. +The format for a client's callback handler is: +.IN "CallbackProc" "" "@DEF@" +.FD 0 +void \fICallbackProc\fP(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP) +.br + Widget \fIw\fP; +.br + XtPointer \fIclient_data\fP; +.br + XtPointer \fIcall_data\fP; +.FN +.IP \fIw\fP 1i +Specifies widget for which the callback is registered. +.IP \fIclient_data\fP 1i +Specifies arbitrary client-supplied data that the widget should pass +back to the client when the widget executes the client's callback +procedure. This is a way for the client registering the callback to +also register client-specific data: a pointer to additional information +about the widget, a reason for invoking the callback, and so on. If no +additional information is necessary, NULL may be passed as this argument. +This field is also frequently known as the \fIclosure\fP. +.IP \fIcall_data\fP 1i +Specifies any callback-specific data the widget wants to pass to the client. +For example, when Scrollbar executes its \fBjumpProc\fP callback list, +it passes the current position of the thumb in \fIcall_data\fP. +.LP +Callbacks can be registered either by creating an argument containing +the callback list described below or by using the special convenience +routines \fBXtAddCallback\fP and \fBXtAddCallbacks\fP. When the widget +is created, a pointer to a list of callback procedure and data pairs can +be passed in the argument list to +.PN XtCreateWidget . +The list is of type +.PN XtCallbackList : +.IN "XtCallbackProc" +.IN "XtAddCallbacks" +.IN "XtAddCallback" +.IN "XtCallbackList" "" "@DEF@" +.IN "XtCallbackRec" "" "@DEF@" +.LP +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + XtCallbackProc callback; + XtPointer closure; +} XtCallbackRec, *XtCallbackList; +.De +.LP +The callback list must be allocated and initialized before calling +.PN XtCreateWidget . +.IN "XtCreateWidget" +The end of the list is identified by an entry containing NULL in +callback and closure. Once the widget is created, the client can change +or de-allocate this list; the widget itself makes no further reference +to it. The closure field contains the client_data passed to the +callback when the callback list is executed. +.LP +The second method for registering callbacks is to use +.PN XtAddCallback +after the widget has been created. +.IN "XtAddCallback" "" "@DEF@" +.FD 0 +void XtAddCallback(\fIw\fP, \fIcallback_name, \fP\fIcallback\fP, \ +\fIclient_data\fP) +.br + Widget \fIw\fP; +.br + String \fIcallback_name\fP; +.br + XtCallbackProc \fIcallback\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget to add the callback to. +.IP \fIcallback_name\fP 1i +Specifies the callback list within the widget to append to. +.IP \fIcallback\fP 1i +Specifies the callback procedure to add. +.IP \fIclient_data\fP 1i +Specifies the data to be passed to the callback when it is invoked. +.LP +.PN XtAddCallback +adds the specified callback to the list for the named widget. +.LP +All widgets provide a callback list named +.PN destroyCallback +.IN "destroyCallback" "" "@DEF@" +where clients can register procedures that are to be executed when the +widget is destroyed. The destroy callbacks are executed when the widget +or an ancestor is destroyed. The \fIcall_data\fP argument is unused for +destroy callbacks. +.NH 2 +Programming Considerations +.LP +.XS + Programming Considerations +.XE +This section provides some guidelines on how to set up an application +program that uses the \*(tk. +.NH 3 +Writing Applications +.LP +.IN "writing applications" +.IN "StringDefs.h" +.IN "Intrinsic.h" +When writing an application that uses the X Toolkit, +you should make sure that your application performs the following: +.IP 1. 5 +Include +.Pn < X11/Intrinsic.h > +in your application programs. +This header file automatically includes +.Pn < X11/Xlib.h >, +so all Xlib functions also are defined. +It may also be necessary to include \fB< X11/StringDefs.h >\fP when setting +up argument lists, as many of the XtN\fIsomething\fP definitions are +only defined in this file. +.IP 2. 5 +Include the widget-specific header files for each widget type +that you need to use. +For example, +.Pn < X11/Xaw/Label.h > +and +.Pn < X11/Xaw/Command.h >. +.IP 3. 5 +Call the +.PN XtAppInitialize +.IN "XtAppInitialize" +function before invoking any other toolkit or Xlib functions. +For further information, +see Section 2.1 and the \fI\*(xT\fP. +.IP 4. 5 +To pass attributes to the widget creation routines that will override +any site or user customizations, set up argument lists. In this +document, a list of valid argument names is provided in the discussion +of each widget. The names each have a global symbol defined that begins +with \fBXtN\fP to help catch spelling errors. For example, +\fBXtNlabel\fP is defined for the \fBlabel\fP resource of many widgets. +.IN "XtN" "" "@DEF@" +.IP +For further information, see Section 2.9.2.2. +.IP 5. 5 +When the argument list is set up, create the widget with the +\fBXtCreateManagedWidget\fP function. For further information, see +Section 2.2 and the \fI\*(xT\fP. +.IN "XtCreateManagedWidget" +.IP 6. 5 +If the widget has any callback routines, set by the +.PN XtNcallback +argument or the +.PN XtAddCallback +function, declare these routines within the application. +.IN "XtAddCallback" +.IP 7. 5 +After creating the initial widget hierarchy, windows must be created +for each widget by calling +.PN XtRealizeWidget +on the top level widget. +.IN "XtRealizeWidget" +.IP 8. 5 +Most applications now sit in a loop processing events using +.PN XtAppMainLoop , +for example: +.IN "XtAppMainLoop" +.IP +.Ds 0 +XtCreateManagedWidget(\fIname\fP, \fIclass\fP, \fIparent\fP, \fIargs\fP, \fInum_args\fP); +XtRealizeWidget(\fIshell\fP); +XtAppMainLoop(\fIapp_context\fP); +.De +.IP +For information about this function, see the \fI\*(xT\fP. +.IP 9. 5 +Link your application with +.PN libXaw +(the Athena widgets), +.PN libXmu +(miscellaneous utilities), +.PN libXt +(the \*(tk \*(xI), +.PN libSM +(Session Management), +.PN libICE +(Inter-Client Exchange), +.PN libXext +(the extension library needed for the shape extension code which allows +rounded Command buttons), and +.PN libX11 +(the core X library). +The following provides a sample command line: +.IN "libXaw" +.IN "libXmu" +.IN "libXt" +.IN "libSM" +.IN "libICE" +.IN "libXext" +.IN "libX11" +.IN "linking applications" +.IN "compiling applications" +.IP +.Ds 0 +cc -o \fIapplication\fP \fIapplication\fP.c \-lXaw \-lXmu \-lXt \ +\-lSM \-lICE \-lXext \-lX11 +.De +.NH 3 +Changing Resource Values +.IN "resource" "" +.LP +The \*(xI support two methods of changing the default resource +values; the resource manager, and an argument list passed into +XtCreateWidget. While resources values will get updated no matter +which method you use, the two methods provide slightly different +functionality. +.IP "Resource Manager" 1.5i +This method picks up resource definitions described in \fI\*(xL\fP from +many different locations at run time. The locations most important to +the application programmer are the \fIfallback resources\fP and the +\fIapp-defaults\fP file, (see \fI\*(xT\fP for the complete list). +Since these resource are loaded at run time, they can be overridden by +the user, allowing an application to be customized to fit the +particular needs of each individual user. These values can also be +modified without the need to rebuild the application, allowing rapid +prototyping of user interfaces. Application programmers should use +resources in preference to hard-coded values whenever possible. +.IP "Argument Lists" 1.5i +The values passed into the widget at creation time via an argument list +cannot be modified by the user, and allow no opportunity for +customization. It is used to set resources that cannot be specified as +strings (e.g. callback lists) or resources that should not be +overridden (e.g. window depth) by the user. +.NH 4 +Specifying Resources +.LP +It is important for all X Toolkit application programmers to +understand how to use the X Resource Manager to specify resources for +widgets in an X application. This section will describe the most common +methods used to specify these resources, and how to use the X Resource +manager. +.IN "xrdb" +.IP \fBXrdb\fP 1.5i +The \fBxrdb\fP utility may be used to load a file containing +resources into the X server. Once the resources are loaded, the +resources will affect any new applications started on the display that +they were loaded onto. +.IN "application defaults" +.IN "app-defaults" +.IN "/usr/lib/X11/app-defaults" +.IP "\fBApplication Defaults\fP" 1.5i +The application defaults (app-defaults) file (normally in +/usr/lib/X11/app-defaults/\fIclassname\fP) for an application is loaded +whenever the application is started. +.LP +The resource specification has two colon-separated parts, a name, and +a value. The \fIvalue\fP is a string whose format is dependent on the +resource specified by \fIname\fP. \fIName\fP is constructed by +appending a resource name to a full widget name. +.LP +The full widget name is a list of the name of every ancestor of the +desired widget separated by periods (.). Each widget also has a class +associated with it. A class is a type of widget (e.g. Label or +Scrollbar or Box). Notice that class names, by convention, begin with +capital letters and instance names begin with lower case letters. The +class of any widget may be used in place of its name in a resource +specification. Here are a few examples: +.IP xman.form.button1 1.5i +This is a fully specified resource name, and will affect only widgets +called button1 that are children of widgets called form that are +children of +applications named xman. (Note that while typically two widgets that +are siblings will have different names, it is not prohibited.) + +.IP Xman.Form.Command 1.5i +This will match any Command widget that is a child of a Form widget +that is itself a child of an application of class \fIXman\fP. +.IP Xman.Form.button1 1.5i +This is a mixed resource name with both widget names and classes specified. +.LP +This syntax allows an application programmer to specify any widget +in the widget tree. To match more than one widget (for example a user +may want to make all Command buttons blue), use an asterisk (*) +instead of a period. When an asterisk is used, any number of widgets +(including zero) may exist between the two widget names. For example: +.IP Xman*Command 1.5i +This matches all Command widgets in the Xman application. +.IP Foo*button1 1.5i +This matches any widget in the Foo application that is named \fIbutton1\fP. +.LP +The root of all application widget trees is the widget returned by +\fBXtAppInitialize\fP. Even though this is actually an +ApplicationShell widget, the toolkit replaces its widget class with the +class name of the application. The name of this widget is either +the name used to invoke the application (\fBargv[0]\fP) or the name of +the application specified using the standard \fI-name\fP command line +option supported by the \*(xI. +.LP +The last step in constructing the resource name is to append the name of +the resource with either a period or asterisk to the full or partial +widget name already constructed. +.IP *foreground:Blue 2.25i +Specifies that all widgets in all applications will have a foreground +color of blue. +.IP Xman*borderWidth:10 2.25i +Specifies that all widgets in an application whose class is Xman will +have a border width of 10 (pixels). +.IP xman.form.button1.label:Testing 2.25i +Specifies that a particular widget in the xman application will have a +label named \fITesting\fP. +.LP +An exclamation point (!) in the first column of a line indicates +that the rest of the line should be treated as a comment. +.LP +\fBFinal Words\fP +.LP +The Resource manager is a powerful tool that can be used very +effectively to customize \*(tk applications at run time by either the +application programmer or the user. Some final points to note: +.IP \(bu 5 +An application programmer may add new resources to their +application. These resources are associated with the global +application, and not any particular widget. The \*(tk function used for +adding the application resources is \fBXtGetApplicationResources\fP. +.IN "XtGetApplicationResources" +.IP \(bu 5 +Be careful when creating resource files. Since widgets will +ignore resources that they do not understand, any spelling +errors will cause a resource to have no effect. +.IP \(bu 5 +Only one resource line will match any given resource. There is a set +of precedence rules, which take the following general stance. +.ta 10n +.IP "" 5 +\(bu More specific overrides less specific, thus period always overrides asterisk. +.IP "" 5 +\(bu Names on the left are more specific and override names on the right. +.IP "" 5 +\(bu When resource specifications are exactly the same, user defaults +.br + will override program defaults. +.LP +For a complete explanation of the rules of precedence, and +other specific topics see \fI\*(xT\fP and \fI\*(xL\fP. +.NH 4 +Creating Argument Lists +.IN "argument lists" "" "@DEF@" +.LP +To set up an argument list for the inline specification of widget attributes, +you may use any of the four approaches discussed in this section. +Each resource name has a global symbol associated with it. This +global symbol has the form XtN\fIresource name\fP. For example, the +symbol for ``foreground'' is \fBXtNforeground\fP. For further information, +see the \fI\*(xT\fP. +.LP +Argument are specified by using the following structure: +.IN "ArgList" "" "@DEF@" +.IN "Arg" "" "@DEF@" +.LP +.Ds 0 +.TA .5i 1.5i +.ta .5i 1.5i +typedef struct { + String name; + XtArgVal value; +} Arg, *ArgList; +.De +.LP +The first approach is to statically initialize the argument list. +For example: +.LP +.Ds 0 +.TA .5i +.ta .5i +static Arg arglist[] = { + {XtNwidth, (XtArgVal) 400}, + {XtNheight, (XtArgVal) 300}, +}; +.De +.LP +This approach is convenient for lists that do not need to be computed +at runtime and makes adding or deleting new elements easy. +The +.IN "XtNumber" +.PN XtNumber +macro is used to compute the number of elements in the argument list, +preventing simple programming errors: +.LP +.Ds +XtCreateWidget(\fIname\fP, \fIclass\fP, \fIparent\fP, \fIarglist\fP, XtNumber(\fIarglist\fP)); +.De +.IN "XtSetArg" "" "@DEF@" +.LP +The second approach is to use the +.PN XtSetArg +macro. +For example: +.LP +.Ds 0 +.TA .5i +.ta .5i +Arg arglist[10]; +XtSetArg(arglist[1], XtNwidth, 400); +XtSetArg(arglist[2], XtNheight, 300); +.De +.LP +To make it easier to insert and delete entries, +you also can use a variable index: +.LP +.Ds 0 +.TA .5i +.ta .5i +Arg arglist[10]; +Cardinal i=0; +XtSetArg(arglist[i], XtNwidth, 400); i++; +XtSetArg(arglist[i], XtNheight, 300); i++; +.De +.LP +The i variable can then be used as the argument list count in the widget +create function. +In this example, +.IN "XtNumber" +.PN XtNumber +would return 10, not 2, and therefore is not useful. +.NT +You should not use auto-increment or auto-decrement +within the first argument to +.PN XtSetArg . +As it is currently implemented, +.PN XtSetArg +is a macro that dereferences the first argument twice. +.NE +.LP +The third approach is to individually set the elements of the +argument list array: +.LP +.Ds 0 +.TA .5i +.ta .5i +Arg arglist[10]; +arglist[0].name = XtNwidth; +arglist[0].value = (XtArgVal) 400; +arglist[1].name = XtNheight; +arglist[1].value = (XtArgVal) 300; +.De +.LP +Note that in this example, as in the previous example, +.IN "XtNumber" +.PN XtNumber +would return 10, not 2, and therefore would not be useful. +.LP +The fourth approach is to use a mixture of the first and third approaches: +you can statically define the argument list but modify some entries at runtime. +For example: +.LP +.Ds 0 +.TA .5i +.ta .5i +static Arg arglist[] = { + {XtNwidth, (XtArgVal) 400}, + {XtNheight, (XtArgVal) NULL}, +}; +arglist[1].value = (XtArgVal) 300; +.De +.LP +In this example, +.IN "XtNumber" +.PN XtNumber +can be used, as in the first approach, for easier code maintenance. +.NH 2 +Example Programs +.XS + Example Programs +.XE +.IN "examples" +.LP +The best way to understand how to use any programming library is by +trying some simple examples. A collection of example programs that +introduces each of the widgets in that Athena widget set, as well as many +important toolkit programming concepts, is available in the X11R6 +release as distributed by the X Consortium. It can be found in the +distribution directory \fBcontrib/examples/mit/Xaw\fP, but see your +site administrator for the exact location of these files on your system. +See the README file from that directory for a guide to the examples. + |