Index: create.patch.sh
===================================================================
--- create.patch.sh (nonexistent)
+++ create.patch.sh (revision 5)
@@ -0,0 +1,15 @@
+#!/bin/sh
+
+VERSION=1.0.14
+
+tar --files-from=file.list -xjvf ../libXaw-$VERSION.tar.bz2
+mv libXaw-$VERSION libXaw-$VERSION-orig
+
+cp -rf ./libXaw-$VERSION-new ./libXaw-$VERSION
+
+diff --unified -Nr libXaw-$VERSION-orig libXaw-$VERSION > libXaw-$VERSION-docbook.patch
+
+mv libXaw-$VERSION-docbook.patch ../patches
+
+rm -rf ./libXaw-$VERSION
+rm -rf ./libXaw-$VERSION-orig
Property changes on: create.patch.sh
___________________________________________________________________
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
Index: file.list
===================================================================
--- file.list (nonexistent)
+++ file.list (revision 5)
@@ -0,0 +1,7 @@
+libXaw-1.0.14/specs/CH1.xml
+libXaw-1.0.14/specs/CH2.xml
+libXaw-1.0.14/specs/CH6.xml
+libXaw-1.0.14/specs/CH7.xml
+libXaw-1.0.14/specs/Grip.xml
+libXaw-1.0.14/specs/SimpleMenu.xml
+libXaw-1.0.14/specs/TextSink.xml
Index: libXaw-1.0.14-new/specs/CH1.xml
===================================================================
--- libXaw-1.0.14-new/specs/CH1.xml (nonexistent)
+++ libXaw-1.0.14-new/specs/CH1.xml (revision 5)
@@ -0,0 +1,642 @@
+<chapter id='Athena_Widgets_and_The_Intrinsics'>
+<title>Athena Widgets and The Intrinsics</title>
+<para>
+The X Toolkit is made up of two distinct pieces, the Xt Intrinsics and a
+widget set. The Athena widget set is a sample implementation of a
+widget set built upon the Intrinsics. In the X Toolkit, a widget is the
+combination of an X window or subwindow and its associated input and
+output semantics.
+</para>
+<para>
+Because the Intrinsics provide the same basic functionality to all widget
+sets it may be possible to use widgets from the Athena widget set with
+other widget sets based upon the Intrinsics. Since widget sets may also
+implement private protocols, all functionality may not be available when
+mixing and matching widget sets. For information about the Intrinsics, see
+the
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>.
+</para>
+<para>
+The Athena widget set is a library package layered on top of the Intrinsics
+and Xlib that provides a set of user interface tools sufficient to build
+a wide variety of applications. This layer extends the basic
+abstractions provided by X and provides the next layer of functionality
+primarily by supplying a cohesive set of sample widgets. Although the
+Intrinsics are a Consortium standard, there is no standard widget set.
+</para>
+
+<para>
+To the extent possible, the Intrinsics are "policy-free". The application
+environment and widget set, not the Intrinsics, define, implement, and
+enforce:
+</para>
+
+<itemizedlist>
+ <listitem><para>Policy</para></listitem>
+ <listitem><para>Consistency</para></listitem>
+ <listitem><para>Style</para></listitem>
+</itemizedlist>
+
+<para>
+Each individual widget implementation defines its own policy. The X Toolkit
+design allows for, but does not necessarily encourage, the free mixing
+of radically differing widget implementations.
+</para>
+
+<sect1 id='Introduction_to_the_X_Toolkit'>
+<title>Introduction to the X Toolkit</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Introduction to the X Toolkit -->
+<!-- .XE -->
+<indexterm significance="preferred"><primary>introduction</primary></indexterm>
+The X Toolkit provides tools that simplify the design of
+application user interfaces in the X Window System programming environment.
+It assists application programmers by providing a set of common
+underlying user-interface functions. It also lets widget programmers
+modify existing widgets, by subclassing, or add new widgets. By using
+the X Toolkit in their applications, programmers can present a similar
+user interface across applications to all workstation users.
+</para>
+<para>
+<!-- .LP -->
+The X Toolkit consists of:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A set of Intrinsics functions for building widgets
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+An architectural model for constructing widgets
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A widget set for application programming
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+While the majority of the Intrinsics functions are intended
+for the widget programmer,
+a subset of the Intrinsics functions are to be used by application programmers
+(see
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>).
+The architectural model lets the widget programmer design new widgets
+by using the Intrinsics and by combining other widgets.
+The application interface layers built on top of the X Toolkit include a
+coordinated set of widgets and composition policies.
+Some of these widgets and policies are specific to a single
+application domain, and others are common to a variety of
+applications.
+</para>
+<para>
+<!-- .LP -->
+The remainder of this chapter discusses the X Toolkit and Athena widget set:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Terminology
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Model
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Conventions used in this manual
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Format of the Widget Reference Chapters
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Terminology">
+<title>Terminology</title>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Terminology -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+In addition to the terms already defined for X programming (see
+
+<citetitle>Xlib - C Language Interface</citetitle>),
+the following terms are specific to the Intrinsics and Athena widget set
+and used throughout this document.
+</para>
+<glosslist>
+<glossentry>
+ <glossterm>Application programmer</glossterm>
+<indexterm significance="preferred"><primary>application programmer</primary></indexterm>
+ <glossdef>
+ <para>
+A programmer who uses the X Toolkit to produce an application user interface.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Child</glossterm>
+<indexterm significance="preferred"><primary>child</primary></indexterm>
+ <glossdef>
+ <para>
+A widget that is contained within another "parent" widget.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Class</glossterm>
+<indexterm significance="preferred"><primary>class</primary></indexterm>
+ <glossdef>
+ <para>
+The general group to which a specific object belongs.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Client</glossterm>
+<indexterm significance="preferred"><primary>client</primary></indexterm>
+ <glossdef>
+ <para>
+A function that uses a widget in an application or for composing
+other widgets.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>FullName</glossterm>
+<indexterm significance="preferred"><primary>FullName</primary></indexterm>
+ <glossdef>
+ <para>
+The name of a widget instance appended to the full name of its parent.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Instance</glossterm>
+<indexterm significance="preferred"><primary>instance</primary></indexterm>
+ <glossdef>
+ <para>
+A specific widget object as opposed to a general widget class.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Method</glossterm>
+<indexterm significance="preferred"><primary>method</primary></indexterm>
+ <glossdef>
+ <para>
+A function or procedure implemented by a widget class.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Name</glossterm>
+<indexterm significance="preferred"><primary>name</primary><secondary>widget</secondary></indexterm>
+ <glossdef>
+ <para>
+The name that is specific to an instance of a widget for a given client.
+This name is specified at creation time and cannot be modified.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Object</glossterm>
+<indexterm significance="preferred"><primary>object</primary></indexterm>
+ <glossdef>
+ <para>
+A data abstraction consisting of private data and private and public
+functions that operate on the private data.
+Users of the abstraction can interact with the object only through calls
+to the object's public functions.
+In the X Toolkit,
+some of the object's public functions are called directly by the application,
+while others are called indirectly when the application calls the common
+Intrinsics functions.
+In general, if a function is common to all widgets,
+an application uses a single Intrinsics function to invoke the function for all
+types of widgets.
+If a function is unique to a single widget type,
+the widget exports the function.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Parent</glossterm>
+<indexterm significance="preferred"><primary>parent</primary></indexterm>
+ <glossdef>
+ <para>
+A widget that contains at least one other ("child") widget.
+A parent widget is also known as a composite widget.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Resource</glossterm>
+<indexterm significance="preferred"><primary>resource</primary></indexterm>
+ <glossdef>
+ <para>
+A named piece of data in a widget that can be set by a client,
+by an application, or by user defaults.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Superclass</glossterm>
+<indexterm significance="preferred"><primary>superclass</primary></indexterm>
+ <glossdef>
+ <para>
+A larger class of which a specific class is a member.
+All members of a class are also members of the superclass.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>User</glossterm>
+<indexterm significance="preferred"><primary>user</primary></indexterm>
+ <glossdef>
+ <para>
+A person interacting with a workstation.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Widget</glossterm>
+<indexterm significance="preferred"><primary>widget</primary></indexterm>
+ <glossdef>
+ <para>
+An object providing a user-interface abstraction (for example, a Scrollbar
+widget).
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Widget class</glossterm>
+<indexterm significance="preferred"><primary>widget class</primary></indexterm>
+ <glossdef>
+ <para>
+The general group to which a specific widget belongs,
+otherwise known as the type of the widget.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry>
+ <glossterm>Widget programmer</glossterm>
+<indexterm significance="preferred"><primary>widget programmer</primary></indexterm>
+ <glossdef>
+ <para>
+A programmer who adds new widgets to the X Toolkit.
+ </para>
+ </glossdef>
+</glossentry>
+</glosslist>
+</sect1>
+<sect1 id="Underlying_Model">
+<title>Underlying Model</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Underlying Model -->
+<!-- .XE -->
+<indexterm significance="preferred"><primary>underlying model</primary></indexterm>
+The underlying architectural model is based on the following premises:
+<!-- .KS -->
+</para>
+<variablelist><?dbfo list-presentation="blocks"?>
+<varlistentry>
+ <term>Widgets are X windows</term>
+ <listitem>
+ <para>
+Every user-interface widget is associated with an X window.
+The X window ID for a widget is readily available from the widget.
+Standard Xlib calls can be used by widgets for many of their input and
+output operations.
+<!-- .KE -->
+<!-- .KS -->
+ </para>
+ </listitem>
+</varlistentry>
+<varlistentry>
+ <term>Information hiding</term>
+ <listitem>
+ <para>
+The data for every widget is private to the widget and its subclasses.
+That is, the data is neither directly accessible
+nor visible outside of the module implementing the widget.
+All program interaction with the widget is performed by a set of operations
+(methods) that are defined for the widget.
+<!-- .KE -->
+<!-- .KS -->
+ </para>
+ </listitem>
+</varlistentry>
+<varlistentry>
+ <term>Widget semantics and widget layout geometry</term>
+ <listitem>
+ <para>
+Widget semantics are clearly separated from widget layout geometry.
+Widgets are concerned with implementing specific user-interface
+semantics. They have little control over issues such as their size or
+placement relative to other widget peers. Mechanisms are provided for
+associating geometric managers with widgets and for widgets to make
+suggestions about their own geometry.
+<!-- .KE -->
+ </para>
+ </listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+<sect1 id="Conventions_Used_in_this_Manual">
+<title>Conventions Used in this Manual</title>
+<itemizedlist>
+ <listitem>
+ <para>
+<indexterm significance="preferred"><primary>conventions</primary><secondary>used in manual</secondary></indexterm>
+All resources available to the widgets are listed with each widget. Many
+of these are available to more than one widget class due to the object
+oriented nature of the Intrinsics. The new resources for each widget are
+listed in bold text, and the inherited resources are listed in plain text.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Global symbols are printed in <function>bold</function> and can be function names,
+symbols defined in include files, or structure names. Arguments are
+printed in <emphasis remap='I'>italics</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Each function is introduced by a general discussion that distinguishes
+it from other functions. The function declaration itself follows, and
+each argument is specifically explained. General discussion of the
+function, if any is required, follows the arguments. Where
+applicable, the last paragraph of the explanation lists the return values
+of the function.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To eliminate any ambiguity between those arguments that you pass and
+those that a function returns to you, the explanations for all
+arguments that you pass start with the word <emphasis remap='I'>specifies</emphasis> or, in the
+case of multiple arguments, the word <emphasis remap='I'>specify</emphasis>. The explanations
+for all arguments that are returned to you start with the word
+<emphasis remap='I'>returns</emphasis> or, in the case of multiple arguments, the word
+<emphasis remap='I'>return</emphasis>. The explanations for all arguments that you can pass
+and are returned start with the words <emphasis remap='I'>specifies and returns</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Any pointer to a structure that is used to return a value is
+designated as such by the <emphasis remap='I'>_return</emphasis> suffix as part of its name.
+All other pointers passed to these functions are used for reading
+only. A few arguments use pointers to structures that are used for
+both input and output and are indicated by using the <emphasis remap='I'>_in_out</emphasis>
+suffix.
+<indexterm significance="preferred"><primary>_return</primary></indexterm>
+<indexterm significance="preferred"><primary>_in_out</primary></indexterm>
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Format_of_the_Widget_Reference_Chapters">
+<title>Format of the Widget Reference Chapters</title>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>conventions</primary><secondary>chapter format</secondary></indexterm>
+<indexterm significance="preferred"><primary>chapter format</primary></indexterm>
+The majority of this document is a reference guide for the Athena
+widget set. Chapters three through six give the programmer all
+information necessary to use the widgets. The layout of the chapters
+follows a specific pattern to allow the programmer to easily find the
+desired information.
+</para>
+<para>
+<!-- .LP -->
+The first few pages of every chapter give an overview of the widgets
+in that section. Widgets are grouped into chapters by functionality.
+<itemizedlist>
+ <listitem><para><xref linkend='Simple_Widgets'/></para></listitem>
+ <listitem><para><xref linkend='Menus'/></para></listitem>
+ <listitem><para><xref linkend='Text_Widgets'/></para></listitem>
+ <listitem><para><xref linkend='Composite_and_Constraint_Widgets'/></para></listitem>
+</itemizedlist>
+</para>
+<para>
+<!-- .LP -->
+Following the introduction will be a description of each widget in that
+chapter. When no functional grouping is obvious the widgets are listed
+in alphabetical order, such as in chapters three and six.
+</para>
+<para>
+<!-- .LP -->
+The first section of each widget's description is a table that
+contains general information about this widget class. Here is the
+table for the Box widget, and an explanation of all the entries.
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application Header file <X11/Xaw/Box.h>
+Class Header file <X11/Xaw/BoxP.h>
+Class boxWidgetClass
+Class Name Box
+Superclass Composite
+<!-- .sp -->
+</literallayout>
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>Application Header File</function>
+ </term>
+ <listitem>
+ <para>
+<indexterm significance="preferred"><primary>application header file</primary></indexterm>
+This file must be included when an application uses this widget.
+It usually contains the class definition, and some resource macros.
+This is often called the <quote>public</quote> header file.
+<indexterm significance="preferred"><primary>class header file</primary></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Class Header File</function>
+ </term>
+ <listitem>
+ <para>
+This file will only be used by widget programmers. It will need to be
+included by any widget that subclasses this widget. This is often
+called the <quote>private</quote> header file.
+<indexterm significance="preferred"><primary>class</primary></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Class</function>
+ </term>
+ <listitem>
+ <para>
+This is the widget class of this widget. This global symbol is passed to
+<function>XtCreateWidget</function> so that the Intrinsics will know which type of widget
+to create.
+<indexterm significance="preferred"><primary>class name</primary></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Class Name</function>
+ </term>
+ <listitem>
+ <para>
+This is the resource name of this class. This name can be used in
+a resource file to match any widget of this class.
+<indexterm><primary>superclass</primary></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>Superclass</function>
+ </term>
+ <listitem>
+ <para>
+This is the superclass that this widget class is descended from. If
+you understand how the superclass works it will allow you to more quickly
+understand what this widget does, since much of its functionality may be
+inherited from its superclass.
+<!-- .sp -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+After this table follows a general description of the default behavior of
+this widget, as seen by the user. In many cases this functionality
+may be overridden by the application programmer, or by the user.
+</para>
+<para>
+<!-- .LP -->
+The next section is a table showing the
+name, class, type and default value of each resource that is available
+to this widget. There is also a column containing notes describing
+special restrictions placed upon individual resources.
+<indexterm significance="preferred"><primary>notes</primary></indexterm>
+<indexterm significance="preferred"><primary>A, note</primary></indexterm>
+<indexterm significance="preferred"><primary>D, note</primary></indexterm>
+<indexterm significance="preferred"><primary>C, note</primary></indexterm>
+<indexterm significance="preferred"><primary>R, note</primary></indexterm>
+<variablelist>
+ <varlistentry>
+ <term>
+ A
+ </term>
+ <listitem>
+ <para>
+This resource may be automatically adjusted when another
+resource is changed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ C
+ </term>
+ <listitem>
+ <para>
+This resource is only settable at widget creation time, and may not
+be modified with <xref linkend='XtSetValues' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ D
+ </term>
+ <listitem>
+ <para>
+Do not modify this resource. While setting this resource will
+work, it can cause unexpected behavior. When this symbol appears
+there is another, preferred, interface provided by the X Toolkit.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ R
+ </term>
+ <listitem>
+ <para>
+This resource is READ-ONLY, and may not be modified.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+After the resource table is a detailed description of every resource
+available to that widget. Many of these are redundant, but printing
+them with each widget saves page flipping. The names of the resources
+that are inherited are printed in plain text, while the names of the
+resources that are new to this class are printed in <function>bold</function>.
+If you have already read the description of the superclass you need
+only pay attention to the resources printed in bold.
+</para>
+<para>
+<!-- .LP -->
+For each composite widget there is a section on layout semantics that
+follows the resource description. This section will describe the
+effect of constraint resources on the layout of the children, as well
+as a general description of where it prefers to place its children.
+</para>
+<para>
+<!-- .LP -->
+Descriptions of default translations and action routines come next, for
+widgets to which they apply. The last item in each widget's
+documentation is the description of all convenience routines provided by
+the widget.
+</para>
+</sect1>
+<sect1 id="Input_Focus">
+<title>Input Focus</title>
+<!-- .XS -->
+<!-- Input Focus -->
+<!-- .XE -->
+<indexterm significance="preferred"><primary>input focus</primary></indexterm>
+<indexterm significance="preferred"><primary>input</primary></indexterm>
+<indexterm significance="preferred"><primary>XtNinput</primary></indexterm>
+<para>
+<!-- .LP -->
+The Intrinsics define a resource on all Shell widgets that interact with
+the window manager called <function>input</function>. This resource requests the
+assistance of window manager in acquiring the input focus. The
+resource defaults to <function>False</function> in the Intrinsics, but is redefined to
+default to <function>True</function> when an application is using the Athena widget
+set. An application programmer may override this default and set the
+resource back to <function>False</function> if the application does not need the window
+manager to give it the input focus. See the
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle> for details
+on the <emphasis remap='I'>input</emphasis> resource.
+
+</para>
+</sect1>
+</chapter>
Index: libXaw-1.0.14-new/specs/CH2.xml
===================================================================
--- libXaw-1.0.14-new/specs/CH2.xml (nonexistent)
+++ libXaw-1.0.14-new/specs/CH2.xml (revision 5)
@@ -0,0 +1,1933 @@
+<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
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>.
+</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>
+prior to calling
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>,
+<function>XtOpenDisplay</function>,
+<function>XtDisplayInitialize</function>,
+or
+<function>XtAppInitialize</function>.
+For full details, please refer to the document
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>,
+section 2.2. However, the following simplest-case
+call is sufficient in many or most applications.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>internationalization</primary></indexterm>
+<indexterm significance="preferred"><primary>XtSetLanguageProc</primary></indexterm>
+<indexterm><primary>locale</primary></indexterm>
+<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).
+<xref linkend='XtOpenApplication' 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.
+<indexterm significance="preferred"><primary>initialization</primary></indexterm>
+<indexterm significance="preferred"><primary>toolkit initialization</primary></indexterm>
+<indexterm significance="preferred"><primary>XtOpenApplication</primary></indexterm>
+<indexterm significance="preferred"><primary>fallback resources</primary></indexterm>
+<funcsynopsis id='XtOpenApplication'>
+<funcprototype>
+<funcdef>Widget <function>XtOpenApplication</function></funcdef>
+ <paramdef>XtAppContext *<parameter>app_context_return</parameter></paramdef>
+ <paramdef>String <parameter>application_class</parameter></paramdef>
+ <paramdef>XrmOptionDescList <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>WidgetClass <parameter>widget_class</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_context_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
+<quote>xman</quote> has a class name of <quote>Xman</quote>.
+ </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
+<citetitle>Xlib - C Language Interface</citetitle>.
+ </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'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class of the widget to be created. Must be shellWidgetClass
+or a subclass.
+ </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 -->
+<indexterm significance="preferred"><primary>widget creation</primary></indexterm>
+<indexterm significance="preferred"><primary>creating widgets</primary></indexterm>
+<indexterm><primary>XtRealizeWidget</primary></indexterm>
+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 <xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+and specifying the top-most widget. The first two steps can be
+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>
+<!-- .LP -->
+To allocate, initialize, and manage a widget, use
+<function>XtCreateManagedWidget</function>.
+<indexterm significance="preferred"><primary>XtCreateManagedWidget</primary></indexterm>
+<funcsynopsis id='XtCreateManagedWidget'>
+<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.
+<indexterm><primary>XtError</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+For further information, see
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>.
+</para>
+</sect2>
+<sect2 id="Common_Resources">
+<title>Common Resources</title>
+<!-- .XS -->
+<!-- Common Resources -->
+<!-- .XE -->
+<indexterm><primary>resource</primary></indexterm>
+<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>
+<indexterm><primary>XtDefaultForeground</primary></indexterm>
+<indexterm><primary>XtDefaultBackground</primary></indexterm>
+</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>
+<indexterm><primary>XtDefaultForeground</primary></indexterm>
+</para>
+</sect2>
+<sect2 id="Resource_Conversions">
+<title>Resource Conversions</title>
+<!-- .XS -->
+<!-- Resource Conversions -->
+<!-- .XE -->
+<indexterm significance="preferred"><primary>conversions</primary></indexterm>
+<indexterm significance="preferred"><primary>string conversions</primary></indexterm>
+<indexterm significance="preferred"><primary>type conversions</primary></indexterm>
+<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>
+<indexterm significance="preferred"><primary>conversions</primary><secondary>ColorCursor</secondary></indexterm>
+<indexterm significance="preferred"><primary>conversions</primary><secondary>Cursor</secondary></indexterm>
+<indexterm><primary>cursor</primary></indexterm>
+<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 <filename class="headerfile"><X11/cursorfont.h></filename>.
+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 -->
+<indexterm significance="preferred"><primary>conversions</primary><secondary>Pixel</secondary></indexterm>
+<indexterm><primary>pixel</primary></indexterm>
+<indexterm><primary>rgb.txt</primary></indexterm>
+<indexterm><primary>XtDefaultForeground</primary></indexterm>
+<indexterm><primary>XtDefaultBackground</primary></indexterm>
+The string-to-pixel converter takes any name that is acceptable to
+XParseColor (see
+<citetitle>Xlib - C Language Interface</citetitle>). In addition this routine understands
+the special toolkit symbols `XtDefaultForeground' and
+`XtDefaultBackground', described in
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>. In short the acceptable
+pixel names are:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Any color name for the rgb.txt file (typically in the directory
+/usr/share/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>
+<indexterm significance="preferred"><primary>bitmap conversions</primary></indexterm>
+<indexterm significance="preferred"><primary>conversions</primary><secondary>Bitmap</secondary></indexterm>
+<indexterm significance="preferred"><primary>bitmapFilePath</primary></indexterm>
+<indexterm significance="preferred"><primary>BitmapFilePath</primary></indexterm>
+<indexterm><primary>/usr/include/X11/bitmaps</primary></indexterm>
+<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 -->
+<indexterm significance="preferred"><primary>realizing widgets</primary></indexterm>
+The
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+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.
+<indexterm significance="preferred"><primary>XtRealizeWidget</primary></indexterm>
+<funcsynopsis id='XtRealizeWidget'>
+<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
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>.
+</para>
+</sect2>
+<sect2 id="Processing_Events">
+<title>Processing Events</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Processing Events -->
+<!-- .XE -->
+<indexterm><primary>events</primary></indexterm>
+<indexterm><primary>XtAppInitialize</primary></indexterm>
+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 <xref linkend='XtAppMainLoop' xrefstyle='select: title'/>.
+<indexterm significance="preferred"><primary>XtAppMainLoop</primary></indexterm>
+<funcsynopsis id='XtAppMainLoop'>
+<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 <xref linkend='XtOpenApplication' xrefstyle='select: title'/>.
+ </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
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>.
+</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
+<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.
+<indexterm significance="preferred"><primary>XtSetMappedWhenManaged</primary></indexterm>
+<indexterm><primary>XtMapWidget</primary></indexterm>
+<indexterm><primary>XtRealizeWidget</primary></indexterm>
+<funcsynopsis id='XtSetMappedWhenManaged'>
+<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
+<xref linkend='XtMapWidget' xrefstyle='select: title'/>
+or make a second call to
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>
+to cause the child window to be mapped.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The definition for
+<xref linkend='XtMapWidget' xrefstyle='select: title'/>
+is:
+<indexterm significance="preferred"><primary>XtMapWidget</primary></indexterm>
+<funcsynopsis id='XtMapWidget'>
+<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 <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 <quote>screen flash</quote>.
+<indexterm significance="preferred"><primary>XtManageChildren</primary></indexterm>
+<indexterm><primary>XtCreateWidget</primary></indexterm>
+<funcsynopsis id='XtManageChildren'>
+<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
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>.
+</para>
+</sect3>
+<sect3 id="Destroying_Widgets">
+<title>Destroying Widgets</title>
+<para>
+<!-- .LP -->
+To destroy a widget instance of any type, use
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+<indexterm significance="preferred"><primary>XtDestroyWidget</primary></indexterm>
+<funcsynopsis id='XtDestroyWidget'>
+<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 -->
+<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
+<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>.
+<indexterm significance="preferred"><primary>XtGetValues</primary></indexterm>
+<funcsynopsis id='XtGetValues'>
+<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
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>.
+</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>.
+<indexterm significance="preferred"><primary>XtSetValues</primary></indexterm>
+<funcsynopsis id='XtSetValues'>
+<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 <xref linkend='XtSetValues' xrefstyle='select: title'/> request is
+ignored.
+</para>
+<para>
+<!-- .LP -->
+For further information about these functions, see the
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>.
+<indexterm><primary>XtGetValues</primary></indexterm>
+<indexterm><primary>XtSetValues</primary></indexterm>
+<!-- .NT -->
+The argument list entry for
+<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>,
+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 -->
+<indexterm><primary>callbacks</primary></indexterm>
+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:
+<indexterm significance="preferred"><primary>CallbackProc</primary></indexterm>
+<funcsynopsis id='CallbackProc'>
+<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 <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>.
+The list is of type
+<function>XtCallbackList :</function>
+<indexterm><primary>XtCallbackProc</primary></indexterm>
+<indexterm><primary>XtAddCallbacks</primary></indexterm>
+<indexterm><primary>XtAddCallback</primary></indexterm>
+<indexterm significance="preferred"><primary>XtCallbackList</primary></indexterm>
+<indexterm significance="preferred"><primary>XtCallbackRec</primary></indexterm>
+</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>.
+<indexterm><primary>XtCreateWidget</primary></indexterm>
+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
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>
+after the widget has been created.
+<indexterm significance="preferred"><primary>XtAddCallback</primary></indexterm>
+<funcsynopsis id='XtAddCallback'>
+<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 -->
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>
+adds the specified callback to the list for the named widget.
+</para>
+<para>
+<!-- .LP -->
+All widgets provide a callback list named
+<function>destroyCallback</function>
+<indexterm significance="preferred"><primary>destroyCallback</primary></indexterm>
+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 -->
+<indexterm><primary>writing applications</primary></indexterm>
+<indexterm><primary>StringDefs.h</primary></indexterm>
+<indexterm><primary>Intrinsic.h</primary></indexterm>
+When writing an application that uses the X Toolkit,
+you should make sure that your application performs the following:
+</para>
+<orderedlist>
+ <listitem>
+ <para>
+Include
+<filename class="headerfile"><X11/Intrinsic.h></filename>
+in your application programs.
+This header file automatically includes
+<filename class="headerfile"><X11/Xlib.h></filename>,
+so all Xlib functions also are defined.
+It may also be necessary to include <filename class="headerfile"><X11/StringDefs.h></filename> 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,
+<filename class="headerfile"><X11/Xaw/Label.h></filename>
+and
+<filename class="headerfile"><X11/Xaw/Command.h></filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Call the
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
+<indexterm><primary>XtOpenApplication</primary></indexterm>
+function before invoking any other toolkit or Xlib functions.
+For further information,
+see Section 2.1 and the
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>.
+ </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.
+<indexterm significance="preferred"><primary>XtN</primary></indexterm>
+ </para>
+ <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
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/> function. For further information, see
+Section 2.2 and the
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>.
+<indexterm><primary>XtCreateManagedWidget</primary></indexterm>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the widget has any callback routines, set by the
+<function>XtNcallback</function>
+argument or the
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>
+function, declare these routines within the application.
+<indexterm><primary>XtAddCallback</primary></indexterm>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+After creating the initial widget hierarchy, windows must be created
+for each widget by calling
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+on the top level widget.
+<indexterm><primary>XtRealizeWidget</primary></indexterm>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Most applications now sit in a loop processing events using
+<function>XtAppMainLoop</function>,
+for example:
+<indexterm><primary>XtAppMainLoop</primary></indexterm>
+<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
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>.
+ </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:
+<indexterm><primary>libXaw</primary></indexterm>
+<indexterm><primary>libXmu</primary></indexterm>
+<indexterm><primary>libXt</primary></indexterm>
+<indexterm><primary>libSM</primary></indexterm>
+<indexterm><primary>libICE</primary></indexterm>
+<indexterm><primary>libXext</primary></indexterm>
+<indexterm><primary>libX11</primary></indexterm>
+<indexterm><primary>linking applications</primary></indexterm>
+<indexterm><primary>compiling applications</primary></indexterm>
+ </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>
+<indexterm><primary>resource</primary></indexterm>
+<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
+
+<citetitle>Xlib - C Language Interface</citetitle> 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
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>
+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.
+<indexterm><primary>xrdb</primary></indexterm>
+<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.
+<indexterm><primary>application defaults</primary></indexterm>
+<indexterm><primary>app-defaults</primary></indexterm>
+<indexterm><primary>/usr/share/X11/app-defaults</primary></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Application Defaults</term>
+ <listitem>
+ <para>
+The application defaults (app-defaults) file (normally in
+/usr/share/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
+<xref linkend='XtOpenApplication' 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 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>.
+<indexterm><primary>XtGetApplicationResources</primary></indexterm>
+ </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
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle> and
+<citetitle>Xlib - C Language Interface</citetitle>.
+</para>
+</sect4>
+<sect4 id="Creating_Argument_Lists">
+<title>Creating Argument Lists</title>
+<indexterm significance="preferred"><primary>argument lists</primary></indexterm>
+<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 <quote>foreground</quote> is <function>XtNforeground</function>. For further information,
+see the
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>.
+</para>
+<para>
+<!-- .LP -->
+Argument are specified by using the following structure:
+<indexterm significance="preferred"><primary>ArgList</primary></indexterm>
+<indexterm significance="preferred"><primary>Arg</primary></indexterm>
+</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
+<indexterm><primary>XtNumber</primary></indexterm>
+<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>
+<indexterm significance="preferred"><primary>XtSetArg</primary></indexterm>
+</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,
+<indexterm><primary>XtNumber</primary></indexterm>
+<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,
+<indexterm><primary>XtNumber</primary></indexterm>
+<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,
+<indexterm><primary>XtNumber</primary></indexterm>
+<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 -->
+<indexterm><primary>examples</primary></indexterm>
+<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 X11R5 contrib
+release as distributed by the X Consortium. It can be found in the
+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>
+</chapter>
Index: libXaw-1.0.14-new/specs/CH6.xml
===================================================================
--- libXaw-1.0.14-new/specs/CH6.xml (nonexistent)
+++ libXaw-1.0.14-new/specs/CH6.xml (revision 5)
@@ -0,0 +1,119 @@
+<chapter id='Composite_and_Constraint_Widgets'>
+<title>Composite and Constraint Widgets</title>
+<para>
+These widgets may contain arbitrary widget children. They implement a
+policy for the size and location of their children.
+</para>
+<para>
+<variablelist>
+ <varlistentry>
+ <term>Box</term>
+ <listitem>
+ <para>
+This widget will pack its children as tightly as possible in non-overlapping rows.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Dialog</term>
+ <listitem>
+ <para>
+An implementation of a commonly used interaction semantic to prompt for
+auxiliary input from the user, such as a filename.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Form</term>
+ <listitem>
+ <para>
+A more sophisticated layout widget that allows the children to specify
+their positions relative to the other children, or to the edges of the Form.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Paned</term>
+ <listitem>
+ <para>
+Allows children to be tiled vertically or horizontally. Controls are
+also provided to allow the user to dynamically resize the individual panes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Porthole</term>
+ <listitem>
+ <para>
+Allows viewing of a managed child which is as large as, or larger than its
+parent, typically under control of a Panner widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Tree</term>
+ <listitem>
+ <para>
+Provides geometry management of widgets arranged in a directed, acyclic graph.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Viewport</term>
+ <listitem>
+ <para>
+Consists of a frame, one or two scrollbars, and an inner window. The
+inner window can contain all the data that is to be displayed. This inner
+window will be clipped by the frame with the scrollbars controlling
+which section of the inner window is currently visible.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<note>
+<para>
+<!-- .LP -->
+The geometry management semantics provided by the X Toolkit give full
+control of the size and position of a widget to the parent of that
+widget. While the children are allowed to request a certain size or
+location, it is the parent who makes the final decision. Many of the
+composite widgets here will deny any geometry request from their
+children by default. If a child widget is not getting the expected size
+or location, it is most likely the parent disallowing a request, or
+implementing semantics slightly different than those expected by the
+application programmer.
+</para>
+<para>
+<!-- .LP -->
+If the application wishes to change the size or location of
+any widget it should make a call to <xref linkend='XtSetValues' xrefstyle='select: title'/>. This will
+<indexterm><primary>XtSetValues</primary></indexterm>
+allow the widget to ask its parent for the new size or location.
+As noted above the parent is allowed to refuse this request,
+and the child must live with the result. If the
+application is unable to achieve the desired semantics, then perhaps it
+should use a different composite widget. Under no circumstances
+should an application programmer resort to <function>XtMoveWidget</function> or
+<indexterm><primary>XtMoveWidget</primary></indexterm>
+<function>XtResizeWidget</function>; these functions are exclusively for the use of
+<indexterm><primary>XtResizeWidget</primary></indexterm>
+Composite widget implementors.
+</para>
+<para>
+<!-- .LP -->
+For more information on geometry management consult the
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>.
+</para>
+</note>
+
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Box.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Dialog.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Form.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Paned.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Porthole.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Tree.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Viewport.xml"/>
+
+</chapter>
Index: libXaw-1.0.14-new/specs/CH7.xml
===================================================================
--- libXaw-1.0.14-new/specs/CH7.xml (nonexistent)
+++ libXaw-1.0.14-new/specs/CH7.xml (revision 5)
@@ -0,0 +1,170 @@
+<chapter id='Creating_New_Widgets_Subclassing'>
+<title>Creating New Widgets (Subclassing)</title>
+<para>
+Although the task of creating a new widget may at first appear a little
+daunting, there is a basic simple pattern that all widgets follow. The
+Athena Widget library contains a special widget called the
+<emphasis remap='I'>Template</emphasis> widget that is intended to assist
+the novice widget programmer in writing a custom widget.
+</para>
+<para>
+Reasons for wishing to write a custom widget include:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Providing a graphical interface not currently supported by any existing
+widget set.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Convenient access to resource management procedures to obtain fonts,
+colors, etc., even if user customization is not desired.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Convenient access to user input dispatch and translation management procedures.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Access to callback mechanism for building higher-level application libraries.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Customizing the interface or behavior of an existing widget to suit a
+special application need.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Desire to allow user customization of resources such as fonts, colors,
+etc., or to allow convenient re-binding of keys and buttons to internal
+functions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Converting a non-Toolkit application to use the Toolkit.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+In each of these cases, the operation needed to create a new widget is
+to "subclass" an existing one. If the desired semantics of the new
+widget are similar to an existing one, then the implementation of the
+existing widget should be examined to see how much work would be
+required to create a subclass that will then be
+able to share the existing class methods. Much time will be saved in
+writing the new widget if an existing widget class Expose, Resize and/or
+GeometryManager method can be used by the subclass.
+</para>
+<para>
+Note that some trivial uses of a <quote>bare-bones</quote> widget may be achieved by
+simply creating an instance of the Core
+widget. The class variable to use when creating a Core widget is
+<function>widgetClass</function>.
+The geometry of the Core widget is determined entirely by the parent
+widget.
+</para>
+<para>
+It is very often the case than an application will have a special need
+for a certain set of functions and that many copies of these functions
+will be needed. For example, when converting an older application to use
+the Toolkit, it may be desirable to have a "Window Widget" class that
+might have the following semantics:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Allocate 2 drawing colors in addition to a background color.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Allocate a text font.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Execute an application-supplied function to handle exposure events.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Execute an application-supplied function to handle user input events.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+It is obvious that a completely general-purpose WindowWidgetClass could
+be constructed that would export all class methods as callbacks lists,
+but such a widget would be very large and would have to choose some
+arbitrary number of resources such as colors to allocate. An application
+that used many instances of the general-purpose widget would therefore
+un-necessarily waste many resources.
+</para>
+<para>
+In this section, an outline will be given of the procedure to follow to
+construct a special-purpose widget to address the items listed above.
+The reader should refer to the appropriate sections of the
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>
+for complete details of the material outlined here.
+
+Section 1.4 of the <citetitle>Intrinsics</citetitle>
+should be read in
+conjunction with this section.
+</para>
+<para>
+All Athena widgets have three separate files associated with them:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A "public" header file containing declarations needed by applications programmers
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A "private" header file containing additional declarations needed by the
+widget and any subclasses
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A source code file containing the implementation of the widget
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+This separation of functions into three files is suggested for all
+widgets, but nothing in the Toolkit actually requires this format. In
+particular, a private widget created for a single application may easily
+combine the "public" and "private" header files into a single file, or
+merge the contents into another application header file. Similarly, the
+widget implementation can be merged into other application code.
+</para>
+
+<para>
+In the following example, the public header file
+<filename class="headerfile"><X11/Xaw/Template.h></filename>,
+the private header file
+<filename class="headerfile"><X11/Xaw/TemplateP.h></filename>
+and the source code file
+<filename class="headerfile"><X11/Xaw/Template.c></filename>
+will be modified to produce the "WindowWidget" described above.
+In each case, the files have been designed so that a global string
+replacement of "Template" and "template"
+with the name of your new widget, using
+the appropriate case, can be done.
+</para>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Template_public_header_file.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Template_private_header_file.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Template_widget_source_file.xml"/>
+</chapter>
Index: libXaw-1.0.14-new/specs/Grip.xml
===================================================================
--- libXaw-1.0.14-new/specs/Grip.xml (nonexistent)
+++ libXaw-1.0.14-new/specs/Grip.xml (revision 5)
@@ -0,0 +1,358 @@
+<sect1 id="Grip_Widget">
+<title>Grip Widget</title>
+<!-- .XS -->
+<!-- Grip Widget -->
+<!-- .XE -->
+<indexterm significance="preferred"><primary>Grip widget</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application header file <X11/Xaw/Grip.h>
+<indexterm><primary>Grip.h</primary></indexterm>
+Class header file <X11/Xaw/GripP.h>
+<indexterm><primary>GripP.h</primary></indexterm>
+Class gripWidgetClass
+<indexterm><primary>gripWidgetClass</primary></indexterm>
+Class Name Grip
+<indexterm><primary>Grip widget</primary><secondary>class name</secondary></indexterm>
+Superclass Simple
+<!-- .sp -->
+</literallayout>
+<para>
+<!-- .LP -->
+The Grip widget provides a small rectangular region in which user input
+events (such as ButtonPress or ButtonRelease) may be handled. The most
+common use for the Grip widget is as an attachment point for visually
+repositioning an object, such as the pane border in a Paned widget.
+</para>
+<sect2 id='Grip::Resources'>
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a Grip widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Grip widget</primary><secondary>resources</secondary></indexterm>
+<informaltable>
+ <tgroup cols='5' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <colspec colname='c5'/>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Type</entry>
+ <entry>Notes</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>callback</entry>
+ <entry>Callback</entry>
+ <entry>Callback</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>cursorName</entry>
+ <entry>Cursor</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>insensitiveBorder</entry>
+ <entry>Insensitive</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>GreyPixmap</entry>
+ </row>
+ <row>
+ <entry>international</entry>
+ <entry>International</entry>
+ <entry>Boolean</entry>
+ <entry>C</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>pointerColor</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>pointerColorBackground</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>callback</function>
+ </term>
+ <listitem>
+ <para>
+All routines on this list are called whenever the <function>GripAction</function>
+action routine is invoked. The <emphasis remap='I'>call_data</emphasis> contains all
+information passed to the action routine. A detailed description
+is given below in the <function>Grip Actions</function> section.
+<!-- .Cm -->
+<!-- .Cu -->
+<!-- .Cn -->
+<!-- .Dp -->
+<!-- .Dc -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>foreground</function>
+ </term>
+ <listitem>
+ <para>
+A pixel value which indexes the widget's colormap to derive the color
+used to flood fill the entire Grip widget.
+<!-- .Hw -->
+<!-- .Ib -->
+<!-- .Ix -->
+<!-- .Mm -->
+<!-- .Pf -->
+<!-- .Pb -->
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+<!-- .Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Grip_Actions">
+<title>Grip Actions</title>
+<indexterm><primary>Grip widget</primary><secondary>actions</secondary></indexterm>
+<para>
+<!-- .LP -->
+The Grip widget does not declare any default event translation bindings,
+but it does declare a single action routine named <function>GripAction</function>. The
+<indexterm><primary>Grip widget</primary><secondary>GripAction routine</secondary></indexterm>
+client specifies an arbitrary event translation table, optionally giving
+parameters to the <function>GripAction</function> routine.
+</para>
+<para>
+<!-- .LP -->
+The <function>GripAction</function> routine executes the callbacks on the
+<function>callback</function> list, passing as <function>call_data</function> a pointer to a
+<function>XawGripCallData</function> structure, defined in the Grip widget's application
+header file.
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.25i -->
+<!-- .ta .5i 2.25i -->
+<indexterm significance="preferred"><primary>XawGripCallData</primary></indexterm>
+<indexterm significance="preferred"><primary>XawGripCallDataRec</primary></indexterm>
+<!-- .sp -->
+typedef struct _XawGripCallData {
+ XEvent *event;
+ String *params;
+ Cardinal num_params;
+} XawGripCallDataRec, *XawGripCallData,
+ GripCallDataRec, *GripCallData; /* supported for R4 compatibility */
+<indexterm><primary>XawGripCallDataRec</primary></indexterm>
+<indexterm><primary>XawGripCallData</primary></indexterm>
+<indexterm><primary>GripCallData</primary></indexterm>
+<!-- .sp -->
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+In this structure, the <emphasis remap='I'>event</emphasis> is a pointer to the input event that
+triggered the action. <emphasis remap='I'>params</emphasis> and <emphasis remap='I'>num_params</emphasis> give the string
+parameters specified in the translation table for the particular event
+binding.
+<indexterm><primary>Grip widget</primary><secondary>GripAction table</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+The following is an example of a translation table that uses the GripAction:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+<!-- .sp -->
+ <Btn1Down>: GripAction(press)
+ <Btn1Motion>: GripAction(move)
+ <Btn1Up>: GripAction(release)
+<!-- .sp -->
+</literallayout>
+For a complete description of the format of translation tables, see the
+
+<citetitle>X Toolkit Intrinsics - C Language Interface</citetitle>.
+
+</para>
+</sect2>
+</sect1>
Index: libXaw-1.0.14-new/specs/SimpleMenu.xml
===================================================================
--- libXaw-1.0.14-new/specs/SimpleMenu.xml (nonexistent)
+++ libXaw-1.0.14-new/specs/SimpleMenu.xml (revision 5)
@@ -0,0 +1,791 @@
+<sect1 id="SimpleMenu_Widget">
+<title>SimpleMenu Widget</title>
+<!-- .XS -->
+<!-- SimpleMenu Widget -->
+<!-- .XE -->
+<indexterm significance="preferred"><primary>SimpleMenu widget</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application Header file <X11/Xaw/SimpleMenu.h>
+<indexterm><primary>SimpleMenu.h</primary></indexterm>
+Class Header file <X11/Xaw/SimpleMenP.h>
+<indexterm><primary>SimpleMenP.h</primary></indexterm>
+Class simpleMenuWidgetClass
+<indexterm><primary>simpleMenuWidgetClass</primary></indexterm>
+Class Name SimpleMenu
+<indexterm><primary>SimpleMenu widget</primary><secondary>class name</secondary></indexterm>
+Superclass OverrideShell
+<!-- .sp -->
+</literallayout>
+<para>
+<!-- .LP -->
+The SimpleMenu widget is a container for the menu entries. It is a
+direct subclass of shell, and is should be created with
+<function>XtCreatePopupShell</function>, not <xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>. This is the
+only part of the menu that
+actually is associated with a window. The SimpleMenu serves as the glue to bind
+the individual menu entries together into a menu.
+</para>
+<sect2 id="SimpleMenu::Resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+<indexterm><primary>SimpleMenu widget</primary><secondary>resources</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+The resources associated with the SimpleMenu widget control aspects
+that will affect the entire menu.
+<informaltable>
+ <tgroup cols='5' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <colspec colname='c5'/>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Type</entry>
+ <entry>Notes</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>allowShellResize</entry>
+ <entry>AllowShellResize</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>backingStore</entry>
+ <entry>BackingStore</entry>
+ <entry>BackingStore</entry>
+ <entry></entry>
+ <entry>see below</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>bottomMargin</entry>
+ <entry>VerticalMargins</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>children</entry>
+ <entry>ReadOnly</entry>
+ <entry>WidgetList</entry>
+ <entry>R</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>createPopupChildProc</entry>
+ <entry>CreatePopupChildProc</entry>
+ <entry>Function</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>cursor</entry>
+ <entry>Cursor</entry>
+ <entry>Cursor</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>geometry</entry>
+ <entry>Geometry</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>Enough space to contain all entries</entry>
+ </row>
+ <row>
+ <entry>label</entry>
+ <entry>Label</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>labelClass</entry>
+ <entry>LabelClass</entry>
+ <entry>Pointer</entry>
+ <entry></entry>
+ <entry>SmeBSBObjectClass</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>menuOnScreen</entry>
+ <entry>MenuOnScreen</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>numChildren</entry>
+ <entry>ReadOnly</entry>
+ <entry>Cardinal</entry>
+ <entry>R</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>overrideRedirect</entry>
+ <entry>OverrideRedirect</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>popdownCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>popupCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>popupOnEntry</entry>
+ <entry>PopupOnEntry</entry>
+ <entry>Widget</entry>
+ <entry>A</entry>
+ <entry>Label or first entry</entry>
+ </row>
+ <row>
+ <entry>rowHeight</entry>
+ <entry>RowHeight</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>saveUnder</entry>
+ <entry>SaveUnder</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>topMargin</entry>
+ <entry>VerticalMargins</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>See below</entry>
+ </row>
+ <row>
+ <entry>visual</entry>
+ <entry>Visual</entry>
+ <entry>Visual</entry>
+ <entry></entry>
+ <entry>CopyFromParent</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>Width of widest entry</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>backingStore</function>
+ </term>
+ <listitem>
+ <para>
+<indexterm><primary>conversions</primary><secondary>BackingStore</secondary></indexterm>
+Determines what type of backing store will be used for the menu. Legal
+values for this resource are <function>NotUseful</function>, <function>WhenMapped</function>, and
+<function>Always</function>. These values are the backing-store integers defined in
+<X11/X.h>.
+<!-- .Rs "notUseful, whenMapped, always, \fPand\fP default" -->
+If <function>default</function> is specified (the default behavior) the server will use
+whatever it thinks is appropriate.
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>bottomMargin</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>topMargin</function>
+ </term>
+ <listitem>
+ <para>
+The amount of space between the top or bottom of the menu and the menu entry
+closest to that edge.
+<!-- .Ch -->
+<!-- .Cm -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>cursor</function>
+ </term>
+ <listitem>
+ <para>
+The shape of the mouse pointer whenever it is in this widget.
+<!-- .Dp -->
+<!-- .Dc -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ geometry
+ </term>
+ <listitem>
+ <para>
+If this resource is specified it will override the x, y, width and
+height of this widget. The format of this string is
+[<<emphasis remap='I'>width</emphasis>>x<<emphasis remap='I'>height</emphasis>>][{+ -} <<emphasis remap='I'>xoffset</emphasis>> {+ -}<<emphasis remap='I'>yoffset</emphasis>>].
+<!-- .Hw -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>label</function>
+ </term>
+ <listitem>
+ <para>
+This label will be placed at the top of the SimpleMenu, and may not be
+highlighted. The name of the
+label object is <function>menuLabel</function>. Using this name it is possible to
+modify the label's attributes through the resource database. When the label
+is created, the <function>label</function> is hard coded to the value of <function>label</function>, and
+<function>justify</function> is hard coded as <function>XtJustifyCenter</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>labelClass</function>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of Sme object created as the menu label.
+<!-- .Mm -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>menuOnScreen</function>
+ </term>
+ <listitem>
+ <para>
+If the menu is automatically positioned under the cursor with the
+<function>XawPositionSimpleMenu</function> action, and this resource is <function>True</function>,
+then the menu will always be fully visible on the screen.
+<!-- .Nc -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ overrideRedirect
+ </term>
+ <listitem>
+ <para>
+Determines the value of the override_redirect attribute of the
+SimpleMenu's window. The override_redirect attribute of a window
+determines whether or not a window manager may interpose itself between
+this window and the root window of the display. For more information
+see the
+<citetitle>Interclient Communications Conventions Manual</citetitle>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ popdownCallback
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ popupCallback
+ </term>
+ <listitem>
+ <para>
+These callback functions are called by the Xt Intrinsics whenever the
+shell is popped up or down (See <emphasis remap='I'>(xT</emphasis> for details).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>popupOnEntry</function>
+ </term>
+ <listitem>
+ <para>
+The <function>XawPositionSimpleMenu</function> action will, by default, popup the
+SimpleMenu with its label (or first entry) directly under the
+pointer. To popup the menu under
+another entry, set this resource to the menu entry that should be
+under the pointer, when the menu is popped up. This allows the
+application to offer the user a default menu entry that can be selected
+with out moving the pointer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>rowHeight</function>
+ </term>
+ <listitem>
+ <para>
+If this resources is zero (the default) then each menu entry will be
+given its desired height. If this resource has any other value then
+all menu entries will be forced to be <function>rowHeight</function> pixels high.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ saveUnder
+ </term>
+ <listitem>
+ <para>
+If this is <function>True</function> then save unders will be active on the menu's window.
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+<!-- .Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="SimpleMenu_Actions">
+<title>SimpleMenu Actions</title>
+<indexterm><primary>SimpleMenu widget</primary><secondary>actions</secondary></indexterm>
+<para>
+<!-- .LP -->
+The SimpleMenu widget supports the following actions:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Switching the entry under the mouse pointer between
+the foreground and background colors with <function>highlight</function>
+and <function>unhighlight</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Processing menu entry callbacks with <function>notify</function>
+<!-- .sp -->
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<indexterm><primary>SimpleMenu widget</primary><secondary>default translations</secondary></indexterm>
+The following are the default translation bindings used
+by the SimpleMenu widget:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.25i -->
+<!-- .ta .5i 2.25i -->
+ <EnterWindow>: highlight( )
+ <LeaveWindow>: unhighlight( )
+ <BtnMotion>: highlight( )
+ <BtnUp>: MenuPopdown( ) notify( ) unhighlight( )
+</literallayout>
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>SimpleMenu widget</primary><secondary>MenuPopdown routine</secondary></indexterm>
+The user can pop down the menu without activating any of the callback
+functions by releasing the pointer button when no menu item is
+highlighted.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+The full list of actions supported by SimpleMenu is:
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>highlight</function>()
+ </term>
+ <listitem>
+ <para>
+Highlight the menu entry that is currently under the pointer.
+Only a item that is highlighted will be notified when the <function>notify</function>
+action is invoked. The look of a highlighted entry is determined by
+the menu entry.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>unhighlight</function>( )
+ </term>
+ <listitem>
+ <para>
+Unhighlights the currently highlighted menu item, and returns it to
+its normal look.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>notify</function>( )
+ </term>
+ <listitem>
+ <para>
+Notifies the menu entry that is currently highlighted that is has been
+selected. It is the responsibility of the menu entry to take the
+appropriate action.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>MenuPopdown</function>(<emphasis remap='I'>menu</emphasis>)
+ </term>
+ <listitem>
+ <para>
+This action is defined in <emphasis remap='I'>(xT</emphasis>.
+<indexterm><primary>SimpleMenu widget</primary><secondary>MenuPopdown routine</secondary></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Positioning_the_SimpleMenu">
+<title>Positioning the SimpleMenu</title>
+<indexterm significance="preferred"><primary>XawPositionSimpleMenu</primary></indexterm>
+<indexterm significance="preferred"><primary>SimpleMenu widget</primary><secondary>positioning</secondary></indexterm>
+<para>
+<!-- .LP -->
+If the SimpleMenu widget is to be used as a pulldown menu then the
+MenuButton widget, or some other outside means should be used to place
+the menu when it is popped up.
+</para>
+<para>
+<!-- .LP -->
+If popup menus are desired it will be necessary to add the
+<function>XawPositionSimpleMenu</function> and <function>MenuPopup</function> actions to the
+translation table of the widget that will be popping up the menu. The
+<function>MenuPopup</function> action is described in <emphasis remap='I'>(xT</emphasis>.
+<function>XawPositionSimpleMenu</function> is a global action procedure registered by
+the SimpleMenu widget when the first one is created or the convenience
+routine <xref linkend='XawSimpleMenuAddGlobalActions' xrefstyle='select: title'/> is called.
+</para>
+<para>
+<!-- .LP -->
+Translation writers should be aware that Xt does not register grabs on
+<quote>don't care</quote> modifiers, and therefore the left hand side of the
+production should be written to exclude unspecified modifiers.
+For example these are the translations needed to popup some of
+<function>xterm's</function> menus:
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.25i -->
+<!-- .ta .5i 2.25i -->
+ !Ctrl<Btn1Down>: XawPositionSimpleMenu(xterm) MenuPopup(xterm)
+ !Ctrl<Btn2Down>: XawPositionSimpleMenu(modes) MenuPopup(modes)
+</literallayout>
+<!-- .sp 1 -->
+</para>
+<para>
+<!-- .LP -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>XawPositionSimpleMenu</function>(<emphasis remap='I'>menu</emphasis>)
+ </term>
+ <listitem>
+ <para>
+The <function>XawPositionSimpleMenu</function> routine will search for the menu name
+passed to it using <function>XtNameToWidget</function> starting with the widget
+invoking the action as the reference widget. If it is unsuccessful it
+will continue up the widget tree using each of the invoking widget's
+ancestors as the reference widget. If it is still unsuccessful it will
+print a warning message and give up. <function>XawPositionSimpleMenu</function> will
+position the menu directly under the pointer cursor. The menu will be
+placed so that the pointer cursor is centered on the entry named by the
+<function>popupOnEntry</function> resource. If the <function>menuOnScreen</function> resource is
+<function>True</function> then the menu will always be fully visible on the screen.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="SimpleMenu::Convenience_Routines">
+<title>Convenience Routines</title>
+<sect3 id="Registering_the_Global_Action_Routines">
+<title>Registering the Global Action Routines</title>
+<para>
+<!-- .LP -->
+<indexterm><primary>XawPositionSimpleMenu</primary></indexterm>
+The <function>XawPositionSimpleMenu</function> action routine may often be invoked
+before any menus have been created. This can occur when an
+application uses dynamic menu creation. In these cases an application will
+need to register this global action routine by calling
+<xref linkend='XawSimpleMenuAddGlobalActions' xrefstyle='select: title'/>:
+<indexterm significance="preferred"><primary>XawSimpleMenuAddGlobalActions</primary></indexterm>
+<funcsynopsis id='XawSimpleMenuAddGlobalActions'>
+<funcprototype>
+ <funcdef>void<function> XawSimpleMenuAddGlobalActions</function></funcdef>
+ <paramdef>XtAppContext<parameter> app_con</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_con</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context in which this action should be registered.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function need only be called once per application and must be
+called before any widget that uses <function>XawPositionSimpleMenu</function> action
+is realized.
+</para>
+</sect3>
+<sect3 id="Getting_and_Clearing_the_Current_Menu_Entry">
+<title>Getting and Clearing the Current Menu Entry</title>
+<para>
+<!-- .LP -->
+To get the currently highlighted menu entry use
+<xref linkend='XawSimpleMenuGetActiveEntry' xrefstyle='select: title'/>:
+<indexterm significance="preferred"><primary>XawSimpleMenuGetActiveEntry</primary></indexterm>
+<funcsynopsis id='XawSimpleMenuGetActiveEntry'>
+<funcprototype>
+ <funcdef>Widget<function> XawSimpleMenuGetActiveEntry</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the SimpleMenu widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function returns the menu entry that is
+currently highlighted, or NULL if no entry is highlighted.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To clear the SimpleMenu widget's internal information about the
+currently highlighted menu entry use
+<xref linkend='XawSimpleMenuClearActiveEntry' xrefstyle='select: title'/>:
+<indexterm significance="preferred"><primary>XawSimpleMenuClearActiveEntry</primary></indexterm>
+<funcsynopsis id='XawSimpleMenuClearActiveEntry'>
+<funcprototype>
+ <funcdef>Widget<function> XawSimpleMenuClearActiveEntry</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the SimpleMenu widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function unsets all internal references to the currently
+highlighted menu entry. It does not <emphasis remap='I'>unhighlight</emphasis> or otherwise
+alter the appearance of the active entry. This function is primarily
+for use by implementors of menu entries.
+
+</para>
+</sect3>
+</sect2>
+</sect1>
Index: libXaw-1.0.14-new/specs/TextSink.xml
===================================================================
--- libXaw-1.0.14-new/specs/TextSink.xml (nonexistent)
+++ libXaw-1.0.14-new/specs/TextSink.xml (revision 5)
@@ -0,0 +1,917 @@
+<sect1 id="TextSink_Object">
+<title>TextSink Object</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- TextSink Object -->
+<!-- .XE -->
+<indexterm significance="preferred"><primary>TextSink object</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+Application Header file <X11/Xaw/TextSink.h>
+<indexterm><primary>TextSink.h</primary></indexterm>
+Class Header file <X11/Xaw/TextSinkP.h>
+<indexterm><primary>TextSinkP.h</primary></indexterm>
+Class textSinkObjectClass
+<indexterm><primary>textSinkObjectClass</primary></indexterm>
+Class Name TextSink
+<indexterm><primary>TextSink object</primary><secondary>class name</secondary></indexterm>
+Superclass Object
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The TextSink object is the root object for all text sinks. Any new text
+sink objects should be subclasses of the TextSink Object. The TextSink
+Class contains all methods that the Text widget expects a text sink to
+export.
+</para>
+<para>
+<!-- .LP -->
+Since all text sinks will have some resources in common, the TextSink
+defines a few new resources.
+</para>
+<sect2 id='TextSink::Resources'>
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating an TextSink object instance, the following resources are
+retrieved from the argument list or from the resource database:
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>AsciiSink object</primary><secondary>resources</secondary></indexterm>
+<informaltable>
+ <tgroup cols='5' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <colspec colname='c5'/>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Type</entry>
+ <entry>Notes</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>foreground</entry>
+ <entry>Foreground</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Bg Bold -->
+<!-- .Dc -->
+<!-- .Sg Bold -->
+</para>
+</sect2>
+<sect2 id="Subclassing_the_TextSink">
+<title>Subclassing the TextSink</title>
+<indexterm significance="preferred"><primary>TextSink object</primary><secondary>subclassing</secondary></indexterm>
+<para>
+<!-- .LP -->
+The only purpose of the TextSink Object is to be subclassed. It
+contains the minimum set of class methods that all text sinks must have.
+While all may be inherited, the direct descendant of TextSink <function>must
+specify</function> some of them as TextSink does contain enough information to
+be a valid text sink by itself. Do not try to use
+the TextSink as a valid sink for the Text widget; it is not intended
+to be used as a sink by itself.
+<informaltable>
+ <tgroup cols='4' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <thead>
+ <row>
+ <entry>Function</entry>
+ <entry>Inherit with</entry>
+ <entry>Public Interface</entry>
+ <entry>must specify</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>DisplayText</entry>
+ <entry>XtInheritDisplayText</entry>
+ <entry>XawTextSinkDisplayText</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>InsertCursor</entry>
+ <entry>XtInheritInsertCursor</entry>
+ <entry>XawTextSinkInsertCursor</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>ClearToBackground</entry>
+ <entry>XtInheritClearToBackground</entry>
+ <entry>XawTextSinkClearToBackground</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>FindPosition</entry>
+ <entry>XtInheritFindPosition</entry>
+ <entry>XawTextSinkFindPosition</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>FindDistance</entry>
+ <entry>XtInheritFindDistance</entry>
+ <entry>XawTextSinkFindDistance</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>Resolve</entry>
+ <entry>XtInheritResolve</entry>
+ <entry>XawTextSinkResolve</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>MaxLines</entry>
+ <entry>XtInheritMaxLines</entry>
+ <entry>XawTextSinkMaxLines</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>MaxHeight</entry>
+ <entry>XtInheritMaxHeight</entry>
+ <entry>XawTextSinkMaxHeight</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>SetTabs</entry>
+ <entry>XtInheritSetTabs</entry>
+ <entry>XawTextSinkSetTabs</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>GetCursorBounds</entry>
+ <entry>XtInheritGetCursorBounds</entry>
+ <entry>XawTextSinkGetCursorBounds</entry>
+ <entry>yes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<sect3 id="Displaying_Text">
+<title>Displaying Text</title>
+<para>
+<!-- .LP -->
+To display a section of the text buffer contained in the text source
+use the function <xref linkend='DisplayText' xrefstyle='select: title'/>:
+<indexterm significance="preferred"><primary>TextSink object</primary><secondary>DisplayText</secondary></indexterm>
+<funcsynopsis id='DisplayText'>
+<funcprototype>
+ <funcdef>void<function> DisplayText</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Positionx,<parameter> y</parameter></paramdef>
+ <paramdef>XawTextPositionpos1,<parameter> pos2</parameter></paramdef>
+ <paramdef>Boolean<parameter> highlight</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the x location to start drawing the text.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the y location to start drawing text.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pos1</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the location within the text source of the first character
+to be printed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pos2</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the location within the text source of the last character
+to be printed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>highlight</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether or not to paint the text region highlighted.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+The Text widget will only pass one line at a time to the text sink, so
+this function does not need to know how to line feed the text. It is
+acceptable for this function to just ignore Carriage Returns. <emphasis remap='I'>x</emphasis>
+and <emphasis remap='I'>y</emphasis> denote the upper left hand corner of the first character to
+be displayed.
+</para>
+</sect3>
+<sect3 id="Displaying_the_Insert_Point">
+<title>Displaying the Insert Point</title>
+<para>
+<!-- .LP -->
+The function that controls the display of the text cursor is
+<xref linkend='InsertCursor' xrefstyle='select: title'/>. This function will be called whenever the text
+widget desires to change the state of, or move the insert point.
+<funcsynopsis id='InsertCursor'>
+<funcprototype>
+ <funcdef>void<function> InsertCursor</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Positionx,<parameter> y</parameter></paramdef>
+ <paramdef>XawTextInsertState<parameter> state</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the x location of the cursor in Pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the y location of the cursor in Pixels.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>state</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the state of the cursor, may be one of <function>XawisOn</function> or
+<function>XawisOff</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<emphasis remap='I'>X</emphasis> and <emphasis remap='I'>y</emphasis> denote the upper left hand corner of the insert point.
+</para>
+</sect3>
+<sect3 id="Clearing_Portions_of_the_Text_window">
+<title>Clearing Portions of the Text window</title>
+<para>
+<!-- .LP -->
+To clear a portion of the Text window to its background color, the Text
+widget will call <xref linkend='ClearToBackground' xrefstyle='select: title'/>. The TextSink object already
+defines this function as calling
+<function>XClearArea</function>
+on the region passed.
+This behavior will be used if you specify
+<function>XtInheritClearToBackground</function> for this method.
+<indexterm><primary>XtInheritClearToBackground</primary></indexterm>
+<indexterm significance="preferred"><primary>TextSink object</primary><secondary>ClearToBackground</secondary></indexterm>
+<funcsynopsis id='ClearToBackground'>
+<funcprototype>
+ <funcdef>void<function> ClearToBackground</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Positionx,<parameter> y</parameter></paramdef>
+ <paramdef>Dimensionwidth,<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the x location, in pixels, of the Region to clear.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the y location, in pixels, of the Region to clear.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the width, in pixels, of the Region to clear.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the height, in pixels, of the Region to clear.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<emphasis remap='I'>X</emphasis> and <emphasis remap='I'>y</emphasis> denote the upper left hand corner of region to clear.
+</para>
+</sect3>
+<sect3 id="Finding_a_Text_Position_Given_Pixel_Values">
+<title>Finding a Text Position Given Pixel Values</title>
+<para>
+<!-- .LP -->
+To find the text character position that will be rendered at a given x
+location the Text widget uses the function <xref linkend='FindPosition' xrefstyle='select: title'/>:
+<indexterm significance="preferred"><primary>TextSink object</primary><secondary>FindPosition</secondary></indexterm>
+<funcsynopsis id='FindPosition'>
+<funcprototype>
+ <funcdef>void<function> FindPosition</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> fromPos</parameter></paramdef>
+ <paramdef>intfromX,<parameter> width</parameter></paramdef>
+ <paramdef>Boolean<parameter> stopAtWordBreak</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> *pos_return</parameter></paramdef>
+ <paramdef>int*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fromPos</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a reference position, usually the first character in this line.
+This character is always to the left of the desired character location.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fromX</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the distance that the left edge of <emphasis remap='I'>fromPos</emphasis> is from the
+left edge of the window. This is the reference x location for the
+reference position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the distance, in pixels, from the reference position to the
+desired character position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>stopAtWordBreak</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether or not the position that is returned should be forced
+to be on a word boundary.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pos_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the character position that corresponds to the location that has
+been specified, or the work break immediately to the left of the
+position if <emphasis remap='I'>stopAtWordBreak</emphasis> is <function>True</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the actual distance between <emphasis remap='I'>fromPos</emphasis> and <emphasis remap='I'>pos_return</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the maximum height of the text between <emphasis remap='I'>fromPos</emphasis> and
+<emphasis remap='I'>pos_return</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function need make no attempt to deal with line feeds. The text
+widget will only call it one line at a time.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Another means of finding a text position is provided by the <xref linkend='Resolve' xrefstyle='select: title'/>
+function:
+<indexterm significance="preferred"><primary>TextSink object</primary><secondary>Resolve</secondary></indexterm>
+<funcsynopsis id='Resolve'>
+<funcprototype>
+ <funcdef>void<function> Resolve</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> fromPos</parameter></paramdef>
+ <paramdef>intfromX,<parameter> width</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> *pos_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fromPos</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a reference position, usually the first character in this line.
+This character is always to the left of the desired character location.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fromX</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the distance that the left edge of <emphasis remap='I'>fromPos</emphasis> is from the
+left edge of the window. This is the reference x location for the
+reference position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the distance, in pixels, from the reference position to the
+desired character position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pos_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the character position that corresponds to the
+location that has been specified, or the word break immediately to the left
+if <emphasis remap='I'>stopAtWordBreak</emphasis> is <function>True</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function need make no attempt to deal with line feeds. The text
+widget will only call it one line at a time. This is a more convenient
+interface to the <xref linkend='FindPosition' xrefstyle='select: title'/> function, and provides a subset of its
+functionality.
+<indexterm><primary>FindPosition</primary></indexterm>
+</para>
+</sect3>
+<sect3 id="Finding_the_Distance_Between_two_Text_Positions">
+<title>Finding the Distance Between two Text Positions</title>
+<para>
+<!-- .LP -->
+To find the distance in pixels between two text positions on the same
+line use the function <xref linkend='FindDistance' xrefstyle='select: title'/>.
+<indexterm significance="preferred"><primary>TextSink object</primary><secondary>FindDistance</secondary></indexterm>
+<funcsynopsis id='FindDistance'>
+<funcprototype>
+ <funcdef>void<function> FindDistance</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XawTextPositionfromPos,<parameter> toPos</parameter></paramdef>
+ <paramdef>int<parameter> fromX</parameter></paramdef>
+ <paramdef>XawTextPosition<parameter> *pos_return</parameter></paramdef>
+ <paramdef>int*width_return,<parameter> *height_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fromPos</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the text buffer position, in characters, of the first position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fromX</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the distance that the left edge of <emphasis remap='I'>fromPos</emphasis> is from the
+left edge of the window. This is the reference x location for the
+reference position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>toPos</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the text buffer position, in characters, of the second position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resWidth</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the actual distance between <emphasis remap='I'>fromPos</emphasis>
+and <emphasis remap='I'>pos_return</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resPos</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the character position that corresponds to the actual character
+position used for <emphasis remap='I'>toPos</emphasis> in the calculations. This may be
+different than <emphasis remap='I'>toPos</emphasis>, for example if <emphasis remap='I'>fromPos</emphasis> and <emphasis remap='I'>toPos</emphasis>
+are on different lines in the file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the maximum height of the text between <emphasis remap='I'>fromPos</emphasis> and
+<emphasis remap='I'>pos_return</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function need make no attempt to deal with line feeds. The Text
+widget will only call it one line at a time.
+</para>
+</sect3>
+<sect3 id="Finding_the_Size_of_the_Drawing_area">
+<title>Finding the Size of the Drawing area</title>
+<para>
+<!-- .LP -->
+To find the maximum number of lines that will fit into the current Text
+widget, use the function <xref linkend='MaxLines' xrefstyle='select: title'/>. The TextSink already defines
+this function to compute the maximum number of lines by using the height
+of <function>font</function>.
+<indexterm significance="preferred"><primary>TextSink object</primary><secondary>MaxLines</secondary></indexterm>
+<funcsynopsis id='MaxLines'>
+<funcprototype>
+ <funcdef>int<function> MaxLines</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>Dimension<parameter> height</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the height of the current drawing area.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+Returns the maximum number of lines that will fit in <emphasis remap='I'>height</emphasis>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To find the height required for a given number of text lines, use
+the function <xref linkend='MaxHeight' xrefstyle='select: title'/>. The TextSink already defines this
+function to compute the maximum height of the window by using the
+height of <function>font</function>.
+<indexterm significance="preferred"><primary>TextSink object</primary><secondary>MaxHeight</secondary></indexterm>
+<funcsynopsis id='MaxHeight'>
+<funcprototype>
+ <funcdef>int<function> MaxHeight</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> lines</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the height of the current drawing area.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+Returns the height that will be taken up by the number of lines passed.
+</para>
+</sect3>
+<sect3 id="Setting_the_Tab_Stops">
+<title>Setting the Tab Stops</title>
+<para>
+<!-- .LP -->
+To set the tab stops for a text sink use the <xref linkend='SetTabs' xrefstyle='select: title'/> function.
+The TextSink already defines this function to set the tab x location in
+pixels to be the number of characters times the figure width of
+<function>font</function>.
+<indexterm significance="preferred"><primary>TextSink object</primary><secondary>SetTabs</secondary></indexterm>
+<funcsynopsis id='SetTabs'>
+<funcprototype>
+ <funcdef>void<function> SetTabs</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>inttab_count,<parameter> *tabs</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSink object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>tab_count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of tabs passed in <emphasis remap='I'>tabs</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>tabs</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the position, in characters, of the tab stops.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function is responsible for the converting character positions passed
+to it into whatever internal positions the TextSink uses for tab placement.
+</para>
+</sect3>
+<sect3 id='Getting_the_Insert_Points_Size_and_Location'>
+<title>Getting the Insert Point's Size and Location</title>
+<para>
+<!-- .LP -->
+To get the size and location of the insert point use the
+<xref linkend='GetCursorBounds' xrefstyle='select: title'/> function.
+<indexterm significance="preferred"><primary>TextSink object</primary><secondary>GetCursorBounds</secondary></indexterm>
+<funcsynopsis id='GetCursorBounds'>
+<funcprototype>
+ <funcdef>void<function> GetCursorBounds</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>XRectangle<parameter> *rect_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the TextSinkObject.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rect_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the location and size of the insert point.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<emphasis remap='I'>Rect</emphasis> will be filled with the current size and location of the
+insert point.
+
+</para>
+</sect3>
+</sect2>
+</sect1>
Index: libXaw-1.0.14-new/specs
===================================================================
--- libXaw-1.0.14-new/specs (nonexistent)
+++ libXaw-1.0.14-new/specs (revision 5)
Property changes on: libXaw-1.0.14-new/specs
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: libXaw-1.0.14-new
===================================================================
--- libXaw-1.0.14-new (nonexistent)
+++ libXaw-1.0.14-new (revision 5)
Property changes on: libXaw-1.0.14-new
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: .
===================================================================
--- . (nonexistent)
+++ . (revision 5)
Property changes on: .
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Radix cross Linux
The main Radix cross Linux repository contains the build scripts of packages, which have the most complete and common functionality for desktop machines
452 Commits
2 Branches
1 Tag