Athena Widget Set -- C Language Interface

X Window System

X Version 11, Release 6.4

Chris D. Peterson
formerly MIT X Consortium

X Window System is a trademark of X Consortium, Inc.

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.

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.

Acknowledgments

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,

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

Chapter 1

Athena Widgets and The Intrinsics

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 Toolkit Intrinsics -- C Language
Interface.

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.

1.1. Introduction to the X Toolkit

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

Athena Widget Set X11, Release 6.4

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
Toolkit Intrinsics -- C Language Interface). 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

1.2. Terminology

In addition to the terms already defined for X programming
(see Xlib -- C Language X Interface), the following terms
are specific to the Intrinsics and Athena widget set and
used throughout this document.

Application programmer

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

Child

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

Athena Widget Set X11, Release 6.4

Class

The general group to which a specific object belongs.

Client

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

FullName

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

Instance

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

Method

A function or procedure implemented by a widget class.

Name

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.

Object

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.

Parent

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

Resource

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

Athena Widget Set X11, Release 6.4

Superclass

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

User

A person interacting with a workstation.

Widget

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

Widget class

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

Widget programmer

A programmer who adds new widgets to the X Toolkit.

1.3. Underlying Model

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.

Athena Widget Set X11, Release 6.4

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.

1.4. Conventions Used in this Manual

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 bold and can be function
names, symbols defined in include files, or structure
names. Arguments are printed in italics.

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 specifies or, in the case of multiple argu-
ments, the word specify. The explanations for all argu-
ments that are returned to you start with the word
returns or, in the case of multiple arguments, the word
return. The explanations for all arguments that you
can pass and are returned start with the words speci-
fies and returns.

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

Athena Widget Set X11, Release 6.4

1.5. Format of the Widget Reference Chapters

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

Application Header File
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.

Class Header File 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

Athena Widget Set X11, Release 6.4

``private'' header file.

Class This is the widget class of this widget.
This global symbol is passed to XtCre-
ateWidget so that the Intrinsics will
know which type of widget to create.

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

Superclass 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 XtSetValues.

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

Athena Widget Set X11, Release 6.4

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.

1.6. Input Focus

The Intrinsics define a resource on all Shell widgets that
interact with the window manager called input. This
resource requests the assistance of window manager in
acquiring the input focus. The resource defaults to False
in the Intrinsics, but is redefined to default to True when
an application is using the Athena widget set. An applica-
tion programmer may override this default and set the
resource back to False if the application does not need the
window manager to give it the input focus. See the X Tool-
kit Intrinsics -- C Language Interface for details on the
input resource.

Athena Widget Set X11, Release 6.4

Chapter 2

Using Widgets

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 Toolkit Intrin-
sics -- C Language Interface.

2.1. Setting the Locale

If it is desirable that the application take advantage of
internationalization (i18n), you must establish locale with
XtSetLanguageProc before XtDisplayInitialize or XtAppIni-
tialize is called. For full details, please refer to the
document X Toolkit Intrinsics -- C Language Interface, 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.

Athena Widget Set X11, Release 6.4

2.2. Initializing the Toolkit

You must call a toolkit initialization function before
invoking any other toolkit routines (besides locale setting,
above). XtAppInitialize 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(app_context_return, application_class, options, num_options,
argc_in_out, argv_in_out, fallback_resources, args, num_args)
XtAppContext *app_context_return;
String application_class;
XrmOptionDescRec options[];
Cardinal num_options;
int *argc_in_out;
String *argv_in_out[];
String *fallback_resources;
ArgList args;
Cardinal num_args;

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

application_class
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''.

options Specifies how to parse the command line for
any application-specific resources. The
options argument is passed as a parameter to
XrmParseCommand. For further information,
see Xlib -- C Language X Interface.

num_options Specifies the number of entries in the
options list.

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

argv_in_out Specifies the command line parameters.

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

Athena Widget Set X11, Release 6.4

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

num_args Specifies the number of arguments in args.

This function will remove the command line arguments that
the toolkit reads from argc_in_out, and argv_in_out. 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.

2.3. Creating a Widget

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

To allocate, initialize, and manage a widget, use XtCreateM-
anagedWidget.

Widget XtCreateManagedWidget(name, widget_class, parent, args, num_args)
String name;
WidgetClass widget_class;
Widget parent;
ArgList args;
Cardinal num_args;

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

widget_class
Specifies the widget class pointer for the created
widget.

parent Specifies the parent widget ID.

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

Athena Widget Set X11, Release 6.4

num_args 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 XtError routine is invoked to inform the
user of the error.

For further information, see X Toolkit Intrinsics -- C Lan-
guage Interface.

2.4. Common Resources

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:

