aboutsummaryrefslogtreecommitdiff
path: root/libXaw/specs/CH2.xml
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2012-04-10 15:05:45 +0200
committermarha <marha@users.sourceforge.net>2012-04-10 15:05:45 +0200
commit4b35ef19b76849cbd854c3b6f92bbc1c2d50f2d8 (patch)
tree3ddf28be6916dd5ea27837431b5be8c94017cd9a /libXaw/specs/CH2.xml
parent5564e91e3cf4ba5cb2fbebbc2d63d18f588016b8 (diff)
parent5f8448ef6b85a9ff72c5af4cec99183c8bb60dc6 (diff)
downloadvcxsrv-4b35ef19b76849cbd854c3b6f92bbc1c2d50f2d8.tar.gz
vcxsrv-4b35ef19b76849cbd854c3b6f92bbc1c2d50f2d8.tar.bz2
vcxsrv-4b35ef19b76849cbd854c3b6f92bbc1c2d50f2d8.zip
Merge remote-tracking branch 'origin/released'
Diffstat (limited to 'libXaw/specs/CH2.xml')
-rw-r--r--libXaw/specs/CH2.xml91
1 files changed, 46 insertions, 45 deletions
diff --git a/libXaw/specs/CH2.xml b/libXaw/specs/CH2.xml
index 08f0ff569..98ac97ee1 100644
--- a/libXaw/specs/CH2.xml
+++ b/libXaw/specs/CH2.xml
@@ -1,5 +1,5 @@
<chapter><title>Using Widgets</title>
-<sect1 id="using_widgets">
+<sect1 id='Using_Widgets'>
<title>Using Widgets</title>
<para>
Widgets serve as the primary tools for building a user interface or
@@ -35,7 +35,7 @@ description of the programming interface is provided in the document
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>
+before <function>XtDisplayInitialize</function> or <xref linkend='XtAppInitialize' xrefstyle='select: title'/>
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.
@@ -69,7 +69,7 @@ of programs in the default "C" locale.
<!-- .XE -->
You must call a toolkit initialization function before invoking any
other toolkit routines (besides locale setting, above).
-<function>XtAppInitialize</function>
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>
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.
@@ -77,7 +77,7 @@ a tree of widgets created by this application.
<!-- .IN "toolkit initialization" "" "@DEF@" -->
<!-- .IN "XtAppInitialize" "" "@DEF@" -->
<!-- .IN "fallback resources" "" "@DEF@" -->
-<funcsynopsis>
+<funcsynopsis id='XtAppInitialize'>
<funcprototype>
<funcdef>Widget<function> XtAppInitialize</function></funcdef>
<paramdef>XtAppContext<parameter> app_context_return</parameter></paramdef>
@@ -126,7 +126,7 @@ first letter of the application name. For example, the application named
Specifies how to parse the command line for any application-specific
resources.
The options argument is passed as a parameter to
-<function>XrmParseCommand</function> .
+<olink targetdoc='libX11' targetptr='XrmParseCommand'><function>XrmParseCommand</function></olink>.
For further information,
see <emphasis remap='I'>Xlib - C Language Interface</emphasis>.
</para>
@@ -220,10 +220,10 @@ 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>
+created for the parent and all its children by using <xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
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
+combined by using <xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>. In addition,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/> is automatically called when the child becomes
managed if the parent is already realized.
</para>
<para>
@@ -231,7 +231,7 @@ managed if the parent is already realized.
To allocate, initialize, and manage a widget, use
<function>XtCreateManagedWidget .</function>
<!-- .IN "XtCreateManagedWidget" "" "@DEF@" -->
-<funcsynopsis>
+<funcsynopsis id='XtCreateManagedWidget'>
<funcprototype>
<funcdef>Widget<function> XtCreateManagedWidget</function></funcdef>
<paramdef>String<parameter> name</parameter></paramdef>
@@ -659,7 +659,7 @@ directory is
<!-- .XE -->
<!-- .IN "realizing widgets" "" "@DEF@" -->
The
-<function>XtRealizeWidget</function>
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
function performs two tasks:
</para>
<itemizedlist>
@@ -675,7 +675,7 @@ for performance reasons.
Creates an X window for the widget and, if it is a composite widget,
realizes each of its managed children.
<!-- .IN "XtRealizeWidget" "" "@DEF@" -->
-<funcsynopsis>
+<funcsynopsis id='XtRealizeWidget'>
<funcprototype>
<funcdef>void<function> XtRealizeWidget</function></funcdef>
<paramdef>Widget<parameter> w</parameter></paramdef>
@@ -708,9 +708,9 @@ see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasi
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>.
+events is <xref linkend='XtAppMainLoop' xrefstyle='select: title'/>.
<!-- .IN "XtAppMainLoop" "" "@DEF@" -->
-<funcsynopsis>
+<funcsynopsis id='XtAppMainLoop'>
<funcprototype>
<funcdef>void<function> XtAppMainLoop</function></funcdef>
<paramdef>XtAppContext<parameter> app_context</parameter></paramdef>
@@ -725,7 +725,7 @@ events is <function>XtAppMainLoop</function>.
<listitem>
<para>
Specifies the application context of this application. The value is
-normally returned by <function>XtAppInitialize</function>.
+normally returned by <xref linkend='XtAppInitialize' xrefstyle='select: title'/>.
</para>
</listitem>
</varlistentry>
@@ -786,13 +786,13 @@ Set an argument value
<!-- .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.
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>. This behavior can be disabled by using
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>, making the client responsible for calling
+<xref linkend='XtMapWidget' xrefstyle='select: title'/> to make the widget viewable.
<!-- .IN "XtSetMappedWhenManaged" "" "@DEF@" -->
<!-- .IN "XtMapWidget" "" "" -->
<!-- .IN "XtRealizeWidget" "" "" -->
-<funcsynopsis>
+<funcsynopsis id='XtSetMappedWhenManaged'>
<funcprototype>
<funcdef>void<function> XtSetMappedWhenManaged</function></funcdef>
<paramdef>Widget<parameter> w</parameter></paramdef>
@@ -821,9 +821,9 @@ 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>
+<xref linkend='XtMapWidget' xrefstyle='select: title'/>
or make a second call to
-<function>XtSetMappedWhenManaged</function>
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>
to cause the child window to be mapped.
</para>
</listitem>
@@ -834,10 +834,10 @@ to cause the child window to be mapped.
<!-- .LP -->
<!-- .sp -->
The definition for
-<function>XtMapWidget</function>
+<xref linkend='XtMapWidget' xrefstyle='select: title'/>
is:
<!-- .IN "XtMapWidget" "" "@DEF@" -->
-<funcsynopsis>
+<funcsynopsis id='XtMapWidget'>
<funcprototype>
<funcdef>void<function> XtMapWidget</function></funcdef>
<paramdef>Widget<parameter> w</parameter></paramdef>
@@ -862,13 +862,13 @@ Specifies the widget.
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
+then use <xref linkend='XtManageChildren' xrefstyle='select: title'/> 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>
+<funcsynopsis id='XtManageChildren'>
<funcprototype>
<funcdef>void<function> XtManageChildren</function></funcdef>
<paramdef>WidgetList<parameter> children</parameter></paramdef>
@@ -916,9 +916,9 @@ see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasi
<para>
<!-- .LP -->
To destroy a widget instance of any type, use
-<function>XtDestroyWidget</function>
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
<!-- .IN "XtDestroyWidget" "" "@DEF@" -->
-<funcsynopsis>
+<funcsynopsis id='XtDestroyWidget'>
<funcprototype>
<funcdef>void<function> XtDestroyWidget</function></funcdef>
<paramdef>Widget<parameter> w</parameter></paramdef>
@@ -940,7 +940,7 @@ Specifies the widget.
</para>
<para>
<!-- .LP -->
-<function>XtDestroyWidget</function>
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
destroys the widget and recursively destroys any children that it may have,
including the windows created by its children.
After calling
@@ -957,7 +957,7 @@ To retrieve the current value of a resource attribute associated
with a widget instance, use
<function>XtGetValues .</function>
<!-- .IN "XtGetValues" "" "@DEF@" -->
-<funcsynopsis>
+<funcsynopsis id='XtGetValues'>
<funcprototype>
<funcdef>void<function> XtGetValues</function></funcdef>
<paramdef>Widget<parameter> w</parameter></paramdef>
@@ -1018,7 +1018,7 @@ To modify the current value of a resource attribute associated with a
widget instance, use
<function>XtSetValues .</function>
<!-- .IN "XtSetValues" "" "@DEF@" -->
-<funcsynopsis>
+<funcsynopsis id='XtSetValues'>
<funcprototype>
<funcdef>void<function> XtSetValues</function></funcdef>
<paramdef>Widget<parameter> w</parameter></paramdef>
@@ -1066,7 +1066,7 @@ Specifies the number of arguments in the argument list.
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
+No notification is given if any part of a <xref linkend='XtSetValues' xrefstyle='select: title'/> request is
ignored.
</para>
<para>
@@ -1076,7 +1076,7 @@ For further information about these functions, see the <emphasis remap='I'>X Too
<!-- .IN "XtSetValues" "" "" -->
<!-- .NT -->
The argument list entry for
-<function>XtGetValues</function>
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
specifies the address to which the caller wants the value copied. The
argument list entry for
<function>XtSetValues ,</function>
@@ -1100,7 +1100,7 @@ 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>
+<funcsynopsis id='CallbackProc'>
<funcprototype>
<funcdef>void<function> CallbackProc</function></funcdef>
<paramdef>Widget<parameter> w</parameter></paramdef>
@@ -1154,7 +1154,7 @@ it passes the current position of the thumb in <emphasis remap='I'>call_data</em
<!-- .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
+routines <xref linkend='XtAddCallback' xrefstyle='select: title'/> 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>
@@ -1191,10 +1191,10 @@ callback when the callback list is executed.
<para>
<!-- .LP -->
The second method for registering callbacks is to use
-<function>XtAddCallback</function>
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>
after the widget has been created.
<!-- .IN "XtAddCallback" "" "@DEF@" -->
-<funcsynopsis>
+<funcsynopsis id='XtAddCallback'>
<funcprototype>
<funcdef>void<function> XtAddCallback</function></funcdef>
<paramdef>Widget<parameter> w</parameter></paramdef>
@@ -1249,7 +1249,7 @@ Specifies the data to be passed to the callback when it is invoked.
</para>
<para>
<!-- .LP -->
-<function>XtAddCallback</function>
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>
adds the specified callback to the list for the named widget.
</para>
<para>
@@ -1310,7 +1310,7 @@ and
<listitem>
<para>
Call the
-<function>XtAppInitialize</function>
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>
<!-- .IN "XtAppInitialize" -->
function before invoking any other toolkit or Xlib functions.
For further information,
@@ -1336,7 +1336,7 @@ For further information, see Section 2.9.2.2. <!-- xref -->
<listitem>
<para>
When the argument list is set up, create the widget with the
-<function>XtCreateManagedWidget</function> function. For further information, see
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/> function. For further information, see
Section 2.2 and the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
<!-- .IN "XtCreateManagedWidget" -->
</para>
@@ -1346,7 +1346,7 @@ Section 2.2 and the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interf
If the widget has any callback routines, set by the
<function>XtNcallback</function>
argument or the
-<function>XtAddCallback</function>
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>
function, declare these routines within the application.
<!-- .IN "XtAddCallback" -->
</para>
@@ -1355,7 +1355,7 @@ function, declare these routines within the application.
<para>
After creating the initial widget hierarchy, windows must be created
for each widget by calling
-<function>XtRealizeWidget</function>
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
on the top level widget.
<!-- .IN "XtRealizeWidget" -->
</para>
@@ -1591,7 +1591,7 @@ This matches any widget in the Foo application that is named <emphasis remap='I'
<para>
<!-- .LP -->
The root of all application widget trees is the widget returned by
-<function>XtAppInitialize</function>. Even though this is actually an
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>. 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
@@ -1880,11 +1880,12 @@ can be used, as in the first approach, for easier code maintenance.
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
+important toolkit programming concepts, is available in the X11R5 contrib
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.
+directory <filename>contrib/examples/Xaw</filename> in the archive
+at <ulink url="http://www.x.org/releases/X11R5/contrib-1.tar.Z" />
+See the <filename>README</filename> file from that directory for a guide
+to the examples.
</para>
</sect2>
</sect1>