aboutsummaryrefslogtreecommitdiff
path: root/libXaw/specs/CH1.xml
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2011-03-25 10:41:05 +0000
committermarha <marha@users.sourceforge.net>2011-03-25 10:41:05 +0000
commit272e57235cd60a2e65ac8258d96a02eb3939b687 (patch)
tree789d74bd6ec1cc468f1f81aab97d4e4dfdb2d5c5 /libXaw/specs/CH1.xml
parentb39f063f74bf0163eaf34db03134f226d18142ec (diff)
downloadvcxsrv-272e57235cd60a2e65ac8258d96a02eb3939b687.tar.gz
vcxsrv-272e57235cd60a2e65ac8258d96a02eb3939b687.tar.bz2
vcxsrv-272e57235cd60a2e65ac8258d96a02eb3939b687.zip
git update until 25 Mar 2011
xserver fontconfig glproto libXau libXft libXmu libfontenc libxcb mesa mkfontscale pixman randrproto xkeyboard-config xtrans xwininfo updated following packages: xproto-7.0.21 xineramaproto-1.2.1 libXt-1.1.1 libxkbfile-1.0.7 libXpm-3.5.9 libXfont-1.4.3 libXaw-1.0.9 bdftopcf-1.0.3 encodings-1.0.4 fixesproto-5.0 font-adobe-100dpi-1.0.3 font-adobe-75dpi-1.0.3 font-adobe-utopia-100dpi-1.0.4 font-adobe-utopia-75dpi-1.0.4 font-adobe-utopia-type1-1.0.4 font-alias-1.0.3 font-arabic-misc-1.0.3 font-bh-100dpi-1.0.3 font-bh-75dpi-1.0.3 font-bh-lucidatypewriter-100dpi-1.0.3 font-bh-lucidatypewriter-75dpi-1.0.3 font-bh-ttf-1.0.3 font-bh-type1-1.0.3 font-bitstream-100dpi-1.0.3 font-bitstream-75dpi-1.0.3 font-bitstream-speedo-1.0.2 font-bitstream-type1-1.0.3 font-cronyx-cyrillic-1.0.3 font-cursor-misc-1.0.3 font-daewoo-misc-1.0.3 font-dec-misc-1.0.3 font-ibm-type1-1.0.3 font-isas-misc-1.0.3 font-jis-misc-1.0.3 font-micro-misc-1.0.3 font-misc-cyrillic-1.0.3 font-misc-ethiopic-1.0.3 font-misc-meltho-1.0.3 font-misc-misc-1.1.2 font-mutt-misc-1.0.3 font-schumacher-misc-1.1.2 font-screen-cyrillic-1.0.4 font-sony-misc-1.0.3 font-sun-misc-1.0.3 font-util-1.2.0 font-winitzki-cyrillic-1.0.3 font-xfree86-type1-1.0.4
Diffstat (limited to 'libXaw/specs/CH1.xml')
-rw-r--r--libXaw/specs/CH1.xml725
1 files changed, 725 insertions, 0 deletions
diff --git a/libXaw/specs/CH1.xml b/libXaw/specs/CH1.xml
new file mode 100644
index 000000000..a4fb08c2d
--- /dev/null
+++ b/libXaw/specs/CH1.xml
@@ -0,0 +1,725 @@
+<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 <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>.
+</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_tk">
+<title>Introduction to the X Toolkit</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Introduction to the X Toolkit -->
+<!-- .XE -->
+<!-- .IN "introduction" "" "@DEF@" -->
+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 <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>).
+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>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Terminology -->
+<!-- .XE -->
+</para>
+<para>
+<!-- .LP -->
+In addition to the terms already defined for X programming (see
+<emphasis remap='I'>Xlib - C Language Interface</emphasis>),
+the following terms are specific to the Intrinsics and Athena widget set
+and used throughout this document.
+</para>
+<para>
+<!-- .LP -->
+<function>Application programmer</function>
+<!-- .IN "application programmer" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A programmer who uses the X Toolkit to produce an application user interface.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Child</function>
+<!-- .IN "child" "" "@DEF" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A widget that is contained within another "parent" widget.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Class</function>
+<!-- .IN "class" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The general group to which a specific object belongs.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Client</function>
+<!-- .IN "client" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A function that uses a widget in an application or for composing
+other widgets.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>FullName</function>
+<!-- .IN "FullName" "" "@DEF" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The name of a widget instance appended to the full name of its parent.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Instance</function>
+<!-- .IN "instance" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A specific widget object as opposed to a general widget class.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Method</function>
+<!-- .IN "method" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A function or procedure implemented by a widget class.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Name</function>
+<!-- .IN "name" "widget" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <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>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Object</function>
+<!-- .IN "object" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <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>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Parent</function>
+<!-- .IN "parent" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A widget that contains at least one other ("child") widget.
+A parent widget is also known as a composite widget.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Resource</function>
+<!-- .IN "resource" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A named piece of data in a widget that can be set by a client,
+by an application, or by user defaults.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Superclass</function>
+<!-- .IN "superclass" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A larger class of which a specific class is a member.
+All members of a class are also members of the superclass.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>User</function>
+<!-- .IN "user" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A person interacting with a workstation.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Widget</function>
+<!-- .IN "widget" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+An object providing a user-interface abstraction (for example, a Scrollbar
+widget).
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Widget class</function>
+<!-- .IN "widget class" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+The general group to which a specific widget belongs,
+otherwise known as the type of the widget.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>Widget programmer</function>
+<!-- .IN "widget programmer" "" "@DEF@" -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A programmer who adds new widgets to the X Toolkit.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Underlying_Model">
+<title>Underlying Model</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Underlying Model -->
+<!-- .XE -->
+<!-- .IN "underlying model" "" "@DEF@" -->
+The underlying architectural model is based on the following premises:
+<!-- .KS -->
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ <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>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ <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>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ <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>
+</itemizedlist>
+</sect1>
+<sect1 id="Conventions_Used_in_this_Manual">
+<title>Conventions Used in this Manual</title>
+<itemizedlist>
+ <listitem>
+ <para>
+<!-- .IN "conventions" "used in manual" "@DEF@" -->
+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.
+<!-- .IN "_return" "" "@DEF@" -->
+<!-- .IN "_in_out" "" "@DEF@" -->
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Format_of_the_Widget_Reference_Chapters">
+<title>Format of the Widget Reference Chapters</title>
+<para>
+<!-- .LP -->
+<!-- .IN "conventions" "chapter format" "@DEF@" -->
+<!-- .IN "chapter format" "" "@DEF@" -->
+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.
+<variablelist>
+ <varlistentry>
+ <term>
+ "Chapter <!-- xref -->
+ </term>
+ <listitem>
+ <para>
+Simple Widgets
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ "Chapter <!-- xref -->
+ </term>
+ <listitem>
+ <para>
+Menus
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ "Chapter <!-- xref -->
+ </term>
+ <listitem>
+ <para>
+Text Widgets
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ "Chapter <!-- xref -->
+ </term>
+ <listitem>
+ <para>
+Composite and Constraint Widget
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</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 &lt;X11/Xaw/Box.h&gt;
+Class Header file &lt;X11/Xaw/BoxP.h&gt;
+Class boxWidgetClass
+Class Name Box
+Superclass Composite
+<!-- .sp -->
+</literallayout>
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>Application Header File</function>
+ </term>
+ <listitem>
+ <para>
+<!-- .IN "application header file" "" "@DEF@" -->
+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 ``public'' header file.
+<!-- .IN "class header file" "" "@DEF@" -->
+ </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 ``private'' header file.
+<!-- .IN "class" "" "@DEF@" -->
+ </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.
+<!-- .IN "class name" "" "@DEF@" -->
+ </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.
+<!-- .IN "superclass" "" -->
+ </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.
+<!-- .IN "notes" "" "@DEF@" -->
+<!-- .IN "A, note" "" "@DEF@" -->
+<!-- .IN "D, note" "" "@DEF@" -->
+<!-- .IN "C, note" "" "@DEF@" -->
+<!-- .IN "R, note" "" "@DEF@" -->
+<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 <function>XtSetValues</function>.
+ </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 -->
+<!-- .IN "input focus" "" "@DEF@" -->
+<!-- .IN "input" "" "@DEF@" -->
+<!-- .IN "XtNinput" "" "@DEF@" -->
+<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
+<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis> for details
+on the <emphasis remap='I'>input</emphasis> resource.
+
+</para>
+</sect1>
+</chapter>