--------------------------------------------------------------------------------
Name Class Type Default Value
--------------------------------------------------------------------------------
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 widget dependent
mappedWhenManaged MappedWhenManaged Boolean True
screen Screen Screen Parent's Screen
sensitive Sensitive Boolean True
translations Translations TranslationTable widget dependent
width Width Dimension widget dependent
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:

Athena Widget Set X11, Release 6.4

------------------------------------------------------------------------
Name Class Type Default Value
------------------------------------------------------------------------
callback Callback XtCallbackList NULL
cursor Cursor Cursor widget dependent
foreground Foreground Pixel XtDefaultForeground
insensitiveBorder Insensitive Pixmap GreyPixmap
------------------------------------------------------------------------

2.5. Resource Conversions

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.

2.5.1. Cursor Conversion

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

o A standard X cursor name from < X11/cursorfont.h >.
The names in cursorfont.h each describe a specific cur-
sor. The resource names for these cursors are exactly
like the names in this file except the XC_ is not used.
The cursor definition XC_gumby has a resource name of
gumby.

o Glyphs, as in FONT font-name glyph-index [[ font-name ]
glyph-index ]. 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.

Athena Widget Set X11, Release 6.4

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

2.5.2. Pixel Conversion

The string-to-pixel converter takes any name that is accept-
able to XParseColor (see Xlib -- C Language X Interface).
In addition this routine understands the special toolkit
symbols `XtDefaultForeground' and `XtDefaultBackground',
described in X Toolkit Intrinsics -- C Language Interface.
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'

2.5.3. Bitmap Conversion

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 bitmapFilePath resource--class BitmapFilePath. 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 bitmapFilePath resource is global
to the application, and may not be specified differently for
each widget that wishes to convert a cursor to bitmap. In
addition to the directories specified in the bitmapFilePath
resource a default directory is searched. When using POSIX
the default directory is /usr/include/X11/bitmaps.

2.6. Realizing a Widget

The XtRealizeWidget 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;

Athena Widget Set X11, Release 6.4

w Specifies the widget.

For further information about this function, see the X Tool-
kit Intrinsics -- C Language Interface.

2.7. Processing Events

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

void XtAppMainLoop(app_context)
XtAppContext app_context;

app_context
Specifies the application context of this applica-
tion. The value is normally returned by XtAppIni-
tialize.

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 Toolkit Intrinsics -- C Lan-
guage Interface.

2.8. Standard Widget Manipulation Functions

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

2.8.1. Mapping Widgets

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

Athena Widget Set X11, Release 6.4

void XtSetMappedWhenManaged(w, map_when_managed)
Widget w;
Boolean map_when_managed;

w Specifies the widget.

map_when_managed
Specifies the new value. If map_when_managed is
True, the widget is mapped automatically when it
is realized. If map_when_managed is False, the
client must call XtMapWidget or make a second call
to XtSetMappedWhenManaged to cause the child win-
dow to be mapped.

The definition for XtMapWidget 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 XtCreateWidget) and then use XtManageChildren 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(children, num_children)
WidgetList children;
Cardinal num_children;

children Specifies a list of children to add.

num_children
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
Toolkit Intrinsics -- C Language Interface.

2.8.2. Destroying Widgets

To destroy a widget instance of any type, use XtDestroyWid-
get.

Athena Widget Set X11, Release 6.4

void XtDestroyWidget(w)
Widget w;

w Specifies the widget.

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

2.8.3. Retrieving Widget Resource Values

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

void XtGetValues(w, args, num_args)
Widget w;
ArgList args;
Cardinal num_args;

w Specifies the widget.

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

num_args 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 ArgList contains a pointer to this storage
(e.g. x and y must be allocated as Position). For further
information, see the X Toolkit Intrinsics -- C Language
Interface.

2.8.4. Modifying Widget Resource Values

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

void XtSetValues(w, args, num_args)
Widget w;
ArgList args;
Cardinal num_args;

w Specifies the widget.

Athena Widget Set X11, Release 6.4

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

num_args 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 XtSetValues request is ignored.

For further information about these functions, see the X
Toolkit Intrinsics -- C Language Interface.

Note

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

2.9. Using the Client Callback Interface

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 CallbackProc(w, client_data, call_data)
Widget w;
XtPointer client_data;
XtPointer call_data;

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

client_data
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

Athena Widget Set X11, Release 6.4

is also frequently known as the closure.

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

Callbacks can be registered either by creating an argument
containing the callback list described below or by using the
special convenience routines XtAddCallback and XtAddCall-
backs. 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 XtCreateWidget. The list is of type XtCall-
backList:

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

The callback list must be allocated and initialized before
calling XtCreateWidget. 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 XtAdd-
Callback after the widget has been created.

void XtAddCallback(w, callback_name, callback, client_data)
Widget w;
String callback_name;
XtCallbackProc callback;
XtPointer client_data;

