<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
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.
<!-- .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.
<!-- .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>
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>
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>
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>
<!-- .XE -->
<!-- .IN "realizing widgets" "" "@DEF@" -->
The
-<function>XtRealizeWidget</function>
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
function performs two tasks:
</para>
<itemizedlist>
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>
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>
<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>
<!-- .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>
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>
<!-- .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>
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>
<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>
</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
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>
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>
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>
<!-- .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>
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>
<!-- .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>
<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>
</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>
<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,
<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>
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>
<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>
<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
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>
projects / framework / uifw / xorg / lib / libxaw.git / blobdiff