














         AAtthheennaa WWiiddggeett SSeett ---- CC LLaanngguuaaggee IInntteerrffaaccee

                      XX WWiinnddooww SSyysstteemm

                  XX VVeerrssiioonn 1111,, RReelleeaassee 77

                        lliibbXXaaww 11..00..77







                     Chris D. Peterson
                 formerly MIT X Consortium



















































X Window System is a trademark of The Open Group.

Copyright (C) 1985, 1986, 1987, 1988, 1989, 1991, 1994 X
Consortium

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documenta-
tion files (the ``Software''), to deal in the Software with-
out restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to
whom the Software is furnished to do so, subject to the fol-
lowing conditions:

The above copyright notice and this permission notice shall
be included in all copies or substantial portions of the
Software.

THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PUR-
POSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSOR-
TIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of the X Con-
sortium shall not be used in advertising or otherwise to
promote the sale, use or other dealings in this Software
without prior written authorization from the X Consortium.

Copyright (C) 1985, 1986, 1987, 1988, 1989, 1991 Digital
Equipment Corporation, Maynard, Massachusetts.

Permission to use, copy, modify and distribute this documen-
tation for any purpose and without fee is hereby granted,
provided that the above copyright notice appears in all
copies and that both that copyright notice and this permis-
sion notice appear in supporting documentation, and that the
name of Digital not be used in in advertising or publicity
pertaining to distribution of the software without specific,
written prior permission.  Digital makes no representations
about the suitability of the software described herein for












any purpose.  It is provided ``as is'' without express or
implied warranty.

































































                      AAcckknnoowwlleeddggmmeennttss



Many thanks go to Ralph Swick (Project Athena / Digital) who
has contributed much time and effort to this widget set.
Previous versions of the widget set are largely due to his
time and effort.  Many of the improvements that I have been
able to make are because he provided a solid foundation to
build upon.  While much of the effort has been Ralph's, many
other people have contributed to the code.


     Mark Ackerman (formerly Project Athena)
     Donna Converse (MIT X Consortium)
     Jim Fulton (formerly MIT X Consortium)
     Loretta Guarino-Reid (Digital WSL)
     Charles Haynes (Digital WSL)
     Rich Hyde (Digital WSL)
     Mary Larson (Digital UEG)
     Joel McCormack (Digital WSL)
     Ron Newman (formerly Project Athena)
     Jeanne Rich (Digital WSL)
     Terry Weissman (formerly Digital WSL)


While not much remains of the X10 toolkit, many of the ideas
for this widget set come from that original version.  The
design and implementation of the X10 toolkit were done by:


     Mike Gancarz (formerly Digital UEG)
     Charles Haynes (Digital WSL)
     Phil Karlton (formerly Digital WSL)
     Kathleen Langone (Digital UEG)
     Mary Larson (Digital UEG)
     Ram Rao (Digital UEG)
     Smokey Wallace (formerly Digital WSL)
     Terry Weissman (formerly Digital WSL)


I have used the formatting ideas, and some of the words from
previous versions of this document.  The X11R3 Athena widget
document was written by:


     Ralph R. Swick (Project Athena/ Digital)
     Terry Weissman (formerly Digital WSL)
     Al Mento (Digital UEG)


Putting this manual together was a major task in and of
itself.  I would like to thank Ralph Swick, Donna Converse,



                              vv








and Jim Fulton for taking the time to help convert my tech-
nical knowledge into legible text.  A special thanks to Jean
Diaz (O'Reilly and Associates) for spending nearly a month
with me working out all the annoying little details.


Chris D. Peterson
MIT X Consortium 1989



The R5 edition of this document has been edited by the
research staff of the MIT X Consortium, with significant
contributions by Jim Fulton (NCD).


Donna Converse
MIT X Consortium 1991



The R6 edition of this document has been edited to reflect
changes brought about by research staff of the Omron Corpo-
ration, with special recognition to Li Yuhong, Seiji Kuwari,
and Hiroshi Kuribayashi for the X11R5/contrib/lib/Xaw inter-
nationalization that inspired this version.


Frank Sheeran
Omron Corporation 1994



























                             vvii










                         CChhaapptteerr 11

             AAtthheennaa WWiiddggeettss aanndd TThhee IInnttrriinnssiiccss



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 Intrin-
sics.  In the X Toolkit, a widget is the combination of an X
window or subwindow and its associated input and output
semantics.

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 mix-
ing and matching widget sets.  For information about the
Intrinsics, see the _X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e
_I_n_t_e_r_f_a_c_e.

The Athena widget set is a library package layered on top of
the Intrinsics and Xlib that provides a set of user inter-
face tools sufficient to build a wide variety of applica-
tions.  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.

To the extent possible, the Intrinsics are "policy-free".
The application environment and widget set, not the Intrin-
sics, define, implement, and enforce:

+o    Policy

+o    Consistency

+o    Style

Each individual widget implementation defines its own pol-
icy.  The X Toolkit design allows for, but does not neces-
sarily encourage, the free mixing of radically differing
widget implementations.

11..11..  IInnttrroodduuccttiioonn ttoo tthhee XX TToooollkkiitt

The X Toolkit provides tools that simplify the design of
application user interfaces in the X Window System program-
ming environment.  It assists application programmers by
providing a set of common underlying user-interface



                              11





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


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 worksta-
tion users.

The X Toolkit consists of:

+o    A set of Intrinsics functions for building widgets

+o    An architectural model for constructing widgets

+o    A widget set for application programming

While the majority of the Intrinsics functions are intended
for the widget programmer, a subset of the Intrinsics func-
tions are to be used by application programmers (see  _X
_T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e).  The architec-
tural 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 poli-
cies.  Some of these widgets and policies are specific to a
single application domain, and others are common to a vari-
ety of applications.

The remainder of this chapter discusses the X Toolkit and
Athena widget set:

+o    Terminology

+o    Model

+o    Conventions used in this manual

+o    Format of the Widget Reference Chapters

11..22..  TTeerrmmiinnoollooggyy


In addition to the terms already defined for X programming
(see _X_l_i_b _-_- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e), the following terms
are specific to the Intrinsics and Athena widget set and
used throughout this document.

AApppplliiccaattiioonn pprrooggrraammmmeerr

     A programmer who uses the X Toolkit to produce an
     application user interface.

CChhiilldd

     A widget that is contained within another "parent" wid-
     get.



                              22





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


CCllaassss

     The general group to which a specific object belongs.

CClliieenntt

     A function that uses a widget in an application or for
     composing other widgets.

FFuullllNNaammee

     The name of a widget instance appended to the full name
     of its parent.

IInnssttaannccee

     A specific widget object as opposed to a general widget
     class.

MMeetthhoodd

     A function or procedure implemented by a widget class.

NNaammee

     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.

OObbjjeecctt

     A data abstraction consisting of private data and pri-
     vate 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 func-
     tions.  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.

PPaarreenntt

     A widget that contains at least one other ("child")
     widget.  A parent widget is also known as a composite
     widget.

RReessoouurrccee

     A named piece of data in a widget that can be set by a
     client, by an application, or by user defaults.



                              33





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


SSuuppeerrccllaassss

     A larger class of which a specific class is a member.
     All members of a class are also members of the super-
     class.

UUsseerr

     A person interacting with a workstation.

WWiiddggeett

     An object providing a user-interface abstraction (for
     example, a Scrollbar widget).

WWiiddggeett ccllaassss

     The general group to which a specific widget belongs,
     otherwise known as the type of the widget.

WWiiddggeett pprrooggrraammmmeerr

     A programmer who adds new widgets to the X Toolkit.

11..33..  UUnnddeerrllyyiinngg MMooddeell

The underlying architectural model is based on the following
premises:

Widgets are X windows

     Every user-interface widget is associated with an X
     window.  The X window ID for a widget is readily avail-
     able from the widget.  Standard Xlib calls can be used
     by widgets for many of their input and output opera-
     tions.

Information hiding

     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 implement-
     ing the widget.  All program interaction with the wid-
     get is performed by a set of operations (methods) that
     are defined for the widget.












                              44





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


Widget semantics and widget layout geometry

     Widget semantics are clearly separated from widget lay-
     out 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 pro-
     vided for associating geometric managers with widgets
     and for widgets to make suggestions about their own
     geometry.

11..44..  CCoonnvveennttiioonnss UUsseedd iinn tthhiiss MMaannuuaall

+o    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.

+o    Global symbols are printed in bboolldd and can be function
     names, symbols defined in include files, or structure
     names.  Arguments are printed in _i_t_a_l_i_c_s.

+o    Each function is introduced by a general discussion
     that distinguishes it from other functions.  The func-
     tion 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.

+o    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 _s_p_e_c_i_f_i_e_s or, in the case of multiple argu-
     ments, the word _s_p_e_c_i_f_y. The explanations for all argu-
     ments that are returned to you start with the word
     _r_e_t_u_r_n_s or, in the case of multiple arguments, the word
     _r_e_t_u_r_n.  The explanations for all arguments that you
     can pass and are returned start with the words _s_p_e_c_i_-
     _f_i_e_s _a_n_d _r_e_t_u_r_n_s.

+o    Any pointer to a structure that is used to return a
     value is designated as such by the ___r_e_t_u_r_n 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 ___i_n___o_u_t suf-
     fix.







                              55





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


11..55..  FFoorrmmaatt ooff tthhee WWiiddggeett RReeffeerreennccee CChhaapptteerrss

The majority of this document is a reference guide for the
Athena widget set.  Chapters three through six give the pro-
grammer 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.

The first few pages of every chapter give an overview of the
widgets in that section.  Widgets are grouped into chapters
by functionality.

Chapter 3
       Simple Widgets

Chapter 4
       Menus

Chapter 5
       Text Widgets

Chapter 6
       Composite and Constraint Widget

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.

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.


Application Header file<X11/Xaw/Box.h>
Class Header file   <X11/Xaw/BoxP.h>
Class               boxWidgetClass
Class Name          Box
Superclass          Composite



AApppplliiccaattiioonn HHeeaaddeerr FFiillee
                    This file must be included when an
                    application uses this widget.  It usu-
                    ally contains the class definition, and
                    some resource macros.  This is often
                    called the ``public'' header file.

CCllaassss HHeeaaddeerr FFiillee   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



                              66





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


                    ``private'' header file.

CCllaassss               This is the widget class of this widget.
                    This global symbol is passed to XXttCCrree--
                    aatteeWWiiddggeett so that the Intrinsics will
                    know which type of widget to create.

CCllaassss NNaammee          This is the resource name of this class.
                    This name can be used in a resource file
                    to match any widget of this class.

SSuuppeerrccllaassss          This is the superclass that this widget
                    class is descended from.  If you under-
                    stand 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.


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.

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.

A    This resource may be automatically adjusted when
     another resource is changed.

C    This resource is only settable at widget creation time,
     and may not be modified with XXttSSeettVVaalluueess.

D    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.

R    This resource is READ-ONLY, and may not be modified.

After the resource table is a detailed description of every
resource available to that widget.  Many of these are redun-
dant, but printing them with each widget saves page flip-
ping.  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 bboolldd.  If you have
already read the description of the superclass you need only
pay attention to the resources printed in bold.

For each composite widget there is a section on layout
semantics that follows the resource description.  This



                              77





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


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.

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.

11..66..  IInnppuutt FFooccuuss

The Intrinsics define a resource on all Shell widgets that
interact with the window manager called iinnppuutt.  This
resource requests the assistance of window manager in
acquiring the input focus.  The resource defaults to FFaallssee
in the Intrinsics, but is redefined to default to TTrruuee when
an application is using the Athena widget set.  An applica-
tion programmer may override this default and set the
resource back to FFaallssee if the application does not need the
window manager to give it the input focus.  See the _X
_T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e for details on
the _i_n_p_u_t resource.



































                              88





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77




                         CChhaapptteerr 22

                       UUssiinngg WWiiddggeettss



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 wid-
get).

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 alterna-
tive application programming interfaces.

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 program-
ming interface is provided in the document _X _T_o_o_l_k_i_t _I_n_t_r_i_n_-
_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e.

22..11..  SSeettttiinngg tthhee LLooccaallee

If it is desirable that the application take advantage of
internationalization (i18n), you must establish locale with
_X_t_S_e_t_L_a_n_g_u_a_g_e_P_r_o_c before XXttDDiissppllaayyIInniittiiaalliizzee or XXttAAppppIInnii--
ttiiaalliizzee is called.  For full details, please refer to the
document _X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e, sec-
tion 2.2. However, the following simplest-case call is suf-
ficient in many or most applications.


          XtSetLanguageProc(NULL, NULL, NULL);


Most notably, this will affect the Standard C locale, deter-
mine 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.






                              99





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


22..22..  IInniittiiaalliizziinngg tthhee TToooollkkiitt

You must call a toolkit initialization function before
invoking any other toolkit routines (besides locale setting,
above).  _X_t_A_p_p_I_n_i_t_i_a_l_i_z_e 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.

Widget XtAppInitialize(_a_p_p___c_o_n_t_e_x_t___r_e_t_u_r_n, _a_p_p_l_i_c_a_t_i_o_n___c_l_a_s_s, _o_p_t_i_o_n_s, _n_u_m___o_p_t_i_o_n_s,
                    _a_r_g_c___i_n___o_u_t, _a_r_g_v___i_n___o_u_t, _f_a_l_l_b_a_c_k___r_e_s_o_u_r_c_e_s, _a_r_g_s, _n_u_m___a_r_g_s)
      XtAppContext *_a_p_p___c_o_n_t_e_x_t___r_e_t_u_r_n;
      String _a_p_p_l_i_c_a_t_i_o_n___c_l_a_s_s;
      XrmOptionDescRec _o_p_t_i_o_n_s[];
      Cardinal _n_u_m___o_p_t_i_o_n_s;
      int *_a_r_g_c___i_n___o_u_t;
      String *_a_r_g_v___i_n___o_u_t[];
      String *_f_a_l_l_b_a_c_k___r_e_s_o_u_r_c_e_s;
      ArgList _a_r_g_s;
      Cardinal _n_u_m___a_r_g_s;


_a_p_p___c_o_n___r_e_t_u_r_n Returns the application context of this
               application, if non-NULL.

_a_p_p_l_i_c_a_t_i_o_n___c_l_a_s_s
               Specifies the class name of this application,
               which is usually the generic name for all
               instances of this application.  A useful con-
               vention is to form the class name by capital-
               izing the first letter of the application
               name. For example, the application named
               ``xman'' has a class name of ``Xman''.

_o_p_t_i_o_n_s        Specifies how to parse the command line for
               any application-specific resources.  The
               options argument is passed as a parameter to
               _X_r_m_P_a_r_s_e_C_o_m_m_a_n_d.  For further information,
               see _X_l_i_b _-_- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e.

_n_u_m___o_p_t_i_o_n_s    Specifies the number of entries in the
               options list.

_a_r_g_c___i_n___o_u_t    Specifies a pointer to the number of command
               line parameters.

_a_r_g_v___i_n___o_u_t    Specifies the command line parameters.

_f_a_l_l_b_a_c_k___r_e_s_o_u_r_c_e_s
               Specifies resource values to be used if the
               site-wide application class defaults file
               cannot be opened, or NULL.





                             1100





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


_a_r_g_s           Specifies the argument list to use when cre-
               ating the Application shell.

_n_u_m___a_r_g_s       Specifies the number of arguments in _a_r_g_s.

This function will remove the command line arguments that
the toolkit reads from _a_r_g_c___i_n___o_u_t, and _a_r_g_v___i_n___o_u_t.  It
will then attempt to open the display.  If the display can-
not be opened, an error message is issued and XtAppInitial-
ize terminates the application.  Once the display is opened,
all resources are read from the locations specified by the
Intrinsics.  This function returns an ApplicationShell wid-
get to be used as the root of the application's widget tree.

22..33..  CCrreeaattiinngg aa WWiiddggeett

Creating a widget is a three-step process.  First, the wid-
get instance is allocated, and various instance-specific
attributes are set by using XXttCCrreeaatteeWWiiddggeett.  Second, the
widget's parent is informed of the new child by using XXttMMaann--
aaggeeCChhiilldd.  Finally, X windows are created for the parent and
all its children by using XXttRReeaalliizzeeWWiiddggeett and specifying the
top-most widget. The first two steps can be combined by
using XXttCCrreeaatteeMMaannaaggeeddWWiiddggeett.  In addition, XXttRReeaalliizzeeWWiiddggeett
is automatically called when the child becomes managed if
the parent is already realized.

To allocate, initialize, and manage a widget, use
_X_t_C_r_e_a_t_e_M_a_n_a_g_e_d_W_i_d_g_e_t.

Widget XtCreateManagedWidget(_n_a_m_e, _w_i_d_g_e_t___c_l_a_s_s, _p_a_r_e_n_t, _a_r_g_s, _n_u_m___a_r_g_s)
      String _n_a_m_e;
      WidgetClass _w_i_d_g_e_t___c_l_a_s_s;
      Widget _p_a_r_e_n_t;
      ArgList _a_r_g_s;
      Cardinal _n_u_m___a_r_g_s;


_n_a_m_e      Specifies the instance name for the created widget
          that is used for retrieving widget resources.

_w_i_d_g_e_t___c_l_a_s_s
          Specifies the widget class pointer for the created
          widget.

_p_a_r_e_n_t    Specifies the parent widget ID.

_a_r_g_s      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 fur-
          ther information, see Section 2.7.2.





                             1111





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


_n_u_m___a_r_g_s  Specifies the number of arguments in the argument
          list.  If the num_args is zero, the argument list
          is never referenced.

When a widget instance is successfully created, the widget
identifier is returned to the application.  If an error is
encountered, the _X_t_E_r_r_o_r routine is invoked to inform the
user of the error.

For further information, see _X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_-
_g_u_a_g_e _I_n_t_e_r_f_a_c_e.

22..44..  CCoommmmoonn RReessoouurrcceess

Although a widget can have unique arguments that it under-
stands, all widgets have common arguments that provide some
regularity of operation.  The common arguments allow arbi-
trary widgets to be managed by higher-level components with-
out regard for the individual widget type.  Widgets will
ignore any argument that they do not understand.

The following resources are retrieved from the argument list
or from the resource database by all of the Athena widgets:

--------------------------------------------------------------------------------
NNaammee                CCllaassss               TTyyppee               DDeeffaauulltt VVaalluuee
--------------------------------------------------------------------------------
accelerators        Accelerators        AcceleratorTable   NULL
ancestorSensitive   AncestorSensitive   Boolean            True
background          Background          Pixel              XtDefaultBackground
backgroundPixmap    Pixmap              Pixmap             XtUnspecifiedPixmap
borderColor         BorderColor         Pixel              XtDefaultForeground
borderPixmap        Pixmap              Pixmap             XtUnspecifiedPixmap
borderWidth         BorderWidth         Dimension          1
colormap            Colormap            Colormap           Parent's Colormap
depth               Depth               int                Parent's Depth
destroyCallback     Callback            XtCallbackList     NULL
height              Height              Dimension          _w_i_d_g_e_t _d_e_p_e_n_d_e_n_t
mappedWhenManaged   MappedWhenManaged   Boolean            True
screen              Screen              Screen             Parent's Screen
sensitive           Sensitive           Boolean            True
translations        Translations        TranslationTable   _w_i_d_g_e_t _d_e_p_e_n_d_e_n_t
width               Width               Dimension          _w_i_d_g_e_t _d_e_p_e_n_d_e_n_t
x                   Position            Position           0
y                   Position            Position           0
--------------------------------------------------------------------------------


The following additional resources are retrieved from the
argument list or from the resource database by many of the
Athena widgets:






                             1122





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


------------------------------------------------------------------------
NNaammee                CCllaassss         TTyyppee             DDeeffaauulltt VVaalluuee
------------------------------------------------------------------------
callback            Callback      XtCallbackList   NULL
cursor              Cursor        Cursor           _w_i_d_g_e_t _d_e_p_e_n_d_e_n_t
foreground          Foreground    Pixel            XtDefaultForeground
insensitiveBorder   Insensitive   Pixmap           GreyPixmap
------------------------------------------------------------------------


22..55..  RReessoouurrccee CCoonnvveerrssiioonnss

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 spe-
cific mention of the allowable values.  Three general con-
verters are described here:

+o    Cursor

+o    Pixel

+o    Bitmap

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.

22..55..11..  CCuurrssoorr CCoonnvveerrssiioonn

The value for the ccuurrssoorrNNaammee resource is specified in the
resource database as a string, and is of the following
forms:

+o    A standard X cursor name from << XX1111//ccuurrssoorrffoonntt..hh >>.
     The names in ccuurrssoorrffoonntt..hh each describe a specific cur-
     sor.  The resource names for these cursors are exactly
     like the names in this file except the XXCC__ is not used.
     The cursor definition XXCC__gguummbbyy has a resource name of
     gguummbbyy.

+o    Glyphs, as in _F_O_N_T _f_o_n_t_-_n_a_m_e _g_l_y_p_h_-_i_n_d_e_x _[_[ _f_o_n_t_-_n_a_m_e _]
     _g_l_y_p_h_-_i_n_d_e_x _].  The first font and glyph specify the
     cursor source pixmap.  The second font and glyph spec-
     ify the cursor mask pixmap.  The mask font defaults to
     the source font, and the mask glyph index defaults to
     the source glyph index.

+o    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.



                             1133





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


     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).

22..55..22..  PPiixxeell CCoonnvveerrssiioonn

The string-to-pixel converter takes any name that is accept-
able to XParseColor (see _X_l_i_b _-_- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e).
In addition this routine understands the special toolkit
symbols `XtDefaultForeground' and `XtDefaultBackground',
described in _X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e.
In short the acceptable pixel names are:

+o    Any color name for the rgb.txt file (typically in the
     directory /usr/lib/X11 on POSIX systems).

+o    A numeric specification of the form #<red><green><blue>
     where these numeric values are hexadecimal digits (both
     upper and lower case).

+o    The special strings `XtDefaultForeground' and `XtDe-
     faultBackground'

22..55..33..  BBiittmmaapp CCoonnvveerrssiioonn

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 bbiittmmaappFFiilleePPaatthh resource--class BBiittmmaappFFiilleePPaatthh.  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 bbiittmmaappFFiilleePPaatthh resource is global
to the application, and may nnoott be specified differently for
each widget that wishes to convert a cursor to bitmap.  In
addition to the directories specified in the bbiittmmaappFFiilleePPaatthh
resource a default directory is searched.  When using POSIX
the default directory is _/_u_s_r_/_i_n_c_l_u_d_e_/_X_1_1_/_b_i_t_m_a_p_s.

22..66..  RReeaalliizziinngg aa WWiiddggeett

The _X_t_R_e_a_l_i_z_e_W_i_d_g_e_t function performs two tasks:

+o    Calculates the geometry constraints of all managed
     descendants of this widget.  The actual calculation is
     put off until realize time for performance reasons.

+o    Creates an X window for the widget and, if it is a com-
     posite widget, realizes each of its managed children.

void XtRealizeWidget(_w)
      Widget _w;





                             1144





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


_w         Specifies the widget.

For further information about this function, see the _X
_T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e.

22..77..  PPrroocceessssiinngg EEvveennttss

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 XXttAAppppMMaaiinnLLoooopp.

void XtAppMainLoop(_a_p_p___c_o_n_t_e_x_t)
      XtAppContext _a_p_p___c_o_n_t_e_x_t;


_a_p_p___c_o_n_t_e_x_t
          Specifies the application context of this applica-
          tion.  The value is normally returned by XXttAAppppIInnii--
          ttiiaalliizzee.

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 _X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_-
_g_u_a_g_e _I_n_t_e_r_f_a_c_e.

22..88..  SSttaannddaarrdd WWiiddggeett MMaanniippuullaattiioonn FFuunnccttiioonnss

After a widget has been created, a client can interact with
that widget by calling one of the standard widget manipula-
tion routines provided by the Intrinsics, or a widget class-
specific manipulation routine.

The Intrinsics provide generic routines to give the applica-
tion programmer access to a set of standard widget func-
tions.  The common widget routines let an application or
composite widget perform the following operations on widgets
without requiring explicit knowledge of the widget type.

+o    Control the mapping of widget windows

+o    Destroy a widget instance

+o    Obtain an argument value

+o    Set an argument value

22..88..11..  MMaappppiinngg WWiiddggeettss

By default, widget windows are mapped (made viewable) auto-
matically by XXttRReeaalliizzeeWWiiddggeett.  This behavior can be disabled
by using XXttSSeettMMaappppeeddWWhheennMMaannaaggeedd, making the client responsi-
ble for calling XXttMMaappWWiiddggeett to make the widget viewable.



                             1155





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


void XtSetMappedWhenManaged(_w, _m_a_p___w_h_e_n___m_a_n_a_g_e_d)
      Widget _w;
      Boolean _m_a_p___w_h_e_n___m_a_n_a_g_e_d;


_w         Specifies the widget.

_m_a_p___w_h_e_n___m_a_n_a_g_e_d
          Specifies the new value.  If map_when_managed is
          TTrruuee, the widget is mapped automatically when it
          is realized.  If map_when_managed is FFaallssee, the
          client must call _X_t_M_a_p_W_i_d_g_e_t or make a second call
          to _X_t_S_e_t_M_a_p_p_e_d_W_h_e_n_M_a_n_a_g_e_d to cause the child win-
          dow to be mapped.


The definition for _X_t_M_a_p_W_i_d_g_e_t is:

void XtMapWidget(_w)
     Widget _w;


_w         Specifies the widget.

When you are creating several children in sequence for a
previously realized common parent it is generally more effi-
cient to construct a list of children as they are created
(using XXttCCrreeaatteeWWiiddggeett) and then use XXttMMaannaaggeeCChhiillddrreenn to
request that their parent managed them all at once.  By man-
aging a list of children at one time, the parent can avoid
wasteful duplication of geometry processing and the associ-
ated ``screen flash''.

void XtManageChildren(_c_h_i_l_d_r_e_n, _n_u_m___c_h_i_l_d_r_e_n)
      WidgetList _c_h_i_l_d_r_e_n;
      Cardinal _n_u_m___c_h_i_l_d_r_e_n;


_c_h_i_l_d_r_e_n  Specifies a list of children to add.

_n_u_m___c_h_i_l_d_r_e_n
          Specifies the number of children to add.

If the parent is already visible on the screen, it is espe-
cially important to batch updates so that the minimum amount
of visible window reconfiguration is performed.

For further information about these functions, see the _X
_T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e.

22..88..22..  DDeessttrrooyyiinngg WWiiddggeettss

To destroy a widget instance of any type, use
_X_t_D_e_s_t_r_o_y_W_i_d_g_e_t.



                             1166





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


void XtDestroyWidget(_w)
      Widget _w;


_w         Specifies the widget.

_X_t_D_e_s_t_r_o_y_W_i_d_g_e_t destroys the widget and recursively destroys
any children that it may have, including the windows created
by its children.  After calling _X_t_D_e_s_t_r_o_y_W_i_d_g_e_t, no further
references should be made to the widget or any children that
the destroyed widget may have had.

22..88..33..  RReettrriieevviinngg WWiiddggeett RReessoouurrccee VVaalluueess

To retrieve the current value of a resource attribute asso-
ciated with a widget instance, use _X_t_G_e_t_V_a_l_u_e_s.

void XtGetValues(_w, _a_r_g_s, _n_u_m___a_r_g_s)
      Widget _w;
      ArgList _a_r_g_s;
      Cardinal _n_u_m___a_r_g_s;


_w         Specifies the widget.

_a_r_g_s      Specifies a variable-length argument list of name
          and aaddddrreessss pairs that contain the resource name
          and the address into which the resource value is
          stored.

_n_u_m___a_r_g_s  Specifies the number of arguments in the argument
          list.

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 AArrggLLiisstt contains a pointer to this storage
(e.g. x and y must be allocated as Position).  For further
information, see the _X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e
_I_n_t_e_r_f_a_c_e.

22..88..44..  MMooddiiffyyiinngg WWiiddggeett RReessoouurrccee VVaalluueess

To modify the current value of a resource attribute associ-
ated with a widget instance, use _X_t_S_e_t_V_a_l_u_e_s.

void XtSetValues(_w, _a_r_g_s, _n_u_m___a_r_g_s)
      Widget _w;
      ArgList _a_r_g_s;
      Cardinal _n_u_m___a_r_g_s;


_w         Specifies the widget.




                             1177





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


_a_r_g_s      Specifies an array of name and vvaalluuee pairs that
          contain the arguments to be modified and their new
          values.

_n_u_m___a_r_g_s  Specifies the number of arguments in the argument
          list.

The arguments and values that are passed will depend on the
widget being modified.  Some widgets may not allow certain
resources to be modified after the widget instance has been
created or realized.  No notification is given if any part
of a XXttSSeettVVaalluueess request is ignored.

For further information about these functions, see the _X
_T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e.

                            Note

     The argument list entry for _X_t_G_e_t_V_a_l_u_e_s specifies
     the address to which the caller wants the value
     copied.  The argument list entry for _X_t_S_e_t_V_a_l_u_e_s,
     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.


22..99..  UUssiinngg tthhee CClliieenntt CCaallllbbaacckk IInntteerrffaaccee

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:

void _C_a_l_l_b_a_c_k_P_r_o_c(_w, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      Widget _w;
      XtPointer _c_l_i_e_n_t___d_a_t_a;
      XtPointer _c_a_l_l___d_a_t_a;


_w         Specifies widget for which the callback is regis-
          tered.

_c_l_i_e_n_t___d_a_t_a
          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 call-
          back to also register client-specific data: a
          pointer to additional information about the wid-
          get, a reason for invoking the callback, and so
          on. If no additional information is necessary,
          NULL may be passed as this argument.  This field



                             1188





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


          is also frequently known as the _c_l_o_s_u_r_e.

_c_a_l_l___d_a_t_a Specifies any callback-specific data the widget
          wants to pass to the client.  For example, when
          Scrollbar executes its jjuummppPPrroocc callback list, it
          passes the current position of the thumb in
          _c_a_l_l___d_a_t_a.

Callbacks can be registered either by creating an argument
containing the callback list described below or by using the
special convenience routines XXttAAddddCCaallllbbaacckk and XXttAAddddCCaallll--
bbaacckkss.  When the widget is created, a pointer to a list of
callback procedure and data pairs can be passed in the argu-
ment list to _X_t_C_r_e_a_t_e_W_i_d_g_e_t.  The list is of type
_X_t_C_a_l_l_b_a_c_k_L_i_s_t:


typedef struct {
     XtCallbackProc callback;
     XtPointer closure;
} XtCallbackRec, *XtCallbackList;


The callback list must be allocated and initialized before
calling _X_t_C_r_e_a_t_e_W_i_d_g_e_t.  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.

The second method for registering callbacks is to use _X_t_A_d_d_-
_C_a_l_l_b_a_c_k after the widget has been created.

void XtAddCallback(_w, _c_a_l_l_b_a_c_k___n_a_m_e_, _c_a_l_l_b_a_c_k, _c_l_i_e_n_t___d_a_t_a)
      Widget _w;
      String _c_a_l_l_b_a_c_k___n_a_m_e;
      XtCallbackProc _c_a_l_l_b_a_c_k;
      XtPointer _c_l_i_e_n_t___d_a_t_a;


_w         Specifies the widget to add the callback to.

_c_a_l_l_b_a_c_k___n_a_m_e
          Specifies the callback list within the widget to
          append to.

_c_a_l_l_b_a_c_k  Specifies the callback procedure to add.

_c_l_i_e_n_t___d_a_t_a
          Specifies the data to be passed to the callback
          when it is invoked.





                             1199





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


_X_t_A_d_d_C_a_l_l_b_a_c_k adds the specified callback to the list for
the named widget.

All widgets provide a callback list named _d_e_s_t_r_o_y_C_a_l_l_b_a_c_k
where clients can register procedures that are to be exe-
cuted when the widget is destroyed.  The destroy callbacks
are executed when the widget or an ancestor is destroyed.
The _c_a_l_l___d_a_t_a argument is unused for destroy callbacks.

22..1100..  PPrrooggrraammmmiinngg CCoonnssiiddeerraattiioonnss

This section provides some guidelines on how to set up an
application program that uses the X Toolkit.

22..1100..11..  WWrriittiinngg AApppplliiccaattiioonnss

When writing an application that uses the X Toolkit, you
should make sure that your application performs the follow-
ing:

1.   Include <_X_1_1_/_I_n_t_r_i_n_s_i_c_._h> in your application programs.
     This header file automatically includes <_X_1_1_/_X_l_i_b_._h>,
     so all Xlib functions also are defined.  It may also be
     necessary to include << XX1111//SSttrriinnggDDeeffss..hh >> when setting
     up argument lists, as many of the XtN_s_o_m_e_t_h_i_n_g defini-
     tions are only defined in this file.

2.   Include the widget-specific header files for each wid-
     get type that you need to use.  For example,
     <_X_1_1_/_X_a_w_/_L_a_b_e_l_._h> and <_X_1_1_/_X_a_w_/_C_o_m_m_a_n_d_._h>.

3.   Call the _X_t_A_p_p_I_n_i_t_i_a_l_i_z_e function before invoking any
     other toolkit or Xlib functions.  For further informa-
     tion, see Section 2.1 and the _X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C
     _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e.

4.   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 XXttNN to help catch spelling errors.
     For example, XXttNNllaabbeell is defined for the llaabbeell resource
     of many widgets.

     For further information, see Section 2.9.2.2.

5.   When the argument list is set up, create the widget
     with the XXttCCrreeaatteeMMaannaaggeeddWWiiddggeett function.  For further
     information, see Section 2.2 and the _X _T_o_o_l_k_i_t _I_n_t_r_i_n_-
     _s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e.

6.   If the widget has any callback routines, set by the
     _X_t_N_c_a_l_l_b_a_c_k argument or the _X_t_A_d_d_C_a_l_l_b_a_c_k function,



                             2200





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


     declare these routines within the application.

7.   After creating the initial widget hierarchy, windows
     must be created for each widget by calling _X_t_R_e_a_l_-
     _i_z_e_W_i_d_g_e_t on the top level widget.

8.   Most applications now sit in a loop processing events
     using _X_t_A_p_p_M_a_i_n_L_o_o_p, for example:


     XtCreateManagedWidget(_n_a_m_e, _c_l_a_s_s, _p_a_r_e_n_t, _a_r_g_s, _n_u_m___a_r_g_s);
     XtRealizeWidget(_s_h_e_l_l);
     XtAppMainLoop(_a_p_p___c_o_n_t_e_x_t);


     For information about this function, see the _X _T_o_o_l_k_i_t
     _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e.

9.   Link your application with _l_i_b_X_a_w (the Athena widgets),
     _l_i_b_X_m_u (miscellaneous utilities), _l_i_b_X_t (the X Toolkit
     Intrinsics), _l_i_b_S_M (Session Management), _l_i_b_I_C_E (Inter-
     Client Exchange), _l_i_b_X_e_x_t (the extension library needed
     for the shape extension code which allows rounded Com-
     mand buttons), and _l_i_b_X_1_1 (the core X library).  The
     following provides a sample command line:


     cc -o _a_p_p_l_i_c_a_t_i_o_n _a_p_p_l_i_c_a_t_i_o_n.c -lXaw -lXmu -lXt -lSM -lICE -lXext -lX11


22..1100..22..  CChhaannggiinngg RReessoouurrccee VVaalluueess

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 pro-
vide slightly different functionality.

Resource Manager
               This method picks up resource definitions
               described in _X_l_i_b _-_- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e
               from many different locations at run time.
               The locations most important to the applica-
               tion programmer are the _f_a_l_l_b_a_c_k _r_e_s_o_u_r_c_e_s
               and the _a_p_p_-_d_e_f_a_u_l_t_s file, (see _X _T_o_o_l_k_i_t
               _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e for the
               complete list).  Since these resource are
               loaded at run time, they can be overridden by
               the user, allowing an application to be cus-
               tomized 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



                             2211





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               should use resources in preference to hard-
               coded values whenever possible.

Argument Lists 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.

22..1100..22..11..  SSppeecciiffyyiinngg RReessoouurrcceess

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.

XXrrddbb           The xxrrddbb 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.

AApppplliiccaattiioonn DDeeffaauullttss
               The application defaults (app-defaults) file
               (normally in /usr/lib/X11/app-defaults/_c_l_a_s_s_-
               _n_a_m_e) for an application is loaded whenever
               the application is started.

The resource specification has two colon-separated parts, a
name, and a value.  The _v_a_l_u_e is a string whose format is
dependent on the resource specified by _n_a_m_e.  _N_a_m_e is con-
structed by appending a resource name to a full widget name.

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:

xman.form.button1
               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.)



                             2222





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


Xman.Form.Command
               This will match any Command widget that is a
               child of a Form widget that is itself a child
               of an application of class _X_m_a_n.

Xman.Form.button1
               This is a mixed resource name with both wid-
               get names and classes specified.

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:

Xman*Command   This matches all Command widgets in the Xman
               application.

Foo*button1    This matches any widget in the Foo applica-
               tion that is named _b_u_t_t_o_n_1.

The root of all application widget trees is the widget
returned by XXttAAppppIInniittiiaalliizzee.  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 applica-
tion (aarrggvv[[00]]) or the name of the application specified
using the standard _-_n_a_m_e command line option supported by
the Intrinsics.

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.

*foreground:Blue      Specifies that all widgets in all
                      applications will have a foreground
                      color of blue.

Xman*borderWidth:10   Specifies that all widgets in an
                      application whose class is Xman will
                      have a border width of 10 (pixels).

xman.form.button1.label:Testing
                      Specifies that a particular widget in
                      the xman application will have a label
                      named _T_e_s_t_i_n_g.

An exclamation point (!) in the first column of a line indi-
cates that the rest of the line should be treated as a com-
ment.

FFiinnaall WWoorrddss




                             2233





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


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:

+o    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 XXttGGeettAApppplliiccaattiioonnRReessoouurrcceess.

+o    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.

+o    Only one resource line will match any given resource.
     There is a set of precedence rules, which take the fol-
     lowing general stance.

     +o    More specific overrides less specific, thus period
     always overrides asterisk.

     +o    Names on the left are more specific and override
     names on the right.

     +o    When resource specifications are exactly the same,
     user defaults
          will override program defaults.

For a complete explanation of the rules of precedence, and
other specific topics see _X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e
_I_n_t_e_r_f_a_c_e and _X_l_i_b _-_- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e.

22..1100..22..22..  CCrreeaattiinngg AArrgguummeenntt LLiissttss

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_r_e_s_o_u_r_c_e _n_a_m_e.  For example, the symbol for ``fore-
ground'' is XXttNNffoorreeggrroouunndd. For further information, see the
_X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e.

Argument are specified by using the following structure:


typedef struct {
     String name;
     XtArgVal value;
} Arg, *ArgList;






                             2244





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The first approach is to statically initialize the argument
list.  For example:


static Arg arglist[] = {
     {XtNwidth, (XtArgVal) 400},
     {XtNheight, (XtArgVal) 300},
};


This approach is convenient for lists that do not need to be
computed at runtime and makes adding or deleting new ele-
ments easy.  The _X_t_N_u_m_b_e_r macro is used to compute the num-
ber of elements in the argument list, preventing simple pro-
gramming errors:


     XtCreateWidget(_n_a_m_e, _c_l_a_s_s, _p_a_r_e_n_t, _a_r_g_l_i_s_t, XtNumber(_a_r_g_l_i_s_t));


The second approach is to use the _X_t_S_e_t_A_r_g macro.  For exam-
ple:


Arg arglist[10];
XtSetArg(arglist[1], XtNwidth, 400);
XtSetArg(arglist[2], XtNheight, 300);


To make it easier to insert and delete entries, you also can
use a variable index:


Arg arglist[10];
Cardinal i=0;
XtSetArg(arglist[i], XtNwidth,  400);       i++;
XtSetArg(arglist[i], XtNheight, 300);       i++;


The i variable can then be used as the argument list count
in the widget create function.  In this example, _X_t_N_u_m_b_e_r
would return 10, not 2, and therefore is not useful.

                            Note

     You should not use auto-increment or auto-decre-
     ment within the first argument to _X_t_S_e_t_A_r_g.  As it
     is currently implemented, _X_t_S_e_t_A_r_g is a macro that
     dereferences the first argument twice.


The third approach is to individually set the elements of
the argument list array:




                             2255





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


Arg arglist[10];
arglist[0].name  = XtNwidth;
arglist[0].value = (XtArgVal) 400;
arglist[1].name  = XtNheight;
arglist[1].value = (XtArgVal) 300;


Note that in this example, as in the previous example,
_X_t_N_u_m_b_e_r would return 10, not 2, and therefore would not be
useful.

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:


static Arg arglist[] = {
     {XtNwidth, (XtArgVal) 400},
     {XtNheight, (XtArgVal) NULL},
};
arglist[1].value = (XtArgVal) 300;


In this example, _X_t_N_u_m_b_e_r can be used, as in the first
approach, for easier code maintenance.

22..1111..  EExxaammppllee PPrrooggrraammss

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 pro-
gramming concepts, is available in the X11R6 release as dis-
tributed by the X Consortium.  It can be found in the dis-
tribution directory ccoonnttrriibb//eexxaammpplleess//mmiitt//XXaaww, but see your
site administrator for the exact location of these files on
your system.  See the README file from that directory for a
guide to the examples.



















                             2266





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77




                         CChhaapptteerr 33

                       SSiimmppllee WWiiddggeettss




Each of these widgets performs a specific user interface
function.  They are _s_i_m_p_l_e because they cannot have widget
children--they may only be used as leaves of the widget
tree.  These widgets display information or take user input.


CCoommmmaanndd   A push button that, when selected, may cause a
          specific action to take place.  This widget can
          display a multi-line string or a bitmap or pixmap
          image.

GGrriipp      A rectangle that, when selected, will cause an
          action to take place.

LLaabbeell     A rectangle that can display a multi-line string
          or a bitmap or pixmap image.

LLiisstt      A list of text strings presented in row column
          format that may be individually selected.  When an
          element is selected an action may take place.

PPaannnneerr    A rectangular area containing a _s_l_i_d_e_r that may be
          moved in two dimensions.  Notification of movement
          may be continuous or discrete.

RReeppeeaatteerr  A push button that triggers an action at an
          increasing rate when selected.  This widget can
          display a multi-line string or a bitmap or pixmap
          image.

SSccrroollllbbaarr A rectangular area containing a _t_h_u_m_b that when
          slid along one dimension may cause a specific
          action to take place.  The Scrollbar may be ori-
          ented horizontally or vertically.

SSiimmppllee    The base class for most of the simple widgets.
          Provides a rectangular area with a settable mouse
          cursor and special border.

SSttrriippCChhaarrtt
          A real time data graph that will automatically
          update and scroll.

TTooggggllee    A push button that contains state information.
          Toggles may also be used as ``radio buttons'' to



                             2277





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


          implement a ``one of many'' or ``zero or one of
          many'' group of buttons.  This widget can display
          a multi-line string or a bitmap or pixmap image.

33..11..  CCoommmmaanndd WWiiddggeett


Application header file<X11/Xaw/Command.h>
Class header file   <X11/Xaw/CommandP.h>
Class               commandWidgetClass
Class Name          Command
Superclass          Label



The Command widget is an area, often rectangular, that con-
tains text or a graphical image. Command widgets are often
referred to as ``push buttons.''  When the pointer is over a
Command widget, the widget becomes highlighted by drawing a
rectangle around its perimeter.  This highlighting indicates
that the widget is ready for selection.  When mouse button 1
is pressed, the Command widget indicates that it has been
selected by reversing its foreground and background colors.
When the mouse button is released, the Command widget's
nnoottiiffyy action is invoked, calling all functions on its call-
back list.  If the pointer is moved off of the widget before
the pointer button is released, the widget reverts to its
normal foreground and background colors, and releasing the
pointer button has no effect.  This behavior allows the user
to cancel an action.

33..11..11..  RReessoouurrcceess

When creating a Command widget instance, the following
resources are retrieved from the argument list or from the
resource database:


-------------------------------------------------------------------------------------------------
NNaammee                  CCllaassss             TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
-------------------------------------------------------------------------------------------------
accelerators          Accelerators      AcceleratorTable     NULL
ancestorSensitive     AncestorSensitive Boolean         D    True
background            Background        Pixel                XtDefaultBackground
backgroundPixmap      Pixmap            Pixmap               XtUnspecifiedPixmap
bitmap                Bitmap            Pixmap               None
borderColor           BorderColor       Pixel                XtDefaultForeground
borderPixmap          Pixmap            Pixmap               XtUnspecifiedPixmap
borderWidth           BorderWidth       Dimension            1
callback              Callback          XtCallbackList       NULL
colormap              Colormap          Colormap             Parent's Colormap
cornerRoundPercent    CornerRoundPercentDimension            25
cursor                Cursor            Cursor               None




                             2288





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


-------------------------------------------------------------------------------------------------
NNaammee                  CCllaassss             TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
-------------------------------------------------------------------------------------------------
cursorName            Cursor            String               NULL
depth                 Depth             int             C    Parent's Depth
destroyCallback       Callback          XtCallbackList       NULL
encoding              Encoding          UnsignedChar         XawTextEncoding8bit
font                  Font              XFontStruct          XtDefaultFont
foreground            Foreground        Pixel                XtDefaultForeground
height                Height            Dimension       A    graphic height + 2 * iinntteerrnnaallHHeeiigghhtt
highlightThickness    Thickness         Dimension       A    2 (0 if Shaped)
insensitiveBorder     Insensitive       Pixmap               GreyPixmap
internalHeight        Height            Dimension            2
internalWidth         Width             Dimension            4
international         International     Boolean         C    False
justify               Justify           Justify              XtJustifyCenter (center)
label                 Label             String               name of widget
leftBitmap            LeftBitmap        Bitmap               None
mappedWhenManaged     MappedWhenManaged Boolean              True
pointerColor          Foreground        Pixel                XtDefaultForeground
pointerColorBackgroundBackground        Pixel                XtDefaultBackground
resize                Resize            Boolean              True
screen                Screen            Screen          R    Parent's Screen
sensitive             Sensitive         Boolean              True
shapeStyle            ShapeStyle        ShapeStyle           Rectangle
translations          Translations      TranslationTable     See below
width                 Width             Dimension       A    graphic width + 2 * iinntteerrnnaallWWiiddtthh
x                     Position          Position             0
y                     Position          Position             0
-------------------------------------------------------------------------------------------------



accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap



                             2299





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               specified will be used instead of the back-
               ground color.

bitmap         A bitmap to display instead of the llaabbeell.
               The default size of the widget will be just
               large enough to contain the bitmap and the
               widget's internal width and height.  The
               resource converter for this resource con-
               structs bitmaps from the contents of files.
               (See CCoonnvveerrttiinngg BBiittmmaappss for details.)  If
               this bitmap is one bit deep then the 1's will
               be rendered in the foreground color, and the
               0's in the background color.  If bbiittmmaapp has a
               depth greater than one, it is copied directly
               into the window.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

ccaallllbbaacckk       A list of routines to be called when the
               nnoottiiffyy action is invoked.

colormap       The colormap that this widget will use.

ccoorrnneerrRRoouunnddPPeerrcceenntt
               When a SShhaappeeSSttyyllee of rroouunnddeeddRReeccttaannggllee is
               used, this resource controls the radius of
               the rounded corner.  The radius of the
               rounded corners is specified as a percentage
               of the length of the shortest side of the
               widget.

cursor         The image that will be displayed as the
               pointer cursor whenever it is in this widget.
               The use of this resource is deprecated in
               favor of ccuurrssoorrNNaammee.

cursorName     The name of the symbol to use to represent
               the pointer cursor.  This resource will over-
               ride the ccuurrssoorr resource if both are speci-
               fied. (See 2.4.1)

depth          The depth of this widget's window.





                             3300





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


destroyCallback
               All functions on this list are called when
               this widget is destroyed.

encoding       The encoding method used by the value of the
               llaabbeell resource.  The value may be XXaawwTTeexxttEEnn--
               ccooddiinngg88bbiitt or XXaawwTTeexxttEEnnccooddiinnggCChhaarr22bb.  When
               iinntteerrnnaattiioonnaall is set to ttrruuee this resource is
               not used.

font           The text font to use when displaying the
               llaabbeell, when the iinntteerrnnaattiioonnaall resource is
               ffaallssee.

fontSet        The text font set to use when displaying the
               llaabbeell, when the iinntteerrnnaattiioonnaall resource is
               ttrruuee.

foreground     A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               widget's window.  This color is also used to
               render all 1's in a bbiittmmaapp one plane deep.

height
width          The height and width of this widget in pix-
               els.

hhiigghhlliigghhttTThhiicckknneessss
               The thickness of the rectangle that is used
               to highlight the internal border of this wid-
               get, alerting the user that it is ready to be
               selected.  The default value is 2 pixels if
               the sshhaappeeSSttyyllee is rreeccttaannggllee, and 0 Pixels (no
               highlighting) otherwise.

insensitiveBorder
               This pixmap will be tiled into the widget's
               border if the widget becomes insensitive.

internalHeight
internalWidth  The minimum amount of space to leave between
               the graphic and the vertical and horizontal
               edges of the window.

international  This is a boolean flag, only settable at wid-
               get creation time.  A value of ffaallssee signals
               the widget to use pre-R6 internationalization
               (specifically, the lack thereof), such as
               using fonts for displaying text, etc.  A
               value of ttrruuee directs the widget to act in an
               internationalized manner, such as utilizing
               font sets for displaying text, etc.





                             3311





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


justify        Specifies left, center, or right alignment of
               graphic within the widget.  This resource may
               be specified with the values XXttJJuussttiiffyyLLeefftt,
               XXttJJuussttiiffyyCCeenntteerr, or XXttJJuussttiiffyyRRiigghhtt.  A con-
               verter is registered for this resource that
               will convert the following strings: lleefftt,,
               rriigghhtt,, and cceenntteerr.  This resource only has
               noticeable effect when the width of the wid-
               get is larger than necessary to display the
               graphic.  Note that when the graphic is a
               multi-line llaabbeell, the longest line will obey
               this justification while shorter lines will
               be left-justified with the longest one.


label          Specifies the text string to be displayed in
               the widget's window if no bitmap is speci-
               fied.  The default is the name of this wid-
               get.  Regardless of the value of eennccooddiinngg or
               iinntteerrnnaattiioonnaall, a single newline character (1
               byte) will cause a line break.

leftBitmap     Specifies a bitmap to display to the left of
               the graphic in the widget's window.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

pointerColor   A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               pointer symbol specified by the ccuurrssoorrNNaammee
               resource.

pointerColorBackground
                 A pixel value which indexes the widget's
                 colormap to derive the background color of
                 the pointer symbol specified by the ccuurrssoorr--
                 NNaammee resource.

resize         Specifies whether the widget should attempt
               to resize to its preferred dimensions when-
               ever its resources are modified with XXttSSeett--
               VVaalluueess.  This attempt to resize may be denied
               by the parent of this widget.  The parent is
               always free to resize the widget regardless
               of the state of this resource.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not



                             3322





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

sshhaappeeSSttyyllee     Nonrectangular widgets may be created using
               this resource.  Nonrectangular widgets are
               supported only on a server that supports the
               SShhaappee EExxtteennssiioonn.  If nonrectangular widgets
               are specified for a server lacking this
               extension, the shape is ignored and the wid-
               gets will be rectangular.  The following
               shapes are currently supported: XXmmuuSShhaappeeRReecctt--
               aannggllee, XXmmuuSShhaappeeOOvvaall, XXmmuuSShhaappeeEElllliippssee, and
               XXmmuuSShhaappeeRRoouunnddeeddRReeccttaannggllee.  A converter is
               registered for this resource that will con-
               vert the following strings: rreeccttaannggllee,, oovvaall,,
               eelllliippssee,, and rroouunnddeeddRReeccttaannggllee.

translations   The event bindings associated with this wid-
               get.

x
y              The location of the upper left outside corner
               of this widget in its parent.

33..11..22..  CCoommmmaanndd AAccttiioonnss

The Command widget supports the following actions:

+o    Switching the button's interior between the foreground
     and background colors with sseett, uunnsseett, and rreesseett.

+o    Processing application callbacks with nnoottiiffyy

+o    Switching the internal border between highlighted and
     unhighlighted states with hhiigghhlliigghhtt and uunnhhiigghhlliigghhtt

The following are the default translation bindings used by
the Command widget:


     <EnterWindow>:   highlight()
     <LeaveWindow>:   reset()
     <Btn1Down>:      set()
     <Btn1Up>:        notify() unset()


The full list of actions supported by Command is:

hhiigghhlliigghhtt(_c_o_n_d_i_t_i_o_n)
               Displays the internal highlight border in the
               color (ffoorreeggrroouunndd or bbaacckkggrroouunndd ) that con-
               trasts with the interior color of the Command
               widget.  The conditions WWhheennUUnnsseett and AAllwwaayyss
               are understood by this action procedure.  If



                             3333





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               no argument is passed, WWhheennUUnnsseett is assumed.

uunnhhiigghhlliigghhtt()  Displays the internal highlight border in the
               color (ffoorreeggrroouunndd or bbaacckkggrroouunndd ) that
               matches the interior color of the Command
               widget.

sseett()          Enters the _s_e_t state, in which nnoottiiffyy is pos-
               sible.  This action causes the button to dis-
               play its interior in the ffoorreeggrroouunndd color.
               The label or bitmap is displayed in the bbaacckk--
               ggrroouunndd color.

uunnsseett()        Cancels the _s_e_t state and displays the inte-
               rior of the button in the bbaacckkggrroouunndd color.
               The label or bitmap is displayed in the ffoorree--
               ggrroouunndd color.

rreesseett()        Cancels any _s_e_t or _h_i_g_h_l_i_g_h_t and displays the
               interior of the button in the bbaacckkggrroouunndd
               color, with the label or bitmap displayed in
               the ffoorreeggrroouunndd color.

nnoottiiffyy()       When the button is in the sseett state this
               action calls all functions in the callback
               list named by the ccaallllbbaacckk resource.  The
               value of the _c_a_l_l___d_a_t_a argument passed to
               these functions is undefined.

A very common alternative to registering callbacks is to
augment a Command's translations with an action performing
the desired function.  This often takes the form of:


*Myapp*save.translations: #augment <Btn1Down>,<Btn1Up>: Save()



                            Note

     When a bitmap of depth greater that one (1) is
     specified the _s_e_t(), _u_n_s_e_t(), and _r_e_s_e_t() actions
     have no effect, since there are no foreground and
     background colors used in a multi-plane pixmap.


33..22..  GGrriipp WWiiddggeett


Application header file<X11/Xaw/Grip.h>
Class header file   <X11/Xaw/GripP.h>
Class               gripWidgetClass
Class Name          Grip
Superclass          Simple



                             3344





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


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.

33..22..11..  RReessoouurrcceess

When creating a Grip widget instance, the following
resources are retrieved from the argument list or from the
resource database:


---------------------------------------------------------------------------------
NNaammee                  CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
---------------------------------------------------------------------------------
accelerators          Accelerators     AcceleratorTable     NULL
ancestorSensitive     AncestorSensitiveBoolean         D    True
background            Background       Pixel                XtDefaultBackground
backgroundPixmap      Pixmap           Pixmap               XtUnspecifiedPixmap
borderColor           BorderColor      Pixel                XtDefaultForeground
borderPixmap          Pixmap           Pixmap               XtUnspecifiedPixmap
borderWidth           BorderWidth      Dimension            0
callback              Callback         Callback             NULL
colormap              Colormap         Colormap             Parent's Colormap
cursor                Cursor           Cursor               None
cursorName            Cursor           String               NULL
depth                 Depth            int             C    Parent's Depth
destroyCallback       Callback         XtCallbackList       NULL
foreground            Foreground       Pixel                XtDefaultForeground
height                Height           Dimension            8
insensitiveBorder     Insensitive      Pixmap               GreyPixmap
international         International    Boolean         C    False
mappedWhenManaged     MappedWhenManagedBoolean              True
pointerColor          Foreground       Pixel                XtDefaultForeground
pointerColorBackgroundBackground       Pixel                XtDefaultBackground
screen                Screen           Screen          R    Parent's Screen
sensitive             Sensitive        Boolean              True
translations          Translations     TranslationTable     NULL
width                 Width            Dimension            8
x                     Position         Position             0
y                     Position         Position             0
---------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if



                             3355





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

ccaallllbbaacckk       All routines on this list are called whenever
               the GGrriippAAccttiioonn action routine is invoked.
               The _c_a_l_l___d_a_t_a contains all information passed
               to the action routine.  A detailed descrip-
               tion is given below in the GGrriipp AAccttiioonnss sec-
               tion.

colormap       The colormap that this widget will use.

cursor         The image that will be displayed as the
               pointer cursor whenever it is in this widget.
               The use of this resource is deprecated in
               favor of ccuurrssoorrNNaammee.

cursorName     The name of the symbol to use to represent
               the pointer cursor.  This resource will over-
               ride the ccuurrssoorr resource if both are speci-
               fied. (See 2.4.1)

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

ffoorreeggrroouunndd     A pixel value which indexes the widget's col-
               ormap to derive the color used to flood fill



                             3366





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               the entire Grip widget.

height
width          The height and width of this widget in pix-
               els.

insensitiveBorder
               This pixmap will be tiled into the widget's
               border if the widget becomes insensitive.

international  This is a boolean flag, only settable at wid-
               get creation time.  While not utilized in
               this widget, it can and should be checked by
               any subclasses that have behavior that should
               vary with locale.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

pointerColor   A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               pointer symbol specified by the ccuurrssoorrNNaammee
               resource.

pointerColorBackground
                 A pixel value which indexes the widget's
                 colormap to derive the background color of
                 the pointer symbol specified by the ccuurrssoorr--
                 NNaammee resource.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

translations   The event bindings associated with this wid-
               get.

x
y              The location of the upper left outside corner
               of this widget in its parent.

33..22..22..  GGrriipp AAccttiioonnss

The Grip widget does not declare any default event transla-
tion bindings, but it does declare a single action routine
named GGrriippAAccttiioonn.  The client specifies an arbitrary event
translation table, optionally giving parameters to the GGrrii--
ppAAccttiioonn routine.



                             3377





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The GGrriippAAccttiioonn routine executes the callbacks on the ccaallll--
bbaacckk list, passing as _c_a_l_l___d_a_t_a a pointer to a XXaawwGGrriippCCaallll--
DDaattaa structure, defined in the Grip widget's application
header file.



typedef struct _XawGripCallData {
     XEvent *event;
     String *params;
     Cardinal num_params;
} XawGripCallDataRec, *XawGripCallData,
  GripCallDataRec, *GripCallData; /* supported for R4 compatibility */



In this structure, the _e_v_e_n_t is a pointer to the input event
that triggered the action.  _p_a_r_a_m_s and _n_u_m___p_a_r_a_m_s give the
string parameters specified in the translation table for the
particular event binding.

The following is an example of a translation table that uses
the GripAction:



     <Btn1Down>:         GripAction(press)
     <Btn1Motion>:       GripAction(move)
     <Btn1Up>:           GripAction(release)


For a complete description of the format of translation
tables, see the _X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_-
_f_a_c_e.

33..33..  LLaabbeell WWiiddggeett


Application header file<X11/Xaw/Label.h>
Class header file   <X11/Xaw/LabelP.h>
Class               labelWidgetClass
Class Name          Label
Superclass          Simple



A Label widget holds a graphic displayed within a rectangu-
lar region of the screen.  The graphic may be a text string
containing multiple lines of characters in an 8 bit or 16
bit character set (to be displayed with a _f_o_n_t), or in a
multi-byte encoding (for use with a _f_o_n_t_s_e_t).  The graphic
may also be a bitmap or pixmap.  The Label widget will allow
its graphic to be left, right, or center justified.  Nor-
mally, this widget can be neither selected nor directly



                             3388





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


edited by the user.  It is intended for use as an output
device only.

33..33..11..  RReessoouurrcceess

When creating a Label widget instance, the following
resources are retrieved from the argument list or from the
resource database:


------------------------------------------------------------------------------------------------
NNaammee                  CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
------------------------------------------------------------------------------------------------
accelerators          Accelerators     AcceleratorTable     NULL
ancestorSensitive     AncestorSensitiveBoolean         D    True
background            Background       Pixel                XtDefaultBackground
backgroundPixmap      Pixmap           Pixmap               XtUnspecifiedPixmap
bitmap                Bitmap           Pixmap               None
borderColor           BorderColor      Pixel                XtDefaultForeground
borderPixmap          Pixmap           Pixmap               XtUnspecifiedPixmap
borderWidth           BorderWidth      Dimension            1
colormap              Colormap         Colormap             Parent's Colormap
cursor                Cursor           Cursor               None
cursorName            Cursor           String               NULL
depth                 Depth            int             C    Parent's Depth
destroyCallback       Callback         XtCallbackList       NULL
encoding              Encoding         UnsignedChar         XawTextEncoding8bit
font                  Font             XFontStruct          XtDefaultFont
fontSet               FontSet          XFontSet             XtDefaultFontSet
foreground            Foreground       Pixel                XtDefaultForeground
height                Height           Dimension       A    graphic height + 2 * iinntteerrnnaallHHeeiigghhtt
insensitiveBorder     Insensitive      Pixmap               GreyPixmap
internalHeight        Height           Dimension            2
internalWidth         Width            Dimension            4
international         International    Boolean         C    False
justify               Justify          Justify              XtJustifyCenter (center)
label                 Label            String               name of widget
leftBitmap            LeftBitmap       Bitmap               None
mappedWhenManaged     MappedWhenManagedBoolean              True
pointerColor          Foreground       Pixel                XtDefaultForeground
pointerColorBackgroundBackground       Pixel                XtDefaultBackground
resize                Resize           Boolean              True
screen                Screen           Screen          R    Parent's Screen
sensitive             Sensitive        Boolean              True
translations          Translations     TranslationTable     See above
width                 Width            Dimension       A    graphic width + 2 * iinntteerrnnaallWWiiddtthh
x                     Position         Position             0
y                     Position         Position             0
------------------------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X



                             3399





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

bbiittmmaapp         A bitmap to display instead of the llaabbeell.
               The default size of the widget will be just
               large enough to contain the bitmap and the
               widget's internal width and height.  The
               resource converter for this resource con-
               structs bitmaps from the contents of files.
               (See CCoonnvveerrttiinngg BBiittmmaappss for details.)  If
               this bitmap is one bit deep then the 1's will
               be rendered in the foreground color, and the
               0's in the background color.  If bbiittmmaapp has a
               depth greater than one, it is copied directly
               into the window.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

colormap       The colormap that this widget will use.

cursor         The image that will be displayed as the
               pointer cursor whenever it is in this widget.
               The use of this resource is deprecated in
               favor of ccuurrssoorrNNaammee.





                             4400





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


cursorName     The name of the symbol to use to represent
               the pointer cursor.  This resource will over-
               ride the ccuurrssoorr resource if both are speci-
               fied. (See 2.4.1)

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

eennccooddiinngg       The encoding method used by the value of the
               llaabbeell resource.  The value may be XXaawwTTeexxttEEnn--
               ccooddiinngg88bbiitt or XXaawwTTeexxttEEnnccooddiinnggCChhaarr22bb.  When
               iinntteerrnnaattiioonnaall is set to ttrruuee this resource is
               not used.

ffoonntt           The text font to use when displaying the
               llaabbeell, when the iinntteerrnnaattiioonnaall resource is
               ffaallssee.

ffoonnttSSeett        The text font set to use when displaying the
               llaabbeell, when the iinntteerrnnaattiioonnaall resource is
               ttrruuee.

ffoorreeggrroouunndd     A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               widget's window.  This color is also used to
               render all 1's in a bbiittmmaapp one plane deep.

height
width          The height and width of this widget in pix-
               els.

insensitiveBorder
               This pixmap will be tiled into the widget's
               border if the widget becomes insensitive.

iinntteerrnnaallHHeeiigghhtt
iinntteerrnnaallWWiiddtthh  The minimum amount of space to leave between
               the graphic and the vertical and horizontal
               edges of the window.

international  This is a boolean flag, only settable at wid-
               get creation time.  A value of ffaallssee signals
               the widget to use pre-R6 internationalization
               (specifically, the lack thereof), such as
               using fonts for displaying text, etc.  A
               value of ttrruuee directs the widget to act in an
               internationalized manner, such as utilizing
               font sets for displaying text, etc.

jjuussttiiffyy        Specifies left, center, or right alignment of
               graphic within the widget.  This resource may



                             4411





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               be specified with the values XXttJJuussttiiffyyLLeefftt,
               XXttJJuussttiiffyyCCeenntteerr, or XXttJJuussttiiffyyRRiigghhtt.  A con-
               verter is registered for this resource that
               will convert the following strings: lleefftt,,
               rriigghhtt,, and cceenntteerr.  This resource only has
               noticeable effect when the width of the wid-
               get is larger than necessary to display the
               graphic.  Note that when the graphic is a
               multi-line llaabbeell, the longest line will obey
               this justification while shorter lines will
               be left-justified with the longest one.


llaabbeell          Specifies the text string to be displayed in
               the widget's window if no bitmap is speci-
               fied.  The default is the name of this wid-
               get.  Regardless of the value of eennccooddiinngg or
               iinntteerrnnaattiioonnaall, a single newline character (1
               byte) will cause a line break.

lleeffttBBiittmmaapp     Specifies a bitmap to display to the left of
               the graphic in the widget's window.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

pointerColor   A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               pointer symbol specified by the ccuurrssoorrNNaammee
               resource.

pointerColorBackground
                 A pixel value which indexes the widget's
                 colormap to derive the background color of
                 the pointer symbol specified by the ccuurrssoorr--
                 NNaammee resource.

rreessiizzee         Specifies whether the widget should attempt
               to resize to its preferred dimensions when-
               ever its resources are modified with XXttSSeett--
               VVaalluueess.  This attempt to resize may be denied
               by the parent of this widget.  The parent is
               always free to resize the widget regardless
               of the state of this resource.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.



                             4422





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


translations   The event bindings associated with this wid-
               get.

x
y              The location of the upper left outside corner
               of this widget in its parent.

33..44..  LLiisstt WWiiddggeett



Application header file<X11/Xaw/List.h>
Class header file   <X11/Xaw/ListP.h>
Class               listWidgetClass
Class Name          List
Superclass          Simple




The List widget contains a list of strings formatted into
rows and columns. When one of the strings is selected, it is
highlighted, and the List widget's NNoottiiffyy action is invoked,
calling all routines on its callback list.  Only one string
may be selected at a time.

33..44..11..  RReessoouurrcceess

When creating a List widget instance, the following
resources are retrieved from the argument list or from the
resource database:


----------------------------------------------------------------------------------------------
NNaammee                  CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
----------------------------------------------------------------------------------------------
accelerators          Accelerators     AcceleratorTable     NULL
ancestorSensitive     AncestorSensitiveBoolean         D    True
background            Background       Pixel                XtDefaultBackground
backgroundPixmap      Pixmap           Pixmap               XtUnspecifiedPixmap
borderColor           BorderColor      Pixel                XtDefaultForeground
borderPixmap          Pixmap           Pixmap               XtUnspecifiedPixmap
borderWidth           BorderWidth      Dimension            1
callback              Callback         Callback             NULL
colormap              Colormap         Colormap             Parent's Colormap
columnSpacing         Spacing          Dimension            6
cursor                Cursor           Cursor               XC_left_ptr
cursorName            Cursor           String               NULL
defaultColumns        Columns          int                  2
depth                 Depth            int             C    Parent's Depth
destroyCallback       Callback         XtCallbackList       NULL
font                  Font             FontStruct           XtDefaultFont
fontSet               FontSet          XFontSet             XtDefaultFontSet




                             4433





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


----------------------------------------------------------------------------------------------
NNaammee                  CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
----------------------------------------------------------------------------------------------
forceColumns          Columns          Boolean              False
foreground            Foreground       Pixel                XtDefaultForeground
height                Height           Dimension       A    Enough space to contain the list
insensitiveBorder     Insensitive      Pixmap               GreyPixmap
internalHeight        Height           Dimension            2
internalWidth         Width            Dimension            4
international         International    Boolean         C    False
list                  List             Pointer              name of widget
longest               Longest          int             A    0
mappedWhenManaged     MappedWhenManagedBoolean              True
numberStrings         NumberStrings    int             A    computed for NULL terminated list
pasteBuffer           Boolean          Boolean              False
pointerColor          Foreground       Pixel                XtDefaultForeground
pointerColorBackgroundBackground       Pixel                XtDefaultBackground
rowSpacing            Spacing          Dimension            2
screen                Screen           Screen          R    Parent's Screen
sensitive             Sensitive        Boolean              True
translations          Translations     TranslationTable     See below
verticalList          Boolean          Boolean              False
width                 Width            Dimension       A    Enough space to contain the list
x                     Position         Position             0
y                     Position         Position             0
----------------------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the



                             4444





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               widget's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

ccaallllbbaacckk       All functions on this list are called when-
               ever the nnoottiiffyy action is invoked.  The
               _c_a_l_l___d_a_t_a argument contains information about
               the element selected and is described in
               detail in the LLiisstt CCaallllbbaacckkss section.

colormap       The colormap that this widget will use.

ccoolluummnnSSppaacciinngg
rroowwSSppaacciinngg     The amount of space, in pixels, between each
               of the rows and columns in the list.

cursor         The image that will be displayed as the
               pointer cursor whenever it is in this widget.
               The use of this resource is deprecated in
               favor of ccuurrssoorrNNaammee.

cursorName     The name of the symbol to use to represent
               the pointer cursor.  This resource will over-
               ride the ccuurrssoorr resource if both are speci-
               fied. (See 2.4.1)

ddeeffaauullttCCoolluummnnss The default number of columns.  This value is
               used when neither the width nor the height of
               the List widget is specified or when
               ffoorrcceeCCoolluummnnss is TTrruuee.

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

ffoonntt           The text font to use when displaying the
               lliisstt, when the iinntteerrnnaattiioonnaall resource is
               ffaallssee.

ffoonnttSSeett        The text font set to use when displaying the
               lliisstt, when the iinntteerrnnaattiioonnaall resource is
               ttrruuee.

ffoorrcceeCCoolluummnnss   Forces the default number of columns to be
               used regardless of the List widget's current
               size.



                             4455





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


ffoorreeggrroouunndd     A pixel value which indexes the widget's col-
               ormap to derive the color used to paint the
               text of the list elements.

height
width          The height and width of this widget in pix-
               els.

insensitiveBorder
               This pixmap will be tiled into the widget's
               border if the widget becomes insensitive.

internalHeight
internalWidth  The margin, in pixels, between the edges of
               the list and the corresponding edge of the
               List widget's window.

lliisstt           An array of text strings displayed in the
               List widget.  If nnuummbbeerrSSttrriinnggss is zero (the
               default) then the lliisstt must be NULL termi-
               nated.  If a value is not specified for the
               lliisstt, then nnuummbbeerrSSttrriinnggss is set to 1, and the
               name of the widget is used as the lliisstt, and
               lloonnggeesstt is set to the length of the name of
               the widget.  The lliisstt is used in place, and
               must be available to the List widget for the
               lifetime of this widget, or until it is
               changed with XXttSSeettVVaalluueess or XXaawwLLiissttCChhaannggee.

international  This is a boolean flag, only settable at wid-
               get creation time.  A value of ffaallssee signals
               the widget to use pre-R6 internationalization
               (specifically, the lack thereof), such as
               using fonts for displaying text, etc.  A
               value of ttrruuee directs the widget to act in an
               internationalized manner, such as utilizing
               font sets for displaying text, etc.

lloonnggeesstt        Specifies the width, in pixels, of the
               longest string in the current list.  The List
               widget will compute this value if zero (the
               default) is specified.  If this resource is
               set by hand, entries longer than this will be
               clipped to fit.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

nnuummbbeerrSSttrriinnggss  The number of strings in the current list.
               If a value of zero (the default) is speci-
               fied, the List widget will compute it.  When
               computing the number of strings the List



                             4466





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               widget assumes that the lliisstt is NULL termi-
               nated.

ppaasstteeBBuuffffeerr    If this resource is set to TTrruuee then the name
               of the currently selected list element will
               be put into CCUUTT__BBUUFFFFEERR__00.

pointerColor   A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               pointer symbol specified by the ccuurrssoorrNNaammee
               resource.

pointerColorBackground
                 A pixel value which indexes the widget's
                 colormap to derive the background color of
                 the pointer symbol specified by the ccuurrssoorr--
                 NNaammee resource.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

translations   The event bindings associated with this wid-
               get.

vveerrttiiccaallLLiisstt   If this resource is set to TTrruuee then the list
               elements will be presented in column major
               order.

x
y              The location of the upper left outside corner
               of this widget in its parent.

33..44..22..  LLiisstt AAccttiioonnss

The List widget supports the following actions:

+o    Highlighting and unhighlighting the list element under
     the pointer with SSeett and UUnnsseett

+o    Processing application callbacks with NNoottiiffyy

The following is the default translation table used by the
List Widget:


     <Btn1Down>,<Btn1Up>:  Set() Notify()






                             4477





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The full list of actions supported by List widget is:

SSeett()          _S_e_t_s the list element that is currently under
               the pointer.  To inform the user that this
               element is currently set, it is drawn with
               foreground and background colors reversed.
               If this action is called when there is no
               list element under the cursor, the currently
               _s_e_t element will be _u_n_s_e_t.

UUnnsseett()        Cancels the _s_e_t state of the element under
               the pointer, and redraws it with normal fore-
               ground and background colors.

NNoottiiffyy()       Calls all callbacks on the List widget's
               callback list.  Information about the cur-
               rently selected list element is passed in the
               _c_a_l_l___d_a_t_a argument (see LLiisstt CCaallllbbaacckkss
               below).

33..44..33..  LLiisstt CCaallllbbaacckkss

All procedures on the List widget's callback list will have
a XXaawwLLiissttRReettuurrnnSSttrruucctt passed to them as _c_a_l_l___d_a_t_a.  The
structure is defined in the List widget's application header
file.


typedef struct _XawListReturnStruct {
     String string;   /* string shown in the list. */
     int list_index;  /* index of the item selected. */
} XawListReturnStruct;

                            Note

     The _l_i_s_t___i_n_d_e_x item used to be called simply
     _i_n_d_e_x.  Unfortunately, this name collided with a
     global name defined on some operating systems, and
     had to be changed.



33..44..44..  CChhaannggiinngg tthhee LLiisstt

To change the list that is displayed, use _X_a_w_L_i_s_t_C_h_a_n_g_e.

void XawListChange(_w, _l_i_s_t, _n_i_t_e_m_s, _l_o_n_g_e_s_t, _r_e_s_i_z_e)
     Widget _w;
     String * _l_i_s_t;
     int _n_i_t_e_m_s, _l_o_n_g_e_s_t;
     Boolean _r_e_s_i_z_e;






                             4488





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


_w         Specifies the List widget.

_l_i_s_t      Specifies the new list for the List widget to dis-
          play.

_n_i_t_e_m_s    Specifies the number of items in the _l_i_s_t.  If a
          value less than 1 is specified, _l_i_s_t must be NULL
          terminated, and the number of items will be calcu-
          lated by the List widget.

_l_o_n_g_e_s_t   Specifies the length of the longest item in the
          _l_i_s_t in pixels.  If a value less than 1 is speci-
          fied, the List widget will calculate the value.

_r_e_s_i_z_e    Specifies a Boolean value that if TTrruuee indicates
          that the List widget should try to resize itself
          after making the change.  The constraints of the
          List widget's parent are always enforced, regard-
          less of the value specified here.

_X_a_w_L_i_s_t_C_h_a_n_g_e will _u_n_s_e_t all list elements that are cur-
rently sseett before the list is actually changed.  The _l_i_s_t is
used in place, and must remain usable for the lifetime of
the List widget, or until _l_i_s_t has been changed again with
this function or with XXttSSeettVVaalluueess.

33..44..55..  HHiigghhlliigghhttiinngg aann IItteemm

To highlight an item in the list, use _X_a_w_L_i_s_t_H_i_g_h_l_i_g_h_t.

void XawListHighlight(_w, _i_t_e_m)
     Widget _w;
     int _i_t_e_m;


_w         Specifies the List widget.

_i_t_e_m      Specifies an index into the current list that
          indicates the item to be highlighted.

Only one item can be highlighted at a time.  If an item is
already highlighted when _X_a_w_L_i_s_t_H_i_g_h_l_i_g_h_t is called, the
highlighted item is unhighlighted before the new item is
highlighted.

33..44..66..  UUnnhhiigghhlliigghhttiinngg aann IItteemm

To unhighlight the currently highlighted item in the list,
use _X_a_w_L_i_s_t_U_n_h_i_g_h_l_i_g_h_t.

void XawListUnhighlight(_w)
     Widget _w;





                             4499





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


_w         Specifies the List widget.

33..44..77..  RReettrriieevviinngg tthhee CCuurrrreennttllyy SSeelleecctteedd IItteemm

To retrieve the list element that is currently _s_e_t, use
_X_a_w_L_i_s_t_S_h_o_w_C_u_r_r_e_n_t.

XawListReturnStruct *XawListShowCurrent(_w)
     Widget _w;


_w         Specifies the List widget.

_X_a_w_L_i_s_t_S_h_o_w_C_u_r_r_e_n_t returns a pointer to an _X_a_w_L_i_s_t_R_e_t_u_r_n_-
_S_t_r_u_c_t structure, containing the currently highlighted item.
If the value of the index member is XAW_LIST_NONE, the
string member is undefined, and no item is currently
selected.

33..44..88..  RReessttrriiccttiioonnss

Many programmers create a ``scrolled list'' by putting a
List widget with many entries as a child of a Viewport wid-
get.  The List continues to create a window as big as its
contents, but that big window is only visible where it
intersects the parent Viewport's window.  (I.e., it is
``clipped.'')

While this is a useful technique, there is a serious draw-
back.  X does not support windows above 32,767 pixels in
width or height, but this height limit will be exceeded by a
List's window when the List has many entries (i.e., with a
12 point font, about 3000 entries would be too many.)


33..55..  PPaannnneerr WWiiddggeett



Application header file<X11/Xaw/Panner.h>
Class header file   <X11/Xaw/PannerP.h>
Class               pannerWidgetClass
Class Name          Panner
Superclass          Simple



A Panner widget is a rectangle, called the ``canvas,'' on
which another rectangle, the ``slider,'' moves in two dimen-
sions.  It is often used with a Porthole widget to move, or
``scroll,'' a third widget in two dimensions, in which case
the slider's size and position gives feedback as to what
portion of the third widget is visible.




                             5500





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The slider may be scrolled around the canvas by pressing,
dragging, and releasing Button1; the default translation
also enables scrolling via arrow keys and some other keys.
While scrolling is in progress, the application receives
notification through callback procedures.  Notification may
be done either continuously whenever the slider moves or
discretely whenever the slider has been given a new loca-
tion.

33..55..11..  RReessoouurrcceess

When creating a Panner widget instance, the following
resources are retrieved from the argument list or from the
resource database:


-----------------------------------------------------------------------------------
NNaammee                  CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
-----------------------------------------------------------------------------------
accelerators          Accelerators     AcceleratorTable     NULL
allowOff              AllowOff         Boolean              False
ancestorSensitive     AncestorSensitiveBoolean         D    True
background            Background       Pixel                XtDefaultBackground
backgroundPixmap      Pixmap           Pixmap               XtUnspecifiedPixmap
backgroundStipple     BackgroundStippleString               NULL
borderColor           BorderColor      Pixel                XtDefaultForeground
borderPixmap          Pixmap           Pixmap               XtUnspecifiedPixmap
borderWidth           BorderWidth      Dimension            1
canvasHeight          CanvasHeight     Dimension            0
canvasWidth           CanvasWidth      Dimension            0
colormap              Colormap         Colormap             Parent's Colormap
cursor                Cursor           Cursor               None
cursorName            Cursor           String               NULL
defaultScale          DefaultScale     Dimension            8
depth                 Depth            int             C    Parent's Depth
destroyCallback       Callback         XtCallbackList       NULL
foreground            Foreground       Pixel                XtDefaultForeground
height                Height           Dimension       A    depends on orientation
internalSpace         InternalSpace    Dimension            4
international         International    Boolean         C    False
lineWidth             LineWidth        Dimension            0
mappedWhenManaged     MappedWhenManagedBoolean              True
pointerColor          Foreground       Pixel                XtDefaultForeground
pointerColorBackgroundBackground       Pixel                XtDefaultBackground
reportCallback        ReportCallback   Callback             NULL
resize                Resize           Boolean              True
rubberBand            RubberBand       Boolean              False
screen                Screen           Screen          R    Parent's Screen
sensitive             Sensitive        Boolean              True
shadowColor           ShadowColor      Pixel                XtDefaultForeground
shadowThickness       ShadowThickness  Dimension            2
sliderX               SliderX          Position             0
sliderY               SliderY          Position             0




                             5511





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


-----------------------------------------------------------------------------------
NNaammee                  CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
-----------------------------------------------------------------------------------
sliderHeight          SliderHeight     Dimension            0
sliderWidth           SliderWidth      Dimension            0
translations          Translations     TranslationTable     See below
width                 Width            Dimension       A    depends on orientation
x                     Position         Position             0
y                     Position         Position             0
-----------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

aalllloowwOOffff       Whether to allow the edges of the slider to
               go off the edges of the canvas.

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

bbaacckkggrroouunnddSSttiippppllee
               The name of a bitmap pattern to be used as
               the background for the area representing the
               canvas.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.




                             5522





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


borderWidth    The width of this widget's window border.

ccaannvvaassHHeeiigghhtt
ccaannvvaassWWiiddtthh    The size of the canvas.

colormap       The colormap that this widget will use.

cursor         The image that will be displayed as the
               pointer cursor whenever it is in this widget.
               The use of this resource is deprecated in
               favor of ccuurrssoorrNNaammee.

cursorName     The name of the symbol to use to represent
               the pointer cursor.  This resource will over-
               ride the ccuurrssoorr resource if both are speci-
               fied. (See 2.4.1)

ddeeffaauullttSSccaallee   The percentage size that the Panner widget
               should have relative to the size of the can-
               vas.

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

ffoorreeggrroouunndd     A pixel value which indexes the widget's col-
               ormap to derive the color used to draw the
               slider.

height
width          The height and width of this widget in pix-
               els.

iinntteerrnnaallSSppaaccee  The width of internal border in pixels
               between a slider representing the full size
               of the canvas and the edge of the Panner wid-
               get.

international  This is a boolean flag, only settable at wid-
               get creation time.  While not utilized in
               this widget, it can and should be checked by
               any subclasses that have behavior that should
               vary with locale.

lliinneeWWiiddtthh      The width of the lines in the rubberbanding
               rectangle when rubberbanding is in effect
               instead of continuous scrolling.  The default
               is 0.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the



                             5533





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               Toolkit when it is realized and managed.

pointerColor   A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               pointer symbol specified by the ccuurrssoorrNNaammee
               resource.

pointerColorBackground
                 A pixel value which indexes the widget's
                 colormap to derive the background color of
                 the pointer symbol specified by the ccuurrssoorr--
                 NNaammee resource.

rreeppoorrttCCaallllbbaacckk All functions on this callback list are
               called when the nnoottiiffyy action is invoked.
               See the PPaannnneerr AAccttiioonnss section for details.

rreessiizzee         Whether or not to resize the panner whenever
               the canvas size is changed so that the
               ddeeffaauullttSSccaallee is maintained.

rruubbbbeerrBBaanndd     Whether or not scrolling should be discrete
               (only moving a rubberbanded rectangle until
               the scrolling is done) or continuous (moving
               the slider itself).  This controls whether or
               not the mmoovvee action procedure also invokes
               the nnoottiiffyy action procedure.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

sshhaaddoowwCCoolloorr    The color of the shadow underneath the
               slider.

sshhaaddoowwTThhiicckknneessss
               The width of the shadow underneath the
               slider.

sslliiddeerrXX
sslliiddeerrYY        The location of the slider in the coordinates
               of the canvas.

sslliiddeerrHHeeiigghhtt
sslliiddeerrWWiiddtthh    The size of the slider.

translations   The event bindings associated with this wid-
               get.





                             5544





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


x
y              The location of the upper left outside corner
               of this widget in its parent.

33..55..22..  PPaannnneerr AAccttiioonnss

The actions supported by the Panner widget are:

ssttaarrtt()        This action begins movement of the slider.

ssttoopp()         This action ends movement of the slider.

aabboorrtt()        This action ends movement of the slider and
               restores it to the position it held when the
               ssttaarrtt action was invoked.

mmoovvee()         This action moves the outline of the slider
               (if the rruubbbbeerrBBaanndd resource is True) or the
               slider itself (by invoking the nnoottiiffyy action
               procedure).

ppaaggee(_x_a_m_o_u_n_t,_y_a_m_o_u_n_t)
               This action moves the slider by the specified
               amounts.  The format for the amounts is a
               signed or unsigned floating-point number
               (e.g., +1.0 or -.5) followed by either pp
               indicating pages (slider sizes), or cc indi-
               cating canvas sizes.  Thus, _p_a_g_e_(_+_0_,_+_._5_p_)
               represents vertical movement down one-half
               the height of the slider and _p_a_g_e_(_0_,_0_) repre-
               sents moving to the upper left corner of the
               canvas.

nnoottiiffyy()       This action informs the application of the
               slider's current position by invoking the
               rreeppoorrttCCaallllbbaacckk functions registered by the
               application.

sseett(_w_h_a_t,_v_a_l_u_e)
               This action changes the behavior of the Pan-
               ner.  The _w_h_a_t argument must currently be the
               string rruubbbbeerrbbaanndd and controls the value of
               the rruubbbbeerrBBaanndd resource.  The _v_a_l_u_e argument
               may have one of the values oonn, ooffff, or ttoogg--
               ggllee.


The default bindings for Panner are:


     <Btn1Down>: start()
     <Btn1Motion>:move()
     <Btn1Up>:   notify() stop()
     <Btn2Down>: abort()



                             5555





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


     <Key>KP_Enter:set(rubberband,toggle)
     <Key>space: page(+1p,+1p)
     <Key>Delete:page(-1p,-1p)
     <Key>BackSpace:page(-1p,-1p)
     <Key>Left:  page(-.5p,+0)
     <Key>Right: page(+.5p,+0)
     <Key>Up:    page(+0,-.5p)
     <Key>Down:  page(+0,+.5p)
     <Key>Home:  page(0,0)


33..55..33..  PPaannnneerr CCaallllbbaacckkss

The functions registered on the rreeppoorrttCCaallllbbaacckk list are
invoked by the nnoottiiffyy action as follows:

void ReportProc(_p_a_n_n_e_r, _c_l_i_e_n_t___d_a_t_a, _r_e_p_o_r_t)
     Widget _p_a_n_n_e_r;
     XtPointer _c_l_i_e_n_t___d_a_t_a;
     XtPointer _r_e_p_o_r_t;    /* (XawPannerReport *) */


_p_a_n_n_e_r    Specifies the Panner widget.

_c_l_i_e_n_t___d_a_t_a
          Specifies the client data.

_r_e_p_o_r_t    Specifies a pointer to an XXaawwPPaannnneerrRReeppoorrtt struc-
          ture containing the location and size of the
          slider and the size of the canvas.

33..66..  RReeppeeaatteerr WWiiddggeett


Application header file<X11/Xaw/Repeater.h>
Class header file   <X11/Xaw/RepeaterP.h>
Class               repeaterWidgetClass
Class Name          Repeater
Superclass          Command



The Repeater widget is a subclass of the Command widget; see
the Command documentation for details.  The difference is
that the Repeater can call its registered callbacks repeat-
edly, at an increasing rate.  The default translation does
so for the duration the user holds down pointer button 1
while the pointer is on the Repeater.

33..66..11..  RReessoouurrcceess

When creating a Repeater widget instance, the following
resources are retrieved from the argument list or from the
resource database:



                             5566





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


-------------------------------------------------------------------------------------------------
NNaammee                  CCllaassss             TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
-------------------------------------------------------------------------------------------------
accelerators          Accelerators      AcceleratorTable     NULL
ancestorSensitive     AncestorSensitive Boolean         D    True
background            Background        Pixel                XtDefaultBackground
backgroundPixmap      Pixmap            Pixmap               XtUnspecifiedPixmap
bitmap                Bitmap            Pixmap               None
borderColor           BorderColor       Pixel                XtDefaultForeground
borderPixmap          Pixmap            Pixmap               XtUnspecifiedPixmap
borderWidth           BorderWidth       Dimension            1
callback              Callback          XtCallbackList       NULL
colormap              Colormap          Colormap             Parent's Colormap
cornerRoundPercent    CornerRoundPercentDimension            25
cursor                Cursor            Cursor               None
cursorName            Cursor            String               NULL
decay                 Decay             Int                  5
depth                 Depth             int             C    Parent's Depth
destroyCallback       Callback          XtCallbackList       NULL
encoding              Encoding          UnsignedChar         XawTextEncoding8bit
flash                 Boolean           Boolean              False
font                  Font              XFontStruct          XtDefaultFont
fontSet               FontSet           XFontSet             XtDefaultFontSet
foreground            Foreground        Pixel                XtDefaultForeground
height                Height            Dimension       A    graphic height + 2 * iinntteerrnnaallHHeeiigghhtt
highlightThickness    Thickness         Dimension       A    2 (0 if Shaped)
initialDelay          Delay             Int                  200
insensitiveBorder     Insensitive       Pixmap               GreyPixmap
internalHeight        Height            Dimension            2
internalWidth         Width             Dimension            4
international         International     Boolean         C    False
justify               Justify           Justify              XtJustifyCenter (center)
label                 Label             String               name of widget
leftBitmap            LeftBitmap        Bitmap               None
mappedWhenManaged     MappedWhenManaged Boolean              True
minimumDelay          MinimumDelay      Int                  10
pointerColor          Foreground        Pixel                XtDefaultForeground
pointerColorBackgroundBackground        Pixel                XtDefaultBackground
repeatDelay           Delay             Int                  50
resize                Resize            Boolean              True
screen                Screen            Pointer         R    Parent's Screen
sensitive             Sensitive         Boolean              True
shapeStyle            ShapeStyle        ShapeStyle           Rectangle
startCallback         StartCallback     Callback             NULL
stopCallback          StopCallback      Callback             NULL
translations          Translations      TranslationTable     See below
width                 Width             Dimension       A    graphic width + 2 * iinntteerrnnaallWWiiddtthh
x                     Position          Position             0
y                     Position          Position             0
-------------------------------------------------------------------------------------------------







                             5577





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

bitmap         A bitmap to display instead of the llaabbeell.
               The default size of the widget will be just
               large enough to contain the bitmap and the
               widget's internal width and height.  The
               resource converter for this resource con-
               structs bitmaps from the contents of files.
               (See CCoonnvveerrttiinngg BBiittmmaappss for details.)  If
               this bitmap is one bit deep then the 1's will
               be rendered in the foreground color, and the
               0's in the background color.  If bbiittmmaapp has a
               depth greater than one, it is copied directly
               into the window.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

callback       A list of routines to be called when the
               nnoottiiffyy action is invoked.

colormap       The colormap that this widget will use.




                             5588





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


cornerRoundPercent
               When a SShhaappeeSSttyyllee of rroouunnddeeddRReeccttaannggllee is
               used, this resource controls the radius of
               the rounded corner.  The radius of the
               rounded corners is specified as a percentage
               of the length of the shortest side of the
               widget.

cursor         The image that will be displayed as the
               pointer cursor whenever it is in this widget.
               The use of this resource is deprecated in
               favor of ccuurrssoorrNNaammee.

cursorName     The name of the symbol to use to represent
               the pointer cursor.  This resource will over-
               ride the ccuurrssoorr resource if both are speci-
               fied. (See 2.4.1)

ddeeccaayy          The number of milliseconds that should be
               subtracted from each succeeding interval
               while the Repeater button is being held down
               until the interval has reached mmiinniimmuummDDeellaayy
               milliseconds.

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

encoding       The encoding method used by the value of the
               llaabbeell resource.  The value may be XXaawwTTeexxttEEnn--
               ccooddiinngg88bbiitt or XXaawwTTeexxttEEnnccooddiinnggCChhaarr22bb.  When
               iinntteerrnnaattiioonnaall is set to ttrruuee this resource is
               not used.

ffllaasshh          Whether or not to flash the Repeater button
               whenever the timer goes off.

font           The text font to use when displaying the
               llaabbeell, when the iinntteerrnnaattiioonnaall resource is
               ffaallssee.

fontSet        The text font set to use when displaying the
               llaabbeell, when the iinntteerrnnaattiioonnaall resource is
               ttrruuee.

foreground     A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               widget's window.  This color is also used to
               render all 1's in a bbiittmmaapp one plane deep.

height




                             5599





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


width          The height and width of this widget in pix-
               els.

highlightThickness
               The thickness of the rectangle that is used
               to highlight the internal border of this wid-
               get, alerting the user that it is ready to be
               selected.  The default value is 2 pixels if
               the sshhaappeeSSttyyllee is rreeccttaannggllee, and 0 Pixels (no
               highlighting) otherwise.

iinniittiiaallDDeellaayy   The number of milliseconds between the begin-
               ning of the Repeater button being held down
               and the first invocation of the ccaallllbbaacckk
               function.

insensitiveBorder
               This pixmap will be tiled into the widget's
               border if the widget becomes insensitive.

internalHeight
internalWidth  The minimum amount of space to leave between
               the graphic and the vertical and horizontal
               edges of the window.

international  This is a boolean flag, only settable at wid-
               get creation time.  A value of ffaallssee signals
               the widget to use pre-R6 internationalization
               (specifically, the lack thereof), such as
               using fonts for displaying text, etc.  A
               value of ttrruuee directs the widget to act in an
               internationalized manner, such as utilizing
               font sets for displaying text, etc.

justify        Specifies left, center, or right alignment of
               graphic within the widget.  This resource may
               be specified with the values XXttJJuussttiiffyyLLeefftt,
               XXttJJuussttiiffyyCCeenntteerr, or XXttJJuussttiiffyyRRiigghhtt.  A con-
               verter is registered for this resource that
               will convert the following strings: lleefftt,,
               rriigghhtt,, and cceenntteerr.  This resource only has
               noticeable effect when the width of the wid-
               get is larger than necessary to display the
               graphic.  Note that when the graphic is a
               multi-line llaabbeell, the longest line will obey
               this justification while shorter lines will
               be left-justified with the longest one.


label          Specifies the text string to be displayed in
               the widget's window if no bitmap is speci-
               fied.  The default is the name of this wid-
               get.  Regardless of the value of eennccooddiinngg or
               iinntteerrnnaattiioonnaall, a single newline character (1



                             6600





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               byte) will cause a line break.

leftBitmap     Specifies a bitmap to display to the left of
               the graphic in the widget's window.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

mmiinniimmuummDDeellaayy   The minimum time between callbacks in mil-
               liseconds.

pointerColor   A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               pointer symbol specified by the ccuurrssoorrNNaammee
               resource.

pointerColorBackground
                 A pixel value which indexes the widget's
                 colormap to derive the background color of
                 the pointer symbol specified by the ccuurrssoorr--
                 NNaammee resource.

rreeppeeaattDDeellaayy    The number of milliseconds between each call-
               back after the first (minus an increasing
               number of ddeeccaayys).

resize         Specifies whether the widget should attempt
               to resize to its preferred dimensions when-
               ever its resources are modified with XXttSSeett--
               VVaalluueess.  This attempt to resize may be denied
               by the parent of this widget.  The parent is
               always free to resize the widget regardless
               of the state of this resource.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

shapeStyle     Nonrectangular widgets may be created using
               this resource.  Nonrectangular widgets are
               supported only on a server that supports the
               SShhaappee EExxtteennssiioonn.  If nonrectangular widgets
               are specified for a server lacking this
               extension, the shape is ignored and the wid-
               gets will be rectangular.  The following
               shapes are currently supported: XXmmuuSShhaappeeRReecctt--
               aannggllee, XXmmuuSShhaappeeOOvvaall, XXmmuuSShhaappeeEElllliippssee, and
               XXmmuuSShhaappeeRRoouunnddeeddRReeccttaannggllee.  A converter is



                             6611





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               registered for this resource that will con-
               vert the following strings: rreeccttaannggllee,, oovvaall,,
               eelllliippssee,, and rroouunnddeeddRReeccttaannggllee.

ssttaarrttCCaallllbbaacckk  The list of functions to invoke by the ssttaarrtt
               action (typically when the Repeater button is
               first pressed).  The callback data parameter
               is set to NULL.

ssttooppCCaallllbbaacckk   The list of functions to invoke by the ssttoopp
               action (typically when the Repeater button is
               released).  The callback data parameter is
               set to NULL.

translations   The event bindings associated with this wid-
               get.

x
y              The location of the upper left outside corner
               of this widget in its parent.

33..66..22..  RReeppeeaatteerr AAccttiioonnss

The Repeater widget supports the following actions beyond
those of the Command button:

ssttaarrtt()        This invokes the functions on the ssttaarrttCCaallll--
               bbaacckk and ccaallllbbaacckk lists and sets a timer to
               go off in iinniittiiaallDDeellaayy milliseconds.  The
               timer will cause the ccaallllbbaacckk functions to be
               invoked with increasing frequency until the
               ssttoopp action occurs.

ssttoopp()         This invokes the functions on the ssttooppCCaallll--
               bbaacckk list and prevents any further timers
               from occuring until the next ssttaarrtt action.


The following are the default translation bindings used by
the Repeater widget:


     <EnterWindow>:   highlight()
     <LeaveWindow>:   unhighlight()
     <Btn1Down>:      set() start()
     <Btn1Up>:        stop() unset()



33..77..  SSccrroollllbbaarr WWiiddggeett



Application header file<X11/Xaw/Scrollbar.h>



                             6622





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


Class header file   <X11/Xaw/ScrollbarP.h>
Class               scrollbarWidgetClass
Class Name          Scrollbar
Superclass          Simple



A Scrollbar widget is a rectangle, called the ``canvas,'' on
which another rectangle, the ``thumb,'' moves in one dimen-
sion, either vertically or horizontally.  A Scrollbar can be
used alone, as a value generator, or it can be used within a
composite widget (for example, a Viewport).  When a Scroll-
bar is used to move, or ``scroll,'' the contents of another
widget, the size and the position of the thumb usually give
feedback as to what portion of the other widget's contents
are visible.

Each pointer button invokes a specific action.  Pointer but-
tons 1 and 3 do not move the thumb automatically.  Instead,
they return the pixel position of the cursor on the scroll
region.  When pointer button 2 is clicked, the thumb moves
to the current pointer position.  When pointer button 2 is
held down and the pointer is moved, the thumb follows the
pointer.

The pointer cursor in the scroll region changes depending on
the current action.  When no pointer button is pressed, the
cursor appears as a double-headed arrow that points in the
direction that scrolling can occur.  When pointer button 1
or 3 is pressed, the cursor appears as a single-headed arrow
that points in the logical direction that the thumb will
move.  When pointer button 2 is pressed, the cursor appears
as an arrow that points to the top or the left of the thumb.

When the user scrolls, the application receives notification
through callback procedures.  For both discrete scrolling
actions, the callback returns the Scrollbar widget, the
client_data, and the pixel position of the pointer when the
button was released.  For continuous scrolling, the callback
routine returns the scroll bar widget, the client data, and
the current relative position of the thumb.  When the thumb
is moved using pointer button 2, the callback procedure is
invoked continuously.  When either button 1 or 3 is pressed,
the callback procedure is invoked only when the button is
released and the client callback procedure is responsible
for moving the thumb.

33..77..11..  RReessoouurrcceess

When creating a Scrollbar widget instance, the following
resources are retrieved from the argument list or from the
resource database:





                             6633





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


----------------------------------------------------------------------------------------
NNaammee                  CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
----------------------------------------------------------------------------------------
accelerators          Accelerators     AcceleratorTable     NULL
ancestorSensitive     AncestorSensitiveBoolean         D    True
background            Background       Pixel                XtDefaultBackground
backgroundPixmap      Pixmap           Pixmap               XtUnspecifiedPixmap
borderColor           BorderColor      Pixel                XtDefaultForeground
borderPixmap          Pixmap           Pixmap               XtUnspecifiedPixmap
borderWidth           BorderWidth      Dimension            1
colormap              Colormap         Colormap             parent's Colormap
cursor                Cursor           Cursor               None
cursorName            Cursor           String               NULL
depth                 Depth            int             C    parent's Depth
destroyCallback       Callback         XtCallbackList       NULL
foreground            Foreground       Pixel                XtDefaultForeground
height                Height           Dimension       A    depends on orientation
insensitiveBorder     Insensitive      Pixmap               GreyPixmap
international         International    Boolean         C    False
jumpProc              Callback         XtCallbackList       NULL
length                Length           Dimension            1
mappedWhenManaged     MappedWhenManagedBoolean              True
minimumThumb          MinimumThumb     Dimension            7
orientation           Orientation      Orientation          XtorientVertical (vertical)
pointerColor          Foreground       Pixel                XtDefaultForeground
pointerColorBackgroundBackground       Pixel                XtDefaultBackground
screen                Screen           Screen          R    parent's Screen
scrollDCursor         Cursor           Cursor               XC_sb_down_arrow
scrollHCursor         Cursor           Cursor               XC_sb_h_double_arrow
scrollLCursor         Cursor           Cursor               XC_sb_left_arrow
scrollProc            Callback         XtCallbackList       NULL
scrollRCursor         Cursor           Cursor               XC_sb_right_arrow
scrollUCursor         Cursor           Cursor               XC_sb_up_arrow
scrollVCursor         Cursor           Cursor               XC_sb_v_arrow
sensitive             Sensitive        Boolean              True
shown                 Shown            Float                0.0
thickness             Thickness        Dimension            14
thumb                 Thumb            Bitmap               GreyPixmap
thumbProc             Callback         XtCallbackList       NULL
topOfThumb            TopOfThumb       Float                0.0
translations          Translations     TranslationTable     See below
width                 Width            Dimension       A    depends on orientation
x                     Position         Position             0
y                     Position         Position             0
----------------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).





                             6644





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

colormap       The colormap that this widget will use.

cursor         The image that will be displayed as the
               pointer cursor whenever it is in this widget.
               The use of this resource is deprecated in
               favor of ccuurrssoorrNNaammee.

cursorName     The name of the symbol to use to represent
               the pointer cursor.  This resource will over-
               ride the ccuurrssoorr resource if both are speci-
               fied. (See 2.4.1)

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

ffoorreeggrroouunndd     A pixel value which indexes the widget's col-
               ormap to derive the color used to draw the
               thumb.

height




                             6655





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


width          The height and width of this widget in pix-
               els.

insensitiveBorder
               This pixmap will be tiled into the widget's
               border if the widget becomes insensitive.

international  This is a boolean flag, only settable at wid-
               get creation time.  While not utilized in
               this widget, it can and should be checked by
               any subclasses that have behavior that should
               vary with locale.

jjuummppPPrroocc       All functions on this callback list are
               called when the NNoottiiffyyTThhuummbb action is
               invoked.  See the SSccrroollllbbaarr AAccttiioonnss section
               for details.

lleennggtthh         The height of a vertical scrollbar or the
               width of a horizontal scrollbar.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

mmiinniimmuummTThhuummbb   The smallest size, in pixels, to which the
               thumb can shrink.

oorriieennttaattiioonn    The orientation is the direction that the
               thumb will be allowed to move.  This value
               can be either XXttoorriieennttVVeerrttiiccaall or XXttoorriieennttHHoo--
               rriizzoonnttaall.  A converter is registered for this
               resource that will convert the following
               strings: vveerrttiiccaall and hhoorriizzoonnttaall.

pointerColor   A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               pointer symbol specified by the ccuurrssoorrNNaammee
               resource.

pointerColorBackground
                 A pixel value which indexes the widget's
                 colormap to derive the background color of
                 the pointer symbol specified by the ccuurrssoorr--
                 NNaammee resource.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

ssccrroollllDDCCuurrssoorr  This cursor is used when scrolling backward
               in a vertical scrollbar.





                             6666





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


ssccrroollllHHCCuurrssoorr  This cursor is used when a horizontal scroll-
               bar is inactive.

ssccrroollllLLCCuurrssoorr  This cursor is used when scrolling forward in
               a horizontal scrollbar.

ssccrroollllPPrroocc     All functions on this callback list may be
               called when the NNoottiiffyySSccrroollll action is
               invoked.  See the SSccrroollllbbaarr AAccttiioonnss section
               for details.

ssccrroollllRRCCuurrssoorr  This cursor is used when scrolling backward
               in a horizontal scrollbar, or when thumbing a
               vertical scrollbar.

ssccrroollllUUCCuurrssoorr  This cursor is used when scrolling forward in
               a vertical scrollbar, or when thumbing a hor-
               izontal scrollbar.

ssccrroollllVVCCuurrssoorr  This cursor is used when a vertical scrollbar
               is inactive.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

sshhoowwnn          This is the size of the thumb, expressed as a
               percentage (0.0 - 1.0) of the length of the
               scrollbar.

tthhiicckknneessss      The width of a vertical scrollbar or the
               height of a horizontal scrollbar.

tthhuummbb          This pixmap is used to tile (or stipple) the
               thumb of the scrollbar.  If no tiling is
               desired, then set this resource to NNoonnee.
               This resource will accept either a bitmap or
               a pixmap that is the same depth as the win-
               dow.  The resource converter for this
               resource constructs bitmaps from the contents
               of files.  (See CCoonnvveerrttiinngg BBiittmmaappss for
               details.)

ttooppOOffTThhuummbb     The location of the top of the thumb, as a
               percentage (0.0 - 1.0) of the length of the
               scrollbar.  This resource was called ttoopp in
               previous versions of the Athena widget set.
               The name collided with the a Form widget con-
               straint resource, and had to be changed.

translations   The event bindings associated with this wid-
               get.




                             6677





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


x
y              The location of the upper left outside corner
               of this widget in its parent.

33..77..22..  SSccrroollllbbaarr AAccttiioonnss

The actions supported by the Scrollbar widget are:

SSttaarrttSSccrroollll(_v_a_l_u_e)
               The possible _v_a_l_u_e_s are Forward, Backward, or
               Continuous.  This must be the first action to
               begin a new movement.

NNoottiiffyySSccrroollll(_v_a_l_u_e)
               The possible _v_a_l_u_e_s are Proportional or Full-
               Length.  If the argument to StartScroll was
               Forward or Backward, NotifyScroll executes
               the ssccrroollllPPrroocc callbacks and passes either;
               the position of the pointer, if _v_a_l_u_e is Pro-
               portional, or the full length of the scroll
               bar, if _v_a_l_u_e is FullLength.  If the argument
               to StartScroll was Continuous, NotifyScroll
               returns without executing any callbacks.

EEnnddSSccrroollll()    This must be the last action after a movement
               is complete.

MMoovveeTThhuummbb()    Repositions the Scrollbar's thumb to the cur-
               rent pointer location.

NNoottiiffyyTThhuummbb()
               Calls the _j_u_m_p_P_r_o_c callbacks and passes the
               relative position of the pointer as a per-
               centage of the scroll bar length.


The default bindings for Scrollbar are:


     <Btn1Down>: StartScroll(Forward)
     <Btn2Down>: StartScroll(Continuous) MoveThumb() NotifyThumb()
     <Btn3Down>: StartScroll(Backward)
     <Btn2Motion>:MoveThumb() NotifyThumb()
     <BtnUp>:    NotifyScroll(Proportional) EndScroll()



Examples of additional bindings a user might wish to specify
in a resource file are:


*Scrollbar.Translations: \
     ~Meta<Key>space: StartScroll(Forward) NotifyScroll(FullLength) \n\
      Meta<Key>space: StartScroll(Backward) NotifyScroll(FullLength) \n\



                             6688





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


                      EndScroll()


33..77..33..  SSccrroollllbbaarr CCaallllbbaacckkss

There are two callback lists provided by the Scrollbar wid-
get.  The procedural interface for these functions is
described here.

The calling interface to the ssccrroollllPPrroocc callback procedure
is:

void ScrollProc(_s_c_r_o_l_l_b_a_r, _c_l_i_e_n_t___d_a_t_a, _p_o_s_i_t_i_o_n)
     Widget _s_c_r_o_l_l_b_a_r;
     XtPointer _c_l_i_e_n_t___d_a_t_a;
     XtPointer _p_o_s_i_t_i_o_n;    /* int */


_s_c_r_o_l_l_b_a_r Specifies the Scrollbar widget.

_c_l_i_e_n_t___d_a_t_a
          Specifies the client data.

_p_o_s_i_t_i_o_n  Specifies a pixel position in integer form.

The ssccrroollllPPrroocc callback is used for incremental scrolling
and is called by the NNoottiiffyySSccrroollll action.  The position
argument is a signed quantity and should be cast to an int
when used. Using the default button bindings, button 1
returns a positive value, and button 3 returns a negative
value. In both cases, the magnitude of the value is the dis-
tance of the pointer in pixels from the top (or left) of the
Scrollbar. The value will never be greater than the length
of the Scrollbar.


The calling interface to the jjuummppPPrroocc callback procedure is:

void JumpProc(_s_c_r_o_l_l_b_a_r, _c_l_i_e_n_t___d_a_t_a, _p_e_r_c_e_n_t)
     Widget _s_c_r_o_l_l_b_a_r;
     XtPointer _c_l_i_e_n_t___d_a_t_a;
     XtPointer _p_e_r_c_e_n_t___p_t_r;    /* float* */


_s_c_r_o_l_l_b_a_r Specifies the ID of the scroll bar widget.

_c_l_i_e_n_t___d_a_t_a
          Specifies the client data.

_p_e_r_c_e_n_t___p_t_r
          Specifies the floating point position of the thumb
          (0.0 - 1.0).





                             6699





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The jjuummppPPrroocc callback is used to implement smooth scrolling
and is called by the NNoottiiffyyTThhuummbb action.  Percent_ptr must
be cast to a pointer to float before use; i.e.


     float percent = *(float*)percent_ptr;


With the default button bindings, button 2 moves the thumb
interactively, and the jjuummppPPrroocc is called on each new posi-
tion of the pointer, while the pointer button remains down.
The value specified by _p_e_r_c_e_n_t___p_t_r is the current location
of the thumb (from the top or left of the Scrollbar)
expressed as a percentage of the length of the Scrollbar.

33..77..44..  CCoonnvveenniieennccee RRoouuttiinneess

To set the position and length of a Scrollbar thumb, use
_X_a_w_S_c_r_o_l_l_b_a_r_S_e_t_T_h_u_m_b.

void XawScrollbarSetThumb(_w, _t_o_p, _s_h_o_w_n)
     Widget _w;
     float _t_o_p;
     float _s_h_o_w_n;


_w         Specifies the Scrollbar widget.

_t_o_p       Specifies the position of the top of the thumb as
          a fraction of the length of the Scrollbar.

_s_h_o_w_n     Specifies the length of the thumb as a fraction of
          the total length of the Scrollbar.

_X_a_w_S_c_r_o_l_l_b_a_r_T_h_u_m_b moves the visible thumb to a new position
(0.0 - 1.0) and length (0.0 - 1.0).  Either the top or shown
arguments can be specified as -1.0, in which case the cur-
rent value is left unchanged.  Values greater than 1.0 are
truncated to 1.0.

If called from jjuummppPPrroocc, XXaawwSSccrroollllbbaarrSSeettTThhuummbb has no effect.

33..77..55..  SSeettttiinngg FFllooaatt RReessoouurrcceess

The sshhoowwnn and ttooppOOffTThhuummbb resources are of type _f_l_o_a_t.  These
resources can be difficult to get into an argument list.
The reason is that C performs an automatic cast of the float
value to an integer value, usually truncating the important
information.  The following code fragment is one portable
method of getting a float into an argument list.


          top = 0.5;
          if (sizeof(float) > sizeof(XtArgVal)) {



                             7700





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


          /*
           * If a float is larger than an XtArgVal then pass this
           * resource value by reference.
           */
                    XtSetArg(args[0], XtNshown, &top);
          }
          else {
          /*
           * Convince C not to perform an automatic conversion, which
           * would truncate 0.5 to 0.
           */
                    XtArgVal * l_top = (XtArgVal *) &top;
                    XtSetArg(args[0], XtNshown, *l_top);
          }



33..88..  SSiimmppllee WWiiddggeett


Application Header file<Xaw/Simple.h>
Class Header file   <Xaw/SimpleP.h>
Class               simpleWidgetClass
Class Name          Simple
Superclass          Core



The Simple widget is not very useful by itself, as it has no
semantics of its own.  It main purpose is to be used as a
common superclass for the other _s_i_m_p_l_e Athena widgets.  This
widget adds six resources to the resource list provided by
the Core widget and its superclasses.

33..88..11..  RReessoouurrcceess

When creating a Simple widget instance, the following
resources are retrieved from the argument list or from the
resource database:


---------------------------------------------------------------------------------
NNaammee                  CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
---------------------------------------------------------------------------------
accelerators          Accelerators     AcceleratorTable     NULL
ancestorSensitive     AncestorSensitiveBoolean         D    True
background            Background       Pixel                XtDefaultBackground
backgroundPixmap      Pixmap           Pixmap               XtUnspecifiedPixmap
borderColor           BorderColor      Pixel                XtDefaultForeground
borderPixmap          Pixmap           Pixmap               XtUnspecifiedPixmap
borderWidth           BorderWidth      Dimension            1
colormap              Colormap         Colormap             Parent's Colormap
cursor                Cursor           Cursor               None




                             7711





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


---------------------------------------------------------------------------------
NNaammee                  CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
---------------------------------------------------------------------------------
cursorName            Cursor           String               NULL
depth                 Depth            int             C    Parent's Depth
destroyCallback       Callback         XtCallbackList       NULL
height                Height           Dimension            0
insensitiveBorder     Insensitive      Pixmap               GreyPixmap
international         International    Boolean         C    False
mappedWhenManaged     MappedWhenManagedBoolean              True
pointerColor          Foreground       Pixel                XtDefaultForeground
pointerColorBackgroundBackground       Pixel                XtDefaultBackground
screen                Screen           Screen          R    Parent's Screen
sensitive             Sensitive        Boolean              True
translations          Translations     TranslationTable     NULL
width                 Width            Dimension            0
x                     Position         Position             0
y                     Position         Position             0
---------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.



                             7722





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


borderWidth    The width of this widget's window border.

colormap       The colormap that this widget will use.

ccuurrssoorr         The image that will be displayed as the
               pointer cursor whenever it is in this widget.
               The use of this resource is deprecated in
               favor of ccuurrssoorrNNaammee.

ccuurrssoorrNNaammee     The name of the symbol to use to represent
               the pointer cursor.  This resource will over-
               ride the ccuurrssoorr resource if both are speci-
               fied. (See 2.4.1)

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

height
width          The height and width of this widget in pix-
               els.

iinnsseennssiittiivveeBBoorrddeerr
               This pixmap will be tiled into the widget's
               border if the widget becomes insensitive.

iinntteerrnnaattiioonnaall  This is a boolean flag, only settable at wid-
               get creation time.  While not utilized in
               this widget, it can and should be checked by
               any subclasses that have behavior that should
               vary with locale.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

ppooiinntteerrCCoolloorr   A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               pointer symbol specified by the ccuurrssoorrNNaammee
               resource.

ppooiinntteerrCCoolloorrBBaacckkggrroouunndd
                 A pixel value which indexes the widget's
                 colormap to derive the background color of
                 the pointer symbol specified by the ccuurrssoorr--
                 NNaammee resource.

screen         The screen on which this widget is displayed.
               This is not a settable resource.





                             7733





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

translations   The event bindings associated with this wid-
               get.

x
y              The location of the upper left outside corner
               of this widget in its parent.

33..99..  SSttrriippCChhaarrtt WWiiddggeett


Application Header file<Xaw/StripChart.h>
Class Header file   <Xaw/StripCharP.h>
Class               stripChartWidgetClass
Class Name          StripChart
Superclass          Simple



The StripChart widget is used to provide a roughly real time
graphical chart of a single value.  For example, it is used
by the common client program xxllooaadd to provide a graph of
processor load.  The StripChart reads data from an applica-
tion, and updates the chart at the uuppddaattee interval speci-
fied.

33..99..11..  RReessoouurrcceess

When creating a StripChart widget instance, the following
resources are retrieved from the argument list or from the
resource database:


-----------------------------------------------------------------------------------------
NNaammee                  CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
-----------------------------------------------------------------------------------------
accelerators          Accelerators     AcceleratorTable     NULL
ancestorSensitive     AncestorSensitiveBoolean         D    True
background            Background       Pixel                XtDefaultBackground
backgroundPixmap      Pixmap           Pixmap               XtUnspecifiedPixmap
borderColor           BorderColor      Pixel                XtDefaultForeground
borderPixmap          Pixmap           Pixmap               XtUnspecifiedPixmap
borderWidth           BorderWidth      Dimension            1
colormap              Colormap         Colormap             Parent's Colormap
cursor                Cursor           Cursor               None
cursorName            Cursor           String               NULL
depth                 Depth            int             C    Parent's Depth
destroyCallback       Callback         XtCallbackList       NULL
foreground            Foreground       Pixel                XtDefaultForeground




                             7744





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


-----------------------------------------------------------------------------------------
NNaammee                  CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
-----------------------------------------------------------------------------------------
getValue              Callback         XtCallbackList       NULL
height                Height           Dimension            120
highlight             Foreground       Pixel                XtDefaultForeground
insensitiveBorder     Insensitive      Pixmap               GreyPixmap
international         International    Boolean         C    False
jumpScroll            JumpScroll       int             A    half the width of the widget
mappedWhenManaged     MappedWhenManagedBoolean              True
minScale              Scale            int                  1
pointerColor          Foreground       Pixel                XtDefaultForeground
pointerColorBackgroundBackground       Pixel                XtDefaultBackground
screen                Screen           Pointer         R    Parent's Screen
sensitive             Sensitive        Boolean              True
translations          Translations     TranslationTable     NULL
update                Interval         int                  10
width                 Width            Dimension            120
x                     Position         Position             0
y                     Position         Position             0
-----------------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap



                             7755





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               specified will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

colormap       The colormap that this widget will use.

cursor         The image that will be displayed as the
               pointer cursor whenever it is in this widget.
               The use of this resource is deprecated in
               favor of ccuurrssoorrNNaammee.

cursorName     The name of the symbol to use to represent
               the pointer cursor.  This resource will over-
               ride the ccuurrssoorr resource if both are speci-
               fied. (See 2.4.1)

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

ffoorreeggrroouunndd     A pixel value which indexes the widget's col-
               ormap to derive the color that will be used
               to draw the graph.

ggeettVVaalluuee       A list of callback functions to call every
               uuppddaattee seconds.  This list should contain one
               function, which returns the value to be
               graphed by the StripChart widget.  The fol-
               lowing section describes the procedural
               interface.  Behavior when this list has more
               than one function is undefined.

height
width          The height and width of this widget in pix-
               els.

hhiigghhlliigghhtt      A pixel value which indexes the widget's col-
               ormap to derive the color that will be used
               to draw the scale lines on the graph.

insensitiveBorder
               This pixmap will be tiled into the widget's
               border if the widget becomes insensitive.

international  This is a boolean flag, only settable at wid-
               get creation time.  While not utilized in
               this widget, it can and should be checked by
               any subclasses that have behavior that should
               vary with locale.





                             7766





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


jjuummppSSccrroollll     When the graph reaches the right edge of the
               window it must be scrolled to the left.  This
               resource specifies the number of pixels it
               will jump.  Smooth scrolling can be achieved
               by setting this resource to 1.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

mmiinnSSccaallee       The minimum scale for the graph.  The number
               of divisions on the graph will always be
               greater than or equal to this value.

pointerColor   A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               pointer symbol specified by the ccuurrssoorrNNaammee
               resource.

pointerColorBackground
                 A pixel value which indexes the widget's
                 colormap to derive the background color of
                 the pointer symbol specified by the ccuurrssoorr--
                 NNaammee resource.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

translations   The event bindings associated with this wid-
               get.

uuppddaattee         The number of seconds between graph updates.
               Each update is represented on the graph as a
               1 pixel wide line.  Every uuppddaattee seconds the
               ggeettVVaalluuee procedure will be used to get a new
               graph point, and this point will be added to
               the right end of the StripChart.

x
y              The location of the upper left outside corner
               of this widget in its parent.

33..99..22..  GGeettttiinngg tthhee SSttrriippCChhaarrtt VVaalluuee

The StripChart widget will call the application routine
passed to it as the ggeettVVaalluuee callback function every uuppddaattee
seconds to obtain another point for the StripChart graph.




                             7777





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The calling interface for the ggeettVVaalluuee callback is:

void (*_g_e_t_V_a_l_u_e_P_r_o_c)(_w, _c_l_i_e_n_t___d_a_t_a, _v_a_l_u_e)
     Widget _w;
     XtPointer _c_l_i_e_n_t___d_a_t_a;
     XtPointer _v_a_l_u_e;    /* double * */


_w         Specifies the StripChart widget.

_c_l_i_e_n_t___d_a_t_a
          Specifies the client data.

_v_a_l_u_e     Returns a pointer to a double.  The application
          should set the address pointed to by this argument
          to a double containing the value to be graphed on
          the StripChart.

This function is used by the StripChart to call an applica-
tion routine.  The routine will pass the value to be graphed
back to the the StripChart in the vvaalluuee field of this rou-
tine.


33..1100..  TTooggggllee WWiiddggeett


Application Header file<Xaw/Toggle.h>
Class Header file   <Xaw/ToggleP.h>
Class               toggleWidgetClass
Class Name          Toggle
Superclass          Command



The Toggle widget is an area, often rectangular, that dis-
plays a graphic.  The graphic may be a text string contain-
ing multiple lines of characters in an 8 bit or 16 bit char-
acter set (to be displayed with a _f_o_n_t), or in a multi-byte
encoding (for use with a _f_o_n_t_s_e_t).  The graphic may also be
a bitmap or pixmap.

This widget maintains a Boolean state (e.g.  True/False or
On/Off) and changes state whenever it is selected.  When the
pointer is on the Toggle widget, the Toggle widget may
become highlighted by drawing a rectangle around its perime-
ter.  This highlighting indicates that the Toggle widget is
ready for selection.  When pointer button 1 is pressed and
released, the Toggle widget indicates that it has changed
state by reversing its foreground and background colors, and
its nnoottiiffyy action is invoked, calling all functions on its
callback list.  If the pointer is moved off of the widget
before the pointer button is released, the Toggle widget
reverts to its previous foreground and background colors,



                             7788





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


and releasing the pointer button has no effect.  This behav-
ior allows the user to cancel the operation.

Toggle widgets may also be part of a ``radio group.''  A
radio group is a list of at least two Toggle widgets in
which no more than one Toggle may be set at any time.  A
radio group is identified by the widget ID of any one of its
members.  The convenience routine XXaawwTToogggglleeGGeettCCuurrrreenntt will
return information about the Toggle widget in the radio
group.

Toggle widget state is preserved across changes in sensitiv-
ity.

33..1100..11..  RReessoouurrcceess

When creating a Toggle widget instance, the following
resources are retrieved from the argument list or from the
resource database:


-------------------------------------------------------------------------------------------------
NNaammee                  CCllaassss             TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
-------------------------------------------------------------------------------------------------
accelerators          Accelerators      AcceleratorTable     NULL
ancestorSensitive     AncestorSensitive Boolean         D    True
background            Background        Pixel                XtDefaultBackground
backgroundPixmap      Pixmap            Pixmap               XtUnspecifiedPixmap
bitmap                Bitmap            Pixmap               None
borderColor           BorderColor       Pixel                XtDefaultForeground
borderPixmap          Pixmap            Pixmap               XtUnspecifiedPixmap
borderWidth           BorderWidth       Dimension            1
callback              Callback          XtCallbackList       NULL
colormap              Colormap          Colormap             Parent's Colormap
cornerRoundPercent    CornerRoundPercentDimension            25
cursor                Cursor            Cursor               None
cursorName            Cursor            String               NULL
depth                 Depth             int             C    Parent's Depth
destroyCallback       Callback          XtCallbackList       NULL
encoding              Encoding          UnsignedChar         XawTextEncoding8bit
font                  Font              XFontStruct          XtDefaultFont
fontSet               FontSet           XFontSet             XtDefaultFontSet
foreground            Foreground        Pixel                XtDefaultForeground
height                Height            Dimension       A    graphic height + 2 * iinntteerrnnaallHHeeiigghhtt
highlightThickness    Thickness         Dimension       A    2 (0 if Shaped)
insensitiveBorder     Insensitive       Pixmap               GreyPixmap
internalHeight        Height            Dimension            2
internalWidth         Width             Dimension            4
international         International     Boolean         C    False
justify               Justify           Justify              XtJustifyCenter (center)
label                 Label             String               name of widget
leftBitmap            LeftBitmap        Bitmap               None
mappedWhenManaged     MappedWhenManaged Boolean              True




                             7799





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


-------------------------------------------------------------------------------------------------
NNaammee                  CCllaassss             TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
-------------------------------------------------------------------------------------------------
pointerColor          Foreground        Pixel                XtDefaultForeground
pointerColorBackgroundBackground        Pixel                XtDefaultBackground
radioData             RadioData         Pointer              Name of widget
radioGroup            Widget            Widget               No radio group
resize                Resize            Boolean              True
screen                Screen            Screen          R    Parent's Screen
sensitive             Sensitive         Boolean              True
shapeStype            ShapeStyle        ShapeStyle           Rectangle
state                 State             Boolean              Off
translations          Translations      TranslationTable     See below
width                 Width             Dimension       A    graphic width + 2 * iinntteerrnnaallWWiiddtthh
x                     Position          Position             0
y                     Position          Position             0
-------------------------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

bitmap         A bitmap to display instead of the llaabbeell.
               The default size of the widget will be just
               large enough to contain the bitmap and the
               widget's internal width and height.  The
               resource converter for this resource con-
               structs bitmaps from the contents of files.
               (See CCoonnvveerrttiinngg BBiittmmaappss for details.)  If
               this bitmap is one bit deep then the 1's will
               be rendered in the foreground color, and the
               0's in the background color.  If bbiittmmaapp has a
               depth greater than one, it is copied directly



                             8800





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               into the window.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

callback       A list of routines to be called when the
               nnoottiiffyy action is invoked.

colormap       The colormap that this widget will use.

cornerRoundPercent
               When a SShhaappeeSSttyyllee of rroouunnddeeddRReeccttaannggllee is
               used, this resource controls the radius of
               the rounded corner.  The radius of the
               rounded corners is specified as a percentage
               of the length of the shortest side of the
               widget.

cursor         The image that will be displayed as the
               pointer cursor whenever it is in this widget.
               The use of this resource is deprecated in
               favor of ccuurrssoorrNNaammee.

cursorName     The name of the symbol to use to represent
               the pointer cursor.  This resource will over-
               ride the ccuurrssoorr resource if both are speci-
               fied. (See 2.4.1)

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

encoding       The encoding method used by the value of the
               llaabbeell resource.  The value may be XXaawwTTeexxttEEnn--
               ccooddiinngg88bbiitt or XXaawwTTeexxttEEnnccooddiinnggCChhaarr22bb.  When
               iinntteerrnnaattiioonnaall is set to ttrruuee this resource is
               not used.

font           The text font to use when displaying the
               llaabbeell, when the iinntteerrnnaattiioonnaall resource is
               ffaallssee.





                             8811





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


fontSet        The text font set to use when displaying the
               llaabbeell, when the iinntteerrnnaattiioonnaall resource is
               ttrruuee.

foreground     A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               widget's window.  This color is also used to
               render all 1's in a bbiittmmaapp one plane deep.

height
width          The height and width of this widget in pix-
               els.

highlightThickness
               The thickness of the rectangle that is used
               to highlight the internal border of this wid-
               get, alerting the user that it is ready to be
               selected.  The default value is 2 pixels if
               the sshhaappeeSSttyyllee is rreeccttaannggllee, and 0 Pixels (no
               highlighting) otherwise.

insensitiveBorder
               This pixmap will be tiled into the widget's
               border if the widget becomes insensitive.

internalHeight
internalWidth  The minimum amount of space to leave between
               the graphic and the vertical and horizontal
               edges of the window.

international  This is a boolean flag, only settable at wid-
               get creation time.  A value of ffaallssee signals
               the widget to use pre-R6 internationalization
               (specifically, the lack thereof), such as
               using fonts for displaying text, etc.  A
               value of ttrruuee directs the widget to act in an
               internationalized manner, such as utilizing
               font sets for displaying text, etc.

justify        Specifies left, center, or right alignment of
               graphic within the widget.  This resource may
               be specified with the values XXttJJuussttiiffyyLLeefftt,
               XXttJJuussttiiffyyCCeenntteerr, or XXttJJuussttiiffyyRRiigghhtt.  A con-
               verter is registered for this resource that
               will convert the following strings: lleefftt,,
               rriigghhtt,, and cceenntteerr.  This resource only has
               noticeable effect when the width of the wid-
               get is larger than necessary to display the
               graphic.  Note that when the graphic is a
               multi-line llaabbeell, the longest line will obey
               this justification while shorter lines will
               be left-justified with the longest one.





                             8822





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


label          Specifies the text string to be displayed in
               the widget's window if no bitmap is speci-
               fied.  The default is the name of this wid-
               get.  Regardless of the value of eennccooddiinngg or
               iinntteerrnnaattiioonnaall, a single newline character (1
               byte) will cause a line break.

leftBitmap     Specifies a bitmap to display to the left of
               the graphic in the widget's window.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

pointerColor   A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               pointer symbol specified by the ccuurrssoorrNNaammee
               resource.

pointerColorBackground
                 A pixel value which indexes the widget's
                 colormap to derive the background color of
                 the pointer symbol specified by the ccuurrssoorr--
                 NNaammee resource.

rraaddiiooDDaattaa      Specifies the data that will be returned by
               XXaawwTToogggglleeGGeettCCuurrrreenntt when this is the cur-
               rently _s_e_t widget in the radio group.  This
               value is also used to identify the Toggle
               that will be set by a call to XXaawwTTooggggllee--
               SSeettCCuurrrreenntt.  The value NULL will be returned
               by XXaawwTToogggglleeGGeettCCuurrrreenntt if no widget in a
               radio group is currently set.  Programmers
               must not specify NULL (or Zero) as rraaddiiooDDaattaa.

rraaddiiooGGrroouupp     Specifies another Toggle widget that is in
               the radio group to which this Toggle widget
               should be added.  A radio group is a group of
               at least two Toggle widgets, only one of
               which may be _s_e_t at a time.  If this value is
               NULL (the default) then the Toggle will not
               be part of any radio group and can change
               state without affecting any other Toggle wid-
               gets.  If the widget specified in this
               resource is not already in a radio group then
               a new radio group will be created containing
               these two Toggle widgets.  No Toggle widget
               can be in multiple radio groups.  The behav-
               ior of a radio group of one toggle is unde-
               fined.  A converter is registered which will
               convert widget names to widgets without
               caching.




                             8833





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


resize         Specifies whether the widget should attempt
               to resize to its preferred dimensions when-
               ever its resources are modified with XXttSSeett--
               VVaalluueess.  This attempt to resize may be denied
               by the parent of this widget.  The parent is
               always free to resize the widget regardless
               of the state of this resource.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

shapeStyle     Nonrectangular widgets may be created using
               this resource.  Nonrectangular widgets are
               supported only on a server that supports the
               SShhaappee EExxtteennssiioonn.  If nonrectangular widgets
               are specified for a server lacking this
               extension, the shape is ignored and the wid-
               gets will be rectangular.  The following
               shapes are currently supported: XXmmuuSShhaappeeRReecctt--
               aannggllee, XXmmuuSShhaappeeOOvvaall, XXmmuuSShhaappeeEElllliippssee, and
               XXmmuuSShhaappeeRRoouunnddeeddRReeccttaannggllee.  A converter is
               registered for this resource that will con-
               vert the following strings: rreeccttaannggllee,, oovvaall,,
               eelllliippssee,, and rroouunnddeeddRReeccttaannggllee.

ssttaattee          Specifies whether the Toggle widget is set
               (TTrruuee) or unset (FFaallssee).

translations   The event bindings associated with this wid-
               get.

x
y              The location of the upper left outside corner
               of this widget in its parent.

33..1100..22..  TTooggggllee AAccttiioonnss

The Toggle widget supports the following actions:

+o    Switching the Toggle widget between the foreground and
     background colors with sseett and uunnsseett and ttooggggllee

+o    Processing application callbacks with nnoottiiffyy

+o    Switching the internal border between highlighted and
     unhighlighted states with hhiigghhlliigghhtt and uunnhhiigghhlliigghhtt

The following are the default translation bindings used by
the Toggle widget:



                             8844





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


     <EnterWindow>:   highlight(Always)
     <LeaveWindow>:   unhighlight()
     <Btn1Down>,<Btn1Up>:toggle() notify()


33..1100..33..  TTooggggllee AAccttiioonnss

The full list of actions supported by Toggle is:

hhiigghhlliigghhtt(_c_o_n_d_i_t_i_o_n)
               Displays the internal highlight border in the
               color (ffoorreeggrroouunndd or bbaacckkggrroouunndd ) that con-
               trasts with the interior color of the Toggle
               widget.  The conditions WWhheennUUnnsseett and AAllwwaayyss
               are understood by this action procedure.  If
               no argument is passed then WWhheennUUnnsseett is
               assumed.

uunnhhiigghhlliigghhtt()  Displays the internal highlight border in the
               color (ffoorreeggrroouunndd or bbaacckkggrroouunndd ) that
               matches the interior color of the Toggle wid-
               get.

sseett()          Enters the _s_e_t state, in which nnoottiiffyy is pos-
               sible.  This action causes the Toggle widget
               to display its interior in the ffoorreeggrroouunndd
               color.  The label or bitmap is displayed in
               the bbaacckkggrroouunndd color.

uunnsseett()        Cancels the _s_e_t state and displays the inte-
               rior of the Toggle widget in the bbaacckkggrroouunndd
               color.  The label or bitmap is displayed in
               the ffoorreeggrroouunndd color.

ttooggggllee()       Changes the current state of the Toggle wid-
               get, causing to be set if it was previously
               unset, and unset if it was previously set.
               If the widget is to be set, and is in a radio
               group then this procedure may unset another
               Toggle widget causing all routines on its
               callback list to be invoked.  The callback
               routines for the Toggle that is to be unset
               will be called before the one that is to be
               set.

rreesseett()        Cancels any sseett or hhiigghhlliigghhtt and displays the
               interior of the Toggle widget in the bbaacckk--
               ggrroouunndd color, with the label displayed in the
               ffoorreeggrroouunndd color.

nnoottiiffyy()       When the Toggle widget is in the sseett state
               this action calls all functions in the call-
               back list named by the ccaallllbbaacckk resource.
               The value of the call_data argument in these



                             8855





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               callback functions is undefined.


                            Note

     When a bitmap of depth greater that one (1) is
     specified the _s_e_t(), _u_n_s_e_t(), and _r_e_s_e_t() actions
     have no effect, since there are no foreground and
     background colors used in a multi-plane pixmap.


33..1100..44..  RRaaddiioo GGrroouuppss

There are typically two types of radio groups desired by
applications.  The default translations for the Toggle wid-
get implement a "zero or one of many" radio group.  This
means that there may be no more than one Toggle widget
active, but there need not be any Toggle widgets active.

The other type of radio group is "one of many" and has the
more strict policy that there will always be exactly one
radio button active.  Toggle widgets can be used to provide
this interface with a slight modification to the translation
table of each Toggle in the group.


     <EnterWindow>:   highlight(Always)
     <LeaveWindow>:   unhighlight()
     <Btn1Down>,<Btn1Up>:set() notify()


This translation table will not allow any Toggle to be _u_n_s_e_t
except as a result of another Toggle becoming _s_e_t.  It is
the application programmer's responsibility to choose an
initial state for the radio group by setting the ssttaattee
resource of one of its member widgets to TTrruuee.

33..1100..55..  CCoonnvveenniieennccee RRoouuttiinneess

The following functions allow easy access to the Toggle wid-
get's radio group functionality.

33..1100..55..11..  CChhaannggiinngg tthhee TTooggggllee''ss RRaaddiioo GGrroouupp..

To enable an application to change the Toggle's radio group,
add the Toggle to a radio group, or remove the Toggle from a
radio group, use XXaawwTToogggglleeCChhaannggeeRRaaddiiooGGrroouupp.

void XawToggleChangeRadioGroup(_w, _r_a_d_i_o___g_r_o_u_p)
     Widget _w, _r_a_d_i_o___g_r_o_u_p;


_w         Specifies the Toggle widget.




                             8866





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


_r_a_d_i_o___g_r_o_u_p
          Specifies any Toggle in the new radio group.  If
          NULL then the Toggle will be removed from any
          radio group of which it is a member.

If a Toggle is already _s_e_t in the new radio group, and the
Toggle to be added is also _s_e_t then the previously _s_e_t Tog-
gle in the radio group is _u_n_s_e_t and its callback procedures
are invoked.

FFiinnddiinngg tthhee CCuurrrreennttllyy sseelleecctteedd TTooggggllee iinn aa rraaddiioo ggrroouupp ooff
TToogggglleess

To find the currently selected Toggle in a radio group of
Toggle widgets use XXaawwTToogggglleeGGeettCCuurrrreenntt.

XtPointer XawToggleGetCurrent(_r_a_d_i_o___g_r_o_u_p);
     Widget _r_a_d_i_o___g_r_o_u_p;


_r_a_d_i_o___g_r_o_u_p
          Specifies any Toggle widget in the radio group.

The value returned by this function is the _r_a_d_i_o_D_a_t_a of the
Toggle in this radio group that is currently set.  The
default value for _r_a_d_i_o_D_a_t_a is the name of that Toggle wid-
get.  If no Toggle is set in the radio group specified then
NULL is returned.

CChhaannggiinngg tthhee TTooggggllee tthhaatt iiss sseett iinn aa rraaddiioo ggrroouupp..

To change the Toggle that is currently set in a radio group
use XXaawwTToogggglleeSSeettCCuurrrreenntt.

void XawToggleSetCurrent(_r_a_d_i_o___g_r_o_u_p, _r_a_d_i_o___d_a_t_a);
     Widget _r_a_d_i_o___g_r_o_u_p;
     XtPointer _r_a_d_i_o___d_a_t_a;


_r_a_d_i_o___g_r_o_u_p
          Specifies any Toggle widget in the radio group.

_r_a_d_i_o___d_a_t_a
          Specifies the _r_a_d_i_o_D_a_t_a identifying the Toggle
          that should be set in the radio group specified by
          the _r_a_d_i_o___g_r_o_u_p argument.

XXaawwTToogggglleeSSeettCCuurrrreenntt locates the Toggle widget to be set by
matching _r_a_d_i_o___d_a_t_a against the rraaddiiooDDaattaa for each Toggle in
the radio group.  If none match, XXaawwTToogggglleeSSeettCCuurrrreenntt returns
without making any changes.  If more than one Toggle
matches, XXaawwTToogggglleeSSeettCCuurrrreenntt will choose a Toggle to set
arbitrarily.  If this causes any Toggle widgets to change
state, all routines in their callback lists will be invoked.



                             8877





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The callback routines for a Toggle that is to be unset will
be called before the one that is to be set.

UUnnsseettttiinngg aallll TToogggglleess iinn aa rraaddiioo ggrroouupp..

To unset all Toggle widgets in a radio group use XXaawwTTooggggllee--
UUnnsseettCCuurrrreenntt.

void XawToggleUnsetCurrent(_r_a_d_i_o___g_r_o_u_p);
     Widget _r_a_d_i_o___g_r_o_u_p;


_r_a_d_i_o___g_r_o_u_p
          Specifies any Toggle widget in the radio group.

If this causes a Toggle widget to change state, all routines
on its callback list will be invoked.








































                             8888





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77




                         CChhaapptteerr 44

                           MMeennuuss




The Athena widget set provides support for single paned non-
hierarchical popup and pulldown menus.  Since menus are such
a common user interface tool, support for them must be pro-
vided in even the most basic widget sets.  In menuing as in
other areas, the Athena Widget Set provides only basic func-
tionality.

Menus in the Athena widget set are implemented as a menu
container (the SimpleMenu widget) and a collection of
objects that comprise the menu entries.  The SimpleMenu wid-
get is itself a direct subclass of the OverrideShell widget
class, so no other shell is necessary when creating a menu.
The managed children of a SimpleMenu must be subclasses of
the Sme (Simple Menu Entry) object.

The Athena widget set provides three classes of Sme objects
that may be used to build menus.


SSmmee       The base class of all menu entries.  It may be
          used as a menu entry itself to provide blank space
          in a menu.  ``Sme'' means ``Simple Menu Entry.''

SSmmeeBBSSBB    This menu entry provides a selectable entry con-
          taining a text string.  A bitmap may also be
          placed in the left and right margins.  ``BSB''
          means ``Bitmap String Bitmap.''

SSmmeeLLiinnee   This menu entry provides an unselectable entry
          containing a separator line.


The SimpleMenu widget informs the window manager that it
should ignore its window by setting the OOvveerrrriiddee RReeddiirreecctt
flag.  This is the correct behavior for the press-drag-
release style of menu operation.  If click-move-click or
``pinable''' menus are desired it is the responsibility of
the application programmer, using the SimpleMenu resources,
to inform the window manager of the menu.

To allow easy creation of pulldown menus, a MenuButton wid-
get is also provided as part of the Athena widget set.






                             8899





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


44..11..  UUssiinngg tthhee MMeennuuss

The default configuration for the menus is press-drag-
release.  The menus will typically be activated by clicking
a pointer button while the pointer is over a MenuButton,
causing the menu to appear in a fixed location relative to
that button; this is a ppuullllddoowwnn menu.  Menus may also be
activated when a specific pointer and/or key sequence is
used anywhere in the application; this is a ppooppuupp menu (e.g.
clicking Ctrl-<pointer button 1> in the common application
xxtteerrmm).  In this case the menu should be positioned under
the cursor. Typically menus will be placed so the pointer
cursor is on the first menu entry, or the last entry
selected by the user.

The menu remains on the screen as long as the pointer button
is held down.  Moving the pointer will highlight different
menu items.  If the pointer leaves the menu, or moves over
an entry that cannot be selected then no menu entry will
highlighted.  When the desired menu entry has been high-
lighted, releasing the pointer button removes the menu, and
causes any mechanism associated with this entry to be
invoked.

44..22..  SSiimmpplleeMMeennuu WWiiddggeett


Application Header file<X11/Xaw/SimpleMenu.h>
Class Header file   <X11/Xaw/SimpleMenP.h>
Class               simpleMenuWidgetClass
Class Name          SimpleMenu
Superclass          OverrideShell



The SimpleMenu widget is a container for the menu entries.
It is a direct subclass of shell, and is should be created
with XXttCCrreeaatteePPooppuuppSShheellll, not XXttCCrreeaatteeMMaannaaggeeddWWiiddggeett.  This is
the only part of the menu that actually is associated with a
window.  The SimpleMenu serves as the glue to bind the indi-
vidual menu entries together into a menu.

44..22..11..  RReessoouurrcceess


The resources associated with the SimpleMenu widget control
aspects that will affect the entire menu.

-------------------------------------------------------------------------------------------------------------
NNaammee                   CCllaassss                  TTyyppee               NNootteess   DDeeffaauulltt VVaalluuee
-------------------------------------------------------------------------------------------------------------
accelerators           Accelerators           AcceleratorTable           NULL
ancestorSensitive      AncestorSensitive      Boolean            D       True




                             9900





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


-------------------------------------------------------------------------------------------------------------
NNaammee                   CCllaassss                  TTyyppee               NNootteess   DDeeffaauulltt VVaalluuee
-------------------------------------------------------------------------------------------------------------
allowShellResize       AllowShellResize       Boolean                    True
background             Background             Pixel                      XtDefaultBackground
backgroundPixmap       Pixmap                 Pixmap                     XtUnspecifiedPixmap
backingStore           BackingStore           BackingStore               see below
borderColor            BorderColor            Pixel                      XtDefaultForeground
borderPixmap           Pixmap                 Pixmap                     XtUnspecifiedPixmap
borderWidth            BorderWidth            Dimension                  1
bottomMargin           VerticalMargins        Dimension                  0
children               ReadOnly               WidgetList         R       NULL
createPopupChildProc   CreatePopupChildProc   Function                   NULL
colormap               Colormap               Colormap                   Parent's Colormap
cursor                 Cursor                 Cursor                     None
depth                  Depth                  int                C       Parent's Depth
destroyCallback        Callback               XtCallbackList             NULL
geometry               Geometry               String                     NULL
height                 Height                 Dimension                  Enough space to contain all entries
label                  Label                  String                     NULL
labelClass             LabelClass             Pointer                    SmeBSBObjectClass
mappedWhenManaged      MappedWhenManaged      Boolean                    True
menuOnScreen           MenuOnScreen           Boolean                    True
numChildren            ReadOnly               Cardinal           R       0
overrideRedirect       OverrideRedirect       Boolean                    True
popdownCallback        Callback               XtCallbackList             NULL
popupCallback          Callback               XtCallbackList             NULL
popupOnEntry           PopupOnEntry           Widget             A       Label or first entry
rowHeight              RowHeight              Dimension                  0
saveUnder              SaveUnder              Boolean                    False
screen                 Screen                 Screen             R       Parent's Screen
sensitive              Sensitive              Boolean                    True
topMargin              VerticalMargins        Dimension                  0
translations           Translations           TranslationTable           See below
visual                 Visual                 Visual                     CopyFromParent
width                  Width                  Dimension                  Width of widest entry
x                      Position               Position                   0
y                      Position               Position                   0
-------------------------------------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.




                             9911





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


bbaacckkiinnggSSttoorree   Determines what type of backing store will be
               used for the menu.  Legal values for this
               resource are NNoottUUsseeffuull, WWhheennMMaappppeedd, and
               AAllwwaayyss.  These values are the backing-store
               integers defined in <X11/X.h>.  A converter
               is registered for this resource that will
               convert the following strings: nnoottUUsseeffuull,,
               wwhheennMMaappppeedd,, aallwwaayyss,, and ddeeffaauulltt.  If ddeeffaauulltt
               is specified (the default behavior) the
               server will use whatever it thinks is appro-
               priate.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

bboottttoommMMaarrggiinn
ttooppMMaarrggiinn      The amount of space between the top or bottom
               of the menu and the menu entry closest to
               that edge.

children       A list of all this composite widget's current
               children.

colormap       The colormap that this widget will use.

ccuurrssoorr         The shape of the mouse pointer whenever it is
               in this widget.

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.




                             9922





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


geometry       If this resource is specified it will over-
               ride the x, y, width and height of this wid-
               get.  The format of this string is
               [<_w_i_d_t_h>x<_h_e_i_g_h_t>][{+ -} <_x_o_f_f_s_e_t> {+
               -}<_y_o_f_f_s_e_t>].

height
width          The height and width of this widget in pix-
               els.

llaabbeell          This label will be placed at the top of the
               SimpleMenu, and may not be highlighted.  The
               name of the label object is mmeennuuLLaabbeell.  Using
               this name it is possible to modify the
               label's attributes through the resource
               database.  When the label is created, the
               llaabbeell is hard coded to the value of llaabbeell,
               and jjuussttiiffyy is hard coded as XXttJJuussttiiffyyCCeenntteerr.

llaabbeellCCllaassss     Specifies the type of Sme object created as
               the menu label.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

mmeennuuOOnnSSccrreeeenn   If the menu is automatically positioned under
               the cursor with the XXaawwPPoossiittiioonnSSiimmpplleeMMeennuu
               action, and this resource is TTrruuee, then the
               menu will always be fully visible on the
               screen.

numChildren    The number of children in this composite wid-
               get.

overrideRedirect
               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 _I_n_t_e_r_c_l_i_e_n_t _C_o_m_m_u_n_i_c_a_-
               _t_i_o_n_s _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l.

popdownCallback
popupCallback  These callback functions are called by the Xt
               Intrinsics whenever the shell is popped up or
               down (See _X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e
               _I_n_t_e_r_f_a_c_e for details).

ppooppuuppOOnnEEnnttrryy   The XXaawwPPoossiittiioonnSSiimmpplleeMMeennuu action will, by
               default, popup the SimpleMenu with its label



                             9933





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               (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.

rroowwHHeeiigghhtt      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
               rroowwHHeeiigghhtt pixels high.

saveUnder      If this is TTrruuee then save unders will be
               active on the menu's window.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

translations   The event bindings associated with this wid-
               get.

x
y              The location of the upper left outside corner
               of this widget in its parent.

44..22..22..  SSiimmpplleeMMeennuu AAccttiioonnss

The SimpleMenu widget supports the following actions:

+o    Switching the entry under the mouse pointer between the
     foreground and background colors with hhiigghhlliigghhtt and
     uunnhhiigghhlliigghhtt

+o    Processing menu entry callbacks with nnoottiiffyy


The following are the default translation bindings used by
the SimpleMenu widget:



     <EnterWindow>:   highlight()
     <LeaveWindow>:   unhighlight()
     <BtnMotion>:     highlight()
     <BtnUp>:         MenuPopdown() notify() unhighlight()





                             9944





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


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.


The full list of actions supported by SimpleMenu is:

hhiigghhlliigghhtt()    Highlight the menu entry that is currently
               under the pointer.  Only a item that is high-
               lighted will be notified when the nnoottiiffyy
               action is invoked.  The look of a highlighted
               entry is determined by the menu entry.

uunnhhiigghhlliigghhtt()  Unhighlights the currently highlighted menu
               item, and returns it to its normal look.

nnoottiiffyy()       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.

MMeennuuPPooppddoowwnn(_m_e_n_u)
               This action is defined in _X _T_o_o_l_k_i_t _I_n_t_r_i_n_-
               _s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e.

44..22..33..  PPoossiittiioonniinngg tthhee SSiimmpplleeMMeennuu

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.

If popup menus are desired it will be necessary to add the
XXaawwPPoossiittiioonnSSiimmpplleeMMeennuu and MMeennuuPPooppuupp actions to the transla-
tion table of the widget that will be popping up the menu.
The MMeennuuPPooppuupp action is described in _X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_-
_C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e.  XXaawwPPoossiittiioonnSSiimmpplleeMMeennuu is a global
action procedure registered by the SimpleMenu widget when
the first one is created or the convenience routine XXaawwSSiimm--
pplleeMMeennuuAAddddGGlloobbaallAAccttiioonnss is called.

Translation writers should be aware that Xt does not regis-
ter grabs on ``don't care'' 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 xxtteerrmm''ss menus:



     !Ctrl<Btn1Down>: XawPositionSimpleMenu(xterm) MenuPopup(xterm)
     !Ctrl<Btn2Down>: XawPositionSimpleMenu(modes) MenuPopup(modes)







                             9955





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


XXaawwPPoossiittiioonnSSiimmpplleeMMeennuu(_m_e_n_u)
                      The XXaawwPPoossiittiioonnSSiimmpplleeMMeennuu routine will
                      search for the menu name passed to it
                      using XXttNNaammeeTTooWWiiddggeett starting with the
                      widget invoking the action as the ref-
                      erence 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.  XXaawwPPoo--
                      ssiittiioonnSSiimmpplleeMMeennuu will position the
                      menu directly under the pointer cur-
                      sor.  The menu will be placed so that
                      the pointer cursor is centered on the
                      entry named by the ppooppuuppOOnnEEnnttrryy
                      resource.  If the mmeennuuOOnnSSccrreeeenn
                      resource is TTrruuee then the menu will
                      always be fully visible on the screen.

44..22..44..  CCoonnvveenniieennccee RRoouuttiinneess

44..22..44..11..  RReeggiisstteerriinngg tthhee GGlloobbaall AAccttiioonn RRoouuttiinneess

The XXaawwPPoossiittiioonnSSiimmpplleeMMeennuu 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 XXaawwSSiimmpplleeMMeennuuAAddddGGlloobbaallAAccttiioonnss:

void XawSimpleMenuAddGlobalActions(_a_p_p___c_o_n)
      XtAppContext _a_p_p___c_o_n;


_a_p_p___c_o_n   Specifies the application context in which this
          action should be registered.

This function need only be called once per application and
must be called before any widget that uses XXaawwPPoossiittiioonnSSiimm--
pplleeMMeennuu action is realized.

44..22..44..22..  GGeettttiinngg aanndd CClleeaarriinngg tthhee CCuurrrreenntt MMeennuu EEnnttrryy

To get the currently highlighted menu entry use XXaawwSSiimmppllee--
MMeennuuGGeettAAccttiivveeEEnnttrryy:

Widget XawSimpleMenuGetActiveEntry(_w)
      Widget _w;


_w         Specifies the SimpleMenu widget.

This function returns the menu entry that is currently high-
lighted, or NULL if no entry is highlighted.



                             9966





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


To clear the SimpleMenu widget's internal information about
the currently highlighted menu entry use XXaawwSSiimmpplleeMMeennuuCClleeaarr--
AAccttiivveeEEnnttrryy:

Widget XawSimpleMenuClearActiveEntry(_w)
      Widget _w;


_w         Specifies the SimpleMenu widget.

This function unsets all internal references to the cur-
rently highlighted menu entry.  It does not _u_n_h_i_g_h_l_i_g_h_t or
otherwise alter the appearance of the active entry.  This
function is primarily for use by implementors of menu
entries.

44..33..  SSmmeeBBSSBB OObbjjeecctt



Application Header file<X11/Xaw/SmeBSB.h>
Class Header file   <X11/Xaw/SmeBSBP.h>
Class               smeBSBObjectClass
Class Name          SmeBSB
Superclass          Sme



The SmeBSB object is used to create a menu entry that con-
tains a string, and optional bitmaps in its left and right
margins.  Since each menu entry is an independent object,
the application is able to change the font, color, height,
and other attributes of the menu entries, on an entry by
entry basis.  The format of the string may either be the
encoding of the 8 bit ffoonntt utilized, or in a multi-byte
encoding for use with a ffoonnttSSeett.

44..33..11..  RReessoouurrcceess

The resources associated with the SmeBSB object are defined
in this section, and affect only the single menu entry spec-
ified by this object.

-----------------------------------------------------------------------------------------
NNaammee                CCllaassss               TTyyppee             NNootteess   DDeeffaauulltt VVaalluuee
-----------------------------------------------------------------------------------------
ancestorSensitive   AncestorSensitive   Boolean          D       True
callback            Callback            Callback                 NULL
destroyCallback     Callback            XtCallbackList           NULL
font                Font                FontStruct               XtDefaultFont
fontSet             FontSet             XFontSet                 XtDefaultFontSet
foreground          Foreground          Pixel                    XtDefaultForeground
height              Height              Dimension        A       Font height + vveerrttSSppaaccee




                             9977





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


-----------------------------------------------------------------------------------------
NNaammee                CCllaassss               TTyyppee             NNootteess   DDeeffaauulltt VVaalluuee
-----------------------------------------------------------------------------------------
international       International       Boolean          C       False
justify             Justify             Justify                  XtjustifyLeft
label               Label               String                   NULL
leftBitmap          LeftBitmap          Pixmap                   XtUnspecifiedPixmap
leftMargin          leftMargin          Dimension                4
rightBitmap         RightBitmap         Pixmap                   XtUnspecifiedPixmap
rightMargin         rightMargin         Dimension                4
sensitive           Sensitive           Boolean                  True
vertSpace           VertSpace           int                      25
width               Width               Dimension        A       TextWidth + margins
-----------------------------------------------------------------------------------------


ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

ccaallllbbaacckk       All callback functions on this list are
               called when the SimpleMenu _n_o_t_i_f_i_e_s this
               entry that the user has selected it.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

ffoonntt           The text font to use when displaying the
               llaabbeell, when the iinntteerrnnaattiioonnaall resource is
               ffaallssee.

ffoonnttSSeett        The text font set to use when displaying the
               llaabbeell, when the iinntteerrnnaattiioonnaall resource is
               ttrruuee.

ffoorreeggrroouunndd     A pixel value which indexes the SimpleMenu's
               colormap to derive the foreground color of
               the menu entry's window.  This color is also
               used to render all 1's in the left and right
               bbiittmmaappss.

height
width          The height and width of this widget in pix-
               els.  Keep in mind that the SimpleMenu widget
               will force the width of all menu entries to
               be the width of the longest entry.

international  This is a boolean flag, only settable at wid-
               get creation time.  A value of ffaallssee signals
               the widget to use pre-R6 internationalization



                             9988





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               (specifically, the lack thereof), such as
               using fonts for displaying text, etc.  A
               value of ttrruuee directs the widget to act in an
               internationalized manner, such as utilizing
               font sets for displaying text, etc.

jjuussttiiffyy        How the label is to be rendered between the
               left and right margins when the space is
               wider than the actual text.  This resource
               may be specified with the values XXttJJuussttii--
               ffyyLLeefftt, XXttJJuussttiiffyyCCeenntteerr, or XXttJJuussttiiffyyRRiigghhtt.
               When specifying the justification from a
               resource file the values lleefftt, cceenntteerr, or
               rriigghhtt may be used.

llaabbeell          This is a the string that will be displayed
               in the menu entry.  The exact location of
               this string within the bounds of the menu
               entry is controlled by the lleeffttMMaarrggiinn, rriigghhtt--
               MMaarrggiinn, vveerrttSSppaaccee, and jjuussttiiffyy resources.

lleeffttBBiittmmaapp
rriigghhttBBiittmmaapp    This is a name of a bitmap to display in the
               left or right margin of the menu entry.  All
               1's in the bitmap will be rendered in the
               foreground color, and all 0's will be drawn
               in the background color of the SimpleMenu
               widget.  It is the programmers' responsibil-
               ity to make sure that the menu entry is tall
               enough, and the appropriate margin wide
               enough to accept the bitmap.  If care is not
               taken the bitmap may extend into another menu
               entry, or into this entry's label.

lleeffttMMaarrggiinn
rriigghhttMMaarrggiinn    This is the amount of space (in pixels) that
               will be left between the edge of the menu
               entry and the label string.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

vveerrttSSppaaccee      This is the amount of vertical padding,
               expressed as a percentage of the height of
               the font, that is to be placed around the
               label of a menu entry.. The label and bitmaps
               are always centered vertically within the
               menu.  The default value for this resource
               (25) causes the default height to be 125% of
               the height of the font.





                             9999





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


44..44..  SSmmeeLLiinnee OObbjjeecctt



Application Header file<X11/Xaw/SmeLine.h>
Class Header file   <X11/Xaw/SmeLineP.h>
Class               smeLineObjectClass
Class Name          SmeLine
Superclass          Sme



The SmeLine object is used to add a horizontal line or menu
separator to a menu.  Since each SmeLine is an independent
object, the application is able to change the color, height,
and other attributes of the SmeLine objects on an entry by
entry basis.  This object is not selectable, and will not
highlight when the pointer cursor is over it.

44..44..11..  RReessoouurrcceess

The resources associated with the SmeLine object are defined
in this section, and affect only the single menu entry spec-
ified by this object.

--------------------------------------------------------------------------------
NNaammee              CCllaassss           TTyyppee             NNootteess   DDeeffaauulltt VVaalluuee
--------------------------------------------------------------------------------
destroyCallback   Callback        XtCallbackList           NULL
foreground        Foreground      Pixel                    XtDefaultForeground
height            Height          Dimension                lliinneeWWiiddtthh
international     International   Boolean          C       False
lineWidth         LineWidth       Dimension                1
stipple           Stipple         Pixmap                   XtUnspecifiedPixmap
width             Width           Dimension                1
--------------------------------------------------------------------------------


destroyCallback
               All functions on this list are called when
               this widget is destroyed.

ffoorreeggrroouunndd     A pixel value which indexes the SimpleMenu's
               colormap to derive the foreground color used
               to draw the separator line.

height
width          The height and width of this widget in pix-
               els.  Keep in mind that the SimpleMenu widget
               will force all menu items to be the width of
               the widest entry.  Thus, setting the width is
               generally not very important.





                             110000





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


international  This is a boolean flag, only settable at wid-
               get creation time.  While not utilized in
               this widget, it can and should be checked by
               any subclasses that have behavior that should
               vary with locale.

lliinneeWWiiddtthh      The width of the horizontal line that is to
               be displayed.

ssttiippppllee        If a bitmap is specified for this resource,
               the line will be stippled through it.  This
               allows the menu separator to be rendered as
               something more exciting than just a line.
               For instance, if you define a stipple that is
               a chain link, then your menu separators will
               look like chains.

44..55..  SSmmee OObbjjeecctt



Application Header file<X11/Xaw/Sme.h>
Class Header file   <X11/Xaw/SmeP.h>
Class               smeObjectClass
Class Name          Sme
Superclass          RectObj



The Sme object is the base class for all menu entries.
While this object is mainly intended to be subclassed, it
may be used in a menu to add blank space between menu
entries.

44..55..11..  RReessoouurrcceess

The resources associated with the SmeLine object are defined
in this section, and affect only the single menu entry spec-
ified by this object.  There are no new resources added for
this class, as it picks up all its resources from the Rec-
tObj class.

--------------------------------------------------------------------------------------
NNaammee                CCllaassss               TTyyppee             NNootteess   DDeeffaauulltt VVaalluuee
--------------------------------------------------------------------------------------
ancestorSensitive   AncestorSensitive   Boolean                  True
callback            Callback            XtCallbackList           NULL
destroyCallback     Callback            XtCallbackList           NULL
height              Height              Dimension                0
international       International       Boolean          C       False
sensitive           Sensitive           Boolean                  True
width               Width               Dimension                1
--------------------------------------------------------------------------------------




                             110011





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

height
width          The height and width of this widget in pix-
               els.  Keep in mind that the SimpleMenu widget
               will force all menu items to be the width of
               the widest entry.

iinntteerrnnaattiioonnaall  This is a boolean flag, only settable at wid-
               get creation time.  While not utilized in
               this widget, it can and should be checked by
               any subclasses that have behavior that should
               vary with locale.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

44..55..22..  SSuubbccllaassssiinngg tthhee SSmmee OObbjjeecctt


To Create a new Sme object _c_l_a_s_s you will need to define
three class methods.  These methods allow the SimpleMenu to
highlight and unhighlight the menu entry as the pointer cur-
sor moves over it, as well as notify the entry when the user
has selected it.  All of these methods may be inherited from
the Sme object, although the default semantics are not very
interesting.

HHiigghhlliigghhtt()
          Called to put the menu entry into the highlighted
          state.

UUnnhhiigghhlliigghhtt()
          Called to return the widget to its normal (unhigh-
          lighted) state.

NNoottiiffyy()  Called when the user selects this menu entry.


Other then these methods, creating a new object is straight
forward.  Here is some information that may help you avoid
some common mistakes.




                             110022





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


1) Objects can be zero pixels high.

2) Objects draw on their parent's window, therefore the
   Drawing dimensions are different from those of widgets.
   For instance, y locations vary from yy to yy ++ hheeiigghhtt, not
   00 to hheeiigghhtt.

3) XtSetValues calls may come from the application while the
   Sme is highlighted, and if the SetValues method returns
   True, will result in an expose event.  The SimpleMenu may
   later call the menu entry's uunnhhiigghhlliigghhtt procedure.  How-
   ever, due to the asynchronous nature of X, the expose
   event generated by XXttSSeettVVaalluueess will come _a_f_t_e_r this
   unhighlight.

4) Remember that your subclass of the Sme does not own the
   window.  Share the space with other menu entries, and
   refrain from drawing outside the subclass's own section
   of the menu.


44..66..  MMeennuuBBuuttttoonn WWiiddggeett


Application Header file<X11/Xaw/MenuButton.h>
Class Header file   <X11/Xaw/MenuButtonP.h>
Class               menuButtonWidgetClass
Class Name          MenuButton
Superclass          Command



The MenuButton widget is an area, often rectangular, that
displays a graphic.  The graphic may be a text string con-
taining multiple lines of characters in an 8 bit or 16 bit
character set (to be displayed with a _f_o_n_t), or in a multi-
byte encoding (for use with a _f_o_n_t_s_e_t).  The graphic may
also be a bitmap or pixmap.

When the pointer cursor is on a MenuButton widget, the
MenuButton becomes highlighted by drawing a rectangle around
its perimeter.  This highlighting indicates that the
MenuButton is ready for selection.  When a pointer button is
pressed, the MenuButton widget will pop up the menu named in
the mmeennuuNNaammee resource.

44..66..11..  RReessoouurrcceess

When creating a MenuButton widget instance, the following
resources are retrieved from the argument list or from the
resource database:






                             110033





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


-------------------------------------------------------------------------------------------------
NNaammee                  CCllaassss             TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
-------------------------------------------------------------------------------------------------
accelerators          Accelerators      AcceleratorTable     NULL
ancestorSensitive     AncestorSensitive Boolean         D    True
background            Background        Pixel                XtDefaultBackground
backgroundPixmap      Pixmap            Pixmap               XtUnspecifiedPixmap
bitmap                Bitmap            Pixmap               None
borderColor           BorderColor       Pixel                XtDefaultForeground
borderPixmap          Pixmap            Pixmap               XtUnspecifiedPixmap
borderWidth           BorderWidth       Dimension            1
callback              Callback          XtCallbackList       NULL
colormap              Colormap          Colormap             Parent's Colormap
cornerRoundPercent    CornerRoundPercentDimension            25
cursor                Cursor            Cursor               None
cursorName            Cursor            String               None
depth                 Depth             int             C    Parent's Depth
destroyCallback       Callback          XtCallbackList       NULL
encoding              Encoding          UnsignedChar         XawTextEncoding8bit
font                  Font              XFontStruct          XtDefaultFont
fontSet               FontSet           XFontSet             XtDefaultFontSet
foreground            Foreground        Pixel                XtDefaultForeground
height                Height            Dimension       A    graphic height + 2 * iinntteerrnnaallHHeeiigghhtt
highlightThickness    Thickness         Dimension       A    2 (0 if Shaped)
insensitiveBorder     Insensitive       Pixmap               GreyPixmap
internalHeight        Height            Dimension            2
internalWidth         Width             Dimension            4
international         International     Boolean         C    False
justify               Justify           Justify              XtJustifyCenter (center)
label                 Label             String               name of widget
leftBitmap            LeftBitmap        Bitmap               None
mappedWhenManaged     MappedWhenManaged Boolean              True
menuName              MenuName          String               "menu"
pointerColor          Foreground        Pixel                XtDefaultForeground
pointerColorBackgroundBackground        Pixel                XtDefaultBackground
resize                Resize            Boolean              True
screen                Screen            Screen          R    Parent's Screen
sensitive             Sensitive         Boolean              True
shapeStype            ShapeStyle        ShapeStyle           Rectangle
translations          Translations      TranslationTable     See below
width                 Width             Dimension       A    graphic width + 2 * iinntteerrnnaallWWiiddtthh
x                     Position          Position             0
y                     Position          Position             0
-------------------------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of



                             110044





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

bitmap         A bitmap to display instead of the llaabbeell.
               The default size of the widget will be just
               large enough to contain the bitmap and the
               widget's internal width and height.  The
               resource converter for this resource con-
               structs bitmaps from the contents of files.
               (See CCoonnvveerrttiinngg BBiittmmaappss for details.)  If
               this bitmap is one bit deep then the 1's will
               be rendered in the foreground color, and the
               0's in the background color.  If bbiittmmaapp has a
               depth greater than one, it is copied directly
               into the window.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

callback       A list of routines to be called when the
               nnoottiiffyy action is invoked.

colormap       The colormap that this widget will use.

cornerRoundPercent
               When a SShhaappeeSSttyyllee of rroouunnddeeddRReeccttaannggllee is
               used, this resource controls the radius of
               the rounded corner.  The radius of the
               rounded corners is specified as a percentage
               of the length of the shortest side of the
               widget.




                             110055





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


cursor         The image that will be displayed as the
               pointer cursor whenever it is in this widget.
               The use of this resource is deprecated in
               favor of ccuurrssoorrNNaammee.

cursorName     The name of the symbol to use to represent
               the pointer cursor.  This resource will over-
               ride the ccuurrssoorr resource if both are speci-
               fied. (See 2.4.1)

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

font           The text font to use when displaying the
               llaabbeell, when the iinntteerrnnaattiioonnaall resource is
               ffaallssee.

fontSet        The text font set to use when displaying the
               llaabbeell, when the iinntteerrnnaattiioonnaall resource is
               ttrruuee.

foreground     A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               widget's window.  This color is also used to
               render all 1's in a bbiittmmaapp one plane deep.

height
width          The height and width of this widget in pix-
               els.

highlightThickness
               The thickness of the rectangle that is used
               to highlight the internal border of this wid-
               get, alerting the user that it is ready to be
               selected.  The default value is 2 pixels if
               the sshhaappeeSSttyyllee is rreeccttaannggllee, and 0 Pixels (no
               highlighting) otherwise.

insensitiveBorder
               This pixmap will be tiled into the widget's
               border if the widget becomes insensitive.

internalHeight
internalWidth  The minimum amount of space to leave between
               the graphic and the vertical and horizontal
               edges of the window.

international  This is a boolean flag, only settable at wid-
               get creation time.  A value of ffaallssee signals
               the widget to use pre-R6 internationalization
               (specifically, the lack thereof), such as



                             110066





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               using fonts for displaying text, etc.  A
               value of ttrruuee directs the widget to act in an
               internationalized manner, such as utilizing
               font sets for displaying text, etc.

justify        Specifies left, center, or right alignment of
               graphic within the widget.  This resource may
               be specified with the values XXttJJuussttiiffyyLLeefftt,
               XXttJJuussttiiffyyCCeenntteerr, or XXttJJuussttiiffyyRRiigghhtt.  A con-
               verter is registered for this resource that
               will convert the following strings: lleefftt,,
               rriigghhtt,, and cceenntteerr.  This resource only has
               noticeable effect when the width of the wid-
               get is larger than necessary to display the
               graphic.  Note that when the graphic is a
               multi-line llaabbeell, the longest line will obey
               this justification while shorter lines will
               be left-justified with the longest one.


label          Specifies the text string to be displayed in
               the widget's window if no bitmap is speci-
               fied.  The default is the name of this wid-
               get.  Regardless of the value of eennccooddiinngg or
               iinntteerrnnaattiioonnaall, a single newline character (1
               byte) will cause a line break.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

mmeennuuNNaammee       The name of a popup shell to popup as a menu.
               The MenuButton will search for this name
               using XXttNNaammeeTTooWWiiddggeett starting with itself as
               the reference widget.  If the search is
               unsuccessful the widget will continue up the
               widget tree using each of its ancestors as
               the reference widget passed to XXttNNaammeeTTooWWiidd--
               ggeett.  If no widget of called mmeennuuNNaammee is
               found by this algorithm, the widget will
               print a warning message and give up.  When
               the menu is found it will be popped up exclu-
               sive and spring_loaded.  The MenuButton wid-
               get does not copy the value of this resource
               into newly allocated memory. The application
               programmer must pass the resource value in
               nonvolatile memory.

pointerColor   A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               pointer symbol specified by the ccuurrssoorrNNaammee
               resource.




                             110077





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


pointerColorBackground
                 A pixel value which indexes the widget's
                 colormap to derive the background color of
                 the pointer symbol specified by the ccuurrssoorr--
                 NNaammee resource.

resize         Specifies whether the widget should attempt
               to resize to its preferred dimensions when-
               ever its resources are modified with XXttSSeett--
               VVaalluueess.  This attempt to resize may be denied
               by the parent of this widget.  The parent is
               always free to resize the widget regardless
               of the state of this resource.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

shapeStyle     Nonrectangular widgets may be created using
               this resource.  Nonrectangular widgets are
               supported only on a server that supports the
               SShhaappee EExxtteennssiioonn.  If nonrectangular widgets
               are specified for a server lacking this
               extension, the shape is ignored and the wid-
               gets will be rectangular.  The following
               shapes are currently supported: XXmmuuSShhaappeeRReecctt--
               aannggllee, XXmmuuSShhaappeeOOvvaall, XXmmuuSShhaappeeEElllliippssee, and
               XXmmuuSShhaappeeRRoouunnddeeddRReeccttaannggllee.  A converter is
               registered for this resource that will con-
               vert the following strings: rreeccttaannggllee,, oovvaall,,
               eelllliippssee,, and rroouunnddeeddRReeccttaannggllee.

translations   The event bindings associated with this wid-
               get.

x
y              The location of the upper left outside corner
               of this widget in its parent.

44..66..22..  MMeennuuBBuuttttoonn AAccttiioonnss

The MenuButton widget supports the following actions:

+o    Switching the button between the foreground and back-
     ground colors with sseett and uunnsseett

+o    Processing application callbacks with nnoottiiffyy

+o    Switching the internal border between highlighted and
     unhighlighted states with hhiigghhlliigghhtt and uunnhhiigghhlliigghhtt



                             110088





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


+o    Popping up a menu with PPooppuuppMMeennuu

The following are the default translation bindings used by
the MenuButton widget:



     <EnterWindow>:   highlight()
     <LeaveWindow>:   reset()
     <BtnDown>:       reset() PopupMenu(


44..66..33..  MMeennuuBBuuttttoonn AAccttiioonnss

The full list of actions supported by MenuButton is:

hhiigghhlliigghhtt(_c_o_n_d_i_t_i_o_n)
               Displays the internal highlight border in the
               color (ffoorreeggrroouunndd or bbaacckkggrroouunndd ) that con-
               trasts with the interior color of the Command
               widget.  The conditions WWhheennUUnnsseett and AAllwwaayyss
               are understood by this action procedure.  If
               no argument is passed, WWhheennUUnnsseett is assumed.

uunnhhiigghhlliigghhtt()  Displays the internal highlight border in the
               color (XXttNNffoorreeggrroouunndd or bbaacckkggrroouunndd ) that
               matches the interior color of the MenuButton
               widget.

sseett()          Enters the _s_e_t state, in which nnoottiiffyy is pos-
               sible.  This action causes the button to dis-
               play its interior in the ffoorreeggrroouunndd color.
               The label or bitmap is displayed in the bbaacckk--
               ggrroouunndd color.

uunnsseett()        Cancels the _s_e_t state and displays the inte-
               rior of the button in the bbaacckkggrroouunndd color.
               The label or bitmap is displayed in the ffoorree--
               ggrroouunndd color.

rreesseett()        Cancels any sseett or hhiigghhlliigghhtt and displays the
               interior of the button in the bbaacckkggrroouunndd
               color, with the label displayed in the ffoorree--
               ggrroouunndd color.

nnoottiiffyy()       When the button is in the sseett state this
               action calls all functions in the callback
               list named by the ccaallllbbaacckk resource.  The
               value of the call_data argument in these
               callback functions is undefined.

PPooppuuppMMeennuu()    Pops up the menu specified by the mmeennuuNNaammee
               resource.




                             110099





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The MenuButton widget does not place a server grab on
itself.  Instead, PopupMenu is registered as a grab action.
As a result, clients which popup menus without using
XtMenuPopup or MenuPopup or PopupMenu in translations will
fail to have a grab active.  They should make a call to
XtRegisterGrabAction on the appropriate action in the appli-
cation initialization routine, or use a different transla-
tion.

















































                             111100





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77




                         CChhaapptteerr 55

                        TTeexxtt WWiiddggeettss




The Text widget provides a window that will allow an appli-
cation to display and edit one or more lines of text.
Options are provided to allow the user to add Scrollbars to
its window, search for a specific string, and modify the
text in the buffer.

The Text widget is made up of a number of pieces; it was
modularized to ease customization.  The AsciiText widget
class (actually not limited to ASCII but so named for com-
patibility) is be general enough to most needs.  If more
flexibility, special features, or extra functionality is
needed, they can be added by implementing a new TextSource
or TextSink, or by subclassing the Text Widget (See Section
5.8 for customization details.)

The words _i_n_s_e_r_t_i_o_n _p_o_i_n_t are used in this chapter to refer
to the text caret.  This is the symbol that is displayed
between two characters in the file.  The insertion point
marks the location where any new characters will be added to
the file.  To avoid confusion the pointer cursor will always
be referred to as the _p_o_i_n_t_e_r.

The text widget supports three edit modes, controlling the
types of modifications a user is allowed to make:

+o    Append-only

+o    Editable

+o    Read-only

Read-only mode does not allow the user or the programmer to
modify the text in the widget.  While the entire string may
be reset in read-only mode with XXttSSeettVVaalluueess, it cannot be
modified via with XXaawwTTeexxttRReeppllaaccee.  Append-only and editable
modes allow the text at the insertion point to be modified.
The only difference is that text may only be added to or
removed from the end of a buffer in append-only mode.


55..11..  TTeexxtt WWiiddggeett ffoorr UUsseerrss

The Text widget provides many of the common keyboard editing
commands.  These commands allow users to move around and
edit the buffer.  If an illegal operation is attempted,



                             111111





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


(such as deleting characters in a read-only text widget),
the X server will beep.

55..11..11..  DDeeffaauulltt KKeeyy BBiinnddiinnggss

The default key bindings are patterned after those in the
EMACS text editor:


Ctrl-a    Beginning Of Line   Meta-b         Backward Word
Ctrl-b    Backward Character  Meta-f         Forward Word
Ctrl-d    Delete Next Character              Meta-iInsert File
Ctrl-e    End Of Line         Meta-k         Kill To End Of Paragraph
Ctrl-f    Forward Character   Meta-q         Form Paragraph
Ctrl-g    Multiply Reset      Meta-v         Previous Page
Ctrl-h    Delete Previous Character          Meta-yInsert Current Selection
Ctrl-j    Newline And Indent  Meta-z         Scroll One Line Down
Ctrl-k    Kill To End Of Line Meta-d         Delete Next Word
Ctrl-l    Redraw Display      Meta-D         Kill Word
Ctrl-m    Newline             Meta-h         Delete Previous Word
Ctrl-n    Next Line           Meta-H         Backward Kill Word
Ctrl-o    Newline And Backup  Meta-<         Beginning Of File
Ctrl-p    Previous Line       Meta->         End Of File
Ctrl-r    Search/Replace Backward            Meta-]Forward Paragraph
Ctrl-s    Search/Replace Forward             Meta-[Backward Paragraph
Ctrl-t    Transpose Characters
Ctrl-u    Multiply by 4       Meta-Delete    Delete Previous Word
Ctrl-v    Next Page           Meta-Shift DeleteKill Previous Word
Ctrl-w    Kill Selection      Meta-Backspace Delete Previous Word
Ctrl-y    Unkill              Meta-Shift BackspaceKill Previous Word
Ctrl-z    Scroll One Line Up
Ctrl-\    Reconnect to input method
Kanji     Reconnect to input method



In addition, the pointer may be used to cut and paste text:


          Button 1 Down  Start Selection
          Button 1 MotionAdjust Selection
          Button 1 Up    End Selection (cut)

          Button 2 Down  Insert Current Selection (paste)

          Button 3 Down  Extend Current Selection
          Button 3 MotionAdjust Selection
          Button 3 Up    End Selection (cut)



Since all of these key and pointer bindings are set through
the translations and resource manager, the user and the
application programmer can modify them by changing the Text



                             111122





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


widget's ttrraannssllaattiioonnss resource.

55..11..22..  SSeeaarrcchh aanndd RReeppllaaccee

The Text widget provides a search popup that can be used to
search for a string within the current Text widget.  The
popup can be activated by typing either _C_o_n_t_r_o_l_-_r or _C_o_n_-
_t_r_o_l_-_s.  If _C_o_n_t_r_o_l_-_s is used the search will be forward in
the file from the current location of the insertion point;
if _C_o_n_t_r_o_l_-_r is used the search will be backward.  The acti-
vated popup is placed under the pointer.  It has a number of
buttons that allow both text searches and text replacements
to be performed.

At the top of the search popup are two toggle buttons
labeled _b_a_c_k_w_a_r_d and _f_o_r_w_a_r_d.  One of these buttons will
always be highlighted; this is the direction in which the
search will be performed.  The user can change the direction
at any time by clicking on the appropriate button.

Directly under the buttons there are two text areas, one
labeled _S_e_a_r_c_h _f_o_r_: and the other labeled _R_e_p_l_a_c_e _w_i_t_h_:.  If
this is a read-only Text widget the _R_e_p_l_a_c_e _w_i_t_h_: field will
be insensitive and no replacements will be allowed.  After
each of these labels will be a text field.  This field will
allow the user to enter a string to search for and the
string to replace it with.  Only one of these text fields
will have a window border around it; this is the active text
field.  Any key presses that occur when the focus in in the
search popup will be directed to the active text field.
There are also a few special key sequences:

     CCaarrrriiaaggee RReettuurrnn: Execute the action, and pop down the search widget.
     TTaabb:             Execute the action, then move to the next field.
     SShhiifftt CCaarrrriiaaggee RReettuurrnn:Execute the action, then move to the next field.
     CCoonnttrrooll--qq TTaabb:   Enter a Tab into a text field.
     CCoonnttrrooll--cc:       Pop down the search popup.


Using these special key sequences should allow simple
searches without ever removing one's hands from the key-
board.

Near the bottom of the search popup is a row of buttons.
These buttons allow the same actions to to be performed as
the key sequences, but the buttons will leave the popup
active.  This can be quite useful if many searches are being
performed, as the popup will be left on the display.  Since
the search popup is a transient window, it may be picked up
with the window manager and pulled off to the side for use
at a later time.

SSeeaarrcchh         Search for the specified string.




                             111133





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


RReeppllaaccee        Replace the currently highlighted string with
               the string in the _R_e_p_l_a_c_e _w_i_t_h text field,
               and move onto the next occurrence of the
               _S_e_a_r_c_h _f_o_r text field.  The functionality is
               commonly referred to as query-replace.

RReeppllaaccee--AAllll    Replace all occurrences of the search string
               with the replace string from the current
               insertion point position to the end (or
               beginning) of the file.  There is no key
               sequence to perform this action.

CCaanncceell         Remove the search popup from the screen.

Finally, when iinntteerrnnaattiioonnaall resource is ttrruuee, there may be a
pre-edit buffer below the button row, for composing input.
Its presence is determined by the X locale in use and the
VendorShell's pprreeeeddiittTTyyppee resource.

The widget hierarchy for the search popup is show below, all
widgets are listed by class and instance name.

Text  <name of Text widget>
     TransientShell  search
          Form  form
               Label label1
               Label  label2
               Toggle  backwards
               Toggle  forwards
               Label  searchLabel
               Text  searchText
               Label  replaceLabel
               Text  replaceText
               Command  search
               Command  replaceOne
               Command  replaceAll
               Command  cancel

55..11..33..  FFiillee IInnsseerrttiioonn

To insert a file into a text widget, type the key sequence
_M_e_t_a_-_i, which will activate the file insert popup.  This
popup will appear under the pointer, and any text typed
while the focus is in this popup will be redirected to the
text field used for the filename.  When the desired filename
has been entered, click on _I_n_s_e_r_t _F_i_l_e, or type _C_a_r_r_i_a_g_e
_R_e_t_u_r_n.  The named file will then be inserted in the text
widget beginning at the insertion point position.  If an
error occurs when opening the file, an error message will be
printed, prompting the user to enter the filename again.
The file insert may be aborted by clicking on _C_a_n_c_e_l.  If
_M_e_t_a_-_i is typed at a text widget that is read-only, it will
beep, as no file insertion is allowed.




                             111144





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The widget hierarchy for the file insert popup is show
below; all widgets are listed by class and instance name.

Text  <name of Text widget>
     TransientShell  insertFile
          Form  form
               Label  label
               Text  text
               Command  insert
               Command  cancel

55..11..44..  TTeexxtt SSeelleeccttiioonnss ffoorr UUsseerrss

The text widgets have a text selection mechanism that allows
the user to copy pieces of the text into the PPRRIIMMAARRYY selec-
tion, and paste into the text widget some text that another
application (or text widget) has put in the PPRRIIMMAARRYY selec-
tion.

One method of selecting text is to press pointer button 1 on
the beginning of the text to be selected, drag the pointer
until all of the desired text is highlighted, and then
release the button to activate the selection.  Another
method is to click pointer button 1 at one end of the text
to be selected, then click pointer button 3 at the other
end.

To modify a currently active selection, press pointer button
3 near either the end of the selection that you want to
adjust.  This end of the selection may be moved while hold-
ing down pointer button 3.  When the proper area has been
highlighted release the pointer button to activate the
selection.

The selected text may now be pasted into another applica-
tion, and will remain active until some other client makes a
selection.  To paste text that some other application has
put into the PPRRIIMMAARRYY selection use pointer button 2.  First
place the insertion point where you would like the text to
be inserted, then click and release pointer button 2.

Rapidly clicking pointer button 1 the following number of
times will adjust the selection as described.

TTwwoo       Select the word under the pointer.  A word bound-
          ary is defined by the Text widget to be a Space,
          Tab, or Carriage Return.

TThhrreeee     Select the line under the pointer.

FFoouurr      Select the paragraph under the pointer.  A para-
          graph boundary is defined by the text widget as
          two Carriage Returns in a row with only Spaces or
          Tabs between them.



                             111155





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


FFiivvee      Select the entire text buffer.

To unset the text selection, click pointer button 1 without
moving it.

55..22..  TTeexxtt WWiiddggeett AAccttiioonnss


All editing functions are performed by translation manager
actions that may be specified through the ttrraannssllaattiioonnss
resource in the Text widget.



Insert Point Movement    Delete
     forward-character        delete-next-character
     backward-character       delete-previous-character
     forward-word             delete-next-word
     backward-word            delete-previous-word
     forward-paragraph        delete-selection
     backward-paragraph
     beginning-of-line
     end-of-line         Selection
     next-line                select-word
     previous-line            select-all
     next-page                select-start
     previous-page            select-adjust
     beginning-of-file        select-end
     end-of-file              extend-start
     scroll-one-line-up       extend-adjust
     scroll-one-line-down     extend-end
                              insert-selection


Miscellaneous            New Line
     redraw-display           newline-and-indent
     insert-file              newline-and-backup
     insert-char              newline
     insert-string
     display-caret
     focus-in            Kill
     focus-in                 kill-word
     search                   backward-kill-word
     multiply                 kill-selection
     form-paragraph           kill-to-end-of-line
     transpose-characters     kill-paragraph
     no-op                    kill-to-end-of-paragraph
     XawWMProtocols
     reconnect-im



Most of the actions take no arguments, and unless otherwise
noted you may assume this to be the case.



                             111166





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


55..22..11..  CCuurrssoorr MMoovveemmeenntt AAccttiioonnss



forward-character()
backward-character()
                    These actions move the insert point for-
                    ward or backward one character in the
                    buffer.  If the insert point is at the
                    end or beginning of a line this action
                    will move the insert point to the next
                    (or previous) line.

forward-word()
backward-word()     These actions move the insert point to
                    the next or previous word boundary.  A
                    word boundary is defined as a Space, Tab
                    or Carriage Return.

forward-paragraph()
backward-paragraph()
                    These actions move the insert point to
                    the next or previous paragraph boundary.
                    A paragraph boundary is defined as two
                    Carriage Returns in a row with only
                    Spaces or Tabs between them.

beginning-of-line()
end-of-line()       These actions move to the beginning or
                    end of the current line.  If the insert
                    point is already at the end or beginning
                    of the line then no action is taken.

next-line()
previous-line()     These actions move the insert point up
                    or down one line.  If the insert point
                    is currently N characters from the
                    beginning of the line then it will be N
                    characters from the beginning of the
                    next or previous line.  If N is past the
                    end of the line, the insert point is
                    placed at the end of the line.

next-page()
previous-page()     These actions move the insert point up
                    or down one page in the file.  One page
                    is defined as the current height of the
                    text widget.  The insert point is always
                    placed at the first character of the top
                    line by this action.

beginning-of-file()
end-of-file()       These actions place the insert point at
                    the beginning or end of the current text



                             111177





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


                    buffer.  The text widget is then
                    scrolled the minimum amount necessary to
                    make the new insert point location visi-
                    ble.

scroll-one-line-up()
scroll-one-line-down()
                    These actions scroll the current text
                    field up or down by one line.  They do
                    not move the insert point.  Other than
                    the scrollbars this is the only way that
                    the insert point may be moved off of the
                    visible text area.  The widget will be
                    scrolled so that the insert point is
                    back on the screen as soon as some other
                    action is executed.

55..22..22..  DDeelleettee AAccttiioonnss



delete-next-character()
delete-previous-character()
                    These actions remove the character imme-
                    diately before or after the insert
                    point.  If a Carriage Return is removed
                    then the next line is appended to the
                    end of the current line.

delete-next-word()
delete-previous-word()
                    These actions remove all characters
                    between the insert point location and
                    the next word boundary.  A word boundary
                    is defined as a Space, Tab or Carriage
                    Return.

delete-selection()  This action removes all characters in
                    the current selection.  The selection
                    can be set with the selection actions.

55..22..33..  SSeelleeccttiioonn AAccttiioonnss



select-word()       This action selects the word in which
                    the insert point is currently located.
                    If the insert point is between words
                    then it will select the previous word.

select-all()        This action selects the entire text
                    buffer.





                             111188





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


select-start()      This action sets the insert point to the
                    current pointer location (if triggered
                    by a button event) or text cursor loca-
                    tion (if triggered by a key event).  It
                    will then begin a selection at this
                    location.  If many of these selection
                    actions occur quickly in succession then
                    the selection count mechanism will be
                    invoked (see the section titled TTeexxtt
                    SSeelleeccttiioonnss ffoorr AApppplliiccaattiioonn PPrrooggrraammmmeerrss
                    for details).

select-adjust()     This action allows a selection started
                    with the _s_e_l_e_c_t_-_s_t_a_r_t action to be modi-
                    fied, as described above.

select-end(_n_a_m_e[,_n_a_m_e,...])
                    This action ends a text selection that
                    began with the _s_e_l_e_c_t_-_s_t_a_r_t action, and
                    asserts ownership of the selection or
                    selections specified.  A _n_a_m_e can be a
                    selection (e.g., PPRRIIMMAARRYY) or a cut
                    buffer (e.g., CCUUTT__BBUUFFFFEERR00).  Note that
                    case is important.  If no _n_a_m_e_s are
                    specified, PPRRIIMMAARRYY is asserted.

extend-start()      This action finds the nearest end of the
                    current selection, and moves it to the
                    current pointer location (if triggered
                    by a button event) or text cursor loca-
                    tion (if triggered by a key event).

extend-adjust()     This action allows a selection started
                    with an _e_x_t_e_n_d_-_s_t_a_r_t action to be modi-
                    fied.

extend-end(_n_a_m_e[,_n_a_m_e,...])
                    This action ends a text selection that
                    began with the _e_x_t_e_n_d_-_s_t_a_r_t action, and
                    asserts ownership of the selection or
                    selections specified.  A _n_a_m_e can be a
                    selection (e.g. PPRRIIMMAARRYY) or a cut buffer
                    (e.g CCUUTT__BBUUFFFFEERR00).  Note that case is
                    important.  If no names are given, PPRRII--
                    MMAARRYY is asserted.

insert-selection(_n_a_m_e[,_n_a_m_e,...])
                    This action retrieves the value of the
                    first (left-most) named selection that
                    exists or the cut buffer that is not
                    empty and inserts it into the Text wid-
                    get at the current insert point loca-
                    tion. A _n_a_m_e can be a selection (e.g.
                    PPRRIIMMAARRYY) or a cut buffer (e.g



                             111199





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


                    CCUUTT__BBUUFFFFEERR00).  Note that case is impor-
                    tant.

55..22..44..  TThhee NNeeww LLiinnee AAccttiioonnss



newline-and-indent()
                    This action inserts a newline into the
                    text and adds spaces to that line to
                    indent it to match the previous line.

newline-and-backup()
                    This action inserts a newline into the
                    text _a_f_t_e_r the insert point.

newline()           This action inserts a newline into the
                    text _b_e_f_o_r_e the insert point.

55..22..55..  KKiillll aanndd AAccttiioonnss



kill-word()
backward-kill-word()
                    These actions act exactly like the
                    _d_e_l_e_t_e_-_n_e_x_t_-_w_o_r_d and _d_e_l_e_t_e_-_p_r_e_v_i_o_u_s_-
                    _w_o_r_d actions, but they stuff the word
                    that was killed into the kill buffer
                    (CCUUTT__BBUUFFFFEERR__11).

kill-selection()    This action deletes the current selec-
                    tion and stuffs the deleted text into
                    the kill buffer (CCUUTT__BBUUFFFFEERR__11).

kill-to-end-of-line()
                    This action deletes the entire line to
                    the right of the insert point position,
                    and stuffs the deleted text into the
                    kill buffer (CCUUTT__BBUUFFFFEERR__11).

kill-paragraph()    This action deletes the current para-
                    graph, if between paragraphs it deletes
                    the paragraph above the insert point,
                    and stuffs the deleted text into the
                    kill buffer (CCUUTT__BBUUFFFFEERR__11).

kill-to-end-of-paragraph()
                    This action deletes everything between
                    the current insert point location and
                    the next paragraph boundary, and stuffs
                    the deleted text into the kill buffer
                    (CCUUTT__BBUUFFFFEERR__11).




                             112200





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


55..22..66..  MMiisscceellllaanneeoouuss AAccttiioonnss



redraw-display()    This action recomputes the location of
                    all the text lines on the display,
                    scrolls the text to vertically center
                    the line containing the insert point on
                    the screen, clears the entire screen,
                    and redisplays it.

insert-file([_f_i_l_e_n_a_m_e])
                    This action activates the insert file
                    popup.  The _f_i_l_e_n_a_m_e option specifies
                    the default filename to put in the file-
                    name buffer of the popup.  If no _f_i_l_e_-
                    _n_a_m_e is specified the buffer is empty at
                    startup.

insert-char()       This action may only be attached to a
                    key event. When the iinntteerrnnaattiioonnaall
                    resource is ffaallssee, this action calls
                    XLookupString to translate the event
                    into a (rebindable) Latin-1 character
                    (sequence) and inserts it into the text
                    at the insert point.  When the iinntteerrnnaa--
                    ttiioonnaall resource is ttrruuee, characters are
                    passed to the input method via
                    XwcLookupString, and any committed
                    string returned is inserted into the
                    text at the insert point.

insert-string(_s_t_r_i_n_g[,_s_t_r_i_n_g,...])
                    This action inserts each _s_t_r_i_n_g into the
                    text at the insert point location.  Any
                    _s_t_r_i_n_g beginning with the characters
                    "0x" followed by an even number of hex-
                    adecimal digits is interpreted as a hex-
                    adecimal constant and the corresponding
                    string is inserted instead.  This hex-
                    adecimal string may represent up to 50
                    8-bit characters.
                     When theiinntteerrnnaattiioonnaall resource is ttrruuee,
                    a hexadecimal string is intrepeted as
                    being in a multi-byte encoding, and a
                    hexadecimal or regular string will
                    result in an error message if it is not
                    legal in the current locale.

display-caret(_s_t_a_t_e,_w_h_e_n)
                    This action allows the insert point to
                    be turned on and off.  The _s_t_a_t_e argu-
                    ment specifies the desired state of the
                    insert point.  This value may be any of



                             112211





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


                    the string values accepted for Boolean
                    resources (e.g. oonn, TTrruuee, ooffff, FFaallssee,
                    etc.).  If no arguments are specified,
                    the default value is TTrruuee.  The _w_h_e_n
                    argument specifies, for EEnntteerrNNoottiiffyy or
                    LLeeaavveeNNoottiiffyy events whether or not the
                    focus field in the event is to be exam-
                    ined.  If the second argument is not
                    specified, or specified as something
                    other than aallwwaayyss then if the action is
                    bound to an  EEnntteerrNNoottiiffyy or LLeeaavveeNNoottiiffyy
                    event, the action will be taken only if
                    the focus field is TTrruuee.  An augmented
                    binding that might be useful is:


                    *Text.Translations: #override \
                         <FocusIn>:     display-caret(on) \n\
                         <FocusOut>:    display-caret(off)


focus-in()
focus-out()         These actions do not currently do any-
                    thing.

search(_d_i_r_e_c_t_i_o_n,[_s_t_r_i_n_g])
                    This action activates the search popup.
                    The _d_i_r_e_c_t_i_o_n must be specified as
                    either ffoorrwwaarrdd or bbaacckkwwaarrdd.  The string
                    is optional and is used as an initial
                    value for the _S_e_a_r_c_h _f_o_r: string.  For
                    further explanation of the search widget
                    see the section on TTeexxtt SSeeaarrcchheess.

multiply(_v_a_l_u_e)     The multiply action allows the user to
                    multiply the effects of many of the text
                    actions.  Thus the following action
                    sequence _m_u_l_t_i_p_l_y_(_1_0_) _d_e_l_e_t_e_-_n_e_x_t_-_w_o_r_d_(_)
                    will delete 10 words.  It does not mat-
                    ter whether these actions take place in
                    one event or many events.  Using the
                    default translations the key sequence
                    _C_o_n_t_r_o_l_-_u_, _C_o_n_t_r_o_l_-_d will delete 4 char-
                    acters.  Multiply actions can be
                    chained, thus _m_u_l_t_i_p_l_y_(_5_) _m_u_l_t_i_p_l_y_(_5_) is
                    the same as _m_u_l_t_i_p_l_y_(_2_5_).  If the string
                    rreesseett is passed to the multiply action
                    the effects of all previous multiplies
                    are removed and a beep is sent to the
                    display.

form-paragraph()    This action removes all the Carriage
                    Returns from the current paragraph and
                    reinserts them so that each line is as



                             112222





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


                    long as possible, while still fitting on
                    the current screen.  Lines are broken at
                    word boundaries if at all possible.
                    This action currently works only on Text
                    widgets that use ASCII text.

transpose-characters()
                    This action will swap the position of
                    the character to the left of the insert
                    point with the character to the right of
                    the insert point.  The insert point will
                    then be advanced one character.

no-op([_a_c_t_i_o_n])     The no-op action makes no change to the
                    text widget, and is mainly used to over-
                    ride translations.  This action takes
                    one optional argument.  If this argument
                    is _R_i_n_g_B_e_l_l then a beep is sent to the
                    display.

XawWMProtocols([_w_m___p_r_o_t_o_c_o_l___n_a_m_e])

                    This action is written specifically for
                    the file insertion and the search and
                    replace dialog boxes.  This action is
                    attached to those shells by the Text
                    widget, in order to handle ClientMessage
                    events with the WM_PROTOCOLS atom in the
                    detail field.  This action supports
                    WM_DELETE_WINDOW on the Text widget pop-
                    ups, and may support other window man-
                    ager protocols if necessary in the
                    future.  The popup will be dismissed if
                    the window manager sends a
                    WM_DELETE_WINDOW request and there are
                    no parameters in the action call, which
                    is the default.  The popup will also be
                    dismissed if the parameters include the
                    string ``wm_delete_window,'' and the
                    event is a ClientMessage event request-
                    ing dismissal or is not a ClientMessage
                    event.  This action is not sensitive to
                    the case of the strings passed as param-
                    eters.

reconnect-im()      When the iinntteerrnnaattiioonnaall resource is ttrruuee,
                    input is usually passed to an input
                    method, a separate process, for compos-
                    ing.  Sometimes the connection to this
                    process gets severed; this action will
                    attempt to reconnect it.  Causes for
                    severage include network trouble, and
                    the user explicitly killing one input
                    method and starting a new one.  This



                             112233





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


                    action may also establish first connec-
                    tion when the application is started
                    before the input method.

55..22..77..  TTeexxtt SSeelleeccttiioonnss ffoorr AApppplliiccaattiioonn PPrrooggrraammmmeerrss

The default behavior of the text selection array is
described in the section called TTeexxtt SSeelleeccttiioonnss ffoorr UUsseerrss.
To modify the selections a programmer must construct a XXaaww--
TTeexxttSSeelleeccttTTyyppee array (called the selection array), contain-
ing the selections desired, and pass this as the new value
for the sseelleeccttiioonnTTyyppeess resource.  The selection array may
also be modified using the XXaawwTTeexxttSSeettSSeelleeccttiioonnAArrrraayy func-
tion.  All selection arrays must end with the value XXaawwssee--
lleeccttNNuullll.  The sseelleeccttiioonnTTyyppeess resource has no converter reg-
istered and cannot be modified through the resource manager.

The array contains a list of entries that will be called
when the user attempts to select text in rapid succession
with the _s_e_l_e_c_t_-_s_t_a_r_t action (usually by clicking a pointer
button).  The first entry in the selection array will be
used when the _s_e_l_e_c_t_-_s_t_a_r_t action is initially called.  The
next entry will be used when _s_e_l_e_c_t_-_s_t_a_r_t is called again,
and so on.  If a timeout value (1/10 of a second) is
exceeded, the the next _s_e_l_e_c_t_-_s_t_a_r_t action will begin at the
top of the selection array.  When XXaawwsseelleeccttNNuullll is reached
the array is recycled beginning with the first element.

XXaawwsseelleeccttAAllll   Selects the contents of the entire buffer.
XXaawwssee--         Selects text characters as the pointer
lleeccttCChhaarr       moves over them.
XXaawwsseelleecctt--     Selects the entire line.
LLiinnee
XXaawwsseelleecctt--     Indicates the end of the selection array.
NNuullll
XXaawwsseelleecctt--     Selects the entire paragraph.
PPaarraaggrraapphh
XXaawwsseelleeccttPPoo--   Selects the current pointer position.
ssiittiioonn
XXaawwsseelleecctt--     Selects whole words as the pointer moves
WWoorrdd           onto them.


The default selectType array is:



{XawselectPosition, XawselectWord, XawselectLine, XawselectParagraph, XawselectAll, XawselectNull}



The selection array is not copied by the text widgets.  The
application must allocate space for the array and cannot
deallocate or change it until the text widget is destroyed



                             112244





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


or until a new selection array is set.

55..33..  DDeeffaauulltt TTrraannssllaattiioonn BBiinnddiinnggss

The following translations are defaults built into every
Text widget.  They can be overridden, or replaced by speci-
fying a new value for the Text widget's ttrraannssllaattiioonnss
resource.



     Ctrl<Key>A:         beginning-of-line() \n\
     Ctrl<Key>B:         backward-character() \n\
     Ctrl<Key>D:         delete-next-character() \n\
     Ctrl<Key>E:         end-of-line() \n\
     Ctrl<Key>F:         forward-character() \n\
     Ctrl<Key>G:         multiply(Reset) \n\
     Ctrl<Key>H:         delete-previous-character() \n\
     Ctrl<Key>J:         newline-and-indent() \n\
     Ctrl<Key>K:         kill-to-end-of-line() \n\
     Ctrl<Key>L:         redraw-display() \n\
     Ctrl<Key>M:         newline() \n\
     Ctrl<Key>N:         next-line() \n\
     Ctrl<Key>O:         newline-and-backup() \n\
     Ctrl<Key>P:         previous-line() \n\
     Ctrl<Key>R:         search(backward) \n\
     Ctrl<Key>S:         search(forward) \n\
     Ctrl<Key>T:         transpose-characters() \n\
     Ctrl<Key>U:         multiply(4) \n\
     Ctrl<Key>V:         next-page() \n\
     Ctrl<Key>W:         kill-selection() \n\
     Ctrl<Key>Y:         insert-selection(CUT_BUFFER1) \n\
     Ctrl<Key>Z:         scroll-one-line-up() \n\
     Ctrl<Key>\:         reconnect-im() \n\
     Meta<Key>B:         backward-word() \n\
     Meta<Key>F:         forward-word() \n\
     Meta<Key>I:         insert-file() \n\
     Meta<Key>K:         kill-to-end-of-paragraph() \n\
     Meta<Key>Q:         form-paragraph() \n\
     Meta<Key>V:         previous-page() \n\
     Meta<Key>Y:         insert-selection(PRIMARY, CUT_BUFFER0) \n\
     Meta<Key>Z:         scroll-one-line-down() \n\
     :Meta<Key>d:        delete-next-word() \n\
     :Meta<Key>D:        kill-word() \n\
     :Meta<Key>h:        delete-previous-word() \n\
     :Meta<Key>H:        backward-kill-word() \n\
     :Meta<Key>\<:       beginning-of-file() \n\
     :Meta<Key>\>:       end-of-file() \n\
     :Meta<Key>]:        forward-paragraph() \n\
     :Meta<Key>[:        backward-paragraph() \n\
     ~Shift Meta<Key>Delete:delete-previous-word() \n\
      Shift Meta<Key>Delete:backward-kill-word() \n\
     ~Shift Meta<Key>Backspace:delete-previous-word() \n\
      Shift Meta<Key>Backspace:backward-kill-word() \n\



                             112255





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


     <Key>Right:         forward-character() \n\
     <Key>Left:          backward-character() \n\
     <Key>Down:          next-line() \n\
     <Key>Up:            previous-line() \n\
     <Key>Delete:        delete-previous-character() \n\
     <Key>BackSpace:     delete-previous-character() \n\
     <Key>Linefeed:      newline-and-indent() \n\
     <Key>Return:        newline() \n\
     <Key>:              insert-char() \n\
     <Key>Kanji:         reconnect-im() \n\
     <FocusIn>:          focus-in() \n\
     <FocusOut>:         focus-out() \n\
     <Btn1Down>:         select-start() \n\
     <Btn1Motion>:       extend-adjust() \n\
     <Btn1Up>:           extend-end(PRIMARY, CUT_BUFFER0) \n\
     <Btn2Down>:         insert-selection(PRIMARY, CUT_BUFFER0) \n\
     <Btn3Down>:         extend-start() \n\
     <Btn3Motion>:       extend-adjust() \n\
     <Btn3Up>:           extend-end(PRIMARY, CUT_BUFFER0) \n


55..44..  TTeexxtt FFuunnccttiioonnss

The following functions are provided as convenience routines
for use with the Text widget.  Although many of these
actions can be performed by modifying resources, these
interfaces are frequently more efficient.

These data structures are defined in the Text widget's pub-
lic header file, <X11/Xaw/Text.h>.

typedef long XawTextPosition;


Character positions in the Text widget begin at 0 and end at
n, where n is the number of characters in the Text source
widget.


typedef struct {
     int _f_i_r_s_t_P_o_s;
     int _l_e_n_g_t_h;
     char *_p_t_r;
     unsigned long _f_o_r_m_a_t;
} XawTextBlock, *XawTextBlockPtr;



_f_i_r_s_t_P_o_s  The first position, or index, to use within the
          _p_t_r field.  The value is commonly zero.

_l_e_n_g_t_h    The number of characters to be used from the _p_t_r
          field.  The number of characters used is commonly
          the number of characters in _p_t_r, and must not be



                             112266





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


          greater than the length of the string in _p_t_r.

_p_t_r       Contains the string to be referenced by the Text
          widget.

_f_o_r_m_a_t    This flag indicates whether the data pointed to by
          ppttrr is char or wchar_t.  When the associated wid-
          get has iinntteerrnnaattiioonnaall set to ffaallssee this field must
          be XawFmt8Bit.  When the associated widget has
          iinntteerrnnaattiioonnaall set to ttrruuee this field must be
          either XawFmt8Bit or XawFmtWide.

Note: Previous versions of Xaw used _F_M_T_8_B_I_T, which has been
retained for backwards compatibility. FFMMTT88BBIITT is deprecated
and will eventually be removed from the implementation.

55..44..11..  SSeelleeccttiinngg TTeexxtt

To select a piece of text, use _X_a_w_T_e_x_t_S_e_t_S_e_l_e_c_t_i_o_n:

void XawTextSetSelection(_w, _l_e_f_t, _r_i_g_h_t)
     Widget _w;
     XawTextPosition _l_e_f_t, _r_i_g_h_t;


_w         Specifies the Text widget.

_l_e_f_t      Specifies the character position at which the
          selection begins.

_r_i_g_h_t     Specifies the character position at which the
          selection ends.

See section 5.4 for a description of XXaawwTTeexxttPPoossiittiioonn.  If
redisplay is enabled, this function highlights the text and
makes it the PPRRIIMMAARRYY selection.  This function does not have
any effect on CCUUTT__BBUUFFFFEERR00.


55..44..22..  UUnnhhiigghhlliigghhttiinngg TTeexxtt

To unhighlight previously highlighted text in a widget, use
XXaawwTTeexxttUUnnsseettSSeelleeccttiioonn:

void XawTextUnsetSelection(_w)
     Widget _w;


_w         Specifies the Text widget.

55..44..33..  GGeettttiinngg CCuurrrreenntt TTeexxtt SSeelleeccttiioonn

To retrieve the text that has been selected by this text
widget use XXaawwTTeexxttGGeettSSeelleeccttiioonnPPooss:



                             112277





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


void XawTextGetSelectionPos(_w, _b_e_g_i_n___r_e_t_u_r_n, _e_n_d___r_e_t_u_r_n)
     Widget _w;
     XawTextPosition *_b_e_g_i_n___r_e_t_u_r_n, *_e_n_d___r_e_t_u_r_n;


_w         Specifies the Text widget.

_b_e_g_i_n___r_e_t_u_r_n
          Returns the beginning of the text selection.

_e_n_d___r_e_t_u_r_n
          Returns the end of the text selection.

See section 5.4 for a description of XXaawwTTeexxttPPoossiittiioonn.  If
the returned values are equal, no text is currently
selected.

55..44..44..  RReeppllaacciinngg TTeexxtt

To modify the text in an editable Text widget use XXaawwTTeexxttRRee--
ppllaaccee:

int XawTextReplace(_w, _s_t_a_r_t, _e_n_d, _t_e_x_t)
     Widget _w;
     XawTextPosition _s_t_a_r_t, _e_n_d;
     XawTextBlock *_t_e_x_t;


_w         Specifies the Text widget.

_s_t_a_r_t     Specifies the starting character position of the
          text replacement.

_e_n_d       Specifies the ending character position of the
          text replacement.

_t_e_x_t      Specifies the text to be inserted into the file.

This function will not be able to replace text in read-only
text widgets.  It will also only be able to append text to
an append-only text widget.

See section 5.4 for a description of XXaawwTTeexxttPPoossiittiioonn and
XXaawwTTeexxttBBlloocckk.

This function may return the following values:

XXaawwEEddiittDDoonnee The text replacement was successful.

XXaawwPPoossiittiioonnEErrrroorr
            The edit mode is XXaawwtteexxttAAppppeenndd and _s_t_a_r_t is not
            the position of the last character of the
            source.




                             112288





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


XXaawwEEddiittEErrrroorr
            Either the Source was read-only or the range to
            be deleted is larger than the length of the
            Source.


The XXaawwTTeexxttRReeppllaaccee arguments _s_t_a_r_t and _e_n_d represent the
text source character positions for the existing text that
is to be replaced by the text in the text block.  The char-
acters from _s_t_a_r_t up to but not including _e_n_d are deleted,
and the characters specified on the text block are inserted
in their place.  If _s_t_a_r_t and _e_n_d are equal, no text is
deleted and the new text is inserted after _s_t_a_r_t.

55..44..55..  SSeeaarrcchhiinngg ffoorr TTeexxtt

To search for a string in the Text widget, use XXaaww--
TTeexxttSSeeaarrcchh:

XawTextPosition XawTextSearch(_w, _d_i_r, _t_e_x_t)
      Widget _w;
      XawTextScanDirection _d_i_r;
      XawTextBlock * _t_e_x_t;


_w         Specifies the Text widget.

_d_i_r       Specifies the direction to search in.  Legal val-
          ues are XXaawwssddLLeefftt and XXaawwssddRRiigghhtt.

_t_e_x_t      Specifies a text block structure that contains the
          text to search for.

See section 5.4 for a description of XXaawwTTeexxttPPoossiittiioonn and
XXaawwTTeexxttBBlloocckk.  The XXaawwTTeexxttSSeeaarrcchh function will begin at the
insertion point and search in the direction specified for a
string that matches the one passed in _t_e_x_t.  If the string
is found the location of the first character in the string
is returned.  If the string could not be found then the
value XXaawwTTeexxttSSeeaarrcchhEErrrroorr is returned.

55..44..66..  RReeddiissppllaayyiinngg TTeexxtt

To redisplay a range of characters, use XXaawwTTeexxttIInnvvaalliiddaattee:

void XawTextInvalidate(_w, _f_r_o_m, _t_o)
      Widget _w;
      XawTextPosition _f_r_o_m, _t_o;


_w         Specifies the Text widget.

_f_r_o_m      Specifies the start of the text to redisplay.




                             112299





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


_t_o        Specifies the end of the text to redisplay.

See section 5.4 for a description of XXaawwTTeexxttPPoossiittiioonn.  The
XXaawwTTeexxttIInnvvaalliiddaattee function causes the specified range of
characters to be redisplayed immediately if redisplay is
enabled or the next time that redisplay is enabled.


To enable redisplay, use XXaawwTTeexxttEEnnaabblleeRReeddiissppllaayy:

void XawTextEnableRedisplay(_w)
      Widget _w;


_w         Specifies the Text widget.

The XXaawwTTeexxttEEnnaabblleeRReeddiissppllaayy function flushes any changes due
to batched updates when XXaawwTTeexxttDDiissaabblleeRReeddiissppllaayy was called
and allows future changes to be reflected immediately.


To disable redisplay while making several changes, use XXaaww--
TTeexxttDDiissaabblleeRReeddiissppllaayy.

void XawTextDisableRedisplay(_w)
       Widget _w;


_w         Specifies the Text widget.

The XXaawwTTeexxttDDiissaabblleeRReeddiissppllaayy function causes all changes to
be batched until either XXaawwTTeexxttDDiissppllaayy or XXaawwTTeexxttEEnnaabblleeRRee--
ddiissppllaayy is called.


To display batched updates, use XXaawwTTeexxttDDiissppllaayy:

void XawTextDisplay(_w)
     Widget _w;


_w         Specifies the Text widget.

The XXaawwTTeexxttDDiissppllaayy function forces any accumulated updates
to be displayed.

55..44..77..  RReessoouurrcceess CCoonnvveenniieennccee RRoouuttiinneess

To obtain the character position of the left-most character
on the first line displayed in the widget (the value of the
ddiissppllaayyPPoossiittiioonn resource), use XXaawwTTeexxttTTooppPPoossiittiioonn.






                             113300





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


XawTextPosition XawTextTopPosition(_w)
      Widget _w;


_w         Specifies the Text widget.


To assign a new selection array to a text widget use XXaaww--
TTeexxttSSeettSSeelleeccttiioonnAArrrraayy:

void XawTextSetSelectionArray(_w, _s_a_r_r_a_y)
      Widget _w;
      XawTextSelectType * _s_a_r_r_a_y;


_w         Specifies the Text widget.

_s_a_r_r_a_y    Specifies a selection array as defined in the sec-
          tion called TTeexxtt SSeelleeccttiioonnss ffoorr AApppplliiccaattiioonn PPrroo--
          ggrraammmmeerrss.

Calling this function is equivalent to setting the value of
the sseelleeccttiioonnTTyyppeess resource.


To move the insertion point to the specified source posi-
tion, use XXaawwTTeexxttSSeettIInnsseerrttiioonnPPooiinntt:

void XawTextSetInsertionPoint(_w, _p_o_s_i_t_i_o_n)
      Widget _w;
      XawTextPosition _p_o_s_i_t_i_o_n;


_w         Specifies the Text widget.

_p_o_s_i_t_i_o_n  Specifies the new position for the insertion
          point.

See section 5.4 for a description of XXaawwTTeexxttPPoossiittiioonn.  The
text will be scrolled vertically if necessary to make the
line containing the insertion point visible.  Calling this
function is equivalent to setting the iinnsseerrttPPoossiittiioonn
resource.


To obtain the current position of the insertion point, use
XXaawwTTeexxttGGeettIInnsseerrttiioonnPPooiinntt:

XawTextPosition XawTextGetInsertionPoint(_w)
      Widget _w;


_w         Specifies the Text widget.




                             113311





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


See section 5.4 for a description of XXaawwTTeexxttPPoossiittiioonn.  The
result is equivalent to retrieving the value of the iinnsseerrtt--
PPoossiittiioonn resource.


To replace the text source in the specified widget, use XXaaww--
TTeexxttSSeettSSoouurrccee:

void XawTextSetSource(_w, _s_o_u_r_c_e, _p_o_s_i_t_i_o_n)
      Widget _w;
      Widget _s_o_u_r_c_e;
      XawTextPosition _p_o_s_i_t_i_o_n;


_w         Specifies the Text widget.

_s_o_u_r_c_e    Specifies the text source object.

_p_o_s_i_t_i_o_n  Specifies character position that will become the
          upper left hand corner of the displayed text.
          This is usually set to zero.

See section 5.4 for a description of XXaawwTTeexxttPPoossiittiioonn.  A
display update will be performed if redisplay is enabled.


To obtain the current text source for the specified widget,
use XXaawwTTeexxttGGeettSSoouurrccee:

Widget XawTextGetSource(_w)
      Widget _w;


_w         Specifies the Text widget.

This function returns the text source that this Text widget
is currently using.


To enable and disable the insertion point, use XXaawwTTeexxttDDiiss--
ppllaayyCCaarreett:

void XawTextDisplayCaret(_w, _v_i_s_i_b_l_e)
      Widget _w;
      Boolean _v_i_s_i_b_l_e;


_w         Specifies the Text widget.

_v_i_s_i_b_l_e   Specifies whether or not the caret should be dis-
          played.

If _v_i_s_i_b_l_e is FFaallssee the insertion point will be disabled.
The marker is re-enabled either by setting _v_i_s_i_b_l_e to TTrruuee,



                             113322





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


by calling XXttSSeettVVaalluueess, or by executing the _d_i_s_p_l_a_y_-_c_a_r_e_t
action routine.

55..55..  AAsscciiii TTeexxtt WWiiddggeett



Application Header file<X11/Xaw/AsciiText.h>
ClassHeader file    <X11/Xaw/AsciiTextP.h>
Class               asciiTextWidgetClass
Class Name          Text
Superclass          Text
Sink Name           textSink
Source Name         textSource



For the ease of internationalization, the AsciiText widget
class name has not been changed, although it is actually
able to support non-ASCII locales.  The AsciiText widget is
really a collection of smaller parts.  It includes the Text
widget itself, a ``Source'' (which supports memory manage-
ment), and a ``Sink'' (which handles the display).  There
are currently two supported sources, the AsciiSrc and Multi-
Src, and two supported sinks, the AsciiSink and MultiSink.
Some of the resources listed below are not actually
resources of the AsciiText, but belong to the associated
source or sink.  This is is noted in the explanation of each
resource where it applies.  When specifying these resources
in a resource file it is necessary to use _*_A_s_c_i_-
_i_T_e_x_t_*_r_e_s_o_u_r_c_e___n_a_m_e instead of _*_A_s_c_i_i_T_e_x_t_._r_e_s_o_u_r_c_e___n_a_m_e,
since they actually belong to the children of the AsciiText
widget, and not the AsciiText widget itself.  However, these
resources may be set directly on the AsciiText widget at
widget creation time, or via XXttSSeettVVaalluueess.

55..55..11..  RReessoouurrcceess

When creating an AsciiText widget instance, the following
resources are retrieved from the argument list or from the
resource database:


------------------------------------------------------------------------------------
NNaammee                  CCllaassss            TTyyppee              NNootteessDDeeffaauulltt VVaalluuee
------------------------------------------------------------------------------------
accelerators          Accelerators     AcceleratorTable       NULL
ancestorSensitive     AncestorSensitiveBoolean           D    True
autoFill              AutoFill         Boolean                False
background            Background       Pixel                  XtDefaultBackground
backgroundPixmap      Pixmap           Pixmap                 XtUnspecifiedPixmap
borderColor           BorderColor      Pixel                  XtDefaultForeground
borderPixmap          Pixmap           Pixmap                 XtUnspecifiedPixmap




                             113333





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


------------------------------------------------------------------------------------
NNaammee                  CCllaassss            TTyyppee              NNootteessDDeeffaauulltt VVaalluuee
------------------------------------------------------------------------------------
borderWidth           BorderWidth      Dimension              1
bottomMargin          Margin           Position               2
callback              Callback         XtCallbackList         NULL
colormap              Colormap         Colormap               Parent's Colormap
cursor                Cursor           Cursor                 XC_xterm
cursorName            Cursor           String                 NULL
dataCompression       DataCompression  Boolean                True
depth                 Depth            int               C    Parent's Depth
destroyCallback       Callback         XtCallbackList         NULL
displayCaret          Output           Boolean                True
displayNonprinting    Output           Boolean                True
displayPosition       TextPosition     XawTextPosition        0
echo                  Output           Boolean                True
editType              EditType         XawTextEditType        XawtextRead
font                  Font             XFontStruct*           XtDefaultFont
fontSet               FontSet          XFontSet               XtDefaultFontSet
foreground            Foreground       Pixel                  XtDefaultForeground
height                Height           Dimension         A    Font height + margins
insensitiveBorder     Insensitive      Pixmap                 GreyPixmap
insertPosition        TextPosition     int                    0
international         International    Boolean           C    False
leftMargin            Margin           Dimension              2
length                Length           int               A    length of ssttrriinngg
mappedWhenManaged     MappedWhenManagedBoolean                True
pieceSize             PieceSize        XawTextPosition        BUFSIZ
pointerColor          Foreground       Pixel                  XtDefaultForeground
pointerColorBackgroundBackground       Pixel                  XtDefaultBackground
resize                Resize           XawTextResizeMode      XawtextResizeNever
rightMargin           Margin           Position               2
screen                Screen           Screen            R    Parent's Screen
scrollHorizontal      Scroll           XawTextScrollMode      XawtextScrollNever
scrollVertical        Scroll           XawTextScrollMode      XawtextScrollNever
selectTypes           SelectTypes      XawTextSelectType*     See above
sensitive             Sensitive        Boolean                True
string                String           String                 NULL
textSink              TextSink         Widget                 An AsciiSink
textSource            TextSource       Widget                 An AsciiSrc
topMargin             Margin           Position               2
translations          Translations     TranslationTable       See above
type                  Type             XawAsciiType           XawAsciiString
useStringInPlace      UseStringInPlace Boolean                False
width                 Width            Dimension              100
wrap                  Wrap             WrapMode               XawtextWrapNever
x                     Position         Position               0
y                     Position         Position               0
------------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X



                             113344





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

autoFill       If this resource is TTrruuee the text widget will
               automatically break a line when the user
               attempts to type into the right margin.  The
               attribute has no effect on files or text
               inserted into the text widget.  It only
               checks to see if the action should be taken
               when a user enters a new character via the
               _i_n_s_e_r_t_-_c_h_a_r_a_c_t_e_r action.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

bottomMargin
leftMargin
rightMargin
topMargin      The amount of space, in pixels, between the
               edge of the window and the corresponding edge
               of the text within the window.  If there is a
               scrollbar active on this edge, then this is
               the space between the text and the scrollbar.

callback       The callbacks registered on this resource
               will be called every time the text buffer
               changes, after the text has been updated.



                             113355





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               This is a resource of the associated source.

colormap       The colormap that this widget will use.

cursor         The image that will be displayed as the
               pointer cursor whenever it is in this widget.
               The use of this resource is deprecated in
               favor of ccuurrssoorrNNaammee.

cursorName     The name of the symbol to use to represent
               the pointer cursor.  This resource will over-
               ride the ccuurrssoorr resource if both are speci-
               fied. (See 2.4.1)

dataCompression
               The AsciiSrc uses an algorithm that may cause
               the text buffer to grow to about twice the
               size of the actual text over time, as the
               text is edited.  On systems where CPU cycles
               are cheaper than memory, it is helpful to
               spend some extra time to compress this buffer
               back to its minimum size.  If this resource
               is TTrruuee, the AsciiSrc will compress its data
               to the minimum size required every time the
               text string is saved, or the value of the
               string is queried.  This is a resource of the
               associated source.

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

displayCaret   Whether or not to display the text insert
               point.

displayNonprinting
               If this resource is TTrruuee, the Text widget
               will display all non-printable characters as
               the string _^_@.  If FFaallssee, the Text widget
               will just leave a blank space where a non-
               printable character exists in the text
               buffer.  This is a resource of the associated
               sink.

displayPosition
               The position in the text buffer of the char-
               acter that is currently displayed in the
               upper left hand corner of the text display.

editType       This is the type of editing that will be
               allowed in this text widget.  Legal values
               are XXaawwtteexxttRReeaadd, XXaawwtteexxttEEddiitt, and



                             113366





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               XXaawwtteexxttAAppppeenndd.  A converter is registered for
               this resource that will convert the following
               strings: rreeaadd,, eeddiitt,, and aappppeenndd.  This is a
               resource of the associated source.

echo           Whether or not to echo characters to the
               screen.  The buffer can still be edited, but
               nothing is displayed.  This mode can be use-
               ful for entering passwords and other sensi-
               tive information.  This is a resource of the
               associated sink.

font           The text font to use when displaying the
               ssttrriinngg, when the iinntteerrnnaattiioonnaall resource is
               ffaallssee.  This is a resource of the associated
               sink.

font           The text font set to use when displaying the
               ssttrriinngg, when the iinntteerrnnaattiioonnaall resource is
               ttrruuee.  This is a resource of the associated
               sink.

foreground     A pixel value which indexes the Text widget's
               colormap to derive the foreground color used
               by the text sink.  This is a resource of the
               associated sink.

height
width          The height and width of this widget in pix-
               els.

insensitiveBorder
               This pixmap will be tiled into the widget's
               border if the widget becomes insensitive.

insertPosition This is the location of the insert point.  It
               is expressed in characters from the beginning
               of the file.  The cursor will always be
               forced to be on the screen.  This resource
               may therefore be used to scroll the text dis-
               play to a certain character position.

length         If the uusseeSSttrriinnggIInnPPllaaccee resource is FFaallssee
               this attribute has no effect.  If that
               resource is TTrruuee, however, then the lleennggtthh
               resource specifies the length of the buffer
               passed to the text widget in the ssttrriinngg
               resource.  This is a resource of the associ-
               ated source.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.



                             113377





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


pointerColor   A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               pointer symbol specified by the ccuurrssoorrNNaammee
               resource.

pointerColorBackground
                 A pixel value which indexes the widget's
                 colormap to derive the background color of
                 the pointer symbol specified by the ccuurrssoorr--
                 NNaammee resource.

pieceSize      This is the size of the internal chunks into
               which the text buffer is broken down for mem-
               ory management.  The larger this value the
               less segmented your memory will be, but the
               slower your editing will be.  The text wid-
               gets will always allocate a chunk of memory
               this size to stuff the ssttrriinngg into, so when
               using small strings, having this buffer large
               can waste memory.  This resource has no
               effect if uusseeSSttrriinnggIInnPPllaaccee is TTrruuee.  This is
               a resource of the associated source.

resize         Controls whether or not the Text widget
               attempts to resize itself when it is no
               longer able to display the full text buffer
               in the associated window.  Any attempt by the
               Text widget to resize itself is always sub-
               ject to the constraints imposed by its par-
               ent.  The values XXaawwtteexxttRReessiizzeeNNeevveerr, XXaawwtteexx--
               ttRReessiizzeeWWiiddtthh, XXaawwtteexxttRReessiizzeeHHeeiigghhtt, and XXaaww--
               tteexxttRReessiizzeeBBootthh are all acceptable for this
               resource.  A converter is registered for this
               resource that will convert the following
               strings: nneevveerr,, hheeiigghhtt,, wwiiddtthh,, and bbootthh.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

scrollHorizontal
scrollVertical These resources control the placement of
               scrollbars on the left and bottom edge of the
               text widget.  These resources accept the val-
               ues XXaawwtteexxttSSccrroollllAAllwwaayyss, XXaawwtteexxttSSccrroollllWWhheenn--
               NNeeeeddeedd, and XXaawwtteexxttSSccrroollllNNeevveerr.  A converter
               is registered for this resource that will
               convert the following strings: aallwwaayyss,, nneevveerr,,
               and wwhheennNNeeeeddeedd.  If XXaawwtteexxttSSccrroollllWWhheennNNeeeeddeedd
               is specified, the appropriate scrollbar will
               only appear when there is text in the buffer
               that is not able to fit within the bounds of
               the current window.  The scrollbar will dis-
               appear when the text once again fits within
               the window.



                             113388





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


selectTypes    Specifies the selection type array that is
               used when multi-click is activated (see TTeexxtt
               SSeelleeccttiioonnss ffoorr AApppplliiccaattiioonn PPrrooggrraammmmeerrss for
               details).  This resource is used in place,
               and must not be freed until the widget is
               destroyed.  There is no type converter regis-
               tered for this resource, so it may not be set
               from the resource manager.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

string         If ttyyppee is XXaawwAAsscciiiiSSttrriinngg then this string
               contains the buffer to be displayed in the
               widget.  If ttyyppee is XXaawwAAsscciiiiFFiillee then the
               string contains the name of the file to be
               displayed.  This string is normally copied by
               the text widget into internal memory, but may
               be used in place by setting the uusseeSSttrriinnggIInn--
               PPllaaccee resource.  As of X11R4 this is a set-
               table resource.  This is a resource of the
               associated source.  When the ssttrriinngg resource
               is queried, using XXttGGeettVVaalluueess, and uusseeSSttrriinngg--
               IInnPPllaaccee is false, the value returned is valid
               until the next time the ssttrriinngg resource is
               queried, or until the application writer
               calls XXaawwAAsscciiiiSSoouurrcceeFFrreeeeSSttrriinngg.  If uusseeSS--
               ttrriinnggIInnPPllaaccee is true, a pointer to the actual
               string is returned.  See also section 5.6.

textSink
textSource     These are the TextSink or TextSource objects
               used by this widget.  When iinntteerrnnaattiioonnaall is
               set to ttrruuee the AsciiText widget initializes
               these resources to point to an MultiSink and
               MultiSrc respectively.  When iinntteerrnnaattiioonnaall is
               set to ffaallssee the AsciiText widget initializes
               these resources to point to an AsciiSink and
               AsciiSrc respectively.

translations   The event bindings associated with this wid-
               get.

type           This resource may be either XXaawwAAsscciiiiSSttrriinngg or
               XXaawwAAsscciiiiFFiillee.  The value of this resource
               determines whether the ssttrriinngg resource con-
               tains the name of a file to be opened or a
               buffer to be displayed by the text widget.  A
               converter has been registered for this
               resource and accepts the values ssttrriinngg and
               ffiillee.  This is a resource of the associated
               source.



                             113399





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


useStringInPlace
               Setting this resource to TTrruuee will disable
               the memory management provided by the Text
               widget, updating the ssttrriinngg resource in
               place.  Using the string in place can be much
               more efficient for text widgets that display
               static data, or where the programmer wishes
               to impose strict constraints on the contents
               of the ssttrriinngg.  When using the string in
               place be sure that: the length of the string
               is specified by setting the lleennggtthh resource,
               the ttyyppee of the Text widget is XXaawwAAssccii--
               iiSSttrriinngg, and that the ssttrriinngg exists for the
               lifetime of the text widget, or until it has
               been reset.  _N_o_t_e_: _S_i_n_c_e _t_h_e _M_u_l_t_i_S_r_c _a_n_d
               _A_s_c_i_i_S_r_c _h_a_v_e _d_i_f_f_e_r_e_n_t _d_a_t_a _f_o_r_m_a_t_s_, _u_s_e _o_f
               _t_h_i_s _r_e_s_o_u_r_c_e _f_o_r_c_e_s _a_p_p_l_i_c_a_t_i_o_n _c_o_d_e _t_o _b_e
               _c_o_g_n_i_s_a_n_t _a_s _t_o _w_h_i_c_h _o_f _t_h_e _t_w_o _i_s _b_e_i_n_g
               _u_s_e_d_.  _A_p_p_l_i_c_a_t_i_o_n _p_r_o_g_r_a_m_m_i_n_g _i_s _s_i_m_p_l_i_f_i_e_d
               _w_h_e_n _u_s_e _o_f _t_h_i_s _r_e_s_o_u_r_c_e _i_s _a_v_o_i_d_e_d_.  This
               is a resource of the associated source.

wrap           When the text in any one line is wider than
               the window there are several possible
               actions.  This resource allows the user to
               decide what will happen.  The accepted values
               for this resource are XXaawwtteexxttWWrraappNNeevveerr, XXaaww--
               tteexxttWWrraappLLiinnee, and XXaawwtteexxttWWrraappWWoorrdd.  With XXaaww--
               tteexxttWWrraappLLiinnee all text that is beyond the
               right edge of the window will be displayed on
               the next line.  With XXaawwtteexxttWWrraappWWoorrdd the same
               action occurs but the text is broken at a
               word boundary if possible.  If no wrapping is
               enabled then the text will extend off the
               edge of the window, and a small rectangle
               will be painted in the right margin to alert
               the user that this line is too long.  A con-
               verter is registered for this resource that
               will convert the following strings: nneevveerr,,
               wwoorrdd,, and lliinnee.

x
y              The location of the upper left outside corner
               of this widget in its parent.



55..66..  AAsscciiii SSoouurrccee OObbjjeecctt aanndd MMuullttii SSoouurrccee OObbjjeecctt



Application Header file<X11/Xaw/AsciiSrc.h> or <X11/Xaw/MultiSrc.h>
Class Header file   <X11/Xaw/AsciiSrcP.h> or  <X11/Xaw/MultiSrcP.h>
Class               asciiSrcObjectClass or multiSrcObjectClass



                             114400





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


Class Name          AsciiSrc or MultiSrc
Superclass          TextSource


The AsciiSrc or MultiSrc object is used by a text widget to
read the text from a file or string in memory.  Depending on
its iinntteerrnnaattiioonnaall resource, an AsciiText widget will create
one or the other of these when the AsciiText itself is cre-
ated.  Both types are nearly identical; the following dis-
cussion applies to both, with MultiSrc differences noted
only as they occur.

The AsciiSrc understands all Latin1 characters plus Tab and
Carriage Return.  _T_h_e _M_u_l_t_i_S_r_c _u_n_d_e_r_s_t_a_n_d_s _a_n_y _s_e_t _o_f _c_h_a_r_-
_a_c_t_e_r _s_e_t_s _t_h_a_t _t_h_e _u_n_d_e_r_l_y_i_n_g _X _i_m_p_l_e_m_e_n_t_a_t_i_o_n_'_s _i_n_t_e_r_n_a_-
_t_i_o_n_a_l_i_z_a_t_i_o_n _h_a_n_d_l_e_s_.

The AsciiSrc can be either of two types: XXaawwAAsscciiiiFFiillee or
XXaawwAAsscciiiiSSttrriinngg.

AsciiSrc objects of type XXaawwAAsscciiiiFFiillee read the text from a
file and store it into an internal buffer.  This buffer may
then be modified, provided the text widget is in the correct
edit mode, just as if it were a source of type XXaawwAAssccii--
iiSSttrriinngg.  Unlike R3 and earlier versions of the AsciiSrc, it
is now possible to specify an editable disk source.  The
file is not updated, however, until a call to XXaawwAAsscciiiiSSaavvee
is made.  When the source is in this mode the uusseeSSttrriinnggIInn--
PPllaaccee resource is ignored.

AsciiSrc objects of type XXaawwAAsscciiiiSSttrriinngg have the text buffer
implemented as a string.  _M_u_l_t_i_S_r_c _o_b_j_e_c_t_s _o_f _t_y_p_e XXaawwAAssccii--
iiSSttrriinngg _h_a_v_e _t_h_e _t_e_x_t _b_u_f_f_e_r _i_m_p_l_e_m_e_n_t_e_d _a_s _a _w_i_d_e _c_h_a_r_a_c_t_e_r
_s_t_r_i_n_g_.  TThhee ssttrriinngg oowwnneerr iiss rreessppoonnssiibbllee ffoorr aallllooccaattiinngg aanndd
mmaannaaggiinngg ssttoorraaggee ffoorr tthhee ssttrriinngg..

In the default case for AsciiSrc objects of type XXaawwAAssccii--
iiSSttrriinngg, the resource uusseeSSttrriinnggIInnPPllaaccee is false, and the
widget owns the string.  The initial value of the string
resource, and any update made by the application programmer
to the string resource with XXttSSeettVVaalluueess, is copied into mem-
ory private to the widget, and managed internally by the
widget.  The application writer does not need to worry about
running out of buffer space (subject to the total memory
available to the application).  The performance does not
decay linearly as the buffer grows large, as is necessarily
the case when the text buffer is used in place.   The appli-
cation writer must use XXttGGeettVVaalluueess to determine the contents
of the text buffer, which will return a copy of the widget's
text buffer as it existed at the time of the XXttGGeettVVaalluueess
call.   This copy is not affected by subsequent updates to
the text buffer, i.e., it is not updated as the user types
input into the text buffer.  This copy is freed upon the
next call to XtGetValues to retrieve the string resource;



                             114411





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


however, to conserve memory, there is a convenience routine,
XXaawwAAsscciiiiSSoouurrcceeFFrreeeeSSttrriinngg, allowing the application program-
mer to direct the widget to free the copy.

When the resource uusseeSSttrriinnggIInnPPllaaccee is true and the AsciiSrc
object is of type XXaawwAAsscciiiiSSttrriinngg, the application is the
string owner.  The widget will take the value of the string
resource as its own text buffer, and the lleennggtthh resource
indicates the buffer size.   In this case the buffer con-
tents change as the user types at the widget; it is not nec-
essary to call XXttGGeettVVaalluueess on the string resource to deter-
mine the contents of the buffer--it will simply return the
address of the application's implementation of the text
buffer.

55..66..11..  RReessoouurrcceess

When creating an AsciiSrc object instance, the following
resources are retrieved from the argument list or from the
resource database:


------------------------------------------------------------------------------------
NNaammee               CCllaassss              TTyyppee             NNootteess   DDeeffaauulltt VVaalluuee
------------------------------------------------------------------------------------
callback           Callback           XtCallbackList           NULL
dataCompression    DataCompression    Boolean                  True
destroyCallback    Callback           Callback                 NULL
editType           EditType           EditMode                 XawtextRead
length             Length             Int              A       length of ssttrriinngg
pieceSize          PieceSize          Int                      BUFSIZ
string             String             String                   NULL
type               Type               AsciiType                XawAsciiString
useStringInPlace   UseStringInPlace   Boolean                  False
------------------------------------------------------------------------------------


ccaallllbbaacckk       The callbacks registered on this resource
               will be called every time the text buffer
               changes, after the text has been updated.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

ddaattaaCCoommpprreessssiioonn
               The AsciiSrc uses an algorithm that may cause
               the text buffer to grow to about twice the
               size of the actual text over time, as the
               text is edited.  On systems where CPU cycles
               are cheaper than memory, it is helpful to
               spend some extra time to compress this buffer
               back to its minimum size.  If this resource
               is TTrruuee, the AsciiSrc will compress its data



                             114422





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               to the minimum size required every time the
               text string is saved, or the value of the
               string is queried.

editType       This is the type of editing that will be
               allowed in this text widget.  Legal values
               are XXaawwtteexxttRReeaadd, XXaawwtteexxttEEddiitt, and XXaawwtteexxttAApp--
               ppeenndd.  A converter is registered for this
               resource that will convert the following
               strings: rreeaadd,, eeddiitt,, and aappppeenndd.

lleennggtthh         If the uusseeSSttrriinnggIInnPPllaaccee resource is FFaallssee
               this attribute has no effect.  If that
               resource is TTrruuee, however, then the lleennggtthh
               resource specifies the length of the buffer
               passed to the text widget in the ssttrriinngg
               resource.

ppiieecceeSSiizzee      This is the size of the internal chunks into
               which the text buffer is broken down for mem-
               ory management.  The larger this value the
               less segmented your memory will be, but the
               slower your editing will be.  The text wid-
               gets will always allocate a chunk of memory
               this size to stuff the ssttrriinngg into, so when
               using small strings, having this buffer large
               can waste memory.  This resource has no
               effect if uusseeSSttrriinnggIInnPPllaaccee is TTrruuee.

ssttrriinngg         If ttyyppee is XXaawwAAsscciiiiSSttrriinngg then this string
               contains the buffer to be displayed in the
               widget.  If ttyyppee is XXaawwAAsscciiiiFFiillee then the
               string contains the name of the file to be
               displayed.  This string is normally copied by
               the text widget into internal memory, but may
               be used in place by setting the uusseeSSttrriinnggIInn--
               PPllaaccee resource.  As of X11R4 this is a set-
               table resource.  When the ssttrriinngg resource is
               queried, using XXttGGeettVVaalluueess, and uusseeSSttrriinnggIInn--
               PPllaaccee is false, the value returned is valid
               until the next time the ssttrriinngg resource is
               queried, or until the application writer
               calls XXaawwAAsscciiiiSSoouurrcceeFFrreeeeSSttrriinngg.  If uusseeSS--
               ttrriinnggIInnPPllaaccee is true, a pointer to the actual
               string is returned.  See also section 5.6.

ttyyppee           This resource may be either XXaawwAAsscciiiiSSttrriinngg or
               XXaawwAAsscciiiiFFiillee.  The value of this resource
               determines whether the ssttrriinngg resource con-
               tains the name of a file to be opened or a
               buffer to be displayed by the text widget.  A
               converter has been registered for this
               resource and accepts the values ssttrriinngg and
               ffiillee.



                             114433





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


uusseeSSttrriinnggIInnPPllaaccee
               Setting this resource to TTrruuee will disable
               the memory management provided by the Text
               widget, updating the ssttrriinngg resource in
               place.  Using the string in place can be much
               more efficient for text widgets that display
               static data, or where the programmer wishes
               to impose strict constraints on the contents
               of the ssttrriinngg.  When using the string in
               place be sure that: the length of the string
               is specified by setting the lleennggtthh resource,
               the ttyyppee of the Text widget is XXaawwAAssccii--
               iiSSttrriinngg, and that the ssttrriinngg exists for the
               lifetime of the text widget, or until it has
               been reset.  _N_o_t_e_: _S_i_n_c_e _t_h_e _M_u_l_t_i_S_r_c _a_n_d
               _A_s_c_i_i_S_r_c _h_a_v_e _d_i_f_f_e_r_e_n_t _d_a_t_a _f_o_r_m_a_t_s_, _u_s_e _o_f
               _t_h_i_s _r_e_s_o_u_r_c_e _f_o_r_c_e_s _a_p_p_l_i_c_a_t_i_o_n _c_o_d_e _t_o _b_e
               _c_o_g_n_i_s_a_n_t _a_s _t_o _w_h_i_c_h _o_f _t_h_e _t_w_o _i_s _b_e_i_n_g
               _u_s_e_d_.  _A_p_p_l_i_c_a_t_i_o_n _p_r_o_g_r_a_m_m_i_n_g _i_s _s_i_m_p_l_i_f_i_e_d
               _w_h_e_n _u_s_e _o_f _t_h_i_s _r_e_s_o_u_r_c_e _i_s _a_v_o_i_d_e_d_.

55..66..22..  CCoonnvveenniieennccee RRoouuttiinneess

The AsciiSrc has a few convenience routines that allow the
application programmer quicker or easier access to some of
the commonly used functionality of the AsciiSrc.

55..66..22..11..  CCoonnsseerrvviinngg MMeemmoorryy

When the AsciiSrc widget is not in uusseeSSttrriinnggIInnPPllaaccee mode
space must be allocated whenever the file is saved, or the
string is requested with a call to XXttGGeettVVaalluueess.  This memory
is allocated on the fly, and remains valid until the next
time a string needs to be allocated.  You may save memory by
freeing this string as soon as you are done with it by call-
ing XXaawwAAsscciiiiSSoouurrcceeFFrreeeeSSttrriinngg.

void XawAsciiSourceFreeString(_w)
Widget _w;


_w         Specifies the AsciiSrc object.

This function will free the memory that contains the string
pointer returned by XXttGGeettVVaalluueess.  This will normally happen
automatically when the next call to XXttGGeettVVaalluueess occurs, or
when the widget is destroyed.

55..66..22..22..  SSaavviinngg FFiilleess

To save the changes made in the current text source into a
file use XXaawwAAsscciiiiSSaavvee.





                             114444





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


Boolean XawAsciiSave(_w)
Widget _w;


_w         Specifies the AsciiSrc object.

XXaawwAAsscciiiiSSaavvee returns TTrruuee if the save was successful.  It
will update the file named in the ssttrriinngg resource.  If the
buffer has not been changed, no action will be taken.  This
function only works on an AsciiSrc of type XXaawwAAsscciiiiFFiillee.


To save the contents of the current text buffer into a named
file use XXaawwAAsscciiiiSSaavveeAAssFFiillee.

Boolean XawAsciiSaveAsFile(_w, _n_a_m_e)
Widget _w;
String _n_a_m_e;


_w         Specifies the AsciiSrc object.

_n_a_m_e      The name of the file to save the current buffer
          into.

This function returns TTrruuee if the save was successful.
XXaawwAAsscciiiiSSaavveeAAssFFiillee will work with a buffer of either type
XXaawwAAsscciiiiSSttrriinngg or type XXaawwAAsscciiiiFFiillee.

55..66..22..33..  SSeeeeiinngg iiff tthhee SSoouurrccee hhaass CChhaannggeedd

To find out if the text buffer in an AsciiSrc object has
changed since the last time it was saved with XXaawwAAsscciiiiSSaavvee
or queried use XXaawwAAsscciiiiSSoouurrcceeCChhaannggeedd.

Boolean XawAsciiSourceChanged(_w)
Widget _w;


_w         Specifies the AsciiSrc object.

This function will return TTrruuee if the source has changed
since the last time it was saved or queried.  The internal
change flag is reset whenever the string is queried via
XXttGGeettVVaalluueess or the buffer is saved via XXaawwAAsscciiiiSSaavvee.


55..77..  AAsscciiii SSiinnkk OObbjjeecctt aanndd MMuullttii SSiinnkk OObbjjeecctt



Application Header file<X11/Xaw/AsciiSink.h>
Class Header file   <X11/Xaw/AsciiSinkP.h>
Class               asciiSinkObjectClass



                             114455





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


Class Name          AsciiSink
Superclass          TextSink


The AsciiSink or MultiSink object is used by a text widget
to render the text.  Depending on its iinntteerrnnaattiioonnaall
resource, a AsciiText widget will create one or the other of
these when the AsciiText itself is created.  Both types are
nearly identical; the following discussion applies to both,
with MultiSink differences noted only as they occur.  The
AsciiSink will display all printing characters in an 8 bit
font, along with handling Tab and Carriage Return.  The name
has been left as ``AsciiSink'' for compatibility.  _T_h_e _M_u_l_-
_t_i_S_i_n_k _w_i_l_l _d_i_s_p_l_a_y _a_l_l _p_r_i_n_t_i_n_g _c_h_a_r_a_c_t_e_r_s _i_n _a _f_o_n_t _s_e_t_,
_a_l_o_n_g _w_i_t_h _h_a_n_d_l_i_n_g _T_a_b _a_n_d _C_a_r_r_i_a_g_e _R_e_t_u_r_n_.    The source
object also reports the text window metrics to the text wid-
gets.

55..77..11..  RReessoouurrcceess

When creating an AsciiSink object instance, the following
resources are retrieved from the argument list or from the
resource database:


--------------------------------------------------------------------------------
NNaammee                 CCllaassss        TTyyppee             NNootteess   DDeeffaauulltt VVaalluuee
--------------------------------------------------------------------------------
background           Background   Pixel                    XtDefaultBackground
destroyCallback      Callback     XtCallbackList           NULL
displayNonprinting   Output       Boolean                  True
echo                 Output       Boolean                  True
font                 Font         XFontStruct*             XtDefaultFont
fontSet              FontSet      XFontSet                 XtDefaultFontSet
foreground           Foreground   Pixel                    XtDefaultForeground
--------------------------------------------------------------------------------


bbaacckkggrroouunndd     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.  This resource is retrieved
               by the AsciiSink instead of being copied from
               the Text widget.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

ddiissppllaayyNNoonnpprriinnttiinngg
               If this resource is TTrruuee, the Text widget
               will display all non-printable characters as
               the string _^_@.  If FFaallssee, the Text widget
               will just leave a blank space where a non-
               printable character exists in the text



                             114466





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               buffer.

eecchhoo           Whether or not to echo characters to the
               screen.  The buffer can still be edited, but
               nothing is displayed.  This mode can be use-
               ful for entering passwords and other sensi-
               tive information.

ffoonntt           The text font to use when displaying the
               ssttrriinngg.  (This resource is present in the
               AsciiSink, but not the MultiSink.)

ffoonnttSSeett        The text font set to use when displaying the
               ssttrriinngg.  (This resource is present in the
               MultiSink, but not the AsciiSink.)


55..88..  CCuussttoommiizziinngg tthhee TTeexxtt WWiiddggeett


The remainder of this chapter will describe customizing the
Text widget.  The Text widget may be customized by subclass-
ing, or by creating new sources and sinks.  Subclassing is
described in detail in Chapter 7; this section will describe
only those things that are specific to the Text widget.
Attributes of the Text widget base class and creating new
sources and sinks will be discussed.

The Text widget is made up of a number of different pieces,
with the Text widget as the base widget class.  It and the
AsciiText widget are the only true "widgets" in the Text
widget family.  The other pieces (sources and sinks) are X
Toolkit objects and have no window associated with them.  No
source or sink is useful unless assigned to a Text widget.

Each of the following pieces of the Text widget has a spe-
cific purpose, and will be, or has been, discussed in detail
in this chapter:

TTeexxtt           This is the glue that binds everything else
               together.  This widget reads the text data
               from the source, and displays the information
               in the sink.  All translations and actions
               are handled in the Text widget itself.

TTeexxttSSiinnkk       This object is responsible for displaying and
               clearing the drawing area.  It also reports
               the configuration of the window that contains
               the drawing area.  The TextSink does not have
               its own window; instead it does its drawing
               on the Text widget's window.

TTeexxttSSrrcc        This object is responsible for reading, edit-
               ing and searching through the text buffer.



                             114477





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


AAsscciiiiSSiinnkk      This object is a subclass of the TextSink and
               knows how to display ASCII text.  Support has
               been added to display any 8-bit character
               set, given the font.

MMuullttiiSSiinnkk      This object is a subclass of the TextSink and
               knows how to display font sets.

AAsscciiiiSSrrcc       This object is a subclass of the TextSrc and
               knows how to read strings and files.

MMuullttiiSSrrcc       This object is a subclass of the TextSrc and
               knows how to read strings and multibyte
               files, converting them to wide characters
               based on locale.

AAsscciiiiTTeexxtt      This widget is a subclass of the Text widget.
               When created, the AsciiText automatically
               creates and attaches either an AsciiSrc and
               AsciiSink, or a MultiSrc and MultiSink, to
               itself.  The AsciiText provides the simplest
               interface to the Athena Text widgets.


55..99..  TTeexxtt WWiiddggeett



Application Header file<X11/Xaw/Text.h>
Class Header file   <X11/Xaw/TextP.h>
Class               textWidgetClass
Class Name          Text
Superclass          Simple



The Text widget is the glue that binds all the other pieces
together, it maintains the internal state of the displayed
text, and acts as a mediator between the source and sink.

This section lists the resources that are actually part of
the Text widget, and explains the functionality provided by
each.

55..99..11..  RReessoouurrcceess

When creating a Text widget instance, the following
resources are retrieved from the argument list or from the
resource database:








                             114488





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


------------------------------------------------------------------------------------
NNaammee                  CCllaassss            TTyyppee              NNootteessDDeeffaauulltt VVaalluuee
------------------------------------------------------------------------------------
accelerators          Accelerators     AcceleratorTable       NULL
ancestorSensitive     AncestorSensitiveBoolean           D    True
autoFill              AutoFill         Boolean                False
background            Background       Pixel                  XtDefaultBackground
backgroundPixmap      Pixmap           Pixmap                 XtUnspecifiedPixmap
borderColor           BorderColor      Pixel                  XtDefaultForeground
borderPixmap          Pixmap           Pixmap                 XtUnspecifiedPixmap
borderWidth           BorderWidth      Dimension              1
bottomMargin          Margin           Position               2
colormap              Colormap         Colormap               Parent's Colormap
cursor                Cursor           Cursor                 XC_xterm
cursorName            Cursor           String                 NULL
depth                 Depth            int               C    Parent's Depth
destroyCallback       Callback         XtCallbackList         NULL
displayCaret          Output           Boolean                True
displayPosition       TextPosition     XawTextPosition        0
height                Height           Dimension         A    Font height + margins
insensitiveBorder     Insensitive      Pixmap                 GreyPixmap
insertPosition        TextPosition     int                    0
leftMargin            Margin           Position               2
mappedWhenManaged     MappedWhenManagedBoolean                True
pointerColor          Foreground       Pixel                  XtDefaultForeground
pointerColorBackgroundBackground       Pixel                  XtDefaultBackground
resize                Resize           XawTextResizeMode      XawtextResizeNever
rightMargin           Margin           Position               4
screen                Screen           Pointer           R    Parent's Screen
scrollHorizontal      Scroll           ScrollMode             XawtextScrollNever
scrollVertical        Scroll           XawTextScrollMode      XawtextScrollNever
selectTypes           SelectTypes      XawTextSelectType*     See above
sensitive             Sensitive        Boolean                True
textSink              TextSink         Widget                 NULL
textSource            TextSource       Widget                 NULL
topMargin             Margin           Position               2
translations          Translations     TranslationTable       See above
unrealizeCallback     Callback         XtCallbackList         NULL
width                 Width            Dimension              100
wrap                  Wrap             WrapMode               XawtextWrapNever
x                     Position         Position               0
y                     Position         Position               0
------------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if



                             114499





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

aauuttooFFiillll       If this resource is TTrruuee the text widget will
               automatically break a line when the user
               attempts to type into the right margin.  The
               attribute has no effect on files or text
               inserted into the text widget.  It only
               checks to see if the action should be taken
               when a user enters a new character via the
               _i_n_s_e_r_t_-_c_h_a_r_a_c_t_e_r action.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

bboottttoommMMaarrggiinn
lleeffttMMaarrggiinn
rriigghhttMMaarrggiinn
ttooppMMaarrggiinn      The amount of space, in pixels, between the
               edge of the window and the corresponding edge
               of the text within the window.  If there is a
               scrollbar active on this edge, then this is
               the space between the text and the scrollbar.

colormap       The colormap that this widget will use.

cursor         The image that will be displayed as the
               pointer cursor whenever it is in this widget.
               The use of this resource is deprecated in
               favor of ccuurrssoorrNNaammee.

cursorName     The name of the symbol to use to represent
               the pointer cursor.  This resource will



                             115500





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               override the ccuurrssoorr resource if both are
               specified. (See 2.4.1)

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

ddiissppllaayyCCaarreett   Whether or not to display the text insert
               point.

ddiissppllaayyPPoossiittiioonn
               The position in the text buffer of the char-
               acter that is currently displayed in the
               upper left hand corner of the text display.

height
width          The height and width of this widget in pix-
               els.

insensitiveBorder
               This pixmap will be tiled into the widget's
               border if the widget becomes insensitive.

iinnsseerrttPPoossiittiioonn This is the location of the insert point.  It
               is expressed in characters from the beginning
               of the file.  The cursor will always be
               forced to be on the screen.  This resource
               may therefore be used to scroll the text dis-
               play to a certain character position.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

pointerColor   A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               pointer symbol specified by the ccuurrssoorrNNaammee
               resource.

pointerColorBackground
                 A pixel value which indexes the widget's
                 colormap to derive the background color of
                 the pointer symbol specified by the ccuurrssoorr--
                 NNaammee resource.

rreessiizzee         Controls whether or not the Text widget
               attempts to resize itself when it is no
               longer able to display the full text buffer
               in the associated window.  Any attempt by the
               Text widget to resize itself is always sub-
               ject to the constraints imposed by its



                             115511





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               parent.  The values XXaawwtteexxttRReessiizzeeNNeevveerr, XXaaww--
               tteexxttRReessiizzeeWWiiddtthh, XXaawwtteexxttRReessiizzeeHHeeiigghhtt, and
               XXaawwtteexxttRReessiizzeeBBootthh are all acceptable for this
               resource.  A converter is registered for this
               resource that will convert the following
               strings: nneevveerr,, hheeiigghhtt,, wwiiddtthh,, and bbootthh.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

ssccrroollllHHoorriizzoonnttaall
ssccrroollllVVeerrttiiccaall These resources control the placement of
               scrollbars on the left and bottom edge of the
               text widget.  These resources accept the val-
               ues XXaawwtteexxttSSccrroollllAAllwwaayyss, XXaawwtteexxttSSccrroollllWWhheenn--
               NNeeeeddeedd, and XXaawwtteexxttSSccrroollllNNeevveerr.  A converter
               is registered for this resource that will
               convert the following strings: aallwwaayyss,, nneevveerr,,
               and wwhheennNNeeeeddeedd.  If XXaawwtteexxttSSccrroollllWWhheennNNeeeeddeedd
               is specified, the appropriate scrollbar will
               only appear when there is text in the buffer
               that is not able to fit within the bounds of
               the current window.  The scrollbar will dis-
               appear when the text once again fits within
               the window.

sseelleeccttTTyyppeess    Specifies the selection type array that is
               used when multi-click is activated (see TTeexxtt
               SSeelleeccttiioonnss ffoorr AApppplliiccaattiioonn PPrrooggrraammmmeerrss for
               details).  This resource is used in place,
               and must not be freed until the widget is
               destroyed.  There is no type converter regis-
               tered for this resource, so it may not be set
               from the resource manager.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

tteexxttSSiinnkk
tteexxttSSoouurrccee     These are the TextSink or TextSource objects
               used by this widget.  When using the Text
               widget these MUST be set by the application
               programmer.

translations   The event bindings associated with this wid-
               get.

wwrraapp           When the text in any one line is wider than
               the window there are several possible
               actions.  This resource allows the user to
               decide what will happen.  The accepted values
               for this resource are XXaawwtteexxttWWrraappNNeevveerr,



                             115522





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               XXaawwtteexxttWWrraappLLiinnee, and XXaawwtteexxttWWrraappWWoorrdd.  With
               XXaawwtteexxttWWrraappLLiinnee all text that is beyond the
               right edge of the window will be displayed on
               the next line.  With XXaawwtteexxttWWrraappWWoorrdd the same
               action occurs but the text is broken at a
               word boundary if possible.  If no wrapping is
               enabled then the text will extend off the
               edge of the window, and a small rectangle
               will be painted in the right margin to alert
               the user that this line is too long.  A con-
               verter is registered for this resource that
               will convert the following strings: nneevveerr,,
               wwoorrdd,, and lliinnee.

uunnrreeaalliizzeeCCaallllbbaacckk
               A list of callback functions which will be
               executed when the Text widget is unrealized.

x
y              The location of the upper left outside corner
               of this widget in its parent.

55..1100..  TTeexxttSSrrcc OObbjjeecctt



Application Header file<X11/Xaw/TextSrc.h>
Class Header file   <X11/Xaw/TextSrcP.h>
Class               textSrcObjectClass
Class Name          TextSrc
Superclass          Object


The TextSrc object is the root object for all text sources.
Any new text source objects should be subclasses of the
TextSrc Object.  The TextSrc Class contains all methods the
Text widget expects a text source to export.

Since all text sources will have some resources in common
the TextSrc defines a few new resources.

55..1100..11..  RReessoouurrcceess

When creating an TextSrc object instance, the following
resources are retrieved from the argument list or from the
resource database:


-----------------------------------------------------------------------------
NNaammee              CCllaassss        TTyyppee             NNootteess   DDeeffaauulltt VVaalluuee
-----------------------------------------------------------------------------
destroyCallback   Callback     XtCallbackList           NULL





                             115533





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


-----------------------------------------------------------------------------
NNaammee              CCllaassss        TTyyppee             NNootteess   DDeeffaauulltt VVaalluuee
-----------------------------------------------------------------------------
editType          EditType     EditMode                 NULL
-----------------------------------------------------------------------------


destroyCallback
               All functions on this list are called when
               this widget is destroyed.

eeddiittTTyyppee       This is the type of editing that will be
               allowed in this text widget.  Legal values
               are XXaawwtteexxttRReeaadd, XXaawwtteexxttEEddiitt, and XXaawwtteexxttAApp--
               ppeenndd.  A converter is registered for this
               resource that will convert the following
               strings: rreeaadd,, eeddiitt,, and aappppeenndd.

55..1100..22..  SSuubbccllaassssiinngg tthhee TTeexxttSSrrcc

The only purpose of the TextSrc Object is to be subclassed.
It contains the minimum set of class methods that all text
sources must have.  All class methods of the TextSrc must be
defined, as the Text widget uses them all.  While all may be
inherited, the direct descendant of TextSrc mmuusstt specify
some of them as TextSrc does not contain enough information
to be a valid text source by itself.  Do not try to use the
TextSrc as a valid source for the Text widget; it is not
intended to be used as a source by itself and bad things
will probably happen.

--------------------------------------------------------------------------------------------
FFuunnccttiioonn           IInnhheerriitt wwiitthh                PPuubblliicc IInntteerrffaaccee                mmuusstt ssppeecciiffyy
--------------------------------------------------------------------------------------------
Read               XtInheritRead               XawTextSourceRead               yes
Replace            XtInheritReplace            XawTextSourceReplace            no
Scan               XtInheritScan               XawTextSourceScan               yes
Search             XtInheritSearch             XawTextSourceSearch             no
SetSelection       XtInheritSetSelection       XawTextSourceSetSelection       no
ConvertSelection   XtInheritConvertSelection   XawTextSourceConvertSelection   no
--------------------------------------------------------------------------------------------


55..1100..22..11..  RReeaaddiinngg TTeexxtt..

To read the text in a text source use the RReeaadd function:

XawTextPosition Read(_w, _p_o_s, _t_e_x_t___r_e_t_u_r_n, _l_e_n_g_t_h)
Widget _w;
XawTextPosition _p_o_s;
XawTextBlock _*_t_e_x_t___r_e_t_u_r_n;
int _l_e_n_g_t_h;





                             115544





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


_w         Specifies the TextSrc object.

_p_o_s       Specifies the position of the first character to
          be read from the text buffer.

_t_e_x_t      Returns the text read from the source.

_l_e_n_g_t_h    Specifies the maximum number of characters the
          TextSrc should return to the application in
          _t_e_x_t___r_e_t_u_r_n.

This function returns the text position immediately after
the characters read from the text buffer.  The function is
not required to read _l_e_n_g_t_h characters if that many charac-
ters are in the file, it may break at any point that is con-
venient to the internal structure of the source.  It may
take several calls to RReeaadd before the desired portion of the
text buffer is fully retrieved.

55..1100..22..22..  RReeppllaacciinngg TTeexxtt..

To replace or edit the text in a text buffer use the RReeppllaaccee
function:

XawTextPosition Replace(_w, _s_t_a_r_t, _e_n_d, _t_e_x_t)
Widget _w;
XawTextPosition _s_t_a_r_t, _e_n_d;
XawTextBlock _*_t_e_x_t;


_w         Specifies the TextSrc object.

_s_t_a_r_t     Specifies the position of the first character to
          be removed from the text buffer.  This is also the
          location to begin inserting the new text.

_e_n_d       Specifies the position immediately after the last
          character to be removed from the text buffer.

_t_e_x_t      Specifies the text to be added to the text source.

This function can return any of the following values:

XXaawwEEddiittDDoonnee The text replacement was successful.

XXaawwPPoossiittiioonnEErrrroorr
            The edit mode is XXaawwtteexxttAAppppeenndd and _s_t_a_r_t is not
            the last character of the source.

XXaawwEEddiittEErrrroorr
            Either the Source was read-only or the range to
            be deleted is larger than the length of the
            Source.




                             115555





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The RReeppllaaccee arguments _s_t_a_r_t and _e_n_d represent the text
source character positions for the existing text that is to
be replaced by the text in the text block.  The characters
from _s_t_a_r_t up to but not including _e_n_d are deleted, and the
buffer specified by the text block is inserted in their
place.  If _s_t_a_r_t and _e_n_d are equal, no text is deleted and
the new text is inserted after _s_t_a_r_t.

55..1100..22..33..  SSccaannnniinngg tthhee TTeexxttSSrrcc

To search the text source for one of the predefined boundary
types use the SSccaann function:

XawTextPosition Scan(_w, _p_o_s_i_t_i_o_n, _t_y_p_e, _d_i_r, _c_o_u_n_t, _i_n_c_l_u_d_e)
Widget _w;
XawTextPosition _p_o_s_i_t_i_o_n;
XawTextScanType _t_y_p_e;
XawTextScanDirection _d_i_r;
int _c_o_u_n_t;
Boolean _i_n_c_l_u_d_e;


_w         Specifies the TextSrc object.

_p_o_s_i_t_i_o_n  Specifies the position to begin scanning the
          source.

_t_y_p_e      Specifies the type of boundary to scan for, may be
          one of: XXaawwssttPPoossiittiioonn, XXaawwssttWWhhiitteeSSppaaccee, XXaawwssttEEOOLL,
          XXaawwssttPPaarraaggrraapphh, XXaawwssttAAllll.  The exact meaning of
          these boundaries is left up to the individual text
          source.

_d_i_r       Specifies the direction to scan, may be either
          XXaawwssddLLeefftt to search backward, or XXaawwssddRRiigghhtt to
          search forward.

_c_o_u_n_t     Specifies the number of boundaries to scan for.

_i_n_c_l_u_d_e   Specifies whether the boundary itself should be
          included in the scan.

The SSccaann function returns the position in the text source of
the desired boundary.  It is expected to return a valid
address for all calls made to it, thus if a particular
request is made that would take the text widget beyond the
end of the source it must return the position of that end.

55..1100..22..44..  SSeeaarrcchhiinngg tthhrroouugghh aa TTeexxttSSrrcc

To search for a particular string use the SSeeaarrcchh function.






                             115566





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


XawTextPosition Search(_w, _p_o_s_i_t_i_o_n, _d_i_r, _t_e_x_t)
Widget _w;
XawTextPosition _p_o_s_i_t_i_o_n;
XawTextScanDirection _d_i_r;
XawTextBlock _*_t_e_x_t;


_w         Specifies the TextSrc object.

_p_o_s_i_t_i_o_n  Specifies the position to begin the search.

_d_i_r       Specifies the direction to search, may be either
          XXaawwssddLLeefftt to search backward, or XXaawwssddRRiigghhtt to
          search forward.

_t_e_x_t      Specifies a text block containing the text to
          search for.

This function will search through the text buffer attempting
to find a match for the string in the text block.  If a
match is found in the direction specified, then the charac-
ter location of the first character in the string is
returned.  If no text was found then XXaawwTTeexxttSSeeaarrcchhEErrrroorr is
returned.

55..1100..22..55..  TTeexxtt SSeelleeccttiioonnss

While many selection types are handled by the Text widget,
text sources may have selection types unknown to the Text
widget.  When a selection conversion is requested by the X
server the Text widget will first call the CCoonnvveerrttSSeelleeccttiioonn
function, to attempt the selection conversion.

Boolean ConvertSelections(_w, _s_e_l_e_c_t_i_o_n, _t_a_r_g_e_t, _t_y_p_e, _v_a_l_u_e___r_e_t_u_r_n, _l_e_n_g_t_h___r_e_t_u_r_n, _f_o_r_m_a_t___r_e_t_u_r_n)
Widget _w;
Atom _*_s_e_l_e_c_t_i_o_n, _*_t_a_r_g_e_t, _*_t_y_p_e;
caddr_t _*_v_a_l_u_e___r_e_t_u_r_n;
unsigned long _*_l_e_n_g_t_h___r_e_t_u_r_n;
int _*_f_o_r_m_a_t___r_e_t_u_r_n;


_w         Specifies the TextSrc object.

_s_e_l_e_c_t_i_o_n Specifies the type of selection that was requested
          (e.g. PPRRIIMMAARRYY).

_t_a_r_g_e_t    Specifies the type of the selection that has been
          requested, which indicates the desired information
          about the selection (e.g. Filename, Text, Window).

_t_y_p_e      Specifies a pointer to the atom into which the
          property type of the converted value of the selec-
          tion is to be stored.  For instance, either file
          name or text might have property type XXAA__SSTTRRIINNGG.



                             115577





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


_v_a_l_u_e___r_e_t_u_r_n
          Returns a pointer into which a pointer to the con-
          verted value of the selection is to be stored.
          The selection owner is responsible for allocating
          this storage.  The memory is considered owned by
          the toolkit, and is freed by XtFree when the
          Intrinsics selection mechanism is done with it.

_l_e_n_g_t_h___r_e_t_u_r_n
          Returns a pointer into which the number of ele-
          ments in value is to be stored.  The size of each
          element is determined by _f_o_r_m_a_t.

_f_o_r_m_a_t___r_e_t_u_r_n
          Returns a pointer into which the size in bits of
          the data elements of the selection value is to be
          stored.

If this function returns TTrruuee then the Text widget will
assume that the source has taken care of converting the
selection, Otherwise the Text widget will attempt to convert
the selection itself.


If the source needs to know when the text selection is modi-
fied it should define a SSeettSSeelleeccttiioonn procedure:

void SetSelection(_w, _s_t_a_r_t, _e_n_d, _s_e_l_e_c_t_i_o_n)
Widget _w;
XawTextPosition _s_t_a_r_t, _e_n_d;
Atom _s_e_l_e_c_t_i_o_n;


_w         Specifies the TextSrc object.

_s_t_a_r_t     Specifies the character position of the beginning
          of the new text selection.

_e_n_d       Specifies the character position of the end of the
          new text selection.

_s_e_l_e_c_t_i_o_n Specifies the type of selection that was requested
          (e.g. PPRRIIMMAARRYY).

55..1111..  TTeexxttSSiinnkk OObbjjeecctt



Application Header file<X11/Xaw/TextSink.h>
Class Header file   <X11/Xaw/TextSinkP.h>
Class               textSinkObjectClass
Class Name          TextSink
Superclass          Object




                             115588





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


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.

Since all text sinks will have some resources in common, the
TextSink defines a few new resources.

55..1111..11..  RReessoouurrcceess

When creating an TextSink object instance, the following
resources are retrieved from the argument list or from the
resource database:


-----------------------------------------------------------------------------
NNaammee              CCllaassss        TTyyppee             NNootteess   DDeeffaauulltt VVaalluuee
-----------------------------------------------------------------------------
background        Background   Pixel                    XtDefaultBackground
destroyCallback   Callback     XtCallbackList           NULL
foreground        Foreground   Pixel                    XtDefaultForeground
-----------------------------------------------------------------------------


bbaacckkggrroouunndd     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

ffoorreeggrroouunndd     A pixel value which indexes the Text widget's
               colormap to derive the foreground color used
               by the text sink.

55..1111..22..  SSuubbccllaassssiinngg tthhee TTeexxttSSiinnkk

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 mmuusstt ssppeecciiffyy 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.

---------------------------------------------------------------------------------------------
FFuunnccttiioonn            IInnhheerriitt wwiitthh                 PPuubblliicc IInntteerrffaaccee               mmuusstt ssppeecciiffyy
---------------------------------------------------------------------------------------------
DisplayText         XtInheritDisplayText         XawTextSinkDisplayText         yes
InsertCursor        XtInheritInsertCursor        XawTextSinkInsertCursor        yes
ClearToBackground   XtInheritClearToBackground   XawTextSinkClearToBackground   no




                             115599





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


---------------------------------------------------------------------------------------------
FFuunnccttiioonn            IInnhheerriitt wwiitthh                 PPuubblliicc IInntteerrffaaccee               mmuusstt ssppeecciiffyy
---------------------------------------------------------------------------------------------
FindPosition        XtInheritFindPosition        XawTextSinkFindPosition        yes
FindDistance        XtInheritFindDistance        XawTextSinkFindDistance        yes
Resolve             XtInheritResolve             XawTextSinkResolve             yes
MaxLines            XtInheritMaxLines            XawTextSinkMaxLines            no
MaxHeight           XtInheritMaxHeight           XawTextSinkMaxHeight           no
SetTabs             XtInheritSetTabs             XawTextSinkSetTabs             no
GetCursorBounds     XtInheritGetCursorBounds     XawTextSinkGetCursorBounds     yes
---------------------------------------------------------------------------------------------


55..1111..22..11..  DDiissppllaayyiinngg TTeexxtt

To display a section of the text buffer contained in the
text source use the function DDiissppllaayyTTeexxtt:

void DisplayText(_w, _x, _y, _p_o_s_1, _p_o_s_2, _h_i_g_h_l_i_g_h_t)
      Widget _w;
      Position _x, _y;
      XawTextPosition _p_o_s_1, _p_o_s_2;
      Boolean _h_i_g_h_l_i_g_h_t;


_w         Specifies the TextSink object.

_x         Specifies the x location to start drawing the
          text.

_y         Specifies the y location to start drawing text.

_p_o_s_1      Specifies the location within the text source of
          the first character to be printed.

_p_o_s_2      Specifies the location within the text source of
          the last character to be printed.

_h_i_g_h_l_i_g_h_t Specifies whether or not to paint the text region
          highlighted.

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.  _x and _y denote the upper left
hand corner of the first character to be displayed.

55..1111..22..22..  DDiissppllaayyiinngg tthhee IInnsseerrtt PPooiinntt

The function that controls the display of the text cursor is
IInnsseerrttCCuurrssoorr.  This function will be called whenever the
text widget desires to change the state of, or move the
insert point.




                             116600





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


void InsertCursor(_w, _x, _y, _s_t_a_t_e)
      Widget _w;
      Position _x, _y;
      XawTextInsertState _s_t_a_t_e;


_w         Specifies the TextSink object.

_x         Specifies the x location of the cursor in Pixels.

_y         Specifies the y location of the cursor in Pixels.

_s_t_a_t_e     Specifies the state of the cursor, may be one of
          XXaawwiissOOnn or XXaawwiissOOffff.

_X and _y denote the upper left hand corner of the insert
point.

55..1111..22..33..  CClleeaarriinngg PPoorrttiioonnss ooff tthhee TTeexxtt wwiinnddooww

To clear a portion of the Text window to its background
color, the Text widget will call CClleeaarrTTooBBaacckkggrroouunndd.  The
TextSink object already defines this function as calling
XXCClleeaarrAArreeaa on the region passed.  This behavior will be used
if you specify XXttIInnhheerriittCClleeaarrTTooBBaacckkggrroouunndd for this method.

void ClearToBackground(_w, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t)
      Widget _w;
      Position _x, _y;
      Dimension _w_i_d_t_h, _h_e_i_g_h_t;


_w         Specifies the TextSink object.

_x         Specifies the x location, in pixels, of the Region
          to clear.

_y         Specifies the y location, in pixels, of the Region
          to clear.

_w_i_d_t_h     Specifies the width, in pixels, of the Region to
          clear.

_h_e_i_g_h_t    Specifies the height, in pixels, of the Region to
          clear.

_X and _y denote the upper left hand corner of region to
clear.

55..1111..22..44..  FFiinnddiinngg aa TTeexxtt PPoossiittiioonn GGiivveenn PPiixxeell VVaalluueess

To find the text character position that will be rendered at
a given x location the Text widget uses the function FFiinnddPPoo--
ssiittiioonn:



                             116611





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


void FindPosition(_w, _f_r_o_m_P_o_s, _f_r_o_m_X, _w_i_d_t_h, _s_t_o_p_A_t_W_o_r_d_B_r_e_a_k, _p_o_s___r_e_t_u_r_n, _w_i_d_t_h___r_e_t_u_r_n, _h_e_i_g_h_t___r_e_t_u_r_n)
      Widget _w;
      XawTextPosition _f_r_o_m_P_o_s;
      int _f_r_o_m_X, _w_i_d_t_h;
      Boolean _s_t_o_p_A_t_W_o_r_d_B_r_e_a_k;
      XawTextPosition _*_p_o_s___r_e_t_u_r_n;
      int _*_w_i_d_t_h___r_e_t_u_r_n, _*_h_e_i_g_h_t___r_e_t_u_r_n;


_w           Specifies the TextSink object.

_f_r_o_m_P_o_s     Specifies a reference position, usually the
            first character in this line.  This character is
            always to the left of the desired character
            location.

_f_r_o_m_X       Specifies the distance that the left edge of
            _f_r_o_m_P_o_s is from the left edge of the window.
            This is the reference x location for the refer-
            ence position.

_w_i_d_t_h       Specifies the distance, in pixels, from the ref-
            erence position to the desired character posi-
            tion.

_s_t_o_p_A_t_W_o_r_d_B_r_e_a_k
            Specifies whether or not the position that is
            returned should be forced to be on a word bound-
            ary.

_p_o_s___r_e_t_u_r_n  Returns the character position that corresponds
            to the location that has been specified, or the
            work break immediately to the left of the posi-
            tion if _s_t_o_p_A_t_W_o_r_d_B_r_e_a_k is TTrruuee.

_w_i_d_t_h___r_e_t_u_r_n
            Returns the actual distance between _f_r_o_m_P_o_s and
            _p_o_s___r_e_t_u_r_n_.

_h_e_i_g_h_t___r_e_t_u_r_n
            Returns the maximum height of the text between
            _f_r_o_m_P_o_s and _p_o_s___r_e_t_u_r_n_.

This function need make no attempt to deal with line feeds.
The text widget will only call it one line at a time.


Another means of finding a text position is provided by the
RReessoollvvee function:








                             116622





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


void Resolve(_w, _f_r_o_m_P_o_s, _f_r_o_m_X, _w_i_d_t_h, _p_o_s___r_e_t_u_r_n)
      Widget _w;
      XawTextPosition _f_r_o_m_P_o_s;
      int _f_r_o_m_X, _w_i_d_t_h;
      XawTextPosition _*_p_o_s___r_e_t_u_r_n;


_w         Specifies the TextSink object.

_f_r_o_m_P_o_s   Specifies a reference position, usually the first
          character in this line.  This character is always
          to the left of the desired character location.

_f_r_o_m_X     Specifies the distance that the left edge of
          _f_r_o_m_P_o_s is from the left edge of the window.  This
          is the reference x location for the reference
          position.

_w_i_d_t_h     Specifies the distance, in pixels, from the refer-
          ence position to the desired character position.

_p_o_s___r_e_t_u_r_n
          Returns the character position that corresponds to
          the location that has been specified, or the word
          break immediately to the left if _s_t_o_p_A_t_W_o_r_d_B_r_e_a_k
          is TTrruuee.

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 FFiinnddPPoossiittiioonn function,
and provides a subset of its functionality.

55..1111..22..55..  FFiinnddiinngg tthhee DDiissttaannccee BBeettwweeeenn ttwwoo TTeexxtt PPoossiittiioonnss

To find the distance in pixels between two text positions on
the same line use the function FFiinnddDDiissttaannccee.

void FindDistance(_w, _f_r_o_m_P_o_s, _f_r_o_m_X, _t_o_P_o_s, _w_i_d_t_h___r_e_t_u_r_n, _p_o_s___r_e_t_u_r_n, _h_e_i_g_h_t___r_e_t_u_r_n)
      Widget _w;
      XawTextPosition _f_r_o_m_P_o_s, _t_o_P_o_s;
      int _f_r_o_m_X;
      XawTextPosition _*_p_o_s___r_e_t_u_r_n;
      int _*_w_i_d_t_h___r_e_t_u_r_n, _*_h_e_i_g_h_t___r_e_t_u_r_n;


_w         Specifies the TextSink object.

_f_r_o_m_P_o_s   Specifies the text buffer position, in characters,
          of the first position.

_f_r_o_m_X     Specifies the distance that the left edge of
          _f_r_o_m_P_o_s is from the left edge of the window.  This
          is the reference x location for the reference
          position.



                             116633





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


_t_o_P_o_s     Specifies the text buffer position, in characters,
          of the second position.

_r_e_s_W_i_d_t_h  Return the actual distance between _f_r_o_m_P_o_s and
          _p_o_s___r_e_t_u_r_n_.

_r_e_s_P_o_s    Returns the character position that corresponds to
          the actual character position used for _t_o_P_o_s in
          the calculations.  This may be different than
          _t_o_P_o_s, for example if _f_r_o_m_P_o_s and _t_o_P_o_s are on
          different lines in the file.

_h_e_i_g_h_t___r_e_t_u_r_n
          Returns the maximum height of the text between
          _f_r_o_m_P_o_s and _p_o_s___r_e_t_u_r_n.

This function need make no attempt to deal with line feeds.
The Text widget will only call it one line at a time.

55..1111..22..66..  FFiinnddiinngg tthhee SSiizzee ooff tthhee DDrraawwiinngg aarreeaa

To find the maximum number of lines that will fit into the
current Text widget, use the function MMaaxxLLiinneess.  The
TextSink already defines this function to compute the maxi-
mum number of lines by using the height of ffoonntt.

int MaxLines(_w, _h_e_i_g_h_t)
      Widget _w;
      Dimension _h_e_i_g_h_t;


_w         Specifies the TextSink object.

_h_e_i_g_h_t    Specifies the height of the current drawing area.

Returns the maximum number of lines that will fit in _h_e_i_g_h_t.


To find the height required for a given number of text
lines, use the function MMaaxxHHeeiigghhtt.  The TextSink already
defines this function to compute the maximum height of the
window by using the height of ffoonntt.

int MaxHeight(_w, _l_i_n_e_s)
      Widget _w;
      int _l_i_n_e_s;


_w         Specifies the TextSink object.

_h_e_i_g_h_t    Specifies the height of the current drawing area.

Returns the height that will be taken up by the number of
lines passed.



                             116644





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


55..1111..22..77..  SSeettttiinngg tthhee TTaabb SSttooppss

To set the tab stops for a text sink use the SSeettTTaabbss func-
tion.  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 ffoonntt.

void SetTabs(_w, _t_a_b___c_o_u_n_t, _t_a_b_s)
      Widget _w;
      int _t_a_b___c_o_u_n_t, _*_t_a_b_s;


_w         Specifies the TextSink object.

_t_a_b___c_o_u_n_t Specifies the number of tabs passed in _t_a_b_s.

_t_a_b_s      Specifies the position, in characters, of the tab
          stops.

This function is responsible for the converting character
positions passed to it into whatever internal positions the
TextSink uses for tab placement.

55..1111..22..88..  GGeettttiinngg tthhee IInnsseerrtt PPooiinntt''ss SSiizzee aanndd LLooccaattiioonn

To get the size and location of the insert point use the
GGeettCCuurrssoorrBBoouunnddss function.

void GetCursorBounds(_w, _r_e_c_t___r_e_t_u_r_n)
Widget _w;
XRectangle _*_r_e_c_t___r_e_t_u_r_n;


_w         Specifies the TextSinkObject.

_r_e_c_t___r_e_t_u_r_n
          Returns the location and size of the insert point.

_R_e_c_t will be filled with the current size and location of
the insert point.

















                             116655





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77




                         CChhaapptteerr 66

              CCoommppoossiittee aanndd CCoonnssttrraaiinntt WWiiddggeettss




These widgets may contain arbitrary widget children.  They
implement a policy for the size and location of their chil-
dren.

BBooxx       This widget will pack its children as tightly as
          possible in non-overlapping rows.

DDiiaalloogg    An implementation of a commonly used interaction
          semantic to prompt for auxiliary input from the
          user, such as a filename.

FFoorrmm      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.

PPaanneedd     Allows children to be tiled vertically or horizon-
          tally.  Controls are also provided to allow the
          user to dynamically resize the individual panes.

PPoorrtthhoollee  Allows viewing of a managed child which is as
          large as, or larger than its parent, typically
          under control of a Panner widget.

TTrreeee      Provides geometry management of widgets arranged
          in a directed, acyclic graph.

VViieewwppoorrtt  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 win-
          dow will be clipped by the frame with the scroll-
          bars controlling which section of the inner window
          is currently visible.


66..00..11..  AA BBrriieeff NNoottee oonn GGeeoommeettrryy MMaannaaggeemmeenntt

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



                             116666





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


those expected by the application programmer.

If the application wishes to change the size or location of
any widget it should make a call to XXttSSeettVVaalluueess.  This will
allow the widget to ask its parent for the new size or loca-
tion.  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
XXttMMoovveeWWiiddggeett or XXttRReessiizzeeWWiiddggeett; these functions are exclu-
sively for the use of Composite widget implementors.

For more information on geometry management consult the _X
_T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e.



66..11..  BBooxx WWiiddggeett



Application Header file<X11/Xaw/Box.h>
Class Header file   <X11/Xaw/BoxP.h>
Class               boxWidgetClass
Class Name          Box
Superclass          Composite



The Box widget provides geometry management of arbitrary
widgets in a box of a specified dimension.  The children are
rearranged when resizing events occur either on the Box or
its children, or when children are managed or unmanaged.
The Box widget always attempts to pack its children as
tightly as possible within the geometry allowed by its par-
ent.

Box widgets are commonly used to manage a related set of
buttons and are often called ButtonBox widgets, but the
children are not limited to buttons.  The Box's children are
arranged on a background that has its own specified dimen-
sions and color.

66..11..11..  RReessoouurrcceess

When creating a Box widget instance, the following resources
are retrieved from the argument list or from the resource
database:








                             116677





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


----------------------------------------------------------------------------
NNaammee             CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
----------------------------------------------------------------------------
accelerators     Accelerators     AcceleratorTable     NULL
ancestorSensitiveAncestorSensitiveBoolean         D    True
background       Background       Pixel                XtDefaultBackground
backgroundPixmap Pixmap           Pixmap               XtUnspecifiedPixmap
borderColor      BorderColor      Pixel                XtDefaultForeground
borderPixmap     Pixmap           Pixmap               XtUnspecifiedPixmap
borderWidth      BorderWidth      Dimension            1
children         ReadOnly         WidgetList      R    NULL
colormap         Colormap         Colormap             Parent's Colormap
depth            Depth            int             C    Parent's Depth
destroyCallback  Callback         XtCallbackList       NULL
height           Height           Dimension       A    see LLaayyoouutt SSeemmaannttiiccss
hSpace           HSpace           Dimension            4
mappedWhenManagedMappedWhenManagedBoolean              True
numChildren      ReadOnly         Cardinal        R    0
orientation      Orientation      Orientation          XtorientVertical
screen           Screen           Screen          R    Parent's Screen
sensitive        Sensitive        Boolean              True
vSpace           VSpace           Dimension            4
translations     Translations     TranslationTable     NULL
width            Width            Dimension       A    see LLaayyoouutt SSeemmaannttiiccss
x                Position         Position             0
y                Position         Position             0
----------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.





                             116688





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

children       A list of all this composite widget's current
               children.

colormap       The colormap that this widget will use.

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

height
width          The height and width of this widget in pix-
               els.

hhSSppaaccee
vvSSppaaccee         The amount of space, in pixels, to leave
               between the children.  This resource speci-
               fies the amount of space left between the
               outermost children and the edge of the box.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

numChildren    The number of children in this composite wid-
               get.

oorriieennttaattiioonn    Specifies whether the preferred shape of the
               box (i.e. the result returned by the
               query_geometry class method) is tall and nar-
               row XXttoorriieennttVVeerrttiiccaall or short and wide XXttoorrii--
               eennttHHoorriizzoonnttaall.  When the Box is a child of a
               parent which enforces width constraints, it
               is usually better to specify XXttoorriieennttVVeerrttiiccaall
               (the default).  When the parent enforces
               height constraints, it is usually better to
               specify XXttoorriieennttHHoorriizzoonnttaall.  A converter is
               registered for this resource that will con-
               vert the following strings: hhoorriizzoonnttaall and
               vveerrttiiccaall.



                             116699





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

translations   The event bindings associated with this wid-
               get.

x
y              The location of the upper left outside corner
               of this widget in its parent.

66..11..22..  LLaayyoouutt SSeemmaannttiiccss

Each time a child is managed or unmanaged, the Box widget
will attempt to reposition the remaining children to compact
the box.  Children are positioned in order left to right,
top to bottom.  The packing algorithm used depends on the
oorriieennttaattiioonn of the Box.

XXttoorriieennttVVeerrttiiccaall
               When the next child does not fit on the cur-
               rent row, a new row is started.  If a child
               is wider than the width of the box, the box
               will request a larger width from its parent
               and will begin the layout process from the
               beginning if a new width is granted.

XXttoorriieennttHHoorriizzoonnttaall
               When the next child does not fit on the cur-
               rent row, the Box widens if possible (so as
               to keep children on a single row); otherwise
               a new row is started.

After positioning all children, the Box widget attempts to
shrink its own size to the minimum dimensions required for
the layout.

66..22..  DDiiaalloogg WWiiddggeett



Application Header file<X11/Xaw/Dialog.h>
Class Header file   <X11/Xaw/DialogP.h>
Class               dialogWidgetClass
Class Name          Dialog
Superclass          Form







                             117700





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The Dialog widget implements a commonly used interaction
semantic to prompt for auxiliary input from a user.  For
example, you can use a Dialog widget when an application
requires a small piece of information, such as a filename,
from the user.  A Dialog widget, which is simply a special
case of the Form widget, provides a convenient way to create
a preconfigured form.

The typical Dialog widget contains three areas.  The first
line contains a description of the function of the Dialog
widget, for example, the string _F_i_l_e_n_a_m_e_:.  The second line
contains an area into which the user types input.  The third
line can contain buttons that let the user confirm or cancel
the Dialog input.  Any of these areas may be omitted by the
application.

66..22..11..  RReessoouurrcceess

When creating a Dialog widget instance, the following
resources are retrieved from the argument list or the
resource database:

--------------------------------------------------------------------------------------------
NNaammee             CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
--------------------------------------------------------------------------------------------
accelerators     Accelerators     AcceleratorTable     NULL
ancestorSensitiveAncestorSensitiveBoolean         D    True
background       Background       Pixel                XtDefaultBackground
backgroundPixmap Pixmap           Pixmap               XtUnspecifiedPixmap
borderColor      BorderColor      Pixel                XtDefaultForeground
borderPixmap     Pixmap           Pixmap               XtUnspecifiedPixmap
borderWidth      BorderWidth      Dimension            1
children         ReadOnly         WidgetList      R    NULL
colormap         Colormap         Colormap             Parent's Colormap
defaultDistance  Thickness        int                  4
depth            Depth            int             C    Parent's Depth
destroyCallback  Callback         XtCallbackList       NULL
height           Height           Dimension       A    Enough space to contain all children
icon             Icon             Bitmap               None
label            Label            String               "label"
mappedWhenManagedMappedWhenManagedBoolean              True
numChildren      ReadOnly         Cardinal        R    0
screen           Screen           Screen          R    Parent's Screen
sensitive        Sensitive        Boolean              True
translations     Translations     TranslationTable     NULL
value            Value            String               no value widget
width            Width            Dimension       A    Enough space to contain all children
x                Position         Position             0
y                Position         Position             0
--------------------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event



                             117711





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

children       A list of all this composite widget's current
               children.

colormap       The colormap that this widget will use.

defaultDistance
               The default internal spacing for the chil-
               dren.  This is the default value for the con-
               straint resources hhoorriizzDDiissttaannccee and vveerrttDDiiss--
               ttaannccee.

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

height
width          The height and width of this widget in pix-
               els.



                             117722





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


iiccoonn           A pixmap image to be displayed immediately to
               the left of the Dialog widget's label.

llaabbeell          A string to be displayed at the top of the
               Dialog widget.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

numChildren    The number of children in this composite wid-
               get.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

translations   The event bindings associated with this wid-
               get.

vvaalluuee          An initial value for the string field that
               the user will enter text into.  By default,
               no text entry field is available to the user.
               Specifying an initial value for vvaalluuee acti-
               vates the text entry field.  If string input
               is desired, but no initial value is to be
               specified then set this resource to "" (empty
               string).

x
y              The location of the upper left outside corner
               of this widget in its parent.

66..22..22..  CCoonnssttrraaiinntt RReessoouurrcceess

Each child of the Dialog widget may request special layout
resources be applied to it.  These _c_o_n_s_t_r_a_i_n_t resources
allow the Dialog widget's children to specify individual
layout requirements.


------------------------------------------------------------------------------
NNaammee            CCllaassss        TTyyppee          NNootteess   DDeeffaauulltt VVaalluuee
------------------------------------------------------------------------------
bottom          Edge         XawEdgeType           XawRubber
fromHoriz       Widget       Widget                NULL (left edge of Dialog)
fromVert        Widget       Widget                NULL (top edge of Dialog)
horizDistance   Thickness    int                   ddeeffaauullttDDiissttaannccee resource




                             117733





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


------------------------------------------------------------------------------
NNaammee            CCllaassss        TTyyppee          NNootteess   DDeeffaauulltt VVaalluuee
------------------------------------------------------------------------------
left            Edge         XawEdgeType           XawRubber
resizable       Boolean      Boolean               FALSE
right           Edge         XawEdgeType           XawRubber
top             Edge         XawEdgeType           XawRubber
vertDistance    Thickness    int                   ddeeffaauullttDDiissttaannccee resource
------------------------------------------------------------------------------


bottom
left
right
top            What to do with this edge of the child when
               the parent is resized.  This resource may be
               any eeddggeeTTyyppee.  See LLaayyoouutt SSeemmaannttiiccss for
               details.

fromHoriz
fromVert       Which widget this child should be placed
               underneath (or to the right of).  If a value
               of NULL is specified then this widget will be
               positioned relative to the edge of the par-
               ent.

horizDistance
vertDistance   The amount of space, in pixels, between this
               child and its left or upper neighbor.

resizable      If this resource is FFaallssee then the parent
               widget will ignore all geometry request made
               by this child.  The parent may still resize
               this child itself, however.

66..22..33..  LLaayyoouutt SSeemmaannttiiccss

The Dialog widget uses two different sets of layout seman-
tics.  One is used when initially laying out the children.
The other is used when the Dialog is resized.

The first layout method uses the ffrroommVVeerrtt and ffrroommHHoorriizz
resources to place the children of the Dialog.  A single
pass is made through the Dialog widget's children in the
order that they were created.  Each child is then placed in
the Dialog widget below or to the right of the widget speci-
fied by the ffrroommVVeerrtt and ffrroommHHoorriizz resources.  The distance
the new child is placed from its left or upper neighbor is
determined by the hhoorriizzDDiissttaannccee and vveerrttDDiissttaannccee resources.
This implies some things about how the order of creation
affects the possible placement of the children.  The Form
widget registers a string to widget converter which does not
postpone conversion and does not cache conversion results.




                             117744





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The second layout method is used when the Dialog is resized.
It does not matter what causes this resize, and it is possi-
ble for a resize to happen before the widget becomes visible
(due to constraints imposed by the parent of the Dialog).
This layout method uses the bboottttoomm, ttoopp, lleefftt, and rriigghhtt
resources.  These resources are used to determine what will
happen to each edge of the child when the Dialog is resized.
If a value of XXaawwCChhaaiinn_<_s_o_m_e_t_h_i_n_g_> is specified, the the edge
of the child will remain a fixed distance from the _c_h_a_i_n
edge of the Dialog.  For example if XXaawwCChhaaiinnLLeefftt is speci-
fied for the rriigghhtt resource of a child then the right edge
of that child will remain a fixed distance from the left
edge of the Dialog widget.  If a value of XXaawwRRuubbbbeerr is spec-
ified, that edge will grow by the same percentage that the
Dialog grew.  For instance if the Dialog grows by 50% the
left edge of the child (if specified as XXaawwRRuubbbbeerr will be
50% farther from the left edge of the Dialog).  One must be
very careful when specifying these resources, for when they
are specified incorrectly children may overlap or completely
occlude other children when the Dialog widget is resized.


--------------------------------------------------------------------------------------
EEddggee TTyyppee         RReessoouurrccee NNaammee   DDeessccrriippttiioonn
--------------------------------------------------------------------------------------
XawChainBottom    ChainBottom     Edge remains a fixed distance from bottom of Dialog
XawChainLeft      ChainLeft       Edge remains a fixed distance from left of Dialog
XawChainRight     ChainRight      Edge remains a fixed distance from right of Dialog
XawChainTop       ChainTop        Edge remains a fixed distance from top of Dialog
XawRubber         Rubber          Edges will move a proportional distance
--------------------------------------------------------------------------------------


66..22..33..11..  EExxaammppllee

If you wish to force the Dialog to never resize one or more
of its children then set lleefftt and rriigghhtt to XXaawwCChhaaiinnLLeefftt and
ttoopp and bboottttoomm to XXaawwCChhaaiinnTToopp.  This will cause the child to
remain a fixed distance from the top and left edges of the
Dialog, and to never resize.

66..22..33..22..  SSppeecciiaall CCoonnssiiddeerraattiioonnss

The Dialog widget automatically sets the ttoopp and bboottttoomm
resources for all Children that are subclasses of the Com-
mand widget, as well as the widget children that are used to
contain the llaabbeell, vvaalluuee, and iiccoonn.  This policy allows the
buttons at the bottom of the Dialog to interact correctly
with the predefined children, and makes it possible for a
client to simply create and manage a new Command button
without having to specify its constraints.

The Dialog will also set ffrroommLLeefftt to the last button in the
Dialog for each new button added to the Dialog widget.



                             117755





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The automatically added constraints cannot be overridden, as
they are policy decisions of the Dialog widget.  If a more
flexible Dialog is desired, the application is free to use
the Form widget to create its own Dialog policy.

66..22..44..  AAuuttoommaattiiccaallllyy CCrreeaatteedd CChhiillddrreenn..

The Dialog uses Label widgets to contain the llaabbeell and iiccoonn.
These widgets are named _l_a_b_e_l and _i_c_o_n respectively.  The
Dialog vvaalluuee is contained in an AsciiText widget whose name
is _v_a_l_u_e.  Using XXttNNaammeeTTooWWiiddggeett the application can change
those resources associated with each of these widgets that
are not available through the Dialog widget itself.


66..22..55..  CCoonnvveenniieennccee RRoouuttiinneess

To return the character string in the text field, use
_X_a_w_D_i_a_l_o_g_G_e_t_V_a_l_u_e_S_t_r_i_n_g.

String XawDialogGetValueString(_w)
     Widget _w;


_w         Specifies the Dialog widget.

This function returns a copy of the value string of the Dia-
log widget.  This string is allocated by the AsciiText wid-
get and will remain valid and unchanged until another call
to XXaawwDDiiaallooggGGeettVVaalluueeSSttrriinngg or an XXttGGeettVVaalluueess call on the
vvaalluuee widget, when the string will be automatically freed,
and a new string is returned.  This string may be freed ear-
lier by calling the function XXaawwAAsscciiiiSSoouurrcceeFFrreeeeSSttrriinngg.


To add a new button to the Dialog widget use XXaawwDDiiaallooggAAdd--
ddBBuuttttoonn.

void XawDialogAddButton(_w, _n_a_m_e, _f_u_n_c, _c_l_i_e_n_t___d_a_t_a)
     Widget _w;
     String _n_a_m_e;
     XtCallbackProc _f_u_n_c;
     XtPointer _c_l_i_e_n_t___d_a_t_a;


_w         Specifies the Dialog widget.

_n_a_m_e      Specifies the name of the new Command button to be
          added to the Dialog.

_f_u_n_c      Specifies a callback function to be called when
          this button is activated.  If NULL is specified
          then no callback is added.




                             117766





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


_c_l_i_e_n_t___d_a_t_a
          Specifies the client_data to be passed to the
          _f_u_n_c.

This function is merely a shorthand for the code sequence:


{
          Widget button = XtCreateManagedWidget(name, commandWidgetClass, w, NULL, ZERO);
          XtAddCallback(button, XtNcallback, func, client_data);
}



66..33..  FFoorrmm WWiiddggeett



Application Header file<X11/Xaw/Form.h>
Class Header file   <X11/Xaw/FormP.h>
Class               formWidgetClass
Class Name          Form
Superclass          Constraint



The Form widget can contain an arbitrary number of children
or subwidgets.  The Form provides geometry management for
its children, which allows individual control of the posi-
tion of each child.  Any combination of children can be
added to a Form.  The initial positions of the children may
be computed relative to the positions of previously created
children.  When the Form is resized, it computes new posi-
tions and sizes for its children.  This computation is based
upon information provided when a child is added to the Form.

The default width of the Form is the minimum width needed to
enclose the children after computing their initial layout,
with a margin of ddeeffaauullttDDiissttaannccee at the right and bottom
edges.  If a width and height is assigned to the Form that
is too small for the layout, the children will be clipped by
the right and bottom edges of the Form.

66..33..11..  RReessoouurrcceess

When creating a Form widget instance, the following
resources are retrieved from the argument list or from the
resource database:









                             117777





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


--------------------------------------------------------------------------------------------
NNaammee             CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
--------------------------------------------------------------------------------------------
accelerators     Accelerators     AcceleratorTable     NULL
ancestorSensitiveAncestorSensitiveBoolean         D    True
background       Background       Pixel                XtDefaultBackground
backgroundPixmap Pixmap           Pixmap               XtUnspecifiedPixmap
borderColor      BorderColor      Pixel                XtDefaultForeground
borderPixmap     Pixmap           Pixmap               XtUnspecifiedPixmap
borderWidth      BorderWidth      Dimension            1
children         ReadOnly         WidgetList      R    NULL
colormap         Colormap         Colormap             Parent's Colormap
defaultDistance  Thickness        int                  4
depth            Depth            int             C    Parent's Depth
destroyCallback  Callback         XtCallbackList       NULL
height           Height           Dimension       A    Enough space to contain all children
mappedWhenManagedMappedWhenManagedBoolean              True
numChildren      ReadOnly         Cardinal        R    0
screen           Screen           Screen          R    Parent's Screen
sensitive        Sensitive        Boolean              True
translations     Translations     TranslationTable     NULL
width            Width            Dimension       A    Enough space to contain all children
x                Position         Position             0
y                Position         Position             0
--------------------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.



                             117788





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

children       A list of all this composite widget's current
               children.

colormap       The colormap that this widget will use.

ddeeffaauullttDDiissttaannccee
               The default internal spacing for the chil-
               dren.  This is the default value for the con-
               straint resources hhoorriizzDDiissttaannccee and vveerrttDDiiss--
               ttaannccee.

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

height
width          The height and width of this widget in pix-
               els.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

numChildren    The number of children in this composite wid-
               get.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

translations   The event bindings associated with this wid-
               get.

x
y              The location of the upper left outside corner
               of this widget in its parent.






                             117799





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


66..33..22..  CCoonnssttrraaiinntt RReessoouurrcceess

Each child of the Form widget may request special layout
resources be applied to it.  These _c_o_n_s_t_r_a_i_n_t resources
allow the Form widget's children to specify individual lay-
out requirements.



----------------------------------------------------------------------------
NNaammee            CCllaassss        TTyyppee          NNootteess   DDeeffaauulltt VVaalluuee
----------------------------------------------------------------------------
bottom          Edge         XawEdgeType           XawRubber
fromHoriz       Widget       Widget                NULL (left edge of Form)
fromVert        Widget       Widget                NULL (top edge of Form)
horizDistance   Thickness    int                   ddeeffaauullttDDiissttaannccee resource
left            Edge         XawEdgeType           XawRubber
resizable       Boolean      Boolean               FALSE
right           Edge         XawEdgeType           XawRubber
top             Edge         XawEdgeType           XawRubber
vertDistance    Thickness    int                   ddeeffaauullttDDiissttaannccee resource
----------------------------------------------------------------------------


bboottttoomm
lleefftt
rriigghhtt
ttoopp            What to do with this edge of the child when
               the parent is resized.  This resource may be
               any eeddggeeTTyyppee.  See LLaayyoouutt SSeemmaannttiiccss for
               details.

ffrroommHHoorriizz
ffrroommVVeerrtt       Which widget this child should be placed
               underneath (or to the right of).  If a value
               of NULL is specified then this widget will be
               positioned relative to the edge of the par-
               ent.

hhoorriizzDDiissttaannccee
vveerrttDDiissttaannccee   The amount of space, in pixels, between this
               child and its left or upper neighbor.

rreessiizzaabbllee      If this resource is FFaallssee then the parent
               widget will ignore all geometry request made
               by this child.  The parent may still resize
               this child itself, however.

66..33..33..  LLaayyoouutt SSeemmaannttiiccss

The Form widget uses two different sets of layout semantics.
One is used when initially laying out the children.  The
other is used when the Form is resized.




                             118800





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The first layout method uses the ffrroommVVeerrtt and ffrroommHHoorriizz
resources to place the children of the Form.  A single pass
is made through the Form widget's children in the order that
they were created.  Each child is then placed in the Form
widget below or to the right of the widget specified by the
ffrroommVVeerrtt and ffrroommHHoorriizz resources.  The distance the new
child is placed from its left or upper neighbor is deter-
mined by the hhoorriizzDDiissttaannccee and vveerrttDDiissttaannccee resources.  This
implies some things about how the order of creation affects
the possible placement of the children.  The Form widget
registers a string to widget converter which does not post-
pone conversion and does not cache conversion results.

The second layout method is used when the Form is resized.
It does not matter what causes this resize, and it is possi-
ble for a resize to happen before the widget becomes visible
(due to constraints imposed by the parent of the Form).
This layout method uses the bboottttoomm, ttoopp, lleefftt, and rriigghhtt
resources.  These resources are used to determine what will
happen to each edge of the child when the Form is resized.
If a value of XXaawwCChhaaiinn_<_s_o_m_e_t_h_i_n_g_> is specified, the the edge
of the child will remain a fixed distance from the _c_h_a_i_n
edge of the Form.  For example if XXaawwCChhaaiinnLLeefftt is specified
for the rriigghhtt resource of a child then the right edge of
that child will remain a fixed distance from the left edge
of the Form widget.  If a value of XXaawwRRuubbbbeerr is specified,
that edge will grow by the same percentage that the Form
grew.  For instance if the Form grows by 50% the left edge
of the child (if specified as XXaawwRRuubbbbeerr will be 50% farther
from the left edge of the Form).  One must be very careful
when specifying these resources, for when they are specified
incorrectly children may overlap or completely occlude other
children when the Form widget is resized.


------------------------------------------------------------------------------------
EEddggee TTyyppee         RReessoouurrccee NNaammee   DDeessccrriippttiioonn
------------------------------------------------------------------------------------
XawChainBottom    ChainBottom     Edge remains a fixed distance from bottom of Form
XawChainLeft      ChainLeft       Edge remains a fixed distance from left of Form
XawChainRight     ChainRight      Edge remains a fixed distance from right of Form
XawChainTop       ChainTop        Edge remains a fixed distance from top of Form
XawRubber         Rubber          Edges will move a proportional distance
------------------------------------------------------------------------------------


66..33..33..11..  EExxaammppllee

If you wish to force the Form to never resize one or more of
its children, then set lleefftt and rriigghhtt to XXaawwCChhaaiinnLLeefftt and
ttoopp and bboottttoomm to XXaawwCChhaaiinnTToopp.  This will cause the child to
remain a fixed distance from the top and left edges of the
Form, and never to resize.




                             118811





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


66..33..44..  CCoonnvveenniieennccee RRoouuttiinneess

To force or defer a re-layout of the Form, use
_X_a_w_F_o_r_m_D_o_L_a_y_o_u_t.

void XawFormDoLayout(_w, _d_o___l_a_y_o_u_t)
     Widget _w;
     Boolean _d_o___l_a_y_o_u_t;


_w         Specifies the Form widget.

_d_o___l_a_y_o_u_t Specifies whether the layout of the Form widget is
          enabled (TTrruuee) or disabled (FFaallssee).

When making several changes to the children of a Form widget
after the Form has been realized, it is a good idea to dis-
able relayout until after all changes have been made.


66..44..  PPaanneedd WWiiddggeett



Application Header file<X11/Xaw/Paned.h>
Class Header file   <X11/Xaw/PanedP.h>
Class               panedWidgetClass
Class Name          Paned
Superclass          Constraint



The Paned widget manages children in a vertically or hori-
zontally tiled fashion.  The panes may be dynamically
resized by the user by using the _g_r_i_p_s that appear near the
right or bottom edge of the border between two panes.

The Paned widget may accept any widget class as a pane
eexxcceepptt Grip.  Grip widgets have a special meaning for the
Paned widget, and adding a Grip as its own pane will confuse
the Paned widget.

66..44..11..  UUssiinngg tthhee PPaanneedd WWiiddggeett

The grips allow the panes to be resized by the user.  The
semantics of how these panes resize is somewhat complicated,
and warrants further explanation here.  When the mouse
pointer is positioned on a grip and pressed, an arrow is
displayed that indicates the pane that is to be to be
resized.  While keeping the mouse button down, the user can
move the grip up and down (or left and right).  This, in
turn, changes the size of the pane.  The size of the Paned
widget will not change.   Instead, it chooses another pane
(or panes) to resize. For more details on which pane it



                             118822





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


chooses to resize, see LLaayyoouutt SSeemmaannttiiccss.

One pointer binding allows the border between two panes to
be moved, without affecting any of the other panes.  When
this occurs the pointer will change to an arrow that points
along the pane border.

The default bindings for the Paned widget's grips are:

-----------------------------------------------------------------------
MMoouussee bbuuttttoonn   PPaannee ttoo RReessiizzee -- VVeerrttiiccaall   PPaannee ttoo RReessiizzee -- HHoorriizzoonnttaall
-----------------------------------------------------------------------
1 (left)       above the grip              left of the grip
2 (middle)     adjust border               adjust border
3 (right)      below the grip              right of the grip
-----------------------------------------------------------------------


66..44..22..  RReessoouurrcceess

When creating a Paned widget instance, the following
resources are retrieved from the argument list or the
resource database:


------------------------------------------------------------------------------------
NNaammee                   CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
------------------------------------------------------------------------------------
accelerators           Accelerators     AcceleratorTable     NULL
ancestorSensitive      AncestorSensitiveBoolean         D    True
background             Background       Pixel                XtDefaultBackground
backgroundPixmap       Pixmap           Pixmap               XtUnspecifiedPixmap
betweenCursor          Cursor           Cursor          A    Depends on orientation
borderColor            BorderColor      Pixel                XtDefaultForeground
borderPixmap           Pixmap           Pixmap               XtUnspecifiedPixmap
borderWidth            BorderWidth      Dimension            1
children               ReadOnly         WidgetList      R    NULL
colormap               Colormap         Colormap             Parent's Colormap
cursor                 Cursor           Cursor               None
depth                  Depth            int             C    Parent's Depth
destroyCallback        Callback         XtCallbackList       NULL
gripCursor             Cursor           Cursor          A    Depends on orientation
gripIndent             GripIndent       Position             10
gripTranslations       Translations     TranslationTable     see below
height                 Height           Dimension       A    Depends on orientation
horizontalBetweenCursorCursor           Cursor               sb_up_arrow
horizontalGripCursor   Cursor           Cursor               sb_h_double_arrow
internalBorderColor    BorderColor      Pixel                XtDefaultForeground
internalBorderWidth    BorderWidth      Dimension            1
leftCursor             Cursor           Cursor               sb_left_arrow
lowerCursor            Cursor           Cursor               sb_down_arrow
mappedWhenManaged      MappedWhenManagedBoolean              True
numChildren            ReadOnly         Cardinal        R    0




                             118833





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


------------------------------------------------------------------------------------
NNaammee                   CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
------------------------------------------------------------------------------------
orientation            Orientation      Orientation          XtorientVertical
refigureMode           Boolean          Boolean              True
rightCursor            Cursor           Cursor               sb_right_arrow
screen                 Screen           Screen          R    Parent's Screen
sensitive              Sensitive        Boolean              True
translations           Translations     TranslationTable     NULL
upperCursor            Cursor           Cursor               sb_up_arrow
verticalBetweenCursor  Cursor           Cursor               sb_left_arrow
verticalGripCursor     Cursor           Cursor               sb_v_double_arrow
width                  Width            Dimension       A    Depends on orientation
x                      Paned            Position             0
y                      Paned            Position             0
------------------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.




                             118844





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


children       A list of all this composite widget's current
               children.

colormap       The colormap that this widget will use.

ccuurrssoorr         The cursor to use when the mouse pointer is
               over the Paned widget, but not in any of its
               children (children may also inherit this cur-
               sor).  It should be noted that the internal
               borders are actually part of the Paned wid-
               get, not the children.

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

ggrriippCCuurrssoorr     The cursor to use when the grips are not
               active.  The default value is vveerrttiiccaall--
               GGrriippCCuurrssoorr or hhoorriizzoonnttaallGGrriippCCuurrssoorr depending
               on the orientation of the Paned widget.

ggrriippIInnddeenntt     The amount of space left between the right
               (or bottom) edge of the Paned widget and all
               the grips.

ggrriippTTrraannssllaattiioonn
               Translation table that will be applied to all
               grips.

height
width          The height and width of this widget in pix-
               els.

hhoorriizzoonnttaallBBeettwweeeennCCuurrssoorr
vveerrttiiccaallBBeettwweeeennCCuurrssoorr
               The cursor to be used for the grip when
               changing the boundary between two panes.
               These resources allow the cursors to be dif-
               ferent depending on the orientation of the
               Paned widget.

hhoorriizzoonnttaallGGrriippCCuurrssoorr
vveerrttiiccaallGGrriippCCuurrssoorr
               The cursor to be used for the grips when they
               are not active. These resources allow the
               cursors to be different depending on the ori-
               entation of the Paned widget.

iinntteerrnnaallBBoorrddeerrCCoolloorr
               A pixel value which indexes the widget's col-
               ormap to derive the internal border color of
               the widget's window.  The class name of this



                             118855





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               resource allows _P_a_n_e_d_*_B_o_r_d_e_r_C_o_l_o_r_: _b_l_u_e to
               set the internal border color for the Paned
               widget.  An optimization is invoked if iinntteerr--
               nnaallBBoorrddeerrCCoolloorr and bbaacckkggrroouunndd are the same,
               and the internal borders are not drawn.
               iinntteerrnnaallBBoorrddeerrWWiiddtthh is still left between the
               panes, however.

iinntteerrnnaallBBoorrddeerrWWiiddtthh
               The width of the internal borders.  This is
               the amount of space left between the panes.
               The class name of this resource allows
               _P_a_n_e_d_*_B_o_r_d_e_r_W_i_d_t_h_: _3 to set the internal bor-
               der width for the Paned widget.

lleeffttCCuurrssoorr
rriigghhttCCuurrssoorr    The cursor used to indicate which is the
               _i_m_p_o_r_t_a_n_t pane to resize when the Paned wid-
               get is oriented horizontally.

lloowweerrCCuurrssoorr
uuppppeerrCCuurrssoorr    The cursor used to indicate which is the
               _i_m_p_o_r_t_a_n_t pane to resize when the Paned wid-
               get is oriented vertically.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

numChildren    The number of children in this composite wid-
               get.  This is not the same as the number of
               panes, since this also contains a grip for
               some of the panes, use XXaawwPPaanneeddGGeettNNuummSSuubb to
               retrieve the number of panes.

oorriieennttaattiioonn    The orientation to stack the panes.  This
               value can be either XXttoorriieennttVVeerrttiiccaall or XXttoo--
               rriieennttHHoorriizzoonnttaall.  A converter is registered
               for this resource that will convert the fol-
               lowing strings: vveerrttiiccaall and hhoorriizzoonnttaall.

rreeffiigguurreeMMooddee   This resource allows pane layout to be sus-
               pended.  If this value is FFaallssee, then no lay-
               out actions will be taken.  This may improve
               efficiency when adding or removing more than
               one pane from the Paned widget.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee



                             118866





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               or sseennssiittiivvee is FFaallssee.

translations   The event bindings associated with this wid-
               get.

x
y              The location of the upper left outside corner
               of this widget in its parent.

66..44..33..  CCoonnssttrraaiinntt RReessoouurrcceess

Each child of the Paned widget may request special layout
resources be applied to it.  These _c_o_n_s_t_r_a_i_n_t resources
allow the Paned widget's children to specify individual lay-
out requirements.


----------------------------------------------------------------------------------
NNaammee                CCllaassss               TTyyppee         NNootteess   DDeeffaauulltt VVaalluuee
----------------------------------------------------------------------------------
allowResize         Boolean             Boolean              False
max                 Max                 Dimension            Infinity
min                 Min                 Dimension            Height of Grips
preferredPaneSize   PreferredPaneSize   Dimension            ask child
resizeToPreferred   Boolean             Boolean              False
showGrip            ShowGrip            Boolean              True
skipAdjust          Boolean             Boolean              False
----------------------------------------------------------------------------------


aalllloowwRReessiizzee    If this value is FFaallssee the the Paned widget
               will disallow all geometry requests from this
               child.

mmaaxx
mmiinn            The absolute maximum or minimum size for this
               pane.  These values will never be overridden
               by the Paned widget.  This may cause some
               panes to be pushed off the bottom (or right)
               edge of the paned widget.

pprreeffeerrrreeddPPaanneeSSiizzee
               Normally the paned widget makes a QueryGeome-
               try call on a child to determine the pre-
               ferred size of the child's pane.  There are
               times when the application programmer or the
               user has a better idea of the preferred size
               of a pane.  Setting this resource causes the
               value passed to be interpreted as the pre-
               ferred size, in pixels, of this pane.

rreessiizzeeTTooPPrreeffeerrrreedd
               Determines whether or not to resize each pane
               to its preferred size when the Paned widget



                             118877





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               is resized.  See LLaayyoouutt SSeemmaannttiiccss for
               details.

sshhoowwGGrriipp       If TTrruuee then a grip will be shown for this
               pane.  The grip associated with a pane is
               either below or to the right of the pane.  No
               grip is ever shown for the last pane.

sskkiippAAddjjuusstt     This resource is used to determine which pane
               is forced to be resized.  Setting this value
               to TTrruuee makes this pane less likely to be
               forced to be resized.  See LLaayyoouutt SSeemmaannttiiccss
               for details.

66..44..44..  LLaayyoouutt SSeemmaannttiiccss

In order to make effective use of the Paned widget it is
helpful to know the rules it uses to determine which child
will be resized in any given situation.  There are three
rules used to determine which child is resized.  While these
rules are always the same, the panes that are searched can
change depending upon what caused the relayout.


LLaayyoouutt RRuulleess

11    Do not let a pane grow larger than its mmaaxx or smaller
     than its mmiinn.

22    Do not adjust panes with sskkiippAAddjjuusstt set.

33    Do not adjust panes away from their preferred size,
     although moving one closer to its preferred size is
     fine.

When searching the children the Paned widget looks for panes
that satisfy all the rules, and if unsuccessful then it
eliminates rule 3 and then 2.  Rule 1 is always enforced.

If the relayout is due to a resize or change in management
then the panes are searched from bottom to top.  If the
relayout is due to grip movement then they are searched from
the grip selected in the direction opposite the pane
selected.

66..44..44..11..  RReessiizziinngg PPaanneess ffrroomm aa GGrriipp AAccttiioonn

The pane above the grip is resized by invoking the Gri-
pAction with UUppLLeeffttPPaannee specified.  The panes below the grip
are each checked against all rules, then rules 2 and 1 and
finally against rule 1 only.  No pane above the chosen pane
will ever be resized.





                             118888





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The pane below the grip is resized by invoking the Gri-
pAction with LLoowwRRiigghhttPPaannee specified.  The panes above the
grip are each checked in this case.  No pane below the cho-
sen pane will ever be resized.

Invoking GripAction with TThhiissBBoorrddeerrOOnnllyy specified just moves
the border between the panes.  No other panes are ever
resized.

66..44..44..22..  RReessiizziinngg PPaanneess aafftteerr tthhee PPaanneedd wwiiddggeett iiss rreessiizzeedd..

When the Pane widget is resized it must determine a new size
for each pane.  There are two methods of doing this.  The
Paned widget can either give each pane its preferred size
and then resize the panes to fit, or it can use the current
sizes and then resize the panes to fit.  The rreessiizzeeTTooPPrree--
ffeerrrreedd resource allows the application to tell the Paned
widget whether to query the child about its preferred size
(subject to the the pprreeffeerrrreeddPPaanneeSSiizzee) or to use the current
size when refiguring the pane locations after the pane has
been resized.

There is one special case.  All panes assume they should
resize to their preferred size until the Paned widget
becomes visible to the user.

66..44..44..33..  MMaannaaggiinngg CChhiillddrreenn aanndd GGeeoommeettrryy MMaannaaggeemmeenntt

The Paned widget always resizes its children to their pre-
ferred sizes when a new child is managed, or a geometry man-
agement request is honored.  The Paned widget will first
attempt to resize itself to contain its panes exactly.  If
this is not possible then it will hunt through the children,
from bottom to top (right to left), for a pane to resize.

66..44..44..44..  SSppeecciiaall CCoonnssiiddeerraattiioonnss

When a user resizes a pane with the grips, the Paned widget
assumes that this new size is the preferred size of the
pane.

66..44..55..  GGrriipp TTrraannssllaattiioonnss

The Paned widget has no action routines of its own, as all
actions are handled through the grips.  The grips are each
assigned a default Translation table.



     <Btn1Down>:      GripAction(Start, UpLeftPane)
     <Btn2Down>:      GripAction(Start, ThisBorderOnly)
     <Btn3Down>:      GripAction(Start, LowRightPane)
     <Btn1Motion>:    GripAction(Move, UpLeftPane)
     <Btn2Motion>:    GripAction(Move, ThisBorderOnly)



                             118899





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


     <Btn3Motion>:    GripAction(Move, LowRightPane)
     Any<BtnUp>:      GripAction(Commit)



The Paned widget interprets the GGrriippAAccttiioonn as taking two
arguments.  The first argument may be any of the following:

SSttaarrtt     Sets up the Paned widget for resizing and changes
          the cursor of the grip.  The second argument
          determines which pane will be resized, and can
          take on any of the three values shown above.

MMoovvee      The internal borders are drawn over the current
          pane locations to animate where the borders would
          actually be placed if you were to move this border
          as shown.  The second argument must match the sec-
          ond argument that was passed to the SSttaarrtt action,
          that began this process.  If these arguments are
          not passed, the behavior is undefined.

CCoommmmiitt    This argument causes the Paned widget to commit
          the changes selected by the previously started
          action.  The cursor is changed back to the grip's
          inactive cursor.  No second argument is needed in
          this case.

66..44..66..  CCoonnvveenniieennccee RRoouuttiinneess

To enable or disable a child's request for pane resizing,
use _X_a_w_P_a_n_e_d_A_l_l_o_w_R_e_s_i_z_e:

void XawPanedAllowResize(_w, _a_l_l_o_w___r_e_s_i_z_e)
     Widget _w;
     Boolean _a_l_l_o_w___r_e_s_i_z_e;


_w         Specifies the child pane.

_a_l_l_o_w___r_e_s_i_z_e
          Specifies whether or not resizing requests for
          this child will be granted by the Paned widget.

If allow_resize is TTrruuee, the Paned widget allows geometry
requests from the child to change the pane's height. If
allow_resize is FFaallssee, the Paned widget ignores geometry
requests from the child to change the pane's height. The
default state is TTrruuee before the Pane is realized and FFaallssee
after it is realized.  This procedure is equivalent to
changing the aalllloowwRReessiizzee constraint resource for the child.


To change the minimum and maximum height settings for a
pane, use _X_a_w_P_a_n_e_d_S_e_t_M_i_n_M_a_x:



                             119900





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


void XawPanedSetMinMax(_w, _m_i_n, _m_a_x)
     Widget _w;
     int _m_i_n, _m_a_x;


_w         Specifies the child pane.

_m_i_n       Specifies the new minimum height of the child,
          expressed in pixels.

_m_a_x       Specifies new maximum height of the child,
          expressed in pixels.

This procedure is equivalent to setting the mmiinn and mmaaxx con-
straint resources for the child.


To retrieve the minimum and maximum height settings for a
pane, use _X_a_w_P_a_n_e_d_G_e_t_M_i_n_M_a_x:

void XawPanedGetMinMax(_w, _m_i_n___r_e_t_u_r_n, _m_a_x___r_e_t_u_r_n)
     Widget _w;
     int _*_m_i_n___r_e_t_u_r_n, _*_m_a_x___r_e_t_u_r_n;


_w         Specifies the child pane.

_m_i_n___r_e_t_u_r_n
          Returns the minimum height of the child, expressed
          in pixels.

_m_a_x___r_e_t_u_r_n
          Returns the maximum height of the child, expressed
          in pixels.

This procedure is equivalent to getting the mmiinn and mmaaxx
resources for this child child.


To enable or disable automatic recalculation of pane sizes
and positions, use _X_a_w_P_a_n_e_d_S_e_t_R_e_f_i_g_u_r_e_M_o_d_e:

void XawPanedSetRefigureMode(_w, _m_o_d_e)
     Widget _w;
     Boolean _m_o_d_e;


_w         Specifies the Paned widget.

_m_o_d_e      Specifies whether the layout of the Paned widget
          is enabled (TTrruuee) or disabled (FFaallssee).

When making several changes to the children of a Paned wid-
get after the Paned has been realized, it is a good idea to



                             119911





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


disable relayout until after all changes have been made.


To retrieve the number of panes in a paned widget use XXaaww--
PPaanneeddGGeettNNuummSSuubb:

int XawPanedGetNumSub(_w)
     Widget _w;


_w         Specifies the Paned widget.

This function returns the number of panes in the Paned wid-
get.  This is nnoott the same as the number of children, since
the grips are also children of the Paned widget.

66..55..  PPoorrtthhoollee WWiiddggeett



Application Header file<X11/Xaw/Porthole.h>
Class Header file   <X11/Xaw/PortholeP.h>
Class               portholeWidgetClass
Class Name          Porthole
Superclass          Composite



The Porthole widget provides geometry management of a list
of arbitrary widgets, only one of which may be managed at
any particular time.  The managed child widget is reparented
within the porthole and is moved around by the application
(typically under the control of a Panner widget).

66..55..11..  RReessoouurrcceess

When creating a Porthole widget instance, the following
resources are retrieved from the argument list or from the
resource database:


----------------------------------------------------------------------------
NNaammee             CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
----------------------------------------------------------------------------
accelerators     Accelerators     AcceleratorTable     NULL
ancestorSensitiveAncestorSensitiveBoolean         D    True
background       Background       Pixel                XtDefaultBackground
backgroundPixmap Pixmap           Pixmap               XtUnspecifiedPixmap
borderColor      BorderColor      Pixel                XtDefaultForeground
borderPixmap     Pixmap           Pixmap               XtUnspecifiedPixmap
borderWidth      BorderWidth      Dimension            1
children         ReadOnly         WidgetList      R    NULL
colormap         Colormap         Colormap             Parent's Colormap




                             119922





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


----------------------------------------------------------------------------
NNaammee             CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
----------------------------------------------------------------------------
depth            Depth            int             C    Parent's Depth
destroyCallback  Callback         XtCallbackList       NULL
height           Height           Dimension       A    see LLaayyoouutt SSeemmaannttiiccss
mappedWhenManagedMappedWhenManagedBoolean              True
numChildren      ReadOnly         Cardinal        R    0
reportCallback   ReportCallback   Callback             NULL
screen           Screen           Screen          R    Parent's Screen
sensitive        Sensitive        Boolean              True
translations     Translations     TranslationTable     NULL
width            Width            Dimension       A    see LLaayyoouutt SSeemmaannttiiccss
x                Position         Position             0
y                Position         Position             0
----------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.




                             119933





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


children       A list of all this composite widget's current
               children.

colormap       The colormap that this widget will use.

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

height
width          The height and width of this widget in pix-
               els.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

numChildren    The number of children in this composite wid-
               get.

rreeppoorrttCCaallllbbaacckk A list of functions to invoke whenever the
               managed child widget changes size or posi-
               tion.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

translations   The event bindings associated with this wid-
               get.

x
y              The location of the upper left outside corner
               of this widget in its parent.

66..55..22..  LLaayyoouutt SSeemmaannttiiccss

The Porthole widget allows its managed child to request any
size that is as large or larger than the Porthole itself and
any location so long as the child still obscures all of the
Porthole.  This widget typically is used with a Panner wid-
get.

66..55..33..  PPoorrtthhoollee CCaallllbbaacckkss

The functions registered on the rreeppoorrttCCaallllbbaacckk list are
invoked whenever the managed child changes size or position:



                             119944





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


void ReportProc(_p_o_r_t_h_o_l_e, _c_l_i_e_n_t___d_a_t_a, _r_e_p_o_r_t)
     Widget _p_o_r_t_h_o_l_e;
     XtPointer _c_l_i_e_n_t___d_a_t_a;
     XtPointer _r_e_p_o_r_t;    /* (XawPannerReport *) */


_p_o_r_t_h_o_l_e  Specifies the Porthole widget.

_c_l_i_e_n_t___d_a_t_a
          Specifies the client data.

_r_e_p_o_r_t    Specifies a pointer to an XXaawwPPaannnneerrRReeppoorrtt struc-
          ture containing the location and size of the
          slider and the size of the canvas.


66..66..  TTrreeee WWiiddggeett



Application Header file<X11/Xaw/Tree.h>
Class Header file   <X11/Xaw/TreeP.h>
Class               treeWidgetClass
Class Name          Tree
Superclass          Constraint



The Tree widget provides geometry management of arbitrary
widgets arranged in a directed, acyclic graph (i.e., a
tree).  The hierarchy is constructed by attaching a con-
straint resource called ttrreeeePPaarreenntt to each widget indicating
which other node in the tree should be treated as the wid-
get's superior.  The structure of the tree is shown by lay-
ing out the nodes in the standard format for tree diagrams
with lines drawn connecting each node with its children.

The Tree sizes itself according to the needs of its children
and is not intended to be resized by its parent.  Instead,
it should be placed inside another composite widget (such as
the PPoorrtthhoollee or VViieewwppoorrtt) that can be used to scroll around
in the tree.

66..66..11..  RReessoouurrcceess

When creating a Tree widget instance, the following
resources are retrieved from the argument list or from the
resource database:









                             119955





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


----------------------------------------------------------------------------
NNaammee             CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
----------------------------------------------------------------------------
accelerators     Accelerators     AcceleratorTable     NULL
ancestorSensitiveAncestorSensitiveBoolean         D    True
autoReconfigure  AutoReconfigure  Boolean              False
background       Background       Pixel                XtDefaultBackground
backgroundPixmap Pixmap           Pixmap               XtUnspecifiedPixmap
borderColor      BorderColor      Pixel                XtDefaultForeground
borderPixmap     Pixmap           Pixmap               XtUnspecifiedPixmap
borderWidth      BorderWidth      Dimension            1
children         ReadOnly         WidgetList      R    NULL
colormap         Colormap         Colormap             Parent's Colormap
depth            Depth            int             C    Parent's Depth
destroyCallback  Callback         XtCallbackList       NULL
foreground       Foreground       Pixel                XtDefaultForeground
gravity          Gravity          XtGravity            WestGravity
height           Height           Dimension       A    see LLaayyoouutt SSeemmaannttiiccss
hSpace           HSpace           Dimension            4
lineWidth        LineWidth        Dimension            0
mappedWhenManagedMappedWhenManagedBoolean              True
numChildren      ReadOnly         Cardinal        R    0
screen           Screen           Screen          R    Parent's Screen
sensitive        Sensitive        Boolean              True
vSpace           VSpace           Dimension            4
translations     Translations     TranslationTable     NULL
width            Width            Dimension       A    see LLaayyoouutt SSeemmaannttiiccss
x                Position         Position             0
y                Position         Position             0
----------------------------------------------------------------------------


aauuttooRReeccoonnffiigguurree
               Whether or not to layout the tree every time
               a node is added or removed.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.

borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap



                             119966





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


               specified will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

children       A list of all this composite widget's current
               children.

colormap       The colormap that this widget will use.

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

foreground     A pixel value which indexes the widget's col-
               ormap to derive the foreground color of the
               widget's window.  This color is also used to
               render all 1's in a bbiittmmaapp one plane deep.

ggrraavviittyy        Specifies the side of the widget from which
               the tree should grow.  Valid values include
               WWeessttGGrraavviittyy, NNoorrtthhGGrraavviittyy, EEaassttGGrraavviittyy, and
               SSoouutthhGGrraavviittyy.  A converter is registered for
               this resource that will convert the following
               strings:  the legal values.

height
width          The height and width of this widget in pix-
               els.

hhSSppaaccee
vvSSppaaccee         The amount of space, in pixels, to leave
               between the children.  This resource speci-
               fies the amount of space left between the
               outermost children and the edge of the box.

lliinneeWWiiddtthh      The width of the lines from nodes that do not
               have a ttrreeeeGGCC constraint resource to their
               children.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

numChildren    The number of children in this composite wid-
               get.

screen         The screen on which this widget is displayed.
               This is not a settable resource.





                             119977





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.

translations   The event bindings associated with this wid-
               get.

x
y              The location of the upper left outside corner
               of this widget in its parent.

66..66..22..  CCoonnssttrraaiinntt RReessoouurrcceess

Each child of the Tree widget must specify its superior node
in the tree.  In addition, it may specify a GC to use when
drawing a line between it and its inferior nodes.

--------------------------------------------------------------------
NNaammee         CCllaassss        TTyyppee         NNootteess   DDeeffaauulltt VVaalluuee
--------------------------------------------------------------------
treeGC       TreeGC       GC                   NULL
treeParent   TreeParent   Widget               NULL
--------------------------------------------------------------------


ttrreeeeGGCC         This specifies the GC to use when drawing
               lines between this widget and its inferiors
               in the tree.  If this resource is not speci-
               fied, the Tree's ffoorreeggrroouunndd and lliinneeWWiiddtthh
               will be used.

ttrreeeePPaarreenntt     This specifies the superior node in the tree
               for this widget.  The default is for the node
               to have no superior (and to therefore be at
               the top of the tree).

66..66..33..  LLaayyoouutt SSeemmaannttiiccss

Each time a child is managed or unmanaged, the Tree widget
will attempt to reposition the remaining children to fix the
shape of the tree if the aauuttooRReeccoonnffiigguurree resource is set.
Children at the top (most superior) of the tree are drawn at
the side specified by the ggrraavviittyy resource.

After positioning all children, the Tree widget attempts to
shrink its own size to the minimum dimensions required for
the layout.

66..66..44..  CCoonnvveenniieennccee RRoouuttiinneess

The most efficient way to layout a tree is to set aauuttooRReeccoonn--
ffiigguurree to False and then use the XXaawwTTrreeeeFFoorrcceeLLaayyoouutt routine
to arrange the children.



                             119988





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


void XawTreeForceLayout(_w)
     Widget _w;


_w         Specifies the Tree widget.

66..77..  VViieewwppoorrtt WWiiddggeett



Application Header file<X11/Xaw/Viewport.h>
Class Header file   <X11/Xaw/ViewportP.h>
Class               viewportWidgetClass
Class Name          Viewport
Superclass          Form



The Viewport widget consists of a frame window, one or two
Scrollbars, and an inner window.  The size of the frame win-
dow is determined by the viewing size of the data that is to
be displayed and the dimensions to which the Viewport is
created.  The inner window is the full size of the data that
is to be displayed and is clipped by the frame window.  The
Viewport widget controls the scrolling of the data directly.
No application callbacks are required for scrolling.

When the geometry of the frame window is equal in size to
the inner window, or when the data does not require
scrolling, the Viewport widget automatically removes any
scrollbars.  The ffoorrcceeBBaarrss option causes the Viewport widget
to display all scrollbars permanently.

66..77..11..  RReessoouurrcceess

When creating a Viewport widget instance, the following
resources are retrieved from the argument list or the
resource database:


----------------------------------------------------------------------------
NNaammee             CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
----------------------------------------------------------------------------
accelerators     Accelerators     AcceleratorTable     NULL
allowHoriz       Boolean          Boolean              False
allowVert        Boolean          Boolean              False
ancestorSensitiveAncestorSensitiveBoolean         D    True
background       Background       Pixel                XtDefaultBackground
backgroundPixmap Pixmap           Pixmap               XtUnspecifiedPixmap
borderColor      BorderColor      Pixel                XtDefaultForeground
borderPixmap     Pixmap           Pixmap               XtUnspecifiedPixmap
borderWidth      BorderWidth      Dimension            1
children         ReadOnly         WidgetList      R    NULL




                             119999





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


----------------------------------------------------------------------------
NNaammee             CCllaassss            TTyyppee            NNootteessDDeeffaauulltt VVaalluuee
----------------------------------------------------------------------------
colormap         Colormap         Colormap             Parent's Colormap
depth            Depth            int             C    Parent's Depth
destroyCallback  Callback         XtCallbackList       NULL
forceBars        Boolean          Boolean              False
height           Height           Dimension            height of the child
mappedWhenManagedMappedWhenManagedBoolean              True
numChildren      ReadOnly         Cardinal        R    0
reportCallback   ReportCallback   XtCallbackList       NULL
screen           Screen           Screen          R    Parent's Screen
sensitive        Sensitive        Boolean              True
translations     Translations     TranslationTable     NULL
useBottom        Boolean          Boolean              False
useRight         Boolean          Boolean              False
width            Width            Dimension            width of the child
x                Position         Position             0
y                Position         Position             0
----------------------------------------------------------------------------


accelerators   A list of event to action bindings to be exe-
               cuted by this widget, even though the event
               occurred in another widget.  (See the _X
               _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
               for details).

aalllloowwHHoorriizz
aalllloowwVVeerrtt      If these resources are FFaallssee then the View-
               port will never create a scrollbar in this
               direction.  If it is TTrruuee then the scrollbar
               will only appear when it is needed, unless
               ffoorrcceeBBaarrss is TTrruuee.

ancestorSensitive
               The sensitivity state of the ancestors of
               this widget.  A widget is insensitive if
               either it or any of its ancestors is insensi-
               tive.  This resource should not be changed
               with XXttSSeettVVaalluueess, although it may be queried.

background     A pixel value which indexes the widget's col-
               ormap to derive the background color of the
               widget's window.

backgroundPixmap
               The background pixmap of this widget's win-
               dow.  If this resource is set to anything
               other than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap
               specified will be used instead of the back-
               ground color.





                             220000





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


borderColor    A pixel value which indexes the widget's col-
               ormap to derive the border color of the wid-
               get's window.

borderPixmap   The border pixmap of this widget's window.
               If this resource is set to anything other
               than XXttUUnnssppeecciiffiieeddPPiixxmmaapp, the pixmap speci-
               fied will be used instead of the border
               color.

borderWidth    The width of this widget's window border.

children       A list of all this composite widget's current
               children.

colormap       The colormap that this widget will use.

depth          The depth of this widget's window.

destroyCallback
               All functions on this list are called when
               this widget is destroyed.

ffoorrcceeBBaarrss      When TTrruuee the scrollbars that have been
               _a_l_l_o_w_e_d will always be visible on the screen.
               If FFaallssee the scrollbars will be visible only
               when the inner window is larger than the
               frame.

height
width          The height and width of this widget in pix-
               els.

mappedWhenManaged
               If this resource is TTrruuee, then the widget's
               window will automatically be mapped by the
               Toolkit when it is realized and managed.

numChildren    The number of children in this composite wid-
               get.

rreeppoorrttCCaallllbbaacckk These callbacks will be executed whenever the
               Viewport adjusts the viewed area of the
               child.  The call_data parameter is a pointer
               to an XawPannerReport structure.

screen         The screen on which this widget is displayed.
               This is not a settable resource.

sensitive      Whether or not the toolkit should pass user
               events to this widget.  The widget will not
               get input events if either aanncceessttoorrSSeennssiittiivvee
               or sseennssiittiivvee is FFaallssee.




                             220011





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


translations   The event bindings associated with this wid-
               get.

uusseeBBoottttoomm
uusseeRRiigghhtt       By default the scrollbars appear on the left
               and top of the screen.  These resources allow
               the vertical scrollbar to be placed on the
               right edge of the Viewport, and the horizon-
               tal scrollbar on the bottom edge of the View-
               port.

x
y              The location of the upper left outside corner
               of this widget in its parent.

66..77..22..  LLaayyoouutt SSeemmaannttiiccss

The Viewport widget manages a single child widget.  When the
size of the child is larger than the size of the Viewport,
the user can interactively move the child within the View-
port by repositioning the scrollbars.

The default size of the Viewport before it is realized is
the width and/or height of the child.  After it is realized,
the Viewport will allow its child to grow vertically or hor-
izontally if aalllloowwVVeerrtt or aalllloowwHHoorriizz are set, respectively.
If the corresponding vertical or horizontal scrollbar is not
enabled, the Viewport will propagate the geometry request to
its own parent and the child will be allowed to change size
only if the Viewport's parent allows it.  Regardless of
whether or not scrollbars are enabled in the corresponding
direction, if the child requests a new size smaller than the
Viewport size, the change will be allowed only if the parent
of the Viewport allows the Viewport to shrink to the appro-
priate dimension.

The scrollbar children of the Viewport are named hhoorriizzoonnttaall
and vveerrttiiccaall.  By using these names the programmer can spec-
ify resources for the individual scrollbars.  XXttSSeettVVaalluueess
can be used to modify the resources dynamically once the
widget ID has been obtained with XXttNNaammeeTTooWWiiddggeett.

                            Note

     Although the Viewport is a Subclass of the Form,
     no resources for the Form may be supplied for any
     of the children of the Viewport.  These con-
     straints are managed internally and are not meant
     for public consumption.








                             220022





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77




                         CChhaapptteerr 77

             CCrreeaattiinngg NNeeww WWiiddggeettss ((SSuubbccllaassssiinngg))

                  Written By: Ralph Swick




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 _T_e_m_p_l_a_t_e widget that is intended
to assist the novice widget programmer in writing a custom
widget.

Reasons for wishing to write a custom widget include:

+o  Providing a graphical interface not currently supported
   by any existing widget set.

+o  Convenient access to resource management procedures to
   obtain fonts, colors, etc., even if user customization is
   not desired.

+o  Convenient access to user input dispatch and translation
   management procedures.

+o  Access to callback mechanism for building higher-level
   application libraries.

+o  Customizing the interface or behavior of an existing wid-
   get to suit a special application need.

+o  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.

+o  Converting a non-Toolkit application to use the Toolkit.

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 Geometry-
Manager method can be used by the subclass.

Note that some trivial uses of a ``bare-bones'' widget may
be achieved by simply creating an instance of the Core



                             220033





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


widget.  The class variable to use when creating a Core wid-
get is _w_i_d_g_e_t_C_l_a_s_s.  The geometry of the Core widget is
determined entirely by the parent widget.

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:

+o  Allocate 2 drawing colors in addition to a background
   color.

+o  Allocate a text font.

+o  Execute an application-supplied function to handle expo-
   sure events.

+o  Execute an application-supplied function to handle user
   input events.

It is obvious that a completely general-purpose WindowWid-
getClass 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.


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 _X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _-_- _C _L_a_n_-
_g_u_a_g_e _I_n_t_e_r_f_a_c_e for complete details of the material out-
lined here.  Section 1.4 of the _I_n_t_r_i_n_s_i_c_s should be read in
conjunction with this section.

All Athena widgets have three separate files associated with
them:


+o  A "public" header file containing declarations needed by
   applications programmers

+o  A "private" header file containing additional declara-
   tions needed by the widget and any subclasses

+o  A source code file containing the implementation of the
   widget

This separation of functions into three files is suggested
for all widgets, but nothing in the Toolkit actually



                             220044





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


requires this format.  In particular, a private widget cre-
ated for a single application may easily combine the "pub-
lic" and "private" header files into a single file, or merge
the contents into another application header file.  Simi-
larly, the widget implementation can be merged into other
application code.


In the following example, the public header file
<_X_1_1_/_X_a_w_/_T_e_m_p_l_a_t_e_._h>, the private header file
<_X_1_1_/_X_a_w_/_T_e_m_p_l_a_t_e_P_._h> and the source code file
<_X_1_1_/_X_a_w_/_T_e_m_p_l_a_t_e_._c> will be modified to produce the "Win-
dowWidget" described above.  In each case, the files have
been designed so that a global string replacement of ``Tem-
plate'' and ``template'' with the name of your new widget,
using the appropriate case, can be done.

77..11..  PPuubblliicc HHeeaaddeerr FFiillee

The public header file contains declarations that will be
required by any application module that needs to refer to
the widget; whether to create an instance of the class, to
perform an _X_t_S_e_t_V_a_l_u_e_s operation, or to call a public rou-
tine implemented by the widget class.

The contents of the Template public header file,
<_X_1_1_/_X_a_w_/_T_e_m_p_l_a_t_e_._h>, are:


  /* XConsortium: Template.h,v 1.2 88/10/25 17:22:09 swick Exp $ */
  /* Copyright (c) X Consortium 1987, 1988 */

  #ifndef _Template_h
  #define _Template_h

  /****************************************************************
   *
   * Template widget
   *
   ****************************************************************/

  /* Resources:

   Name         Class        RepType Default Value
   ----                   -----      --------------------
   background   Background           PixelXtDefaultBackground
   border       BorderColor          PixelXtDefaultForeground
   borderWidth  BorderWidth          Dimension1
   destroyCallback        Callback   PointerNULL
   height       Height       Dimension0
   mappedWhenManaged      MappedWhenManagedBooleanTrue
   sensitive    Sensitive    Boolean True
   width        Width        Dimension0
   x                      Position   Position0



                             220055





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


   y                      Position   Position0

  */

  /* define any special resource names here that are not in <X11/StringDefs.h> */

  #define XtNtemplateResource "templateResource"

  #define XtCTemplateResource "TemplateResource"

  /* declare specific TemplateWidget class and instance datatypes */

  typedef struct _TemplateClassRec*  TemplateWidgetClass;
  typedef struct _TemplateRec*       TemplateWidget;

  /* declare the class constant */

  extern WidgetClass templateWidgetClass;

  #endif /* _Template_h */



You will notice that most of this file is documentation.
The crucial parts are the last 8 lines where macros for any
private resource names and classes are defined and where the
widget class datatypes and class record pointer are
declared.

For the "WindowWidget", we want 2 drawing colors, a callback
list for user input and an eexxppoosseeCCaallllbbaacckk callback list, and
we will declare three convenience procedures, so we need to
add




  /* Resources:
    ...
   callback     Callback  Callback   NULL
   drawingColor1          Color      PixelXtDefaultForeground
   drawingColor2          Color      PixelXtDefaultForeground
   exposeCallback         Callback   CallbackNULL
   font                   Font       XFontStruct*XtDefaultFont
    ...
   */

  #define XtNdrawingColor1 "drawingColor1"
  #define XtNdrawingColor2 "drawingColor2"
  #define XtNexposeCallback "exposeCallback"

  extern Pixel WindowColor1(/* Widget */);
  extern Pixel WindowColor2(/* Widget */);
  extern Font  WindowFont(/* Widget */);



                             220066





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


Note that we have chosen to call the input callback list by
the generic name, ccaallllbbaacckk, rather than a specific name.  If
widgets that define a single user-input action all choose
the same resource name then there is greater possibility for
an application to switch between widgets of different types.

77..22..  PPrriivvaattee HHeeaaddeerr FFiillee

The private header file contains the complete declaration of
the class and instance structures for the widget and any
additional private data that will be required by anticipated
subclasses of the widget.  Information in the private header
file is normally hidden from the application and is designed
to be accessed only through other public procedures; e.g.
_X_t_S_e_t_V_a_l_u_e_s.

The contents of the Template private header file,
<_X_1_1_/_X_a_w_/_T_e_m_p_l_a_t_e_P_._h>, are:


  /* XConsortium: TemplateP.h,v 1.2 88/10/25 17:31:47 swick Exp $ */

  /* Copyright (c) X Consortium 1987, 1988
   */

  #ifndef _TemplateP_h
  #define _TemplateP_h

  #include <X11/Xaw/Template.h>
  /* include superclass private header file */
  #include <X11/CoreP.h>

  /* define unique representation types not found in <X11/StringDefs.h> */

  #define XtRTemplateResource "TemplateResource"

  typedef struct {
    int empty;
  } TemplateClassPart;

  typedef struct _TemplateClassRec {
    CoreClassPart         core_class;
    TemplateClassPart     template_class;
  } TemplateClassRec;

  extern TemplateClassRec templateClassRec;

  typedef struct {
    /* resources */
    char* resource;
    /* private state */
  } TemplatePart;

  typedef struct _TemplateRec {



                             220077





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


    CorePart    core;
    TemplatePart          template;
  } TemplateRec;

  #endif /* _TemplateP_h */



The private header file includes the private header file of
its superclass, thereby exposing the entire internal struc-
ture of the widget.  It may not always be advantageous to do
this; your own project development style will dictate the
appropriate level of detail to expose in each module.

The "WindowWidget" needs to declare two fields in its
instance structure to hold the drawing colors, a resource
field for the font and a field for the expose and user input
callback lists:


  typedef struct {
    /* resources */
    Pixel color_1;
    Pixel color_2;
    XFontStruct* font;
    XtCallbackList expose_callback;
    XtCallbackList input_callback;
    /* private state */
    /* (none) */
  } WindowPart;


77..33..  WWiiddggeett SSoouurrccee FFiillee

The source code file implements the widget class itself.
The unique part of this file is the declaration and initial-
ization of the widget class record structure and the decla-
ration of all resources and action routines added by the
widget class.

The contents of the Template implementation file,
<_X_1_1_/_X_a_w_/_T_e_m_p_l_a_t_e_._c>, are:


  /* XConsortium: Template.c,v 1.2 88/10/25 17:40:25 swick Exp $ */

  /* Copyright (c) X Consortium 1987, 1988
   */

  #include <X11/IntrinsicP.h>
  #include <X11/StringDefs.h>
  #include "TemplateP.h"

  static XtResource resources[] = {



                             220088





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


  #define offset(field) XtOffsetOf(TemplateRec, template.field)
    /* {name, class, type, size, offset, default_type, default_addr}, */
      { XtNtemplateResource, XtCTemplateResource, XtRTemplateResource,
      sizeof(char*), offset(resource), XtRString, (XtPointer) "default" },
  #undef offset
  };

  static void TemplateAction(/* Widget, XEvent*, String*, Cardinal* */);

  static XtActionsRec actions[] =
  {
    /* {name,   procedure}, */
    {"template",          TemplateAction},
  };

  static char translations[] =
  " <Key>:      template() \n\
  ";

  TemplateClassRec templateClassRec = {
    { /* core fields */
    /* superclass         */ (WidgetClass) &widgetClassRec,
    /* class_name         */ "Template",
    /* widget_size        */ sizeof(TemplateRec),
    /* class_initialize   */ NULL,
    /* class_part_initialize */      NULL,
    /* class_inited       */ FALSE,
    /* initialize         */ NULL,
    /* initialize_hook    */ NULL,
    /* realize  */        XtInheritRealize,
    /* actions  */        actions,
    /* num_actions        */ XtNumber(actions),
    /* resources          */ resources,
    /* num_resources      */ XtNumber(resources),
    /* xrm_class          */ NULLQUARK,
    /* compress_motion    */ TRUE,
    /* compress_exposure  */ TRUE,
    /* compress_enterleave */        TRUE,
    /* visible_interest   */ FALSE,
    /* destroy  */        NULL,
    /* resize   */        NULL,
    /* expose   */        NULL,
    /* set_values         */ NULL,
    /* set_values_hook    */ NULL,
    /* set_values_almost  */ XtInheritSetValuesAlmost,
    /* get_values_hook    */ NULL,
    /* accept_focus       */ NULL,
    /* version  */        XtVersion,
    /* callback_private   */ NULL,
    /* tm_table */        translations,
    /* query_geometry     */ XtInheritQueryGeometry,
    /* display_accelerator   */      XtInheritDisplayAccelerator,
    /* extension          */ NULL
    },



                             220099





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


    { /* template fields */
    /* empty    */        0
    }
  };

  WidgetClass templateWidgetClass = (WidgetClass)&templateClassRec;


The resource list for the "WindowWidget" might look like the
following:


  static XtResource resources[] = {
  #define offset(field) XtOffsetOf(WindowWidgetRec, window.field)
    /* {name, class, type, size, offset, default_type, default_addr}, */
    { XtNdrawingColor1, XtCColor, XtRPixel, sizeof(Pixel),
                  offset(color_1), XtRString, XtDefaultForeground },
    { XtNdrawingColor2, XtCColor, XtRPixel, sizeof(Pixel),
                  offset(color_2), XtRString, XtDefaultForeground },
    { XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*),
                  offset(font), XtRString, XtDefaultFont },
    { XtNexposeCallback, XtCCallback, XtRCallback, sizeof(XtCallbackList),
                  offset(expose_callback), XtRCallback, NULL },
    { XtNcallback, XtCCallback, XtRCallback, sizeof(XtCallbackList),
                  offset(input_callback), XtRCallback, NULL },
  #undef offset
  };


The user input callback will be implemented by an action
procedure which passes the event pointer as call_data.  The
action procedure is declared as:


  /* ARGSUSED */
  static void InputAction(w, event, params, num_params)
    Widget w;
    XEvent *event;
    String *params;          /* unused */
    Cardinal *num_params; /* unused */
  {
    XtCallCallbacks(w, XtNcallback, (XtPointer)event);
  }

  static XtActionsRec actions[] =
  {
    /* {name,   procedure}, */
    {"input",   InputAction},
  };


and the default input binding will be to execute the input
callbacks on _K_e_y_P_r_e_s_s and _B_u_t_t_o_n_P_r_e_s_s:




                             221100





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


  static char translations[] =
  " <Key>:      input() \n\
    <BtnDown>:  input() \
  ";


In the class record declaration and initialization, the only
field that is different from the Template is the expose pro-
cedure:


  /* ARGSUSED */
  static void Redisplay(w, event, region)
    Widget w;
    XEvent *event;        /* unused */
    Region region;
  {
    XtCallCallbacks(w, XtNexposeCallback, (XtPointer)region);
  }

  WindowClassRec windowClassRec = {

    ...

    /* expose   */        Redisplay,



The "WindowWidget" will also declare three public procedures
to return the drawing colors and the font id, saving the
application the effort of constructing an argument list for
a call to _X_t_G_e_t_V_a_l_u_e_s:



  Pixel WindowColor1(w)
    Widget w;
  {
    return ((WindowWidget)w)->window.color_1;
  }

  Pixel WindowColor2(w)
    Widget w;
  {
    return ((WindowWidget)w)->window.color_2;
  }

  Font WindowFont(w)
    Widget w;
  {
    return ((WindowWidget)w)->window.font->fid;
  }





                             221111





AAtthheennaa WWiiddggeett SSeett                               lliibbXXaaww 11..00..77


The "WindowWidget" is now complete.  The application can
retrieve the two drawing colors from the widget instance by
calling either _X_t_G_e_t_V_a_l_u_e_s, or the WWiinnddoowwCCoolloorr functions.
The actual window created for the "WindowWidget" is avail-
able by calling the _X_t_W_i_n_d_o_w function.




















































                             221122








                     TTaabbllee ooff CCoonntteennttss


Acknowledgments  . . . . . . . . . . . . . . . . . . . .   v
Chapter 1 - Athena Widgets and The Intrinsics  . . . . .   1
     Introduction to the X Toolkit . . . . . . . . . . .   1
     Terminology . . . . . . . . . . . . . . . . . . . .   2
     Underlying Model  . . . . . . . . . . . . . . . . .   4
     Input Focus . . . . . . . . . . . . . . . . . . . .   8
Chapter 2 - Using Widgets  . . . . . . . . . . . . . . .   9
     Setting the Locale  . . . . . . . . . . . . . . . .   9
     Initializing the Toolkit  . . . . . . . . . . . . .  10
     Creating a Widget . . . . . . . . . . . . . . . . .  11
     Common Resources  . . . . . . . . . . . . . . . . .  12
     Resource Conversions  . . . . . . . . . . . . . . .  13
     Realizing a Widget  . . . . . . . . . . . . . . . .  14
     Processing Events . . . . . . . . . . . . . . . . .  15
     Standard Widget Manipulation Functions  . . . . . .  15
     Using the Client Callback Interface . . . . . . . .  18
     Programming Considerations  . . . . . . . . . . . .  20
     Example Programs  . . . . . . . . . . . . . . . . .  26
Chapter 3 - Simple Widgets . . . . . . . . . . . . . . .  27
     Command Widget  . . . . . . . . . . . . . . . . . .  28
     Grip Widget . . . . . . . . . . . . . . . . . . . .  34
     Label Widget  . . . . . . . . . . . . . . . . . . .  38
     List Widget . . . . . . . . . . . . . . . . . . . .  43
     Panner Widget . . . . . . . . . . . . . . . . . . .  50
     Repeater Widget . . . . . . . . . . . . . . . . . .  56
     Scrollbar Widget  . . . . . . . . . . . . . . . . .  62
     Simple Widget . . . . . . . . . . . . . . . . . . .  71
     StripChart Widget . . . . . . . . . . . . . . . . .  74
     Toggle Widget . . . . . . . . . . . . . . . . . . .  78
Chapter 4 - Menus  . . . . . . . . . . . . . . . . . . .  89
     Using the Menus . . . . . . . . . . . . . . . . . .  90
     SimpleMenu Widget . . . . . . . . . . . . . . . . .  90
     SmeBSB Object . . . . . . . . . . . . . . . . . . .  97
     SmeLine Object  . . . . . . . . . . . . . . . . . . 100
     Sme Object  . . . . . . . . . . . . . . . . . . . . 101
     MenuButton Widget . . . . . . . . . . . . . . . . . 103
Chapter 5 - Text Widgets.  . . . . . . . . . . . . . . . 111
     Text Widget for Users . . . . . . . . . . . . . . . 111
     Actions Supported by all Text Widgets . . . . . . . 116
     Default Translation Bindings  . . . . . . . . . . . 125
     Text Functions  . . . . . . . . . . . . . . . . . . 126
     AsciiText Widget  . . . . . . . . . . . . . . . . . 133
     AsciiSrc Object . . . . . . . . . . . . . . . . . . 140
     AsciiSink Object  . . . . . . . . . . . . . . . . . 145
     Customizing the Text Widget . . . . . . . . . . . . 147
     Text Widget . . . . . . . . . . . . . . . . . . . . 148
     TextSrc Object  . . . . . . . . . . . . . . . . . . 153
     TextSink Object . . . . . . . . . . . . . . . . . . 158
Chapter 6 - Composite and Constraint Widgets . . . . . . 166
     Box Widget  . . . . . . . . . . . . . . . . . . . . 167
     Dialog Widget . . . . . . . . . . . . . . . . . . . 170



                             iiiiii








     Form Widget . . . . . . . . . . . . . . . . . . . . 177
     Paned Widget  . . . . . . . . . . . . . . . . . . . 182
     Porthole Widget . . . . . . . . . . . . . . . . . . 192
     Tree Widget . . . . . . . . . . . . . . . . . . . . 195
     Viewport Widget . . . . . . . . . . . . . . . . . . 199
Chapter 7 - Creating New Widgets (Subclassing) . . . . . 203
Index  . . . . . . . . . . . . . . . . . . . . . . . . . 213


















































                             iivv