w Specifies the widget to add the callback to.

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

callback Specifies the callback procedure to add.

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

Athena Widget Set X11, Release 6.4

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

All widgets provide a callback list named destroyCallback
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 call_data argument is unused for destroy callbacks.

2.10. Programming Considerations

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

2.10.1. Writing Applications

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

1. Include <X11/Intrinsic.h> in your application programs.
This header file automatically includes <X11/Xlib.h>,
so all Xlib functions also are defined. It may also be
necessary to include < X11/StringDefs.h > when setting
up argument lists, as many of the XtNsomething 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,
<X11/Xaw/Label.h> and <X11/Xaw/Command.h>.

3. Call the XtAppInitialize function before invoking any
other toolkit or Xlib functions. For further informa-
tion, see Section 2.1 and the X Toolkit Intrinsics -- C
Language Interface.

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 XtN to help catch spelling errors.
For example, XtNlabel is defined for the label 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 XtCreateManagedWidget function. For further
information, see Section 2.2 and the X Toolkit Intrin-
sics -- C Language Interface.

6. If the widget has any callback routines, set by the
XtNcallback argument or the XtAddCallback function,

Athena Widget Set X11, Release 6.4

declare these routines within the application.

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

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

XtCreateManagedWidget(name, class, parent, args, num_args);
XtRealizeWidget(shell);
XtAppMainLoop(app_context);

For information about this function, see the X Toolkit
Intrinsics -- C Language Interface.

9. Link your application with libXaw (the Athena widgets),
libXmu (miscellaneous utilities), libXt (the X Toolkit
Intrinsics), libSM (Session Management), libICE (Inter-
Client Exchange), libXext (the extension library needed
for the shape extension code which allows rounded Com-
mand buttons), and libX11 (the core X library). The
following provides a sample command line:

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

2.10.2. Changing Resource Values

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 Xlib -- C Language X Interface
from many different locations at run time.
The locations most important to the applica-
tion programmer are the fallback resources
and the app-defaults file, (see X Toolkit
Intrinsics -- C Language Interface 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

Athena Widget Set X11, Release 6.4

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.

2.10.2.1. Specifying Resources

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.

Xrdb The xrdb 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.

Application Defaults
The application defaults (app-defaults) file
(normally in /usr/lib/X11/app-defaults/class-
name) for an application is loaded whenever
the application is started.

The resource specification has two colon-separated parts, a
name, and a value. The value is a string whose format is
dependent on the resource specified by name. Name 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.)

Athena Widget Set X11, Release 6.4

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

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

The root of all application widget trees is the widget
returned by XtAppInitialize. 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 (argv[0]) or the name of the application specified
using the standard -name 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 Testing.

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.

Final Words

Athena Widget Set X11, Release 6.4

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

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 Toolkit Intrinsics -- C Language
Interface and Xlib -- C Language X Interface.

2.10.2.2. Creating Argument Lists

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
XtNresource name. For example, the symbol for ``fore-
ground'' is XtNforeground. For further information, see the
X Toolkit Intrinsics -- C Language Interface.

Argument are specified by using the following structure:

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

Athena Widget Set X11, Release 6.4

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 XtNumber macro is used to compute the num-
ber of elements in the argument list, preventing simple pro-
gramming errors:

XtCreateWidget(name, class, parent, arglist, XtNumber(arglist));

The second approach is to use the XtSetArg 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, XtNumber
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 XtSetArg. As it
is currently implemented, XtSetArg is a macro that
dereferences the first argument twice.

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

Athena Widget Set X11, Release 6.4

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,
XtNumber 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, XtNumber can be used, as in the first
approach, for easier code maintenance.

2.11. Example Programs

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 contrib/examples/mit/Xaw, 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.

Athena Widget Set X11, Release 6.4

Chapter 3

Simple Widgets

Each of these widgets performs a specific user interface
function. They are simple 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.

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

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

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

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

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

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

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

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

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

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

Athena Widget Set X11, Release 6.4

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.

3.1. Command Widget

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

3.1.1. Resources

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

Athena Widget Set X11, Release 6.4

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 Tool-
kit Intrinsics -- C Language Interface 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 XtSetValues, 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 XtUnspecifiedPixmap, the pixmap

Athena Widget Set X11, Release 6.4

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

bitmap A bitmap to display instead of the label.
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 Converting Bitmaps 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 bitmap 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 XtUnspecifiedPixmap, 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
notify action is invoked.

colormap The colormap that this widget will use.

cornerRoundPercent
When a ShapeStyle of roundedRectangle 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 cursorName.

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

depth The depth of this widget's window.

Athena Widget Set X11, Release 6.4

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

encoding The encoding method used by the value of the
label resource. The value may be XawTextEn-
coding8bit or XawTextEncodingChar2b. When
international is set to true this resource is
not used.

