diff options
Diffstat (limited to 'libXaw/spec/CH2')
| -rw-r--r-- | libXaw/spec/CH2 | 1103 |
1 files changed, 0 insertions, 1103 deletions
diff --git a/libXaw/spec/CH2 b/libXaw/spec/CH2 deleted file mode 100644 index 9e6c17a8a..000000000 --- a/libXaw/spec/CH2 +++ /dev/null @@ -1,1103 +0,0 @@ -.\" $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. - |