diff options
Diffstat (limited to 'libXaw/specs/CH2.xml')
| -rw-r--r-- | libXaw/specs/CH2.xml | 1891 |
1 files changed, 1891 insertions, 0 deletions
diff --git a/libXaw/specs/CH2.xml b/libXaw/specs/CH2.xml new file mode 100644 index 000000000..08f0ff569 --- /dev/null +++ b/libXaw/specs/CH2.xml @@ -0,0 +1,1891 @@ +<chapter><title>Using Widgets</title> +<sect1 id="using_widgets"> +<title>Using Widgets</title> +<para> +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). +</para> +<para> +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 Intrinsics mechanisms, +want to implement alternative application programming interfaces. +</para> +<para> +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 X Toolkit, only one is described here. A full +description of the programming interface is provided in the document +<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +<sect2 id="Setting_the_Locale"> +<title>Setting the Locale</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Setting the Locale --> +<!-- .XE --> +If it is desirable that the application take advantage of +internationalization (i18n), you must establish locale with +<function>XtSetLanguageProc</function> +before <function>XtDisplayInitialize</function> or <function>XtAppInitialize</function> +is called. For full details, please refer to the document +<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>, section 2.2. However, the following simplest-case +call is sufficient in many or most applications. +</para> +<para> +<!-- .LP --> +<!-- .IN "internationalization" "" "" --> +<!-- .IN "XtSetLanguageProc" "" "@DEF@" --> +<!-- .IN "locale" "" "" --> +<literallayout class="monospaced"> +<!-- .TA .5i 2i --> +<!-- .ta .5i 2i --> + XtSetLanguageProc(NULL, NULL, NULL); +</literallayout> +</para> +<para> +<!-- .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. +</para> +</sect2> +<sect2 id="Initializing_the_Toolkit"> +<title>Initializing the Toolkit</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Initializing the Toolkit --> +<!-- .XE --> +You must call a toolkit initialization function before invoking any +other toolkit routines (besides locale setting, above). +<function>XtAppInitialize</function> +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@" --> +<funcsynopsis> +<funcprototype> + <funcdef>Widget<function> XtAppInitialize</function></funcdef> + <paramdef>XtAppContext<parameter> app_context_return</parameter></paramdef> + <paramdef>String<parameter> application_class</parameter></paramdef> + <paramdef>XrmOptionDescRec<parameter> options</parameter></paramdef> + <paramdef>Cardinal<parameter> num_options</parameter></paramdef> + <paramdef>int<parameter> *argc_in_out</parameter></paramdef> + <paramdef>String<parameter> *argv_in_out</parameter></paramdef> + <paramdef>String<parameter> *fallback_resources</parameter></paramdef> + <paramdef>ArgList<parameter> args</parameter></paramdef> + <paramdef>Cardinal<parameter> num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_con_return</emphasis> + </term> + <listitem> + <para> +Returns the application context of this application, if non-NULL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>application_class</emphasis> + </term> + <listitem> + <para> +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''. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>options</emphasis> + </term> + <listitem> + <para> +Specifies how to parse the command line for any application-specific +resources. +The options argument is passed as a parameter to +<function>XrmParseCommand</function> . +For further information, +see <emphasis remap='I'>Xlib - C Language Interface</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_options</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the options list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>argc_in_out</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the number of command line parameters. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>argv_in_out</emphasis> + </term> + <listitem> + <para> +Specifies the command line parameters. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>fallback_resources</emphasis> + </term> + <listitem> + <para> +Specifies resource values to be used if the site-wide application class +defaults file cannot be opened, or NULL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies the argument list to use when creating the Application shell. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of arguments in <emphasis remap='I'>args</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function will remove the command line arguments that the toolkit +reads from <emphasis remap='I'>argc_in_out</emphasis>, and <emphasis remap='I'>argv_in_out</emphasis>. 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 Intrinsics. This function returns an ApplicationShell +widget to be used as the root of the application's widget tree. +</para> +</sect2> +<sect2 id="Creating_a_Widget"> +<title>Creating a Widget</title> +<para> +<!-- .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 <function>XtCreateWidget</function>. Second, the widget's parent is informed +of the new child by using <function>XtManageChild</function>. Finally, X windows are +created for the parent and all its children by using <function>XtRealizeWidget</function> +and specifying the top-most widget. The first two steps can be +combined by using <function>XtCreateManagedWidget</function>. In addition, +<function>XtRealizeWidget</function> is automatically called when the child becomes +managed if the parent is already realized. +</para> +<para> +<!-- .LP --> +To allocate, initialize, and manage a widget, use +<function>XtCreateManagedWidget .</function> +<!-- .IN "XtCreateManagedWidget" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>Widget<function> XtCreateManagedWidget</function></funcdef> + <paramdef>String<parameter> name</parameter></paramdef> + <paramdef>WidgetClass<parameter> widget_class</parameter></paramdef> + <paramdef>Widget<parameter> parent</parameter></paramdef> + <paramdef>ArgList<parameter> args</parameter></paramdef> + <paramdef>Cardinal<parameter> num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>name</emphasis> + </term> + <listitem> + <para> +Specifies the instance name for the created widget that is used for retrieving +widget resources. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>widget_class</emphasis> + </term> + <listitem> + <para> +Specifies the widget class pointer for the created widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>parent</emphasis> + </term> + <listitem> + <para> +Specifies the parent widget ID. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +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. <!-- xref> --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of arguments in the argument list. +If the num_args is zero, the argument list is never referenced. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +When a widget instance is successfully created, the widget identifier +is returned to the application. If an error is encountered, the +<function>XtError</function> +routine is invoked to inform the user of the error. +<!-- .IN "XtError" "" "" --> +</para> +<para> +<!-- .LP --> +For further information, see <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +</sect2> +<sect2 id="Common_Resources"> +<title>Common Resources</title> +<!-- .XS --> +<!-- Common Resources --> +<!-- .XE --> +<!-- .IN "resource" "" --> +<para> +<!-- .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. +</para> +<para> +<!-- .LP --> +The following resources are retrieved from the argument list +or from the resource database by all of the Athena widgets: +<informaltable> + <tgroup cols='4' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <thead> + <row> + <entry>Name</entry> + <entry>Class</entry> + <entry>Type</entry> + <entry>Default Value</entry> + </row> + </thead> + <tbody> + <row> + <entry>accelerators</entry> + <entry>Accelerators</entry> + <entry>AcceleratorTable</entry> + <entry>NULL</entry> + </row> + <row> + <entry>ancestorSensitive</entry> + <entry>AncestorSensitive</entry> + <entry>Boolean</entry> + <entry>True</entry> + </row> + <row> + <entry>background</entry> + <entry>Background</entry> + <entry>Pixel</entry> + <entry>XtDefaultBackground</entry> + </row> + <row> + <entry>backgroundPixmap</entry> + <entry>Pixmap</entry> + <entry>Pixmap</entry> + <entry>XtUnspecifiedPixmap</entry> + </row> + <row> + <entry>borderColor</entry> + <entry>BorderColor</entry> + <entry>Pixel</entry> + <entry>XtDefaultForeground</entry> + </row> + <row> + <entry>borderPixmap</entry> + <entry>Pixmap</entry> + <entry>Pixmap</entry> + <entry>XtUnspecifiedPixmap</entry> + </row> + <row> + <entry>borderWidth</entry> + <entry>BorderWidth</entry> + <entry>Dimension</entry> + <entry>1</entry> + </row> + <row> + <entry>colormap</entry> + <entry>Colormap</entry> + <entry>Colormap</entry> + <entry>Parent's Colormap</entry> + </row> + <row> + <entry>depth</entry> + <entry>Depth</entry> + <entry>int</entry> + <entry>Parent's Depth</entry> + </row> + <row> + <entry>destroyCallback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry>NULL</entry> + </row> + <row> + <entry>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry><emphasis remap='I'>widget dependent</emphasis></entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry>True</entry> + </row> + <row> + <entry>screen</entry> + <entry>Screen</entry> + <entry>Screen</entry> + <entry>Parent's Screen</entry> + </row> + <row> + <entry>sensitive</entry> + <entry>Sensitive</entry> + <entry>Boolean</entry> + <entry>True</entry> + </row> + <row> + <entry>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry><emphasis remap='I'>widget dependent</emphasis></entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry><emphasis remap='I'>widget dependent</emphasis></entry> + </row> + <row> + <entry>x</entry> + <entry>Position</entry> + <entry>Position</entry> + <entry>0</entry> + </row> + <row> + <entry>y</entry> + <entry>Position</entry> + <entry>Position</entry> + <entry>0</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<!-- .IN "XtDefaultForeground" "" "" --> +<!-- .IN "XtDefaultBackground" "" "" --> +</para> +<para> +<!-- .LP --> +The following additional resources are retrieved from the argument list +or from the resource database by many of the Athena widgets: +<informaltable> + <tgroup cols='4' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <thead> + <row> + <entry>Name</entry> + <entry>Class</entry> + <entry>Type</entry> + <entry>Default Value</entry> + </row> + </thead> + <tbody> + <row> + <entry>callback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry>NULL</entry> + </row> + <row> + <entry>cursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry><emphasis remap='I'>widget dependent</emphasis></entry> + </row> + <row> + <entry>foreground</entry> + <entry>Foreground</entry> + <entry>Pixel</entry> + <entry>XtDefaultForeground</entry> + </row> + <row> + <entry>insensitiveBorder</entry> + <entry>Insensitive</entry> + <entry>Pixmap</entry> + <entry>GreyPixmap</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<!-- .IN "XtDefaultForeground" "" "" --> +</para> +</sect2> +<sect2 id="Resource_Conversions"> +<title>Resource Conversions</title> +<!-- .XS --> +<!-- Resource Conversions --> +<!-- .XE --> +<!-- .IN "conversions" "" "@DEF@" --> +<!-- .IN "string conversions" "" "@DEF@" --> +<!-- .IN "type conversions" "" "@DEF@" --> +<para> +<!-- .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: +</para> +<itemizedlist> + <listitem> + <para> +Cursor + </para> + </listitem> + <listitem> + <para> +Pixel + </para> + </listitem> + <listitem> + <para> +Bitmap + </para> + </listitem> +</itemizedlist> +<para> +<!-- .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. +</para> +<sect3 id="Cursor_Conversion"> +<title>Cursor Conversion</title> +<!-- .IN "conversions" "ColorCursor" "@DEF@" --> +<!-- .IN "conversions" "Cursor" "@DEF@" --> +<!-- .IN "cursor" "" "" --> +<para> +<!-- .LP --> +The value for the <function>cursorName</function> resource is specified in the resource +database as a string, and is of the following forms: +</para> +<itemizedlist> + <listitem> + <para> +A standard X cursor name from <function>< X11/cursorfont.h ></function>. +The names in <function>cursorfont.h</function> each describe a specific cursor. The +resource names for these cursors are exactly like the names in this file +except the <function>XC_</function> is not used. The cursor definition <function>XC_gumby</function> +has a resource name of <function>gumby</function>. + </para> + </listitem> + <listitem> + <para> +Glyphs, as in <emphasis remap='I'>FONT font-name glyph-index [[ font-name ] glyph-index ]</emphasis>. +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. + </para> + </listitem> + <listitem> + <para> +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). <!-- xref --> + </para> + </listitem> +</itemizedlist> +</sect3> +<sect3 id="Pixel_Conversion"> +<title>Pixel Conversion</title> +<para> +<!-- .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 <emphasis remap='I'>Xlib - C Language Interface</emphasis>). In addition this routine understands +the special toolkit symbols `XtDefaultForeground' and +`XtDefaultBackground', described in <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. In short the acceptable +pixel names are: +</para> +<itemizedlist> + <listitem> + <para> +Any color name for the rgb.txt file (typically in the directory +/usr/lib/X11 on POSIX systems). + </para> + </listitem> + <listitem> + <para> +A numeric specification of the form #<red><green><blue> where these +numeric values are hexadecimal digits (both upper and lower case). + </para> + </listitem> + <listitem> + <para> +The special strings `XtDefaultForeground' and `XtDefaultBackground' + </para> + </listitem> +</itemizedlist> +</sect3> +<sect3 id="Bitmap_Conversion"> +<title>Bitmap Conversion</title> +<!-- .IN "bitmap conversions" "" "@DEF@" --> +<!-- .IN "conversions" "Bitmap" "@DEF@" --> +<!-- .IN "bitmapFilePath" "" "@DEF@" --> +<!-- .IN "BitmapFilePath" "" "@DEF@" --> +<!-- .IN "/usr/include/X11/bitmaps" "" "" --> +<para> +<!-- .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 <function>bitmapFilePath</function> resource--class +<function>BitmapFilePath</function>. 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 <function>bitmapFilePath</function> resource is +global to the application, and may <function>not</function> be specified differently +for each widget that wishes to convert a cursor to bitmap. In addition +to the directories specified in the <function>bitmapFilePath</function> resource a +default directory is searched. When using POSIX the default +directory is +<function>/usr/include/X11/bitmaps .</function> +</para> +</sect3> +</sect2> +<sect2 id="Realizing_a_Widget"> +<title>Realizing a Widget</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Realizing a Widget --> +<!-- .XE --> +<!-- .IN "realizing widgets" "" "@DEF@" --> +The +<function>XtRealizeWidget</function> +function performs two tasks: +</para> +<itemizedlist> + <listitem> + <para> +Calculates the geometry constraints of all managed descendants +of this widget. The actual calculation is put off until realize time +for performance reasons. + </para> + </listitem> + <listitem> + <para> +Creates an X window for the widget and, if it is a composite widget, +realizes each of its managed children. +<!-- .IN "XtRealizeWidget" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtRealizeWidget</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> + </para> + </listitem> + <listitem> + <para> +Specifies the widget. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +For further information about this function, +see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +</sect2> +<sect2 id="Processing_Events"> +<title>Processing Events</title> +<para> +<!-- .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 <function>XtAppMainLoop</function>. +<!-- .IN "XtAppMainLoop" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtAppMainLoop</function></funcdef> + <paramdef>XtAppContext<parameter> app_context</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context of this application. The value is +normally returned by <function>XtAppInitialize</function>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .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 +<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +</sect2> +<sect2 id="Standard_Widget_Manipulation_Functions"> +<title>Standard Widget Manipulation Functions</title> +<!-- .XS --> +<!-- Standard Widget Manipulation Functions --> +<!-- .XE --> +<para> +<!-- .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 Intrinsics, or a widget class-specific manipulation routine. +</para> +<para> +<!-- .LP --> +The Intrinsics 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. +</para> +<itemizedlist> + <listitem> + <para> +Control the mapping of widget windows + </para> + </listitem> + <listitem> + <para> +Destroy a widget instance + </para> + </listitem> + <listitem> + <para> +Obtain an argument value + </para> + </listitem> + <listitem> + <para> +Set an argument value + </para> + </listitem> +</itemizedlist> +<sect3 id="Mapping_Widgets"> +<title>Mapping Widgets</title> +<para> +<!-- .LP --> +By default, +widget windows are mapped (made viewable) automatically by +<function>XtRealizeWidget</function>. This behavior can be disabled by using +<function>XtSetMappedWhenManaged</function>, making the client responsible for calling +<function>XtMapWidget</function> to make the widget viewable. +<!-- .IN "XtSetMappedWhenManaged" "" "@DEF@" --> +<!-- .IN "XtMapWidget" "" "" --> +<!-- .IN "XtRealizeWidget" "" "" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtSetMappedWhenManaged</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>Boolean<parameter> map_when_managed</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>map_when_managed</emphasis> + </term> + <listitem> + <para> +Specifies the new value. +If map_when_managed is <function>True</function>, the widget is mapped automatically +when it is realized. If map_when_managed is <function>False</function>, the client +must call +<function>XtMapWidget</function> +or make a second call to +<function>XtSetMappedWhenManaged</function> +to cause the child window to be mapped. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .sp --> +The definition for +<function>XtMapWidget</function> +is: +<!-- .IN "XtMapWidget" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtMapWidget</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .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 <function>XtCreateWidget</function>) and +then use <function>XtManageChildren</function> 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" "" "" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtManageChildren</function></funcdef> + <paramdef>WidgetList<parameter> children</parameter></paramdef> + <paramdef>Cardinal<parameter> num_children</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>children</emphasis> + </term> + <listitem> + <para> +Specifies a list of children to add. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_children</emphasis> + </term> + <listitem> + <para> +Specifies the number of children to add. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .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. +</para> +<para> +<!-- .LP --> +For further information about these functions, +see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +</sect3> +<sect3 id="Destroying_Widgets"> +<title>Destroying Widgets</title> +<para> +<!-- .LP --> +To destroy a widget instance of any type, use +<function>XtDestroyWidget</function> +<!-- .IN "XtDestroyWidget" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtDestroyWidget</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<function>XtDestroyWidget</function> +destroys the widget and recursively destroys any children that it may have, +including the windows created by its children. +After calling +<function>XtDestroyWidget ,</function> +no further references should be made to the widget or any children +that the destroyed widget may have had. +</para> +</sect3> +<sect3 id="Retrieving_Widget_Resource_Values"> +<title>Retrieving Widget Resource Values</title> +<para> +<!-- .LP --> +To retrieve the current value of a resource attribute associated +with a widget instance, use +<function>XtGetValues .</function> +<!-- .IN "XtGetValues" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtGetValues</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>ArgList<parameter> args</parameter></paramdef> + <paramdef>Cardinal<parameter> num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies a variable-length argument list of name and <function>address</function> +pairs that contain the resource name and the address into which the +resource value is stored. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of arguments in the argument list. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .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 <function>ArgList</function> +contains a pointer to this storage (e.g. x and y must be +allocated as Position). For further information, see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +</sect3> +<sect3 id="Modifying_Widget_Resource_Values"> +<title>Modifying Widget Resource Values</title> +<para> +<!-- .LP --> +To modify the current value of a resource attribute associated with a +widget instance, use +<function>XtSetValues .</function> +<!-- .IN "XtSetValues" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtSetValues</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>ArgList<parameter> args</parameter></paramdef> + <paramdef>Cardinal<parameter> num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies an array of name and <function>value</function> pairs that contain the +arguments to be modified and their new values. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of arguments in the argument list. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .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 <function>XtSetValues</function> request is +ignored. +</para> +<para> +<!-- .LP --> +For further information about these functions, see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +<!-- .IN "XtGetValues" "" "" --> +<!-- .IN "XtSetValues" "" "" --> +<!-- .NT --> +The argument list entry for +<function>XtGetValues</function> +specifies the address to which the caller wants the value copied. The +argument list entry for +<function>XtSetValues ,</function> +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 --> +</para> +</sect3> +</sect2> +<sect2 id="Using_the_Client_Callback_Interface"> +<title>Using the Client Callback Interface</title> +<para> +<!-- .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@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> CallbackProc</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XtPointer<parameter> client_data</parameter></paramdef> + <paramdef>XtPointer<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies widget for which the callback is registered. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +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 <emphasis remap='I'>closure</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Specifies any callback-specific data the widget wants to pass to the client. +For example, when Scrollbar executes its <function>jumpProc</function> callback list, +it passes the current position of the thumb in <emphasis remap='I'>call_data</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +Callbacks can be registered either by creating an argument containing +the callback list described below or by using the special convenience +routines <function>XtAddCallback</function> and <function>XtAddCallbacks</function>. When the widget +is created, a pointer to a list of callback procedure and data pairs can +be passed in the argument list to +<function>XtCreateWidget .</function> +The list is of type +<function>XtCallbackList :</function> +<!-- .IN "XtCallbackProc" --> +<!-- .IN "XtAddCallbacks" --> +<!-- .IN "XtAddCallback" --> +<!-- .IN "XtCallbackList" "" "@DEF@" --> +<!-- .IN "XtCallbackRec" "" "@DEF@" --> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + XtCallbackProc callback; + XtPointer closure; +} XtCallbackRec, *XtCallbackList; +</literallayout> +</para> +<para> +<!-- .LP --> +The callback list must be allocated and initialized before calling +<function>XtCreateWidget .</function> +<!-- .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. +</para> +<para> +<!-- .LP --> +The second method for registering callbacks is to use +<function>XtAddCallback</function> +after the widget has been created. +<!-- .IN "XtAddCallback" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtAddCallback</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>String<parameter> callback_name</parameter></paramdef> + <paramdef>XtCallbackProc<parameter> callback</parameter></paramdef> + <paramdef>XtPointer<parameter> client_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget to add the callback to. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>callback_name</emphasis> + </term> + <listitem> + <para> +Specifies the callback list within the widget to append to. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>callback</emphasis> + </term> + <listitem> + <para> +Specifies the callback procedure to add. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the data to be passed to the callback when it is invoked. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<function>XtAddCallback</function> +adds the specified callback to the list for the named widget. +</para> +<para> +<!-- .LP --> +All widgets provide a callback list named +<function>destroyCallback</function> +<!-- .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 <emphasis remap='I'>call_data</emphasis> argument is unused for +destroy callbacks. +</para> +</sect2> +<sect2 id="Programming_Considerations"> +<title>Programming Considerations</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Programming Considerations --> +<!-- .XE --> +This section provides some guidelines on how to set up an application +program that uses the X Toolkit. +</para> +<sect3 id="Writing_Applications"> +<title>Writing Applications</title> +<para> +<!-- .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: +</para> +<orderedlist> + <listitem> + <para> +Include +<function>< X11/Intrinsic.h ></function> +in your application programs. +This header file automatically includes +<function>< X11/Xlib.h >,</function> +so all Xlib functions also are defined. +It may also be necessary to include <function>< X11/StringDefs.h ></function> when setting +up argument lists, as many of the XtN<emphasis remap='I'>something</emphasis> definitions are +only defined in this file. + </para> + </listitem> + <listitem> + <para> +Include the widget-specific header files for each widget type +that you need to use. +For example, +<function>< X11/Xaw/Label.h ></function> +and +<function>< X11/Xaw/Command.h >.</function> + </para> + </listitem> + <listitem> + <para> +Call the +<function>XtAppInitialize</function> +<!-- .IN "XtAppInitialize" --> +function before invoking any other toolkit or Xlib functions. +For further information, +see Section 2.1 and the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. + </para> + </listitem> + <listitem> + <para> +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 <function>XtN</function> to help catch spelling errors. For example, +<function>XtNlabel</function> is defined for the <function>label</function> resource of many widgets. +<!-- .IN "XtN" "" "@DEF@" --> + </para> + </listitem> + <listitem> + <para> +For further information, see Section 2.9.2.2. <!-- xref --> + </para> + </listitem> + <listitem> + <para> +When the argument list is set up, create the widget with the +<function>XtCreateManagedWidget</function> function. For further information, see +Section 2.2 and the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +<!-- .IN "XtCreateManagedWidget" --> + </para> + </listitem> + <listitem> + <para> +If the widget has any callback routines, set by the +<function>XtNcallback</function> +argument or the +<function>XtAddCallback</function> +function, declare these routines within the application. +<!-- .IN "XtAddCallback" --> + </para> + </listitem> + <listitem> + <para> +After creating the initial widget hierarchy, windows must be created +for each widget by calling +<function>XtRealizeWidget</function> +on the top level widget. +<!-- .IN "XtRealizeWidget" --> + </para> + </listitem> + <listitem> + <para> +Most applications now sit in a loop processing events using +<function>XtAppMainLoop ,</function> +for example: +<!-- .IN "XtAppMainLoop" --> + </para> + </listitem> + <listitem> + <para> +<literallayout class="monospaced"> +XtCreateManagedWidget(<emphasis remap='I'>name</emphasis>, <emphasis remap='I'>class</emphasis>, <emphasis remap='I'>parent</emphasis>, <emphasis remap='I'>args</emphasis>, <emphasis remap='I'>num_args</emphasis>); +XtRealizeWidget(<emphasis remap='I'>shell</emphasis>); +XtAppMainLoop(<emphasis remap='I'>app_context</emphasis>); +</literallayout> + </para> + </listitem> + <listitem> + <para> +For information about this function, see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. + </para> + </listitem> + <listitem> + <para> +Link your application with +<function>libXaw</function> +(the Athena widgets), +<function>libXmu</function> +(miscellaneous utilities), +<function>libXt</function> +(the X Toolkit Intrinsics), +<function>libSM</function> +(Session Management), +<function>libICE</function> +(Inter-Client Exchange), +<function>libXext</function> +(the extension library needed for the shape extension code which allows +rounded Command buttons), and +<function>libX11</function> +(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" --> + </para> + </listitem> + <listitem> + <para> +<literallayout class="monospaced"> +cc -o <emphasis remap='I'>application</emphasis> <emphasis remap='I'>application</emphasis>.c \-lXaw \-lXmu \-lXt \ +\-lSM \-lICE \-lXext \-lX11 +</literallayout> + </para> + </listitem> +</orderedlist> +</sect3> +<sect3 id="Changing_Resource_Values"> +<title>Changing Resource Values</title> +<!-- .IN "resource" "" --> +<para> +<!-- .LP --> +The Intrinsics 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. +<variablelist> + <varlistentry> + <term>Resource Manager</term> + <listitem> + <para> +This method picks up resource definitions described in <emphasis remap='I'>Xlib - C Language Interface</emphasis> from +many different locations at run time. The locations most important to +the application programmer are the <emphasis remap='I'>fallback resources</emphasis> and the +<emphasis remap='I'>app-defaults</emphasis> file, (see <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis> 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Argument Lists</term> + <listitem> + <para> +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. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<sect4 id="Specifying_Resources"> +<title>Specifying Resources</title> +<para> +<!-- .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" --> +<variablelist> + <varlistentry> + <term> + <function>Xrdb</function> + </term> + <listitem> + <para> +The <function>xrdb</function> 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" --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Application Defaults</term> + <listitem> + <para> +The application defaults (app-defaults) file (normally in +/usr/lib/X11/app-defaults/<emphasis remap='I'>classname</emphasis>) for an application is loaded +whenever the application is started. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +The resource specification has two colon-separated parts, a name, and +a value. The <emphasis remap='I'>value</emphasis> is a string whose format is dependent on the +resource specified by <emphasis remap='I'>name</emphasis>. <emphasis remap='I'>Name</emphasis> is constructed by +appending a resource name to a full widget name. +</para> +<para> +<!-- .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: +<variablelist> + <varlistentry> + <term> + xman.form.button1 + </term> + <listitem> + <para> +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.) + + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Xman.Form.Command + </term> + <listitem> + <para> +This will match any Command widget that is a child of a Form widget +that is itself a child of an application of class <emphasis remap='I'>Xman</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Xman.Form.button1 + </term> + <listitem> + <para> +This is a mixed resource name with both widget names and classes specified. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .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: +<variablelist> + <varlistentry> + <term> + Xman*Command + </term> + <listitem> + <para> +This matches all Command widgets in the Xman application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Foo*button1 + </term> + <listitem> + <para> +This matches any widget in the Foo application that is named <emphasis remap='I'>button1</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +The root of all application widget trees is the widget returned by +<function>XtAppInitialize</function>. 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 (<function>argv[0]</function>) or the name of +the application specified using the standard <emphasis remap='I'>-name</emphasis> command line +option supported by the Intrinsics. +</para> +<para> +<!-- .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. +<variablelist> + <varlistentry> + <term> + *foreground:Blue + </term> + <listitem> + <para> +Specifies that all widgets in all applications will have a foreground +color of blue. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Xman*borderWidth:10 + </term> + <listitem> + <para> +Specifies that all widgets in an application whose class is Xman will +have a border width of 10 (pixels). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + xman.form.button1.label:Testing + </term> + <listitem> + <para> +Specifies that a particular widget in the xman application will have a +label named <emphasis remap='I'>Testing</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +An exclamation point (!) in the first column of a line indicates +that the rest of the line should be treated as a comment. +</para> +<para> +<!-- .LP --> +<function>Final Words</function> +</para> +<para> +<!-- .LP --> +The Resource manager is a powerful tool that can be used very +effectively to customize X Toolkit applications at run time by either the +application programmer or the user. Some final points to note: +</para> +<itemizedlist> + <listitem> + <para> +An application programmer may add new resources to their +application. These resources are associated with the global +application, and not any particular widget. The X Toolkit function used for +adding the application resources is <function>XtGetApplicationResources</function>. +<!-- .IN "XtGetApplicationResources" --> + </para> + </listitem> + <listitem> + <para> +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. + </para> + </listitem> + <listitem> + <para> +Only one resource line will match any given resource. There is a set +of precedence rules, which take the following general stance. +<!-- .ta 10n --> + </para> + </listitem> + <listitem> + <itemizedlist> + <listitem> + <para> +More specific overrides less specific, thus period always overrides asterisk. + </para> + </listitem> + <listitem> + <para> +Names on the left are more specific and override names on the right. + </para> + </listitem> + <listitem> + <para> +When resource specifications are exactly the same, user defaults +will override program defaults. + </para> + </listitem> + </itemizedlist> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +For a complete explanation of the rules of precedence, and +other specific topics see <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis> and <emphasis remap='I'>Xlib - C Language Interface</emphasis>. +</para> +</sect4> +<sect4 id="Creating_Argument_Lists"> +<title>Creating Argument Lists</title> +<!-- .IN "argument lists" "" "@DEF@" --> +<para> +<!-- .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<emphasis remap='I'>resource name</emphasis>. For example, the +symbol for ``foreground'' is <function>XtNforeground</function>. For further information, +see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +<para> +<!-- .LP --> +Argument are specified by using the following structure: +<!-- .IN "ArgList" "" "@DEF@" --> +<!-- .IN "Arg" "" "@DEF@" --> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i 1.5i --> +<!-- .ta .5i 1.5i --> +typedef struct { + String name; + XtArgVal value; +} Arg, *ArgList; +</literallayout> +</para> +<para> +<!-- .LP --> +The first approach is to statically initialize the argument list. +For example: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +static Arg arglist[] = { + {XtNwidth, (XtArgVal) 400}, + {XtNheight, (XtArgVal) 300}, +}; +</literallayout> +</para> +<para> +<!-- .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" --> +<function>XtNumber</function> +macro is used to compute the number of elements in the argument list, +preventing simple programming errors: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +XtCreateWidget(<emphasis remap='I'>name</emphasis>, <emphasis remap='I'>class</emphasis>, <emphasis remap='I'>parent</emphasis>, <emphasis remap='I'>arglist</emphasis>, XtNumber(<emphasis remap='I'>arglist</emphasis>)); +</literallayout> +<!-- .IN "XtSetArg" "" "@DEF@" --> +</para> +<para> +<!-- .LP --> +The second approach is to use the +<function>XtSetArg</function> +macro. +For example: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +Arg arglist[10]; +XtSetArg(arglist[1], XtNwidth, 400); +XtSetArg(arglist[2], XtNheight, 300); +</literallayout> +</para> +<para> +<!-- .LP --> +To make it easier to insert and delete entries, +you also can use a variable index: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +Arg arglist[10]; +Cardinal i=0; +XtSetArg(arglist[i], XtNwidth, 400); i++; +XtSetArg(arglist[i], XtNheight, 300); i++; +</literallayout> +</para> +<para> +<!-- .LP --> +The i variable can then be used as the argument list count in the widget +create function. +In this example, +<!-- .IN "XtNumber" --> +<function>XtNumber</function> +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 +<function>XtSetArg .</function> +As it is currently implemented, +<function>XtSetArg</function> +is a macro that dereferences the first argument twice. +<!-- .NE --> +</para> +<para> +<!-- .LP --> +The third approach is to individually set the elements of the +argument list array: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .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; +</literallayout> +</para> +<para> +<!-- .LP --> +Note that in this example, as in the previous example, +<!-- .IN "XtNumber" --> +<function>XtNumber</function> +would return 10, not 2, and therefore would not be useful. +</para> +<para> +<!-- .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: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +static Arg arglist[] = { + {XtNwidth, (XtArgVal) 400}, + {XtNheight, (XtArgVal) NULL}, +}; +arglist[1].value = (XtArgVal) 300; +</literallayout> +</para> +<para> +<!-- .LP --> +In this example, +<!-- .IN "XtNumber" --> +<function>XtNumber</function> +can be used, as in the first approach, for easier code maintenance. +</para> +</sect4> +</sect3> +</sect2> +<sect2 id="Example_Programs"> +<title>Example Programs</title> +<!-- .XS --> +<!-- Example Programs --> +<!-- .XE --> +<!-- .IN "examples" --> +<para> +<!-- .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 <function>contrib/examples/mit/Xaw</function>, 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. +</para> +</sect2> +</sect1> +</chapter> |