font The text font to use when displaying the
label, when the international resource is
false.

fontSet The text font set to use when displaying the
label, when the international resource is
true.

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 bitmap 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 shapeStyle is rectangle, 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 false signals
the widget to use pre-R6 internationalization
(specifically, the lack thereof), such as
using fonts for displaying text, etc. A
value of true directs the widget to act in an
internationalized manner, such as utilizing
font sets for displaying text, etc.

Athena Widget Set X11, Release 6.4

justify Specifies left, center, or right alignment of
graphic within the widget. This resource may
be specified with the values XtJustifyLeft,
XtJustifyCenter, or XtJustifyRight. A con-
verter is registered for this resource that
will convert the following strings: left,
right, and center. 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 label, 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 encoding or
international, 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 True, 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 cursorName
resource.

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

resize Specifies whether the widget should attempt
to resize to its preferred dimensions when-
ever its resources are modified with XtSet-
Values. 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

Athena Widget Set X11, Release 6.4

get input events if either ancestorSensitive
or sensitive is False.

shapeStyle Nonrectangular widgets may be created using
this resource. Nonrectangular widgets are
supported only on a server that supports the
Shape Extension. 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: XmuShapeRect-
angle, XmuShapeOval, XmuShapeEllipse, and
XmuShapeRoundedRectangle. A converter is
registered for this resource that will con-
vert the following strings: rectangle, oval,
ellipse, and roundedRectangle.

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.

3.1.2. Command Actions

The Command widget supports the following actions:

o Switching the button's interior between the foreground
and background colors with set, unset, and reset.

o Processing application callbacks with notify

o Switching the internal border between highlighted and
unhighlighted states with highlight and unhighlight

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:

highlight(condition)
Displays the internal highlight border in the
color (foreground or background ) that con-
trasts with the interior color of the Command
widget. The conditions WhenUnset and Always
are understood by this action procedure. If

Athena Widget Set X11, Release 6.4

no argument is passed, WhenUnset is assumed.

unhighlight() Displays the internal highlight border in the
color (foreground or background ) that
matches the interior color of the Command
widget.

set() Enters the set state, in which notify is pos-
sible. This action causes the button to dis-
play its interior in the foreground color.
The label or bitmap is displayed in the back-
ground color.

unset() Cancels the set state and displays the inte-
rior of the button in the background color.
The label or bitmap is displayed in the fore-
ground color.

reset() Cancels any set or highlight and displays the
interior of the button in the background
color, with the label or bitmap displayed in
the foreground color.

notify() When the button is in the set state this
action calls all functions in the callback
list named by the callback resource. The
value of the call_data 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 set(), unset(), and reset() actions
have no effect, since there are no foreground and
background colors used in a multi-plane pixmap.

3.2. Grip Widget

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

Athena Widget Set X11, Release 6.4

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.

3.2.1. Resources

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

---------------------------------------------------------------------------------
Name Class Type NotesDefault Value
---------------------------------------------------------------------------------
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
---------------------------------------------------------------------------------

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

Athena Widget Set X11, Release 6.4

either it or any of its ancestors is insensi-
tive. This resource should not be changed
with XtSetValues, 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 XtUnspecifiedPixmap, 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 XtUnspecifiedPixmap, the pixmap speci-
fied will be used instead of the border
color.

borderWidth The width of this widget's window border.

callback All routines on this list are called whenever
the GripAction action routine is invoked.
The call_data contains all information passed
to the action routine. A detailed descrip-
tion is given below in the Grip Actions 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 cursorName.

cursorName The name of the symbol to use to represent
the pointer cursor. This resource will over-
ride the cursor 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.

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

Athena Widget Set X11, Release 6.4

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 True, 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 cursorName
resource.

pointerColorBackground
A pixel value which indexes the widget's
colormap to derive the background color of
the pointer symbol specified by the cursor-
Name 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 ancestorSensitive
or sensitive is False.

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.

3.2.2. Grip Actions

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

Athena Widget Set X11, Release 6.4

The GripAction routine executes the callbacks on the call-
back list, passing as call_data a pointer to a XawGripCall-
Data 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 event is a pointer to the input event
that triggered the action. params and num_params 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 Toolkit Intrinsics -- C Language Inter-
face.

3.3. Label Widget

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 font), or in a
multi-byte encoding (for use with a fontset). 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

Athena Widget Set X11, Release 6.4

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

3.3.1. Resources

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

------------------------------------------------------------------------------------------------
Name Class Type NotesDefault Value
------------------------------------------------------------------------------------------------
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 * internalHeight
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 * internalWidth
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

Athena Widget Set X11, Release 6.4

Toolkit Intrinsics -- C Language Interface
for details).