Digital PDFs

AA-MFOSA-TE

1998

97 pages

Original

3.2MB

Document:	ULTRIX Worksystem Software Guide to the X Toolkit Widgets: C Language Binding
Order Number:	AA-MFOSA-TE
Revision:	000
Pages:	97
Original Filename:

OCR Text

ULTRI
Worksystem Software

Guide to the X Toolkit Widgets:
C Language Binding

Order Number: AA-MFOSA-TE

ULTRIX Worksystem Software
Guide to the X Toolkit Widgets:
C Language Binding

Order No. AA-MF09A-TE

ULTRIX Worksystem Software, Version 2.0

Digital Equipment Corporation

The information in this document is subject to change without notice and should not be
construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation
assumes no responsibility for any errors that may appear in this document.
The software described in this document is furnished under a license and may be used or
copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is not
supplied by DIGITAL or its affiliated companies.

The following are trademarks of Digital Equipment Corporation:

DEC
DECnet
DECUS
DECwindows
MicroVAX

ULTRIX
ULTRIX-ll
ULTRIX-32
VAX
VAXstation

VMS
VT
XUI
ULTRIX Worksystem Software
~BmBDma

UNIX is a registered trademark of AT&T in the USA and other countries.
X Window System is a trademark of MIT.
This manual was written and produced by the ULTRIX Documentation Group in Nashua, New
Hampshire.

Contents

About This Ma nua I
1 Athena Widgets and Intrinsics
1.1 Introduction to the X Toolkit Library

1-1

1.2 Terminology ..............................................................................................

1-2

1.3 Underlying Model ....................................................................................

1-4

1.4 Design Principles and Philosophy.........................................................

1-4

1.4.1 Languages and Language Bindings ...........................................
1.4.2 Widget IDs ...................................................................................

1-4
1-5

2 Using Widgets
2.1 Initializing the Toolkit

2-1

2.2 Creating a Widget ..................................................................................

2-2

2.3 Common Arguments in the Widget Argument List ..........................

2-3

2.4 Realizing a Widget .................................................................. ................

2-5

2.5 Standard Widget Manipulation Functions ............................................

2-5

2.5.1 Mapping Widgets .........................................................................
2.5.2 Destroying Widgets .....................................................................
2.5.3 Retrieving Widget Resource Values ..........................................
2.5.4 Modifying Widget Resource Values ...........................................

2-5
2-6
2-7
2-7

2.6 Using the Client Callback Interface .....................................................

2-8

2.7 Programming Considerations ................................................................. 2-10
2.7.1 Writing Applications .................................................................... 2-10
2.7.2 Creating Argument Lists ............................................................ 2-11
2.7.3 Sample Program .......................................................................... 2-13

3 Athe na Widget Set
3.1 Command Widget ....................................................................................

3-1

3.2 Label Widget ...........................................................................................

3-4

3.3 Text Widget .............................................................................................

3-7

3.3.1 Selection Actions .........................................................................
3.3.2 Selecting Text ..............................................................................
3.3.3 Unhighlighting Text ....................................................................
3.3.4 Getting Selected Text Character Positions .............................
3.3.5 Replacing Text .............................................................................
3.3.6 Redisplaying Text ........................................................................
3.3.7 Changing Resources ....................................................................
3.3.8 Creating Sources and Sinks ......................................................

3-14
3-15
3-15
3-15
3-16
3-17
3-18
3-19

3.4 Scrollbar Widget

3-21

3.5 Viewport Widget ...................................................................................... 3-26
3.6 Box Widget .............................................................................................. 3-28
3.7 VPaned Widget ........................................................................................ 3-29
3.8 Form Widget ........................................................................................... 3-33
3.9 Dialog Widget .......................................................................................... 3-36
3.10 List Widget ............................................................................................ 3-37
3.10.1 Changing the List .....................................................................
3.10.2 Highlighting an Item ................................................................
3.10.3 Unhighlighting an Item ............................................................
3.10.4 Retrieving the Currently Selected Item .................................

3-40
3-41
3-41
3-42

3.11 Grip Widget ........................................................................................... 3-42

iv Contents

4 Creating a Custom Widget
4.1 Public Header File ..................................................................................

4-3

4.2 Private Header File ................................................................................

4-5

4.3 Widget Source File .................................................................................

4-6

Index

Contents v

About This Manual

The Guide to the X Toolkit Widgets: C Language Binding describes the
"Athena" widget set that you can use to write X Toolkit-based application
programs. Note that the information provided is specific to the C
programming language.

Audience
The audience for this manual is the application programmer who will use
the Athena widget set with the Intrinsics to build an X Toolkit-based
application.
This manual does not attempt to teach how to write an XUI application,
nor does it attempt to teach C programming concepts.

Organization
The Guide te the X Toolkit Widgets contains the following:
Chapter 1
Athena Widgets and Intrinsics
Chapter 2

Chapter 3

Chapter 4

Provides a general overview of the X Toolkit.
Using Widgets
Describes how to initialize the X toolkit, create a widget,
map widgets, destroy widgets, obtain or modify widget
resource values, and use callbacks. In addition, it discusses
the common arguments (resources) that are associated with
all of the Athena widgets.
Athena Widget Set
Describes, in detail, the eleven Athena widgets: Command
widget, Label widget, Text widget, Scrollbar widget, Viewport
widget, Box widget, VPaned widget, Form widget, Dialog
widget, List widget, and Grip widget.
Creating a Custom Widget
Provides programming hints for writing your own X Toolkitbased widget.

Related Documents
XU] Sty le Guide
Describes the XUI user interface and, hence, the "look and feel" of
an XUI application.
Guide to the XU] Toolkit: C Language Binding
Describes the XUI Toolkit widget set that you can use to write your
XUI-based application.

Guide to the Xlib Library: C Language Binding
Describes the low-level C functions that you can use to write your Xbased application.
X Window System Protocol: X Version 11
Describes the precise semantics of the XII protocol specification.

Conventions
The following typeface conventions are used in this manual:
special

In text, all function names, events, errors, constant names,
and pathnames are presented in this type.

UPPERCASE

Although the ULTRIX system differentiates between
lowercase and uppercase characters, uppercase is used
intentionally in this manual where it is applicable.
The primary occurrence for a given index entry is in this
type.

boldface

In addition, each function is introduced by a general discussion that
distinguishes it from other functions. The function declaration itself
follows, and each argument is specifically explained. General discussion of
the function, if any is required, follows the arguments.

viii About This Manual

Athena Widgets and Intrinsics

The Athena widget set and the Intrinsics make up the X Toolkit. In the
X Toolkit, a widget is the combination of an X window or subwindow and
its associated input and output semantics. The Athena widgets provide the
base functionality necessary to build a wide variety of application
environments. Because the Intrinsics mask implementation details from the
widget and application programmer, the Athena widgets and the application
environments built with them are fully compatible with the other widget
sets built with the Intrinsics. For information about the Intrinsics, see the
Guide to the XUI Toolkit Intrinsics.
The Athena widget set is a library package layered on top of the Intrinsics
and Xlib. 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.
To the extent possible, the X Toolkit is policy free. The application
environment, not the X Toolkit, defines, implements, and enforces:
•
•

Policy
Consistency

•
Style
Each individual widget implementation defines its own policy. The X
Toolkit design allows for but does not necessarily encourage the free mixing
of radically differing widget implementations.

1.1

Introduction to the X Toolkit Library

The X Toolkit library provides tools that simplify the design of application
user interfaces in the X Window System programming environment. It
assists application programmers by providing a set of common underlying
user-interface functions. It also lets widget programmers modify existing
widgets or add new widgets. By using the X Toolkit library in their
applications, programmers present a similar user interface across
applications to all workstation users.

The X Toolkit consists of:
•

A set of Intrinsics functions for building widgets

•

An architectural model for constructing widgets

•
A sample interface (widget set) for programming
While the majority of the Intrinsics functions are intended for the widget
programmer, a subset of the Intrinsics functions are to be used by
application programmers (see the Guide to the XUI Toolkit Intrinsics).
The architectural model lets the widget programmer design new widgets by
using the Intrinsics and by combining other widgets. The application
interface layers built on top of the X Toolkit include a coordinated set of
widgets and composition policies. Some of these widgets and policies are
specific to an application domain, and others are common across a number
of application domains.
The X Toolkit also can implement one or more application interface layers
to:
•

Verify the toolkit architecture

•

Provide a base set of widgets and composition policies that can be
incorporated in other application interface layers

•

Make the X Toolkit immediately usable by those application
programmers who find that a supplied application interface layer meets
their needs
The remainder of this chapter discusses the X Toolkit:
•

Terminology

•
•

Model
Design principles and philosophy

1.2

Terminology

In addition to the terms already defined for X programming (see the
Guide to the Xlib Library), the following terms are specific to the
Intrinsics and used throughout this book.
Application programmer
A programmer who uses the X Toolkit to produce an application user
interface.
Child
A widget that is contained within another ("parent") widget.
Class
The general group to which a specific object belongs.

1-2 Athena Widgets and Intrinsics

Client
A function that uses a widget in an application or for composing other
widgets.
Full name
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
The functions or procedures that a widget class implements.
Name
The name that is specific to an instance of a widget for a given
client.
Object
A software data abstraction consisting of private data and private and
public functions that operate on the private data. Users of the
abstraction can interact with the object only through calls to the
object's public functions. In the X Toolkit, some of the object's
public functions are called directly by the application, while others are
called indirectly when the application calls the common Intrinsics
functions. In general, if a function is common to all widgets, an
application uses a single Intrinsics function to invoke the function for
all types of widgets. If a function is unique to a single widget type,
the widget exports the function as another "Xt" 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.
Superclass
A larger class of which a specific class is a member. All members of
a class are also members of the .superclass.
User
A person interacting with a workstation.

Athena Widgets and Intrinsics 1-3

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 contained in a unique X window. The
X window ID for a widget is readily available from the widget ID, so
standard Xlib window manipulation procedures can operate on widgets.
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 implementing the widget. All program interaction with the
widget is performed by a set of operations (methods) that are defined
for the widget.
Widget semantics and widget layout geometry
Widget semantics are clearly separated from widget layout geometry.
Widgets are concerned with implementing specific user-interface
semantics. They have little control over issues such as their size or
placement relative to other widget peers. Mechanisms are provided
for associating geometric managers with widgets and for widgets to
make .suggestions about their own geometry.

1.4

Design Principles a nd Philosophy

The X Toolkit follows two design principles throughout, which cover
languages and language bindings as well as widget IDs.
1.4.1

Languages and Language Bindings

The X Toolkit facilitates access from objective languages. However, the X
Toolkit library is conveniently usable by application programs written in
nonobjective languages. Procedural interface guidelines are required when
the X Toolkit is used with nonobjective languages.

1-4 Athena Widgets and Intrinsics

The guidelines for the procedural interfaces are:
•

Strings are passed as null-terminated character arrays.

•

Most other arrays are passed using two parameters: a size and a
pointer to the first element.

•

Most numeric arguments are passed by value.

•

Structures as arguments are avoided, unless a method for building
them is provided for languages without pointers. Pointers embedded
in structures are allowed, but they should be avoided if an equivalent
alternative is available.

•

Pointers are not recommended as return arguments, unless they will
never have to be dereferenced by the caller. If they need to be
dereferenced, the caller should allocate storage and pass the address to
the procedure to fill in.

•
•

Procedures can be passed as parameters.
The ownership of dynamically allocated storage is determined on a
case-by-case basis. The application is also permitted to replace the
standard memory allocation and freeing routines used by the library at
build time.

1.4.2
Widget IDs
All references to widgets use a unique identifier that is known as the
widget ID. The widget ID is returned to the client by the XtCreateWidget
function. From an application programmer's perspective, a widget ID is an
opaque data type; no particular interpretation can be assigned to it. Given
a widget ID, you can retrieve the corresponding X window ID, the Display
and Screen structures, and other information by using Intrinsics functions.
From a widget programmer's perspective, the widget ID actually is a
pointer to a data structure known as the widget instance record. Several
parts of the data structure are common to all widget types, while other
parts are unique to a particular widget type. The widget's private data
that is associated with a particular widget instance normally is included
directly in the widget instance record.

Athena Widgets and Intrinsics 1·5

Using Widgets 2

Widgets serve as the primary tools for building a user interface or
application environment. The widget set consists of primitive widgets (for
example, a command button) and composite widgets (for example, a Dialog
widget) .
The remaining chapters of this guide explain the widgets and the geometry
managers that work together to provide a set of user-interface components.
These user-interface components serve as a default interface for application
programmers who do not want to implement their own widgets. In
addition, they serve as examples or a starting point for those widget
programmers who, using the Intrinsics mechanisms, want to implement
alternative application programming interfaces.
This chapter discusses the common features of the X Toolkit widgets.

2.1

Initializing the Toolkit

You must invoke the toolkit initialization function Xtlnitialize before invoking
any other toolkit routines. Xtlnitialize opens the X server connection,
parses standard parts of the command line, and creates an initial widget
that is to serve as the root of a tree of widgets that will be created by
this application.
Widget Xt In i t i a I i ze (shell_name,

application_class,
num_o ptio ns, argc , argv)
S t r i n g shell_name;
S t r i n g application_class;
X r mO p t ion Des eRe C 0 ptio ns [] ;
Ca rd i na I num_options;
Car din a I * argc ;
S t r i n g argv [] ;

shell_name

options,

Specifies the name of the application shell widget instance,
which usually is something generic like "main".

application_class
Specifies the class name of this application, which usually is
the generic name for all instances of this application. By

convention, the class name is formed by reversing the case
of the application's first significant letter. For example, an
application named "xterm" would have a class name of
"XTerm".
options
Specifies how to parse the command line for any applicationspecific resources. The options argument is passed as a
parameter to XrmParseCommand. For further information,
see the Guide to the Xlib Library.
num_options Specifies the number of entries in the options list.
argc
Specifies a pointer to the number of command line
parameters.

argv
Specifies the command line parameters.
For further information about this function, see the Guide to the XUI
Toolkit Intrinsics.

2.2

Creating a Widget

Creating a widget is a three-step process. First, the widget 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 XtManageChild. 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
XtC reateManagedWidget. In addition, XtRealizeWidget is automatically
called when the child becomes managed if the parent is already realized.
To allocate and initialize a widget, use XtCreateWidget.

widget_class, parent,
num_args)

Widget XtCreateWidget(name,

args,

S t r i n g name;
Wi dgetC I ass widget_class;
Wid get parent;
A r g Lis t args;
Ca rd i na I num_args;

name

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

widget_class
parent
args

Specifies the widget class pointer for the created widget.
Specifies the parent widget ID.
Specifies the argument list. The argument list is a variablelength list composed of name and value pairs that contain
information pertaining to the specific widget instance being

2-2 Using Widgets

created.

num_args

For further information, see Section 2.7.2.

Specifies the number of arguments in the argument list.
When 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 the Guide to the XUI Toolkit Intrinsics.

2.3

Common Arguments in the Widget Argument List

Although a widget can have unique arguments that it understands, all
widgets have common arguments that provide some regularity of operation.
The common arguments allow arbitrary widgets to be managed by higherlevel components without regards to the individual widget type. All
widgets ignore any argument that they do not understand.
The following resources are retrieved from the argument list or from the
resource database by all X Toolkit widgets:
Name

Type

Default

XtNbackground
XtNbackgroundPixmap
XtNborderColor
XtNborderPixmap
XtNborderWidth
X tN destroyCallback
XtNheight
XtNmappedWhenManaged
XtN sensitive
XtNtranslations
XtNwidth
XtNx
XtNy

Pixel
Pixmap
Pixel
Pixmap
Dimension
XtCallbackList
Dimension
Boolean
Boolean
TranslationTable
Dimension
Position
Position

XtDefaultBackground
None
XtDefaultForeground
None
1
NULL
Widget dependent
True
True
None
Widget dependent
0
0

XtNbackground

Specifies the window's background color.

XtNbackgroundPixmap

Specifies the window's background pixmap.

XtNborderColor

Specifies the window's border color.

XtN borderPixmap

Specifies the window's border pixmap.

Using Widgets 2·3

XtNborderWidth

Specifies the width of the border in pixels.

XtNdestroyC all bac k

Specifies the callback for XtDestroyWidget.

XtNheight

Specifies the height of the widget.

XtNmappedWhenManaged

Specifies whether XtMapWidget is automatic.

XtNsensitive

Specifies whether the widget should receive input.

XtNtranslations

Specifies the event-to-action translations.

XtNwidth

Specifies the width of the widget.

XtNx

Specifies the x coordinate within the parent.

XtNy

Specifies the y coordinate within the parent.

The following additional resources are retrieved from the argument list or
from the resource database by many X Toolkit widgets:
Name

Type

Default

XtNcallback
XtNcursor
XtNforeground

x tCallbackList
Cursor
Pixel

NULL
None
XtDefaultForeground

XtNcaliback

Specifies the callback functions and client data.

XtNcursor

Specifies the pointer cursor.

XtNforeground

Specifies the foreground color.

The value for the XtNcursor resource can be specified in the resource
database as a string, which can be specified as one of the following:
•
•

A standard X cursor name from <X11/cursorfont.h>
FONT font-name glyph-index [ [ font-name ] glyph-index ]

•
A relative or absolute file name
The first font and glyph specify the cursor source pixmap. The second
font and glyph specify the cursor mask pixmap. The mask font defaults
to the source font, and the mask glyph index defaults to the source glyph
index.
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"

2-4 Using Widgets

is tried. If" msk" fails, no cursor mask will be used. If a relative file
name is used, the directory specified by the resource name bitmapFilePath
or class BitmapFilePath is added to the beginning of the file name. If the
bitmapFilePath resource is not defined, the default directory on a UNIXbased system is lusrlinclude/X11/bitmaps.

2.4

Realizing a Widget

The XtRealizeWidget function performs two tasks:
•

Creates an X window for the widget and, if it is a composite widget,
for each of its managed children.

•

Maps each window onto the screen.
void XtReal izeWidget(w)
Widget w;

Specifies the widget.

For further information about this function, see the Guide to the XUI
Toolkit Intrinsics.

2.5

Standard Widget Manipulation Functions

After a widget has been created, a client can interact with that widget by
calling either of the following:
•

One of the standard widget manipulation routines that provide
functions that all widgets support

•
A widget class-specific manipulation routine
The X Toolkit provides generic routines to provide the application
programmer access to a set of standard widget functions. These routines
let an application or composite widget manipulate widgets without requiring
explicit knowledge of the widget type. The standard widget manipulation
functions let you:
•

Control the location, size and mapping of widget windows

•

Destroy a widget instance

•
•

Obtain an argument value
Set an argument value

2.5.1

Mapping Widgets

By default, widget windows automatically are mapped (made viewable) by
XtRealizeWidget. This behavior can be changed by using
XtSetMappedWhenManaged, and it then is the client's responsibility to use
the XtMapWidget function to make the widget viewable.

Using Widgets 2·5

vo i d XtSetMappedWhenManaged (w,
Widget w;
Boo lean map_when_managed;

map_when_managed)

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

The definition for XtMapWidget is:
XtMapWidget(w)
Widget w;

Specifies the widget.
w
When you create several children in sequence for a common parent after it
has been realized, it is generally more efficient to construct a list of
children as they are created and use XtManageChildren to inform their
parent of them all at once, instead of causing each child to be managed
separately. By managing a list of children at one time, the parent can
avoid wasteful duplication of geometry processing and the associated
"screen flash".
vo i d XtManageCh i I d ren (children,
Wid get Lis t childre n ;
Ca r din a I num_children;

num_children)

Specifies a list of children to add.
children
num_children Specifies the number of children to add.
If the parent is already visible on the screen, it is especially important to
batch updates so that the minimum amount of visible window
reconfiguration is performed.
For further information about these functions, see the Guide to the XUI
Toolkit Intrinsics.
2.5.2

Destroying Widgets

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

2-6 Using Widgets

void XtDestroyWidget(w)
Widget 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 to the widget IDs of any children that the destroyed widget may have
had.
w

2.5.3
Retrieving Widget Resource Va lues
To retrieve the current value of a resource attribute associated with a
widget instance, use XtGetValues.
v 0 i d X t Get Val u e s ( w , args,
Widget w;
A r g Lis t args;
Ca rd i na I num_args;

num_args)

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.
Specifies the number of arguments in the argument list.

num_args

The arguments and values passed in the argument list are dependent on
the widget. Note that the caller is responsible for allocating space into
which the returned resource value is copied; the Arg List contains a pointer
to this storage. The caller must allocate storage of the type as
represented in the widget. For example, x and y must be allocated as
Position and so on. For further information, see the Guide to the XUI
Toolkit Intrinsics.

2.5.4
Modifying Widget Resource Values
To modify the current value of a resource attribute associated with a
widget instance, use XtSetValues.
v 0 i d X t Set Val u e s ( w , args,
Widget w;
A r g Lis t args;
Ca rd i na I num_args;

num_args)

Using Widgets 2-7

Specifies the widget.
Specifies a variable-length argument list 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 passed in the argument list 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 ofaXtSetValues request is ignored.
For further information about these functions, see the Guide to the XUI
Toolkit Intrinsics.
w
args

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

Using the Client Callback Interface

Widgets communicate changes in their state to their clients by means of a
callback facility. The format for a client's callback handler is:
v 0 i d CallbackProc (w , client_data,
Widget w;
cad d r _ t client_data;
cadd r _ t call_data;

call_data)

Specifies widget for which the callback is registered.
Specifies arbitrary client-supplied data that the widget should
pass back to the client when the widget executes the client's
callback procedure. This is a way for the client registering
the callback to also register client-specific data: a pointer to
additional information about the widget, a reason for invoking
the callback, and so on. It is perfectly normal to have
client_data of NULL if all necessary information is in the
widget. This field is also frequently known as the closure.
Specifies any callback-specific data the widget wants to pass
to the client. For example, when Scrollbar executes its

2-8 Using Widgets

jumpProc callback list, it passes the current position of the
thumb in the calLdata argument.
Callbacks can be registered with widgets in one of two ways. When the
widget is created, a pointer to a list of callback procedure and data pairs
can be passed in the argument list to XtCreateWidget. The list is of type
XtCalibackList:
typedef struct {
XtCallbackProc callback;
caddr_t 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 XtAddCaliback after
the widget has been created.
void XtAddCallback(w, callback_name, callback,
Widget w;
S t r i n g callback_name;
X t C a I I b a c k Pro c callback;
cad d r _ t client_data;
w

client_data)

Specifies the widget to add the callback to.

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

callback
client_data

Specifies the callback procedure to add.
Specifies the data to be passed to the callback when it is
invoked.
XtAddCaliback adds the specified callback to the list for the named widget.
All widgets provide a callback list named XtNdestroyCaliback where clients
can register procedures that are to be executed when the widget is
destroyed. The destroy callbacks are executed when the widget or an
ancestor is destroyed. The calLdata argument is unused for destroy
callbacks.
The Intrinsics provide additional functions for further manipulating a
callback list. For information about these functions, see XtCaliCalibacks,
XtRemoveCaliback, XtRemoveCalibacks, and XtRemoveAIiCalibacks in the
Guide to the XUI Toolkit Intrinsics.

Using Widgets 2-9

2.7

Programming Considerations

This section provides some guidelines to set up an application program that
uses the X Toolkit. This section discusses:
•
•
2.7.1

Writing applications
Creating argument lists
Writing Applications

When writing an application that uses the toolkit, you should make sure
that your application performs the following:
1.

Include < X11 /lntrinsic.h > in your application programs. This header
file automatically includes < X11/Xlib. h >, so all Xlib functions also are
defined.

Include the widget-specific header files for each widget type that you
need to use. For example, <X11/Labe/'h> and <X11/Command.h >.
Call the Xtlnitialize function before invoking any other toolkit or Xlib
functions. For further information, see Section 2.1 and the Guide to
the XUI Toolkit Intrinsics.
To pass attributes to the widget creation routines that will over-ride
any site or user customizations, set up argument lists. In this
document, a list of valid argument names that start with XtN is
provided in the discussion of each widget.
For further information, see Section 2.7.2.

8.
9.

When the argument list is set up, create the widget by using the
XtCreateWidget function. For further information, see Section 2.2 and
the Guide to the XUI Toolkit Intrinsics.
If the widget has any callback routines, which are usually defined by
the XtNcallback argument or the XtAddCallback function, declare these
routines within the application.
After a widget has been created, use XtManageChiid to manage it. If
there is no manipulation of the widget between XtCreateWidget and
XtManageChild, you can do this in a single step by using
XtCreateManagedWidget. For further information about these
functions, see the Guide to the XUI Toolkit Intrinsics.
After creating the initial widget hierarchy, windows must be created
for each widget by calling XtRealizeWidget on the top level widget.
Most applications now sit in a loop processing events using
XtMainLoop, for example:
XtCreateManagedWidgetC name, class, parent, args, num_args);
XtRealizeWidget(parent) ;

2-10 Using Widgets

x tMainLoop( ) ;

10.

For information about this function, see the Guide to the XUI Toolkit
Intrinsics.
Link your application with libXaw.a (the Athena widgets), IibXmu.a
(miscellaneous utilities), IibXt.a (the Intrinsics), and IibX11.a (the core
X library). The following provides a sample command line:
cc -0 application application.c -IXaw -IXmu -IXt -IX11

2.7.2
Creating Argument Lists
To set up an argument list for the inline specification of widget attributes,
you can use one of the four approaches discussed in this section. You
should use whichever approach fits the needs of the application and you
are most comfortable with. In general, argument lists should be kept as
short as possible to allow widget attributes to be specified through the
resource database. Whenever a client inserts a specific attribute value in
an argument list, the user is prevented from customizing the behavior of
the widget. Resource names in the resource database, by convention,
correspond to their symbolic names that are used in argument list without
the XtN prefix. For example, the resource name for XtNforeground is
"foreground". For further information, see the Guide to the XUI Toolkit
Intrinsics.
The Arg structure contains:
typedef struct {
String name;
XtArgVal value;
} Arg, *ArgList;
The first approach lets you statically initialize the argument list.
example:
static Arg arglist[] = {
{XtNwidth, (XtArgVal) 400},
{XtNheight, (XtArgVal) 300},

For

};

This approach makes it easy to add or delete new elements. The
XtNumber macro can be used to compute the number of elements in the
argument list, thus preventing simple programming errors. The following
provides an example:
XtCreateWidget( name, class, parent, arglist, XtNumberC arglist));

Using Widgets 2-11

The second approach lets you use the XtSetArg macro.
Arg arglist[10];
XtSetArg( arglist[l], XtNwidth, 400);
XtSetArg( arglist[2], XtNheight, 300);

For example:

To make it easier to insert and delete entries, you also can use a variable
index, as in this example:
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-decrement within the
first argument to XtSetArg. As it is currently implemented,
XtSetArg is a macro that dereferences the first argument twice.
The third approach lets you individually set the elements of the argument
list array, one piece at a time. For example:
Arg arglist[10];
arglist[O].name = XtNwidth;
arglist[O].value = (XtArgVal) 400;
arglist[l].name = XtNheight;
arglist[l].value = (XtArgVal) 300;
Note that in this example, as in the previous example, XtNumber would
return 10, not 2, and therefore is not useful.
The fourth approach lets you 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[l].value = (XtArgVal) 300;
In this example, XtNumber can be used, as in the first approach, for easier
code maintenance.

2-12 Using Widgets

2.7.3
Sample Program
The following program creates one command button that, when pressed,
causes the program to exit. This example is a complete program that
illustrates:

•
•
•
•

Toolkit initialization
Optional command-line arguments
Widget creation
Callback routines

#include <stdio.h>
#include <X11/Intrinsic.h>
#include <X11/Command.h>
static XrmOptionDescRec options[] = {
{"-Iabel", "*button.label", XrmoptionSepArg,
} ;

NULL}

Syntax (ca I I)
char *call;
fprintf(stderr,

"Usage:

%s\n",

call);

void Activate(w, cl ient_data, call_data)
Widget w;
caddr_t cl ient_data;
/* unused */
caddr_t call_data;
/* unused */
printf(lIbutton was activated.\n");
exit(O);
void main(argc, argv)
unsigned int argc;
char **argv;
Widget toplevel;
static XtCallbackRec callbacks[]
{ Activate, NULL },
{ NULL, NULL },
} ;
static Arg args[] = {
{ XtNca I I back, (XtArgVa I) ca I I backs
};
toplevel

= Xtlnitialize("main",

Demo
options,
XtNumber(options) ,
II

&a r gc, a r gv );
if (argc != 1) Syntax(argv[O]);

(continued on next page)

Using Widgets 2-13

XtCreateManagedWidget("button",commandWidgetClass,toplevel,
args, XtNumber(args»;
XtReal izeWidget(toplevel);
XtMainLoop();
}

2-14 Using Widgets

Athena Widget Set 3

This chapter describes the following Athena widgets:
• Command
• Label
• Text
• Scrollbar
• Viewport
• Box
• VPaned
• Form
• Dialog
• List
• Grip

3.1

Command Widget

The Command widget is a rectangular button that contains a text or
pixmap label. When the pointer cursor is on the button, the button border
is highlighted to indicate that the button is available for selection. Then,
when a pointer button is pressed and released the button is selected, and
the application's callback routine is invoked.
The class variable for the Command widget is commandWidgetClass.
When creating a Command widget instance, the following resources are
retrieved from the argument list or from the resource database:
Name

Type

Default

XtNbackground
XtNbackgroundPixmap
XtNbitmap
XtNborderColor
XtNborderPixmap

Pixel
Pix map
Pix map
Pixel
Pixmap

XtDefaultBackground
None
None
XtDefaultForeground
None

Name

Type

XtNborderWidth
XtNcallback
XtNcursor
XtN destroyCallback
XtNfont
XtNforeground
XtNheight
XtNhighlightThickness
XtNinsensitiveBorder
XtNinternalHeight
XtNinternalWidth
XtNjustify
XtNlabel
XtNmappedWhenManaged
XtNresize
XtN sensitive
XtNtranslations
XtNwidth
XtNx
XtNy

Dimension
XtCallbackList
Cursor
XtCallbackList
XFontStruct*
Pixel
Dimension
Dimension
Pixmap
Dimension
Dimension
XtJustify
String
Boolean
Boolean
Boolean
TranslationTable
Dimension
Position
Position

Default
1

NULL
None
NULL
XtDefaultFont
XtDefaultForeground
Text height
2
Gray
2
4

XtJustifyCenter
Button name
True
True
True
see below
Text width
0
0

For an explanation of the common widget resources associated with the
Command widget, see Section 2.3. The new resources associated with the
Command widget are:
XtNbitmap

Specifies a bitmap to display in place of the text
label. See the description of this resource in the
Label widget for further details.

XtNfont

Specifies the label font.

XtNheight

Specifies the height of the Command widget. The
default value is the minimum height that will
contain:
XtNinternalheight + height of XtNlabel +
XtNinternalHeight
If the specified height is larger than the minimum,
the label string is centered vertically.

XtNhighlightThickness

Specifies the width of border that is to be
highlighted.

3-2 Athena Widget Set

XtNinsensitiveBorder

Specifies the border when it is not sensitive.

XtNinternalHeight

Represents the distance in pixels between the top
and bottom of the label text or bitmap and the
horizontal edges of the Command widget.
HighlightThickness can be larger or smaller than this
value,

XtNinternalWidth

Represents the distance in pixels between the ends
of the label text or bitmap and the vertical edges of
the Command widget. HighlightThickness can be
larger or smaller than this value.

XtNjustify

Specifies left, center, or right alignment of the label
string within the Command widget. If it is specified
within an ArgList, one of the values XtJustifyLeft,
XtJustifyCenter, or XtJustifyRight can be specified. In
a resource of type "string", one of the values "left",
"center", or "right" can be specified.

XtNlabel

Specifies the text string that is to be displayed in
the Command widget if no bitmap is specified. The
default is the widget name of the Command widget.

XtNresize

Specifies whether the Command widget should
attempt to resize to its preferred dimensions
whenever XtSetValues is called for it. The default is
True.

XtNsensitive

If set to False, the Command widget will change its
window border to XtNinsensitiveBorder and will stipple
the label string.

XtNwidth

Specifies the width of the Command widget. The
default value is the minimum width that will contain:
XtNinternalWidth + width of XtNlabel +
X tNinternalWidth
If the width is larger or smaller than the mInImum,
XtNjustify determines how the label string is aligned.

The Command widget supports the following actions:
•
•
•

Switching the button between the foreground and background colors
with set and unset
Processing application callbacks with notify
Switching the internal border between highlighted and unhighlighted
states with highlight and unhighlight

Athena Widget Set 3·3

The following are the default translation bindings that are used by the
Command widget:
<EnterWindow>:
<LeaveWindow>:
<BtnlDown>:
<BtnlUp>:

highlight( )
reset( )
set( )
notify() unset()

With these bindings, the user can cancel the action before releasing the
button by moving the pointer out of the Command widget.
The full list of actions supported by Command is:
bighlight( )
Displays the internal highlight border in the XtNforeground
color.
unhighlight() Displays the internal highlight border in the XtNbackground
color.
set( )
Enters the "set" state, in which notify is possible and
displays the interior of the button, including the highlight
border, in the foreground color. The label is displayed in the
background color.
unset( )
Cancels the "set" state and displays the interior of the
button, including the highlight border, in the background
color. The label is displayed in the foreground color.
reset( )
Cancels any set or highlight and displays the interior of the
button in the background color, with the label displayed in
the foreground color.
notify( )
Executes the XtNcaliback callback list if executed in the set
state. The value of the calLdata argument is undefined.
To create a Command widget instance, use XtCreateWidget and specify the
class variable commandWidgetClass.
To destroy a Command widget instance, use XtDestroyWidget and specify
the widget ID of the button.
The Command widget supports two callback lists: XtNdestroyCallback and
XtNcaliback. The notify action executes the callbacks on the XtNcaliback
list. The calLdata argument is unused.

3.2

Label Widget

A Label is an noneditable text string or pixmap that is displayed within a
window. The string is limited to one line and can be aligned to the left,
right, or center of its window. A Label can neither be selected nor
directly edited by the user.

3-4 Athena Widget Set

The class variable for the Label widget is labelWidgetClass.
When creating a Label widget instance, the following resources are retrieved
from the argument list or from the resource database:
Name

Type

Default

XtNbackground
XtNbackgroundPixmap
XtNbitmap
XtNborderColor
XtNborderPixmap
XtNborderWidth
XtNcursor
XtN destroyCallback
XtNfont
XtNforeground
XtNheight
XtNinsensitiveBorder
XtNinternalHeight
XtNinternalWidth
XtNjustify
XtNlabel
XtNmappedWhenManaged
XtNresize
XtN sensitive
XtNwidth
XtNx
XtNy

Pixel
Pix map
Pixmap
Pixel
Pixmap
Dimension
Cursor
XtCallbackList
XFontStruct*
Pixel
Dimension
Pix map
Dimension
Dimension
XtJustify
String
Boolean
Boolean
Boolean
Dimension
Position
Position

XtDefaultBackground
None
None
XtDefaultForeground
None
1

None
NULL
XtDefaultFont
XtDefaultForeground
text height
Gray
2
4

XtJustifyCenter
label name
True
True
True
text width
0
0

For an explanation of the common widget resources associated with the
Label widget, see Section 2.3. The new resources associated with the
Label widget are:
XtNbitmap

Specifies a bitmap to display in place of the text
label. The bitmap can be specified as a string in
the resource data base. The StringToPixmap
converter will interpret the string as the name of a
file in the bitmap utility format that is to be loaded
into a pixmap.

Athena Widget Set 3-5

The string can be an absolute or a relative file
name. If a relative file name is used, the directory
specified by the resource name bitmap File Path or thE
resource class BitmapFilePath is add to the beginninJ
of the specified file name. If the bitmapFilePath
resource is not defined, the default directory on a
UNIX-based system is lusr/include/X11/bitmaps.
XtNfont

Specifies the label font.

XtNheight

Specifies the height of the Label widget. The
default value is the minimum height that will
contain:
XtNinternalheight + height of XtNlabel +
XtNinternalHeight
If the specified height is larger than the minimum,
the label string is centered vertically.

XtNinsensitiveBorder

Specifies the border when the widget is not
sensitive.

XtNinternalHeight

Represents the distance in pixels between the top
and bottom of the label text or bitmap and the
horizontal edges of the Label widget.

XtNinternalWidth

Represents the distance in pixels between the ends
of the label text or bitmap and the vertical edges 0
the Label widget.

XtNjustify

Specifies left, center, or right alignment of the label
string within the Label widget. If it is specified
within an ArgList, one of the values XtJustifyLeft,
XtJustifyCenter, or XtJustifyRight can be specified. I:
a resource of type "string", one of the values "left'
"center", or "right" can be specified.

XtNlabel

Specifies the text string that is to be displayed in
the button if no bitmap is specified. The default is
the widget name of the Label widget.

XtNresize

Specifies whether the Label widget should attempt
resize to its preferred dimensions whenever
XtSetValues is called for it.

XtNsensitive

If set to False, the Label widget will change its
window border to XtNinsensitiveBorder and will stipp
the label string.

3-6 Athena Widget Set

XtNwidth

Specifies the width of the Label widget. The default
value is the minimum width that will contain:
XtNinternalWidth + width of XtNlabel +
X tNinternalWidth
If the width is larger or smaller than the mmnnum,
XtNjustify determines how the label string is aligned.

To create a Label widget instance, use XtCreateWidget and specify the class
variable labelWidgetC lass.
To destroy a Label widget instance, use XtDestroyWidget and specify the
widget ID of the label.
The Label widget supports only the XtNdestroyCaliback callback list.

3.3

Text Widget

A Text widget is a window that provides a way for an application to
display one or more lines of text. The displayed text can reside in a file
on disk or in a string in memory. An option also lets an application
display a vertical Scrollbar in the Text window, letting the user scroll
through the displayed text. Other options allow an application to let the
user modify the text in the window.
The Text widget is divided into three parts:
•

Source

•
Sink
•
Text widget
The idea is to separate the storage of the text (source) from the painting
of the text (sink). The Text widget coordinates the sources and sinks.
Clients usually will use AsciiText widgets that automatically create the
source and sink for the client. A client can, if it so chooses, explicitly
create the source and sink before creating the Text widget.
The source stores and manipulates the text. The X Toolkit provides string
and disk file sources. The source determines what editing functions may
be performed on the text.
The sink obtains the fonts and the colors in which to paint the text. The
sink also computes what text can fit on each line. The X Toolkit provides
a single-font, single-color ASCII sink.
If a disk file is used to display the text, two edit modes are available:
•
•

Append
Read-only

Athena Widget Set 3-7

Append mode lets the user enter text into the window, while read-only
mode does not. Text may only be entered if the insertion point is after
the last character in the window.
If a string in memory is used, the application must allocate the amount of
space needed. If a string in memory is used to display text, three types
of edit mode are available:
•
Append-only
•
Read-only
•
Editable
The first two modes are the same as displaying text from a disk file.
Editable mode lets the user place the cursor anywhere in the text and
modify the text at that position. The text cursor position can be modified
by using the key strokes or pointer buttons defined by the event bindings.
Many standard keyboard editing facilities are supported by the event
bindings. The following actions are supported:
Cursor Movement
forward-character
backward-character
forward-word
backward-word
forward-paragraph
backward-paragraph
beginning-of-line
end-of-line
next-line
previous-line
next-page
previous-page
beginning-of-file
end-of-file
scroll-one-line-up
scroll-one-line-down

Delete

New Line
newline-and-indent
newline-and-backup
newline

Miscellaneous
redraw-display
insert-file
do-nothing

Kill

Unkill
kill-word
backward-kill-word
kill-selection
kill-to-end-of-line
kill-to-end-of-paragraph

3-8 Athena Widget Set

delete-next-character
delete-previous-character
delete-next-word
delete-previous-word
delete-selection

Selection
select-word
select-all
select-start
select-adjust
select-end
extend-start
extend-adjust
extend-end

unkill
stuff
insert-selection

Note

2.
3.

A page corresponds to the size of the Text window. For
example, if the Text window is 50 lines in length, scrolling
forward one page is the same as scrolling forward 50 lines.
The delete action deletes a text item. The kill action deletes a
text item and puts the item in the kill buffer (X cut buffer 1).
The unkill action inserts the contents of the kill buffer into the
text at the current position. The stuff action inserts the
contents of the paste buffer (X cut buffer 0) into the text at
the current position. The insert-selection action retrieves the
value of a specified X selection or cut buffer, with fall-back to
alternative selections or cut buffers.

The default event bindings for the Text widget are:
char defaultTextTranslations[] =
Ctrl<Key>F:
Ctrl<Key>B:
Ctrl <Key >D:
Ctrl<Key>A:
Ctrl<Key>E:
Ctrl<Key>H:
Ctrl<Key>J:
Ctrl <Key> K:
Ctrl<Key>L:
Ctrl <Key >M:
Ctrl<Key>N:
Ctrl <Key >0:
Ctrl<Key>P:
Ctrl <Key>V:
Ctrl <Key> W:
Ctrl <Key >Y:
Ctrl <Key >Z:
Meta<Key>F:
Meta <Key >B:
Meta <Key >1:
Meta <Key> K:
Meta <Key>V:
Meta <Key> Y:
Meta<Key>Z:
:Meta <Key >d:

forward-character() "n"
backward-character() "n"
delete-next-character() "n"
beginning-of-line() "n"
end-of-line() "n"
delete-previous-character() "n"
newline-and-indent() "n"
kill-to-end-of-line() "n"
redraw-display() "n"
newline() "n"
next-line() "n"
newline-and-backup() "n "
previous-line() "n"
next-page() "n"
kill-selection() "n"
unkill() "n"
scroll-one-line-up() "n"
forward-word() "n"
backward-word() "n"
insert-file() "n"
kill-to-end-of-paragraph() "n"
previous-page() "n"
stuff() "n"
scroll-one-line-down() "n"
delete-next-word() "n"

Athena Widget Set 3-9

:Meta<Key>D:
:Meta <Key >h:
:Meta <Key >H:
:Meta <Key > "<:
:Meta<Key> ,,>:
:Meta <Key>]:
:Meta<Key>[:
'"Shift Meta <Key >Delete:
Shift Meta <Key >Delete:
"Shift Meta <Key >Backspace:
Shift Meta<Key>Backspace:
<Key>Right:
<Key>Left:
<Key>Down:
<Key>Up:
<Key>Delete:
<Key>BackSpace:
<Key>Linefeed:
<Key>Return:
<Key>:
<FocusIn>:
<FocusOut >:
<BtnlDown>:
<BtnlMotion>:
<BtnlUp>:
<Btn2Down>:
<Btn3Down>:
<Btn3Motion>:
<Btn3Up>:

kill-word() "-n "delete-previous-word() "-n "
backward-kill-word() "-n "
beginning-of-file() "-n "
end-of-file() "-n"
forward-paragraph() "-n"
backward-paragraph() "-n"
delete-previous-word() "-n"
backward-kill-word() "-n "
delete-previous-word() "-n "
backward-kill-word() "-n"
forward-character() "-n"
backward-character() "-n"
next-line() "-n"
previous-line() "-n"
delete-previous-character() "-n "
delete-previous-character() "-n"
newline-and-indent() "-n"
newline() "-n"
insert-char() "-n"
focus-in() "-n "
focus-out() "-n"
select-start() "n"
extend-adjust() "-n"
extend-end( PRIMARY, CUT_BUFFERO) "-n"
insert-selection( PRIMARY, CUT _B UFFERO) "-n"
extend-start() "n"
extend-adjust() "-n"
extend-end(PRIMARY, CUT_BUFFERO) "

A user-supplied resource entry can use application-specific bindings, a subset
of the supplied default bindings, or both. The following is an example of a
user-supplied resource entry that uses a subset of the default bindings:
Xmh*Text.Translations: "
<Key>Right:
<Key>Left:
Meta <Key >F:
Meta <Key >B:
:Meta<Key>]:
:Meta <Key >[:
<Key>:

forward-character() "-n"
backward-character() "-n"
forward-word() "-n"
backward-word() "-n"
forward-paragraph() "n"
backward-paragraph() "n"
insert-char( )

An augmented binding that is useful with the xclipboard utility is:

3-10 Athena Widget Set

*Text.Translations: #override "Button1 <Btn2Down>:

extend-end( CLIPBOARD)

A Text widget lets both the user and the application take control of the
text being displayed. The user takes control with the scroll bar or with
key strokes defined by the event bindings. The scroll bar option places
the scroll bar on the left side of the window and can be used with any
editing mode. The application takes control with procedure calls to the
Text widget to:
•

Display text at a specified position

•
•

Highlight specified text areas
Replace specified text areas

The text that is selected within a Text window may be assigned to an X
selection or copied into a cut buffer and can be retrieved by the application
with the Intrinsics XtGetSelectionValue or the Xlib XFetchBytes functions
respectively. Several standard selection schemes (e.g.
character/word/paragraph with multi-click) are supported through the event
bindings.
The class variable for the Text widget is textWidgetClass.
To create a Text string widget, use XtCreateWidget and specify the class
variable asciiStringWidgetClass.
To create a Text file widget, use XtCreateWidget and specify the class
variable asciiDiskWidgetClass.
Note

If you want to create an instance of the class textWidgetClass,
you must provide a source and a sink when the widget is
created. The Text widget cannot be instantiated without both.

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

Type

Default

XtNbackground
XtNbackgroundPixmap
XtNborderColor
XtNborderPixmap
XtNborderWidth
XtNcursor
XtNdialogHOffset
XtNdialogVOffset

Pixel
Pixmap
Pixel
Pix map
Dimension
Cursor
int
int

XtDefaultBackground
None
XtDefaultForeground
None
4
XC_xterm
10
10

Athena Widget Set 3-11

Name

Type

Default

XtNdestroyCallback
XtN display Position
XtNeditType
XtNfile
XtNforeground
XtNfont
XtNheight
XtN insertPosition
XtNleftMargin
XtNlength
XtN mappedWhenManaged
XtN selectTypes
XtN sensitive
XtNstring
XtNtextOptions
XtNtextSink
XtNtextSource
XtNtranslations
XtNwidth
XtNx
XtNy

XtCallbackList
int
XtEditType
char*
Pixel
XFontStruct*
Dimension
int
Dimension
int
Boolean
XtTextSelectType *
Boolean
char*
int
XtTextSink
XtTextSource
TranslationTable
Dimension
Position
Position

NULL
0
XttextRead
tmpnam( )
Black
Fixed
Font height
0
2

String length
True
See below
True
Blank
None
None
None
See above
100
0
0

For an explanation of the common widget resources associated with the
Text widget, see Section 2.3. The new resources associated with the Text
widget are:
XtNdialogHOffset
XtNd ialogVOffset

Specified the horizontal and vertical offsets for the
insert file dialog box.

XtNdisplayPosition

Specifies the character position of first line.

XtNediType

Specifies the edit mode (see Notes).

XtNfile

Specifies the file for asciiDiskClass.

XtNfont

Specifies the font name.

XtNinsertPosition

Specifies the character position of the caret.

XtNleftMargin

Specifies the left margin in pixels.

XtNlength

Specifies the size of the string buffer.

XtNselectTypes

Specifies the selection units for multiclicks.

3-12 Athena Widget Set

XtNstring

Specifies the string for asciiStringWidgetClass.

XtNtextOptions
XtNtextSink
XtNtextSource

See Notes.

Note

1.
2.
3.

You cannot use XtNeditType, XtNfile, XtNlength, and XtNfont with
the XtTextSetValues and the XtTextGetValues calls.
The XtNeditType attribute has one of the values XttextAppend,
XttextEdit, or XttextRead.
If asciiStringWidgetClass is used, the resource XtNstring specifies
a buffer containing the text to be displayed and edited.
AsciiStringWidget does not copy this buffer but uses it in-place.

The options for the XtNtextOptions attribute are:
editable
resizeHeight
resizeWidth

scroll Horizontal
scroliOnOverflow
scroliVertical
wordBreak

Specifies whether or not the user is allowed to
modify the text.
Makes a request to the parent widget to lengthen
the window if all the text cannot fit in the window.
Makes a request to the parent widget to widen the
window if the text becomes too long to fit on one
line.
Puts a scroll bar on the top of the window.
Automatically scrolls the text up when new text is
entered below the bottom (last) line.
Puts a scroll bar on the left side of the window.
Starts a new line when a word does not fit on the
current line.

These options can be ORed together to set more than one at the same
time.
XtNselectionTypes is an array of entries of type XtTextSelectType and is
used for multiclick. As the pointer button is clicked in rapid succession,
each click highlights the next "type" described in the array.
XtselectAll

Selects the contents of the entire buffer.

Athena Widget Set 3-13

XtselectChar

S elects text characters as the pointer moves over
them.

XtselectLine

Selects the entire line.

XtselectNull

Indicates the end of the selection array.

XtselectParagraph

S elects the entire paragraph (delimited by newline
characters) .

XtselectPosition

S elects the current pointer position.

X tselect Word

Selects whole words (delimited by whitespace) as th4
pointer moves onto them.

The default selectType array is:
{XtselectPosition, XtselectWord, XtselectLine, XtselectParagraph, XtselectAll, XtselectNull}

For the default case, two rapid pointer clicks highlight the current word,
three clicks highlight the current line, four clicks highlight the current
paragraph, and five clicks highlight the entire text. If the timeout value is
exceeded, the next pointer click returns to the first entry in the selection
array. The selection array is not copied by the Text widget. The client
must allocate space for the array and cannot deallocate or change it until
the Text widget is destroyed or until a new selection array is set.
3.3.1

Selection Actions

The Text widget fully supports the X selection and cut buffer mechanisms.
The following actions can be used to specify button bindings that will cause
Text to assert ownership of one or more selections, to store the selected
text into a cut buffer, and to retrieve the value of a selection or cut
buffer and insert it into the text value.
insert-selection( name[,name, ... ])
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 input stream. The specified name can be that of
any selection (for example, PRIMARY or SECONDARy) or a
cut buffer (i.e. CUT_BUFFERO through CUT_BUFFER7).
Note that case matters.
select-start( ) U nselects any previously selected text and begins selecting
new text.
select-adjust( )
extend-adjust( )
Continues selecting text from the previous start position.

3-14 Athena Widget Set

start-extend() Begins extending the selection from the farthest (left or
right) edge.
select-end( name [,name, ... ])
extend-end( name [,name, ... ])
Ends the text selection, asserts ownership of the specified
selection( s) and stores the text in the specified cut buffer( s).
The specified name can be that of a selection (for example,
PRIMARY or SECONDARY) or a cut buffer (i.e.
CUT_BUFFERO through CUT_BUFFER7). Note that case is
significant. ' If CUT_BUFFERO is listed, the cut buffers are
rotated before storing into buffer O.
3.3.2
Selecting Text
To enable an application to select a piece of text, use XtTextSetSelection.
typedef

long XtTextPosition;

vo i d XtTextSetSe I ect ion (w, left,
Widget w;
X t T ext Po sit ion left, right;

right)

Specifies the window ID.
Specifies the character position at which the selection begins.
right
Specifies the character position at which the selection ends.
If redisplay is not disabled, this function highlights the text and makes it
the PRIMARY selection.
left

3.3.3
Unhighlighting Text
To unhighlight previously highlighted text in a window, use
XtTextU nsetSelection.
void XtTextUnsetSelection(w)
Widget w;

3.3.4
Getting Selected Text Character Positions
To enable the application to get the character positions of the selected
text, use XtTextGetSelectionPos.

Athena Widget Set 3-15

vo i d XtTex tGet Se I ect i onPos (w, posl,
Widget w;
X t T ext Po sit ion * posl, * pos2 ;

pos2)

Specifies the window ID.
posl
Specifies a pointer to the location to which the beginning
character position of the selection is returned.
pos2
Specifies a pointer to the location to which the ending
character position of the selection is returned.
If the returned values are equal, there is no current selection.
w

3.3.5
Replacing Text
To enable an application to replace text, use XtTextReplace.
i nt XtTextRep I ace(w, start_pos, end_pos,
Widget w;
XtTextPosition start-pos, end_pos;
Xt Te x t B I 0 c k * text;

text)

Specifies the window ID.
start_pos
Specifies the starting character position of the text
replacement.
end_pos
Specifies the ending character position of the text
replacement.
text
Specifies the text to be inserted into the file.
The XtTextReplace function deletes text in the specified range (startPos,
endPos) and inserts the new text at startPos. The return value is
XawEditDone if the replacement is successful, XawPositionError if the edit
mode is XttextAppend and startPos is not the last character of the source,
or XawEditError if either the source was read-only or the range to be
deleted is larger than the length of the source.
The XtTextBlock structure defined in <X11/Text.h> contains:
w

typedef struct {
int firstPos;
int length;
char *ptr;
Atom format;
} XtTextBlock, *TextBlockPtr;

The firstPos field is the starting point to use within the ptr field. The
value is usually zero. The length field is the number of characters that
are transferred from the ptr field. The number of characters transferred is

3·16 Athena Widget Set

usually the number of characters in ptr. The format field is not currently
used, but should be specified as FMT8BIT. The XtTextReplace arguments
start_pos and en<Lpos represent the text source character positions for the
existing text that is to be replaced by the text in the XtTextBlock
structure. The characters from start_pos up to but not including end_pos
are deleted, and the characters that are specified by the text block are
inserted in their place. If start_pos and end_pos are equal, no text is
deleted and the new text is inserted after start_pos.
Note

Only ASCII text is currently supported, and only one font can be
used for each Text widget.

Redisplaying Text
3.3.6
To redisplay a range of characters, use XtTextinvalidate.
v 0 i d X t T ext I n val ida t e ( w , fro m , to)
Widget w;
X t T ext Po sit ion fro m , to;

The XtTextlnvalidate 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 XtTextEnableRedisplay.
void XtTextEnableRedisplay(w)
Widget w;

The XtTextEnableRedisplay function flushes any changes due to batched
updates when XtTextDisableRedisplay was called and allows future changes
to be reflected immediately.
To disable redisplay while making several changes, use
XtTextDisableRedisplay.
void XtTextDisableRedisplay(w)
Widget w;

The XtTextDisableRedisplay function causes all changes to be batched until
XtTextDisplay or XtTextEnableRedisplay is called.
To display batched updates, use XtTextDisplay.

Athena Widget Set 3-17

void XtTextDisplay(w)
Widget w;

The XtTextDisplay function forces any accumulated updates to be displayed.
To notify the source that the length has been changed, use
XtTextSetLastPos.
v 0 i d X t T ext Set Las t Po s ( w , last);
Widget w;
XtText Pos i t i on last;

The XtTextSetLastPos function notifies the text source that data has been
added to or removed from the end of the source.
3.3.7

Changing Resources

The following procedures are convenience procedures that replace calls to
XtSetValues or XtGetValues when only a single resource is to be modified
or retrieved.
To assigns a new value to XtNtextOptions resource, use
XtTextChangeOptions.
vo i d XtTextChangeOpt ions (w,
Widget w;
i n t options;

options)

To obtain the current value of XtNtextOptions for the specified widget, use
XtTextGetOptions.
int XtTextGetOptions(w)
Widget w;

To obtain the character position of the left-most character on the first line
displayed in the widget (that is, the value of XtNdisplayPosition), use
XtTextTopPosition.
XtTextPosition XtTextTopPosition(w)
Widget w;

To move the insertion caret to the specified source position, use
XtTextSetinsertionPoint.

3-18 Athena Widget Set

void XtTextSetInsertionPoint(w, position)
Widget w;
XtTextPosition posU~n;

The text will be scrolled vertically if necessary to make the line containing
the insertion point visible. The result is equivalent to setting the
XtNinsertPosition resource.
To obtain the current position of the insertion caret, use
XtTextGetlnsertionPoint.
XtTextPosition XtTextGetInsertionPoint(w)
Widget w;

The result is equivalent to retrieving the value of the XtNinsertPosition
resource.
To replace the text source in the specified widget, use XtTextSetSource.
vo i d XtTextSetSou rce (w, source, position)
Widget w;
XtTextSource sou~e;
XtTextPosition posU~n;

A display update will be performed if redisplay has not been disabled.
To obtain the current text source for the specified widget, use
XtTextGetSource.
XtTextSource XtTextGetSource(w)
Widget w;

3.3.8

Creating Sources and Sinks

The following functions for creating and destroying text sources and sinks
are called automatically by AsciiStringWidget and AsciiDiskWidget and it is
therefore only necessary for the client to use them when creating an
instance of textWidgetClass.
To create a new ASCII text sink, use XtAsciiSinkCreate.

Athena Widget Set 3-19

X t T ext Sin k X t As c i i Sin k C rea t e ( w , args , num_args)
Widget w;
A r g Lis t args;
Ca rd i na I num_args;

The resources required by the sink are qualified by the name and class of
the parent and the sub-part name XtNtextSink and class XtCTextSink.
To deallocate an ASCII text sink, use XtAsciiSinkDestroy.
v 0 i d X t As c i i Sin k Des t roy (sink)
X t Te x t Sin k sink;

The sink must not be in use by any widget or an error will result.
To create a new text disk source, use XtDiskSourceCreate.
XtTextSource XtDiskSourceCreate(w,
Widget w;
A r g Lis t args;
Ca rd i na I num_args;

args,

num_args)

The resources required by the source are qualified by the name and class
of the parent and the sub-part name XtNtextSource and class
XtCTextSource.

To deallocate a text disk source, use XtDiskSourceDestroy.
void XtDiskSourceDestroy(soune)
XtTextSource source;

The source must not be in use by any widget or an error will result.
To create a new text string source, use ~tStringSourceCreate.
XtTextSource XtStringSourceCreate(w,
Widget w;
A r g Lis t args;
Ca rd i na I num_args;

args,

num_args)

The resources required by the source are qualified by the name and class
of the parent and the sub-part name XtNtextSource and class
XtCTextSource.

To deallocate a text string source, use XtStringSourceDestroy.

3-20 Athena Widget Set

void XtStringSourceDestroy(soune)
XtTextSource soune;
The source must not be in use by any widget or an error will result.

3.4

Scrollbar Widget

The Scrollbar widget is a rectangular area that contains a slide region and
a thumb (slide bar). A Scrollbar can be used alone, as a valuator, or it
can be used within a composite widget (for example, a Viewport). A
Scrollbar can be aligned either vertically or horizontally.
When a Scrollbar is created, it is drawn with the thumb in a contrasting
color. The thumb is normally used to scroll client data and to give visual
feedback on the percentage of the client data that is visible.
Each pointer button invokes a specific scroll bar action. That is, given
either a vertical or horizontal alignment, the pointer button actions will
scroll or return data as appropriate for that alignment. Pointer buttons 1
and 3 do not perform scrolling operations by default. 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 pointer is moved, the thumb
follows the pointer.
The cursor in the scroll region changes depending on the current action.
When no pointer button is pressed, the cursor appears as an 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 client will move the data. When pointer
button 2 is pressed, the cursor appears as an arrow that points to the
thumb.
While scrolling is in progress, the application receives notification from
callback procedures. For both scrolling actions, the callback returns the
Scrollbar widget ID, the client_data, and the pixel position of the pointer
when the button was released. For smooth scrolling, the callback routine
returns the scroll bar window, 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.
The class variable for the Scrollbar widget is scrolibarWidgetClass.
When creating a Scrollbar widget instance, the following resources are
retrieved from the argument list or from the resource database:

Athena Widget Set 3-21

Name

Type

Default

XtNbackground
XtNbackgroundPixmap
XtNborderColor
XtNborderPixmap
XtNborderWidth
XtN destroyC allback
XtNforeground
XtNheight
XtNjumpProc
XtNlength
XtNmappedWhenManaged
XtN orientation
XtNscrollDCursor
XtNscrollHCursor
XtNscrollLCursor
XtN scrollProc
XtN scrollRCursor
XtN scrollUCursor
XtNscrollVCursor
XtNsensitive
XtNshown
XtNthickness
XtNthumb
XtNtop
XtNtranslations
XtNwidth
XtNx
XtNy

Pixel
Pix map
Pixel
Pixmap
Dimension
XtCallbackList
Pixel
Dimension
XtCallbackList
Dimension
Boolean
XtOrientation
Cursor
Cursor
Cursor
XtC allbackList
Cursor
Cursor
Cursor
Boolean
float
Dimension
Pix map
float
TranslationTable
Dimension
Position
Position

white
None
XtDefaultForeground
None

1
NULL
black
See below
NULL
None
True
Xtorient Vertical
XC_sb_do~arrow

XC_sb_h_double_arrow
XC_sb_Ieft_arrow
NULL
XC_sb_right_arrow
XC_sb_ up_arrow
XC_sb_ v_double_arrow
True
NULL

14
Grey
NULL
See below
See below
NULL
NULL

For an explanation of the common widget resources associated with the
Scrollbar widget, see Section 2.3. The new resources associated with the
Scrollbar widget are:
XtNjumpProc

Specifies the callback procedure for thumb selection.

XtNlength

Specifies the major dimension, which is the height 0
X torient Vertical.

XtNorientation

Specifies the vertical or horizontal orientation of the
widget.

3·22 Athena Widget Set

XtNscroliDCursor

Specifies the cursor that is to be used when scrolling
down.

XtNscrollHCursor

Specifies the idle horizontal cursor.

XtNscrollLCursor

Specifies the cursor that is to be used when scrolling
left.

XtscroliProc

Specifies the callback procedure for the slide region.

XtNscroliRCursor

Specifies the cursor that is to be used when scrolling
right.

XtNscrollUCursor

pecifies the cursor that is to be used when scrolling
up.

XtNscrollVCursor

Specifies the idle vertical cursor.

XtNshown

Specifies the percentage that the thumb covers.

XtNthickness

Specifies the minor dimension, whcih is the height of
XtorientHorizontal.

XtNthumb

Specifies the pixmap that is to be used for the
thumb.

XtNtop

Specifies the position on the scroll bar.

Note that the class for all cursor resources is XtCCursor.
You can set the dimensions of the Scrollbar two ways. As for all widgets,
you can use the XtNwidth and XtNheight resources. In addition, you can
use an alternative method that is independent of the vertical or horizontal
orientation:
XtNlength
XtNthickness

Specifies the height for a vertical Scrollbar and the
width for a horizontal Scrollbar.
Specifies the width for a vertical Scrollbar and the
height for a horizontal Scrollbar.

To create a Scrollbar widget instance, use XtCreateWidget and specify the
class variable scrolibarWidgetClass.
To destroy a Scrollbar widget instance, use XtDestroyWidget and specify the
widget ID for the Scrollbar.

Athena Widget Set 3-23

The arguments to the XtNscroliProc callback procedure are:

v 0 i d ScrollProc (scrollbar,

client_data, position)
Widget scrollbar;
cad d r _ t client_data;
caddr_t position;
/"'C int */

scrollbar
client_data
position

Specifies the ID of the Scrollbar.
Specifies the client data.
Returns the pixel position of the thumb in integer form.

The XtNscroliProc callback is used for incremental scrolling and is called by
the NotifyScroll 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 distance of the pointer in
pixels from the top (or left) of the Scrollbar. The value will never be less
than zero or greater than the length of the Scrollbar.
The arguments to the XtNjumpProc callback procedure are:

v 0 i d JumpProc (scrollbar,

client_data, percent)
Widget scrollbar;
cad d r _ t client_data;
cad d r _ t pe rce nt_ptr ;
/ * flo a t * * /

scrollbar
client_data
percent_ptr

Specifies the ID of the scroll bar window.
Specifies the client data.
Specifies the floating point position of the thumb (0.0 1.0) .

The XtNjumpProc callback is used to implement smooth scrolling and is
called by the NotifyThumb 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 XtNjumpProc is called on each new position of the pointer.
Note

An older interface used XtNthumbProc and passed the percentage
by value rather than by reference. This interface is not portable
across machine architectures and therefore is no longer supported
but is still implemented for those (non-portable) applications
which used it.

3·24 Athena Widget Set

To set the position and length of a Scrollbar thumb, use
XtScrolibarSetThumb.
void XtScrollbarSetThumb(w,
Widget w;
f loa t top;
flo a t shown;

top,

shown)

Specifies the Scrollbar widget ID.

top

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

shown

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

XtScrolibarThumb moves the visible thumb to 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 current value is left unchanged. Values greater
than 1.0 are truncated to 1.0.
If called from XtNjumpProc, XtScrolibarSetThumb has no effect.

The actions supported by the Scrollbar widget are:
StartScroll( value)
The possible values are Forward, Backward, or Continuous.
This must be the first action to begin a new movement.
NotifyScroll( value)
The possible values are Proportional or FullLength. If the
argument to StartS croll was Forward or Backward,
NotifyScroll executes the XtNscroliProc callbacks and passes
either the position of the pointer if its argument is
Proportional or the full length of the scroll bar if its
argument is FullLength. If the argument to StartScroll was
Continuous, NotifyScroll returns without executing any
callbacks.
EndScroll( )

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

MoveThumb() Repositions the scroll bar thumb to the current pointer
location.
N otifyThumb( )
Calls the XtNjumpProc callbacks and passes the relative
position of the pointer as a percentage of the scroll bar
length.

Athena Widget Set 3-25

The default bindings for Scrollbar are:
<BtnlDown >:
<Btn2Down>:
<Btn3Down>:
<Btn2Motion >:
<BtnUp>:

StartScroll( Forward)
StartScroll( Continuous) MoveThumb() NotifyThumb()
StartScroll( Backward)
MoveThumb() NotifyThumb()
NotifyScroll( Proportional) EndScroll()

Examples of additional bindings a user might wish to specify in a resource
file are:
*Scrollbar. Translations: "Meta <KeyPress >space:
Meta <KeyPress >space:

3.5

StartScroll( Forward) N otifyScroll( FullLength) '-.n "StartScroll( Backward) NotifyScroll( FullLength) '-.n "EndScroll( )

Viewport Widget

The Viewport widget consists of a frame window, one or two Scrollbars,
and an inner window. The frame window 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 scroll bars. The forceBars option causes the
Viewport widget to display any scroll bar permanently.
The class variable for the Viewport widget is viewportWidgetClass.
When creating a Viewport widget instance, the following resources are
retrieved from the argument list or from the resource database:
Name

Type

Default

XtN allowHoriz
XtNallowVert
XtNbackground
XtNbackgroundPixmap
XtNborderColor
XtNborderPixmap
XtNborderWidth
XtN destroyCallback
XtNforceBars
XtNheight
XtNmappedWhenManaged

Boolean
Boolean
Pixel
Pix map
Pixel
Pixmap
Dimension
XtCallbackList
Boolean
Dimension
Boolean

False
False
XtDefaultBackground
None
XtDefaultForeground
None
1
NULL
False
height of child
True

3-26 Athena Widget Set

Name

Type

Default

XtN sensitive
XtNtranslations
XtNuseBottom
XtNuseRight
XtNwidth
XtNx
XtNy

Boolean
TranslationTable
Boolean
Boolean
Dimension
Position
Position

True
None
False
False
width of child
0
0

For an explanation of the common widget resources associated with the
Viewport widget, see Section 2.3 The new resources associated with the
Viewport widget are:
XtNaliowHoriz

Specifies whether horizontal scroll bars are to be
allowed.

XtNallowVert

Specifies whether vertical scroll bars are to be
allowed.

XtNforceBars

Specifies whether to force the display of scroll bars.

XtNuseBottom

Specifies whether to use top or bottom bars.

XtNuseRight

Specifies whether to use right or left bars.

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 Viewport by repositioning the Scrollbars.
The default size of the Viewport before it is realized is the width and/or
height of the child. Mter it is realized, the viewport will allow its child to
grow vertically or horizontally if XtNallowVert or XtNaliowHoriz were set,
respectively. If the corresponding vertical or horizontal scrolling were 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 (grand) parent
allows it. Regardless of whether or not scrolling was 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 appropriate dimension.
To create a Viewport widget instance, use XtCreateWidget and specify the
class variable viewportWidgetClass.
To insert a child into a Viewport widget, use XtCreateWidget and specify
the widget ID of the previously created Viewport as the parent.

Athena Widget Set 3-27

To remove a child from a Viewport widget, use XtUnmanageChild or
XtDestroyWidget and specify the widget ID of the child.
To delete the inner window, any children, and the frame window, use
XtDestroyWidget and specify the widget ID of the Viewport widget.

3.6

Box Widget

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 when children are added or deleted.
The Box widget always attempts to pack its children as closely as possible
within the geometry allowed by its parent.
Box widgets are commonly used to manage a related set of Command
widgets and are frequently called ButtonBox widgets, but the children are
not limited to buttons.
The children are arranged on a background that has its own specified
dimensions and color.
The class variable for the Box widget is boxWidgetClass.
When creating a Box widget instance, the following resources are retrieved
from the argument list or from the resource database:
Name

Type

Default

XtNbackground
XtNbackgroundPixmap
XtNborderColor
XtNborderPixmap
XtNborderVVidth
XtN destroyCallback
XtNhSpace
XtNheight
XtN mappedVVhenManaged
XtNtranslations
XtNvSpace
XtNwidth
XtNx
XtNy

Pixel
Pix map
Pixel
Pix map
Dimension
X tC allbackList
Dimension
Dimension
Boolean
TranslationTable
Dimension
Dimension
Position
Position

X tDefaultB ackground
None
X tDefaultForeground
None
1

NULL
4
see below
True
None
4
width of widest child
0
0

For an explanation of the common widget resources associated with the
Box widget, see Section 2.3. The new resources associated with the Box
widget are:

3-28 Athena Widget Set

XtNhSpace

Specifies the left and right distance between children.

XtNvSpace

Specifies the top and bottom distance between
children.

The Box widget positions its children in rows with XtNhSpace pixels to the
left and right of each child and XtNvSpace pixels between rows. If the
Box width is not specified, the Box widget uses the width of the widest
child. 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. When the next child
does not fit on the current 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 it
parent and will begin the layout process from the beginning if a new width
is granted. After positioning all children, the Box widget attempts to
shrink its own size to the minimum dimensions required for the layout.
To create a box widget instance, use XtCreateWidget and specify the class
variable boxWidgetClass.
To add a child to the Box, use XtCreateWidget and specify the widget ID
of the Box as the parent of the new widget.
To remove a child from the Box, use XtUnmanageChild or XtDestroyWidget
and specify the widget ID of the child.
To destroy a Box widget instance, use XtDestroyWidget and specify the
widget ID of the Box widget. All the children of this box are
automatically destroyed at the same time.

3.7

VPaned Widget

The VPaned widget manages children in a vertically tiled fashion. A
region, called a grip, appears on the border between each child. When the
pointer is positioned on a grip and pressed, an arrow is displayed that
indicates the significant pane that is being resized. While keeping the
pointer button down, the user can move the pointer up or down. This, in
turn, changes the window borders, causing one pane to shrink and some
other pane to grow. The cursor indicates the pane that is of interest to
the user; some other pane in the opposite direction will be chosen to grow
or shrink an equal amount. The choice of alternate pane is a function of
the XtNmin, XtNmax and XtNskipAdjust constraints on the other panes.
With the default bindings, button 1 resizes the pane above the selected
grip, button 3 resizes the pane below the selected grip and button 2
repositions the border between two panes only.
The class variable for the VPaned widget is vPanedWidgetClass.

Athena Widget Set 3-29

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

Type

Default

XtNbackground
XtNbackgroundPixmap
XtNbetweenCursor
XtNborderColor
XtNborderPixmap
XtNborderWidth
XtN destroyC allback
XtNforeground
XtNgripCursor
XtN griplndent
XtN gripTranslations
XtNheight
XtNlowerCursor
XtNmappedWhenManaged
XtNrefigureMode
XtNsensitive
XtNtranslations
XtN upperCursor
XtNwidth
XtNx
XtNy

Pixel
Pix map
Cursor
Pixel
Pix map
Dimension
XtC allbackList
Pixel
Cursor
Position
TranslationTable
Dimension
Cursor
Boolean
Boolean
Boolean
TranslationTable
Cursor
Dimension
Position
Position

XtDefaultB ackground
None
XC_sb_Ieft_arrow
XtDefaultForeground
None
1
NULL
Black
XC_sb_ v_double_arrow
10
internal
sum of child heights
XC_sb_doWIL-arrow
True
On
True
None
XC_sb_ up_arrow
width of widest child
0
0

For an explanation of the common widget resources associated with the
VPaned widget, see Section 2.3. The new resources associated with the
VPaned widget are:
XtNbetweenCursor

Specifies the cursor that is to be used for changing
the boundary.

XtNgripCursor

Specifies the cursor that is to be used when the gri
is not active.

XtNgriplndent

Specifies the offset of the grip, in pixels, from the
margin.

XtNgripTranslations

Specifies the button bindings for the grip.

XtNlowerCursor

Specifies the cursor that is to be used when resizin~
a pane below the grip.

3-30 Athena Widget Set

XtNrefigureMode

Specifies whether children should be adjusted.

XtNupperCursor

Specifies the cursor that is to be used when resizing
a pane above the grip.

To create a VPaned widget instance, use XtCreateWidget and specify the
class variable vPanedWidgetClass.
Once the parent frame is created, you then add panes to it. Any type of
widget can be paned.
To add a child pane to a VPaned frame, use XtCreateWidget and specify
the widget ID of the VPaned widget as the parent of each new child pane.
During the creation of a child pane, the following resources, by which the
VPaned widget controls the placement of the child, can be specified in the
argument list or retrieved from the resource database:
Name

Type

Default

XtN allowResize
XtNmax
XtNmin
XtN skipAdjust

Boolean
Dimension
Dimension
Boolean

False
unlimited
1
False

XtNaliowResize

If False, specifies to ignore child resize requests.

XtNmax

Specifies the maximum height for a pane.

XtNmin

Specifies the minimum height for a pane.

XtNskipAdj ust

If True, the VPaned widget should not automatically
resize the pane.

To delete a pane from a vertically paned window frame, use
XtUnmanageWidget or XtDestroyWidget and specify the widget ID of the
child pane.
To enable or disable a child's request for pane resizing, use
XtPanedAliowResize.

Athena Widget Set 3-31

va i d Xt PanedA I I owRes i ze (w,
Widget w;
Boo I ean allow_resize;

allow_resize)

Specifies the widget ID of the child widget pane.
w
allow_resize Enables or disables a pane window for resizing requests.
If allow_resize is True, VPane allows geometry requests from the child to
change the pane's height. If allow_resize is False, VPane ignores geometry
requests from the child to change the pane's height. The default state is
True before the VPane is realized and False after it is realized. This
procedure is equivalent to changing the XtNaliowResize resource for the
child.
To change the mInnnum and maximum height settings for a pane, use
XtPanedSetMinMax.
v 0 i d Xt Pan e d Set Min Ma x ( w , min,
Widget w;
i nt

min,

max)

max;

Specifies the widget ID of the child widget pane.
m~n
New minimum height of the child, expressed in pixels.
max
New maximum height of the child, expressed in pixels.
This procedure is equivalent to setting the XtNmin and XtNmax resources
for the child.
w

To enable or disable automatic recalculation of pane sizes and positions, use
XtPanedSetRefigureMode.
void XtPanedSetRefigureMode(w,
Widget w;
Boolean mode;

mode)

Specifies the widget ID of the VPaned widget.
mode
Enables or disables refiguration.
You should set the mode to FALSE if you add multiple panes to or
remove multiple panes from the parent frame after it has been realized,
unless you can arrange to manage all the panes at once using
XtManageChildren. Mter all the panes are added, set the mode to TRUE.
This avoids unnecessary geometry calculations and "window dancing".
To delete an entire VPaned widget and all associated data structures, use
XtDestroyWidget and specify the widget ID of the VPaned widget. All the
children of the VPaned widget are automatically destroyed at the same
time.
w

3·32 Athena Widget Set

3.8

Form Widget

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 position 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 other children.
When the Form is resized, it computes new positions and sizes for its
children. This computation is based upon information provided when a
child is added to the Form.
The class variable for a Form widget is formWidgetClass.
When creating a Form widget instance, the following resources are retrieved
from the argument list or from the resource database:
Name

Type

Default

XtNbackground
XtNbackgroundPixmap
XtNborderColor
XtNborderPixmap
XtNborderWidth
XtN defaultDistance
XtN destroyC allback
XtNheight
XtNmappedWhenManaged
XtN sensitive
XtNtranslations
XtNwidth
XtNx
XtNy

Pixel
Pixmap
Pixel
Pix map
Dimension
int
XtCallbackList
Dimension
Boolean
Boolean
TranslationTable
Dimension
Position
Position

XtDefaultBackground
None
XtDefaultForeground
None
1
4
NULL
computed at realize
True
True
None
computed at realize
NULL
NULL

For an explanation of the common widget resources associated with the
Form widget, see Section 2.3. The new resources associated with the
Form widget are:
XtNdefaultDistance

Specifies the default distance for XtNhorizDistance
and XtNvertDistance.

To create a Form widget instance, use XtCreateWidget and specify the class
variable formWidgetClass.

Athena Widget Set 3-33

To add a new child to a Form, use XtCreateWidget and specify the widget
ID of the previously created Form as the parent of the child.
When creating children that are to be added to a Form, the following
additional resources are retrieved from the argument list or from the
resource database:
Name

Type

Default

XtNbottom
XtNfromHoriz
XtNfromVert
XtNhorizDistance
XtNleft
XtN res iz able
XtNright
XtNtop
XtN vert Distance

XtEdgeType
Widget
Widget
int
XtEdgeType
Boolean
XtEdgeType
XtEdgeType
int

XtRubber
NULL
NULL
XtdefaultDistance
XtRubber
FALSE
XtRubber
XtRubber
XtdefaultDistance

If XtNresizable is True, the child is allowed to be resized.
When a widget is added to a Form, constraints can be specified to the
Form to indicate where the child should be positioned within the Form.

The resources XtNhorizDistance and XtNfromHoriz let the widget position
itself a specified number of pixels horizontally away from another widget in
the form. As an example, XtNhorizDistance could equal 10 and
XtNfromHoriz could be the widget ID of another widget in the Form. The
new widget will be placed 10 pixels to the right of the widget defined in
XtNfromHoriz. If XtNfromHoriz equals NULL, then XtNhorizDistance is
measured from the left edge of the Form.
Similarly, the resources XtNvertDistance and XtNfromVert let the widget
position itself a specified number of pixels vertically away from another
widget in the Form. If XtNfromVert equals NULL, then XtNvertDistance is
measured from the top of the Form. Form provides a String'roWidget
conversion procedure. Using this procedure, the resource database may be
used to specify the XtNfromHoriz and XtNfromVert resources by widget name
rather than widget id. The string value must be the name of a child of
the same Form widget parent.
The XtNtop, XtNbottom, XtNleft, and XtNright resources tell the Form where
to position the child when the Form is resized. XtEdgeType is defined in
< X11/Form.h > and is one of XtChainTop, XtChainBottom, XtChainLeft,
XtChainRight or XtRubber.

3-34 Athena Widget Set

The values XtChainTop, XtChainBottom, XtChainLeft, and XtChainRight
specify that a constant distance from an edge of the child to the top,
bottom, left, and right edges respectively of the Form is to be maintained.
The value XtRubber specifies that a proportional distance from the edge of
the child to the left or top edge of the Form is to be maintained when
the form is resized. The proportion is determined from the initial position
of the child and the initial size of the Form. Form provides a
StringToEdgeType conversion procedure to allow the resize constraints to
be easily specified in a resource file.
The default width of the Form is the minimum width needed to enclose
the children after computing their initial layout, with a margin of
XtNdefaultDistance 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.
To remove a child from a Form, use XtUnmanageChild or XtDestroyWidget
and specify the widget ID of the child widget.
To destroy a Form widget instance, use XtDestroyWidget and specify the
widget ID of the Form. All children of the Form are automatically
destroyed at the same time.
When a new child becomes managed or an old child unmanaged, Form will
recalculate the positions of its children according to the values of the
XtNhorizDistance, XtNfromHoriz, XtNvertDistance and XtNfromVert constraints
at the time the change is made. No re-Iayout is performed when a child
makes a geometry request.
To force or defer a re-Iayout of the Form, use XtFormDoLayout.
void XtFormDoLayout(w,
Widget w;
Boolean do_layout;

do_layout)

Specifies the Form widget.
Enables (if True) or disables (if False) layout of the Form
widget.
When making several changes to the children of a Form widget after the
Form has been realized, it is a good idea to disable re-Iayout until all
changes have been made, then allow the layout. Form increments an
internal count each time XtFormDoLayout is called with do_layout False
and decrements the count when do_layout is True. When the count
reaches 0, Form performs are-layout.
w

Athena Widget Set 3-35

3.9

Dialog Widget

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 file name, from the user. A Dialog widget is simply a special
case of the Form widget that 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
"Filename:". 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.
The class variable for the Dialog widget is dialogWidgetClass.
When creating a Dialog widget instance, the following resources are
retrieved from the argument list or from the resource database:
Name

Type

Default

XtNbackground
XtNbackgroundPixmap
XtNborderColor
XtNborderPixmap
XtNborderWidth
XtN destroyC allback
XtNheight
XtNlabel
XtN mappedWhenManaged
XtNmaximumLength
XtN sensitive
XtNtranslations
XtNvalue
XtNwidth
XtNx
XtNy

Pixel
Pix map
Pixel
Pix map
Dimension
XtCallbackList
Dimension
String
Boolean
int
Boolean
TranslationTable
char*
Dimension
Position
Position

XtDefaultB ackground
None
XtDefaultForeground
None
1

NULL
computed at create
Label name
True

256
True
None
NULL
computed at create
NULL
NULL

For an explanation of the common widget resources associated with the
Dialog widget, see Section 2.3. The new resources associated with the
Dialog widget are:
XtNlabel

Specifies the label string that is to be displayed.

XtNmaximumLength

Specifies the maximum number of input characters.

3-36 Athena Widget Set

Specifies a pointer to the input string.

XtNvalue

The instance name of the label widget within the Dialog widget is "label",
and the instance name of the Dialog value widget is "value".
To create a Dialog widget instance, you can use XtCreateWidget and specify
the class variable dialogWidgetClass.
To add a child button to the Dialog box, use XtCreateWidget and specify
widget ID of the previously created Dialog box as the parent of each child.
When creating buttons, you do not have to specify form constraints. The
Dialog box will automatically add the constraints.
To return the character string in the text field, use XtDialogGetValueString.
char *XtDialogGetValueString(w)
Widget w;

w
Specifies the widget ID of the Dialog box.
If a string was specified in the XtNvalue resource, Dialog will store the
input directly into the string.

To remove a child button from the Dialog box, use XtUnmanageChild or
XtDestroyWidget and specify the widget ID of the child.
To destroy a Dialog widget instance, use XtDestroyWidget and specify the
widget ID of the Dialog widget. All children of the Dialog are
automatically destroyed at the same time.

3.10

List Widget

The List widget is a rectangle that contains a list of strings formatted into
rows and columns. When one of the strings is selected, it is highlighted,
and an application callback routine is invoked.
The class variable for the List widget is listWidgetClass.
When creating a List widget instance, the following resources are retrieved
from the argument list or from the resource database:
Name

Type

Default

XtNbackground
XtNbackgroundPixmap
XtNborderColor
XtNborderPixmap
XtNborderWidth

Pixel
Pix map
Pixel
Pixmap
Dimension

XtDefaultBackground
None
XtDefaultForeground
None
1

Athena Widget Set 3-37

Name

Type

Default

XtNcallback
XtN columnS pacing
XtNcursor
XtN defaultColumns
XtN destroyCallback
XtNfont
XtNforceColumns
XtNforeground
XtNheight
XtNinsensitiveB order
XtNinternalHeight
XtNinternalWidth
XtNlist
XtNlongest
XtNmappedWhenManaged
XtNnumberStrings
XtNpasteBuffer
XtNrowSpacing
XtNsensitive
XtNtranslations
X tNverticalList
XtNwidth
XtNx
XtNy

XtCallbackList
Dimension
Cursor
int
XtCallbackList
XFontS truct *
Boolean
Pixel
Dimension
Pixmap
Dimension
Dimension
String *
int
Boolean
int
Boolean
Dimension
Boolean
TranslationTable
Boolean
Dimension
Position
Position

NULL
6
left_ptr
2

NULL
X tDefaultFont
False
XtDefaultForeground
Contains list exactly
Gray
2

4
List name
Longest item
Number of strings
False
4
True
None
False
Contains list exactly
0
0

For an explanation of the common widget resource associated with the
List widget, see Section 2.3. The new resources associated with the List
widget are:
XtNcolurnnSpacing
XtNrowSpacing

Specify the amount of space between each of the
rows and columns in the list.

XtNdefaultCol urn ns

Specifies the default number of columns, which if
used when neither the width nor the height of
the List widget is specified or when
XtNforceColumns is True.

Xtfont

Specifies the font for the list text.

3·38 Athena Widget Set

XtNforceColumns

Specifies that the default number of columns is
to be used no matter what the current size of
the List widget is.

XtNheight

Specifies the height of the List widget. The
default value is the minimum height that will
contain the entire list with the spacing values
specified. If the specified height is larger than
the minimum, the list is put in the upper left
corner.

XtNinsensitiveBorder

Specifies the border to use when it is not
sensitive.

XtNinternalHeight

Represents a margin, in pixels, between the top
and bottom of the list and the edges of the List
widget.

XtNinternalWidth

Represents a margin, in pixels, between the left
and right edges of the list and the edges of the
List widget.

XtNlist

Specifies the array of text strings that is to
displayed in the List widget. If the default for
XtNnumberStrings is used, the list must be nullterminated. If a value is not specified for the
list, the number of strings is set to 1, and the
name of the widget is used as the list.

XtNlongest

Specifies the length of the longest string in the
current list in pixels. If the client knows the
length, it should specify it. The List widget will
compute a default length by searching through
the list.

XtNnumberStrings

Specifies the number of strings in the current
list. If a value is not specified, the list must be
null-terminated.

XtNpasteBuffer

If this is True, then the value of the string

selected will be put into X cut buffer O.
XtNsensitive

If set to False, the List widget will change its
window border to XtNinsensitiveBorder and display

all items in the list as stippled strings. While
the List widget is insensitive, no item in the list
can be selected or highlighted.

Athena Widget Set 3-39

XtNverticalList

If this is True, the elements in the list are
arranged vertically; if False, the elements are
arranged horizontally.

XtNwidth

Specifies the width of, the List widget. The
default value is the minimum width that will
contain the entire list with the spacing values
specified. If the specified width is larger than
the minimum, the list is put in the upper left
corner.

The List widget has three predefined actions: Set, Unset, and Notify. Set
and Unset allow switching the foreground and background colors for the
current list item. Notify allows processing application callbacks.
The following is the default translation table used by the List Widget:
<BtnlDown>, <Btnl Up >:

Set() Notify()

To create a List widget instance, use XtCreateWidget and specify the class
variable listWidgetClass.
To destroy a List widget instance, use XtDestroyWidget and specify the
widget ID of the List widget.
The List widget supports two callback lists:
•

XtNdestroyCaliback

•

XtNcaliback

The notify action executes the callbacks on the the XtNcaliback list.
The calLdata argument passed to callbacks on the XtNcaliback list is a
pointer to an XtListReturnStruct structure, defined in < X11/List. h >:
typedef struct _XtListReturnStruct
String string;
int index;
} XtListReturnStruct;

3.10.1

1* string shown in the list. *1
1* index of the item selected. *1

Cha nging the List

To change the list that is displayed, use XtListChange.

3-40 Athena Widget Set

void XtListChange(w, list,
Widget w;
S t r i n g * list;
i n t nitems, longest;
Boo I e a n resize;

list
nitems
longest

nitems,

longest,

resize)

Specifies the widget ID.
Specifies the new list for the list widget to display.
Specifies the number of items in the list. If a value less
than 1 is specified, list must be null terminated.
Specifies the length of the longest item in the list in pixels.
If a value less than 1 is specified, the List widget calculates

the value for you.
Specifies a Boolean value that indicates whether the List
resize
widget should try to resize itself ( True) or not ( False) after
making the change. Note that the constraints of the parent
of this widget are always enforced, regardless of the value
specified.
XtListChange changes the list of strings that the List widget is to display.
3.10.2

Highlighting an Item

To highlight an item in the list use, XtListHighlight
v 0 i d X t Lis t H i g h I i g h t (w ,
Widget w;
in t item;
w

ite m) ;

Specifies the widget ID.

item

Specifies the 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 XtListHighlight is called, the highlighted item is
immediately unhighlighted and the new item is highlighted.
3.10.3

Unhighlighting an Ite m

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

Athena Widget Set 3-41

void XtListUnhightlight(w)
Widget w;
w

3.10.4

Specifies the widget ID.
Retrieving the Currently Selected Item

To retrieve an item in the list use, XtListShowCurrent

XtListReturnStruct *XtListShowCurrent(w);
Widget w;
Specifies the widget ID.
The XtListShowCurrent function returns a pointer to an XtListReturnStruct
structure, contains the currently highlighted item. If the value of the
index member is XT_LIST_NONE, the string member is undefined, which
indicates that no item is currently selected.
w

3.11

Grip Widget

The Grip widget provides a small region in which user input events (such
as ButtonPressor ButtonRelease) may be handled. The most common use
for the grip is as an attachment point for visually repositioning an object,
such as the pane border in a VPaned widget.
The class variable for the Grip widget is gripWidgetClass.
When creating a Grip widget instance, the following resources are retrieved
from the argument list or from the resource database:
Name

Type

Default

XtNborderColor
XtNborder Pixmap
XtNborderWidth
XtNcallback
XtNcursor
XtN destroyCallback
XtNforeground
XtNheight
XtN mappedWhenManaged
XtN sensitive
XtNtranslations
XtNwidth
XtNx
XtNy

Pixel
Pix map
Dimension
XtCallbackList
Cursor
XtCallbackList
Pixel
Dimension
Boolean
Boolean
TranslationTable
Dimension
Position
Position

XtDefaultForeground
None

3-42 Athena Widget Set

None
None
NULL
XtDefaultForeground
8
True
True
None
8
0
0

For an explanation of the common widget resources associated with the
Grip widget, see Section 2.3. Note that the Grip widget displays its region
with the foreground pixel only.
The Grip widget does not declare any default event translation bindings,
but it does declare a single action routine named GripAction in its action
table. The client specifies an arbitrary event translation table giving
parameters to the GripAction routine.
The GripAction action executes the callbacks on the XtNcaliback list,
passing as calLdata a pointer to a GripCaliData structure, defined in
<X11/Grip.h>
typedef struct _GripCallData {
XEvent *event;
String *params;
Cardinal num_params;
} GripCallDataRec, *GripCallData;

In this structure, the event field is a pointer to the input event that
triggered the action, and 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 GripAction translation table:
<BtnlDown>:
<BtnlMotion >:
<BtnlUp>:

GripAction( press)
GripAction( move)
GripAction( release)

For a complete description of the format of action routines, see the Guide
to the XUI Toolkit Intrinsics.
To create a Grip widget instance, use XtCreateWidget and specify the class
variable gripWidgetClass.
To destroy a Command button widget instance, use XtDestroyWidget and
specify the ID of the Grip widget.

Athena Widget Set 3-43

Creating a Custom Widget 4

Although the task of creating a new wid~et may at first appear a little
daunting, there is a basic simple pattern that all widgets follow. The
Athena widget library contains three files that are intended to assist in
writing a custom widget.
The reasons for writing a custom widget include:
•

Convenient access to resource management procedures to obtain fonts,
colors, and so on, even if user customization is not desired.

•

Convenient access to user input dispatch and translation management
procedures.
• Access to callback mechanism for building higher-level application
libraries.
• Customizing the interface or behavior of an existing widget to suit a
special application need.
• Desire to allow user customization of resources such as fonts, colors,
and so on, or to allow convenient rebinding of keys and buttons to
internal functions.

• Converting a non-X Toolkit application to use the X 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 GeometryManager method can be shared by the
subclass.
Note that some trivial uses of a "bare-bones" widget may be achieved by
simply creating an instance of the Core widget. The class variable to use
when creating a Core widget is widgetClass. 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 X

Toolkit, it may be desirable to have a "Window Widget" class that might
have the following semantics:
• Allocate two drawing colors in addition to a background color
• Allocate a text font
• Execute an application-supplied function to handle exposure events
• Execute an application-supplied function to handle user input events
It is obvious that a completely general-purpose WindowWidgetClass could be
constructed that would export all class methods as callbacks lists, but such
a widget would be very large and would have to choose some arbitrary
number of resources such as colors to allocate. An application that used
many instances of the general-purpose widget would therefore unnecessarily
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 this manual for complete
details of the material outlined here. In addition, Section 1.4 of the
I ntrinsics should be read in conjunction with this section.
All Athena widgets have three separate files associated with them:
•

A "public" header file containing declarations needed by applications
programmers
• A "private" header file containing additional declarations needed by the
widget and any subclasses
• 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 X Toolkit actually requires this format. In particular, a
private widget created for a single application may easily combine the
"public" and "private" header files into a. single file or merge the contents
into another application header file. Similarly, the widget implementation
can be merged into other application code.
In the following example, the public header file < X11/Template.h >, the
private header file <X11/TemplateP.h> and the source code file
< X11/Template.c > will be modified to produce the "WindowWidget"
described above. In each case, the files have been designed so that a
global string replacement of "Template" and "template" with the name of
your new widget, using the appropriate case, can be done.

4-2 Creating a Custom Widget

4.1

Public Header File

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 XtSetValues operation, or to call a
public routine implemented by the widget class.
The contents of the Template public header file, < X11/Template.h >, are:
#include <X111copyright.h>

1* XConsortium: Template.h,v 1.2 88/10/25 17:22:09 swick Exp $ *1
1* Copyright Massachusetts Institute of Technology 1987, 1988 *1
#ifndef _ Template_h
#define _ Template_h

1***************************************************** ***********

*
* Template widget
*
****************************************************************/
1* Resources:
Name

Class

RepType

Default Value

background
border
borderWidth
destroyCallback
height
mappedWhenManaged
sensitive
width
x
y

Background
BorderColor
BorderWidth
Callback
Height
MappedWhenManaged
Sensitive
Width
Position
Position

Pixel
Pixel
Dimension
Pointer
Dimension
Boolean
Boolean
Dimension
Position
Position

XtDefaultBackground
XtDefaultForeground
1
NULL
0
True
True
0
0
0

1* define any special resource names here that are not in <X111StringDefs.h> */
#define XtNtemplateResource

"templateResource

#define XtCTemplateResource

" TemplateResource"

Creating a Custom Widget 4·3

1* declare specific TemplateWidget class and instance datatypes *1
typedef struct _ TemplateClassRec*
typedef struct _ TemplateRec*

TemplateWidgetClass;
TemplateWidget;

1* declare the class constant *1
extern WidgetClass templateWidgetClass;
#endif

_ Template_h

Note 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 two drawing colors, a callback list for
user input and an X tN exposeCallback callback list, and we will declare
three convenience procedures, so we need to add the following:

1* Resources:
callback
drawingColorl
drawingColor2
exposeC allback
font

Callback
Color
Color
Callback
Font

Callback
Pixel
Pixel
Callback
XFontStruct*

NULL
XtDefaultForeground
XtDefaultForeground
NULL
XtDefaultFont

*1
#define XtNdrawingColorl
#define XtNdrawingColor2
#define XtNexposeCallback

" drawingColorl"
" drawingColor2"
" exposeCallback"

extern Pixel WindowColor1( 1* Widget *1);
extern Pixel WindowColor2( 1* Widget *1);
extern Font WindowFont( 1* Widget *1);

Note that we have chosen to call the input callback list by the generic
name, XtNcallback, 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.

4-4 Creating a Custom Widget

4.2

Private Header File

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, for example,
XtSetValues.

The contents of the Template private header file, <X111TemplateP.h >, are:
#include <X111copyright.h>

1* XConsortium: TemplateP.h,v 1.2 88/10/25 17:31:47 swick Exp $ */
1* Copyright Massachusetts Institute of Technology 1987, 1988 */
#ifndef _ TemplateP _h
#define _ TemplateP_h
#include "Template.h"
1* include superclass private header file *1
#include <X111CoreP.h>

1* define unique representation types not found in <XU/StringDefs.h> *1
#define XtRTemplateResource

" TemplateResource"

typedef struct {
int empty;
} TemplateClassPart;
typedef struct _ TemplateClassRec
CoreClassPart
core_class;
TemplateClassPart template_class;
TemplateClassRec;
extern TemplateClassRec templateClassRec;
typedef struct {
1* resources *1
char* resource;
1* private state *1
TemplatePart;
typedef struct _ TemplateRec
core;
CorePart

Creating a Custom Widget 4-5

TemplatePart
} TemplateRec;

template;

#endif _ TemplateP_h

The private header file includes the private header file of its superclass,
thereby exposing the entire internal structure 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
1* resources *1
Pixel color_1;
Pixel color_2;
XFontStruct* font;
XtCallbackList expose_callback;
XtCallbackList input_callback;
1* private state *1
1* (none) *1
} WindowPart;

4.3

Widget Source File

The source code file implements the widget class itself. The unique part
of this file is the declaration and initialization of the widget class record
structure and the declaration of all resources and action routines added by
the widget class.
The contents of the Template implementation file, < X11/Template.c >, are:
#include <X111copyright.h>

1* XConsortium: Template.c,v 1.2 88/10/25 17:40:25 swick Exp $ *1
1* Copyright Massachusetts Institute of Technology 1987, 1988 *1
#include <Xll/IntrinsicP.h>
#include <X111StringDefs.h>
#include "TemplateP.h"
static XtResource resources[] = {
#define offset( field) XtOffset( TemplateWidget, template.field)

4-6 Creating a Custom Widget

1* {name, class, type, size, offset, default_type, default_addr}, *1
{ XtNtemplateResource, XtCTemplateResource, XtRTemplateResource, sizeof( char*) ,
offset( resource), XtRString, " default" },
#undef offset
};
static void TemplateAction(l* Widget, XEvent*, String*, Cardinal* */);
static XtActionsRec actions[] =

1* {name,
{"template" ,

procedure}, *1
TemplateAction} ,

};

static char translations[] =
<Key>:
template() "-n"

II.

TemplateC lassRec templateClassRec
{ 1* core fields *1
1* superclass
*1
1* class_name
*1
1* widget_size
*1
1* class_initialize
*1
1* class_part_initialize
1* class_inited
*1
1* initialize
*1
1* initialize_hook
*1
1* realize
*1
1* actions
*1
1* num_actions
*1
1* resources
*1
1* num_resources
*1
1* xrID-class
*1
1* compress_motion *1
1* compress_exposure
1* compress_enterleave *1
1* visible_interest *1
1* destroy
*1
1* resize
*1
*1
1* expose
1* set_values
*1
1* set_values_hook *1
1* set_values_almost

( WidgetClass) &widgetClassRec,
" Template" ,
sizeof( TemplateRec) ,
NULL,
NULL,
*1
FALSE,
NULL,
NULL,
XtlnheritRealize,
actions,
XtNumber( actions),
resources,
XtNumber( resources),
NULLQUARK,
TRUE,
TRUE,
*1
TRUE,
FALSE,
NULL,
NULL,
NULL,
NULL,
NULL,
XtInheritSet ValuesAlmost,
*1

Creating a Custom Widget 4-7

/* get_values_hook */
*/
/* accept_focus
*/
/* version
/* callbacLprivate */
/* tm_table
*/
/* query_geometry */
/* display_accelerator
/* extension
*/

NULL,
NULL,
XtVersion,
NULL,
translations,
XtlnheritQueryGeometry,
*/
XtlnheritDisplayAccelerator,
NULL

{ /* template fields */
/* empty
*/
,

}

};

WidgetClass templateWidgetClass = (WidgetClass) &templateClassRec;

The resource list for the "WindowWidget" might look like the following:
static XtResource resources[] = {
#define offset( field) XtOffset( WindowWidget, window. field)
/* {name, class, type, size, offset, default_type, default_addr}, */
{ XtNdrawingC0 lorl, XtCColor, XtRPixel, sizeof(Pixel),
offset( color_l), 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 calLdata. 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 */

4-8 Creating a Custom Widget

XtCallCallbacks( w, XtNcallback, (caddr_t) event);

static XtActionsRec actions[]

1* {name,
{"input" ,

procedure}, *1
InputAction} ,

};

The default input binding will be to execute the input callbacks on
KeyPress and ButtonPress:
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 procedure:
1* ARGSUSED *1
static void Redisplay( w, event, region)
Widget w;
XEvent *event;
1* unused *1
Region region;
XtCallCallbacks( w, XtNexposeCallback, (caddr_t) region);

WindowClassRec windowClassRec

1* 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 XtGetValues:
Pixel WindowColorl( w)
Widget w;
return « WindowWidget) w) ->window.color_l;

Creating a Custom Widget 4-9

Pixel WindowColor2( w)
Widget w;
return « WindowWidget) w) - >window.color_2;

Font WindowFont( w)
Widget w;
return « WindowWidget) w) - >window.font- >fid;

The "WindowWidget" is now complete. The application can retrieve the
two drawing colors from the widget instance by calling either XtGetValues,
or the W indowColor functions. The actual window created for the
"WindowWidget" is available by calling the XtWindow function.
To test the new "WindowWidget", you may substitute "window" for
"command" in the sample program given in Section 2.7.3.

4·10 Creating a Custom Widget

Index

ButtonRelease, 3-42
lusr/include/X11lhitmaps, 2-5, 3-5

C allbackProc, 2·8
Child, 1-2
Class, 1·2
Client, 1·3
Command widget, 3·1
creating, 3-4
destroying, 3-4
resources, 3-1
commandWidgetClass, 3-1, 3-4
Creating widgets:
Box, 3-29
Command, 3-4
Dialog, 3-37
Form, 3-33
Grip, 3-43
Label, 3-7
List, 3-40
Scrollbar, 3-23
Text file, 3-11
Text string, 3-11
VPaned, 3-31
CUT_BUFFERO, 3-14, 3-15
CUT_BUFFER7, 3-14, 3-15

Application programmer, 1·2
Arg, 2·11
ArgList, 2-7, 2·11, 3-2, 3-5
asciiDiskClass, 3-12
AsciiDiskWidget, 3-19
asciiDiskWidgetClas s, 3-11
AsciiStringWidget, 3-13, 3-19
asciiS tringWidgetC lass , 3-11, 3-12,
3-13
AsciiText, 3-7
B

BitmapFilePath, 2-5
bitmapFilePath, 2-5
BitmapFilePath, 3-5
bitmapFilePath, 3-5
Box widget, 3·28
adding children, 3-29
creating, 3-29
destroying, 3-29
removing children, 3-29
resources, 3-28
boxWidgetClass, 3-28, 3-29
ButtonPress, 3-42, 4-9

Destroying widgets:
Box, 3-29
Command, 3-4

Dialog, 3-37
Form, 3-35
Grip, 3-43
Label, 3-7
list, 3-40
Scrollbar, 3-23
Viewport, 3-28
VPaned, 3-32
Dialog widget, 3·36
adding children, 3-37
creating, 3-37
destroying, 3-37
removing children, 3-37
resources, 3-36
dialogWidgetClas s, 3-36, 3-37
Display, 1-5

GripAction, 3-43
GripCallData, 3-43
GripCallDataRec, 3-43
gripWidgetClass, 3-42, 3-43
I

Instance, 1·3

J
JumpProc, 3·24

K
KeyPress, 4-9

editable, 3-13

Label widget, 3-4
creating, 3-7
destroying, 3-7
resources, 3-5
labelWidgetClass, 3-5, 3-7
libXl1.a, 2-11
libXaw.a, 2-11
libXmu.a, 2-11
libXt.a, 2-11
List widget, 3-37
creating, 3-40
destroying, 3-40
resources, 3-37
listWidgetClass, 3-37, 3-40

False, 2-6, 3-2, 3-5, 3-31, 3-32,
3-35, 3-38, 3-41
FMT8BIT, 3-17
forceBars, 3-26
Form widget, 3-33
adding children, 3-34
child resources, 3-34
creating, 3-33
deleting children, 3-35
destroying, 3-35
re-Iayout, 3-35
resources, 3-33
form WidgetClass, 3-33
Fullname, 1-3
G
Grip widget, 3-42
creating, 3-43
destroying, 3-43
GripAction table, 3-43

2 Index

Method, 1·3

3-35, 3-38, 3-41

Name, 1-3

User, 1-3

Object, 1-3

Viewport widget, 3-26
creating, 3-27
destroying, 3-28
inserting a child, 3-27
removing a child, 3-28
resources, 3-26
viewportWidgetClass, 3-26, 3-27
VPaned widget, 3-29
adding pane, 3-31
change height settings, 3-32
child resources, 3-31
creating, 3-31
deleting pane, 3-31
destroying, 3-32
disable auto-reconfiguring, 3-32
disable pane resizing, 3-31
enable auto-reconfiguring, 3-32
enable pane resizing, 3-31
resources, 3-30
vPanedWidgetClass, 3-30, 3-31

Parent, 1-3
PRIMARY, 3-14, 3-15

R
resizeHeight, 3-13
resizeWidth, 3-13
Resource, 1-3

S
Screen, 1-5
Scrollbar widget, 3-21
creating, 3-23
destroying, 3-23
resources, 3-21
setting thumb values, 3-25
scrollbarWidgetClass, 3-21, 3-23
scrollHorizontal, 3-13
scrollOnOverflow, 3-13
ScrollProc, 3-23
scrollVertical, 3-13
SECONDARY, 3-14, 3-15
Superclass, 1-3

T
Template widget, 4-1
Text widget, 3-7
creating, 3-11
default bindings, 3-9
edit modes, 3-8
resources, 3-11
textWidgetClass, 3-11, 3-19
True, 2-6, 3-2, 3-31, 3-32, 3-34,

W
Widget class, 1-4
Widget programmer, 1-4
Widget, 1-3
widgetClass, 4-1
wordBreak, 3-13

x
X111Command.h, 2-10
X111cursorfont.h, 2-4
X11IForm.h, 3-34
X111Grip.h, 3-43
X111Intrinsic.h, 2-10

Index 3

X11lLabel.h, 2-10
X11IList.h, 3-40
X111Template.c, 4-2, 4-6
X111Template.h, 4-2, 4-3
X111TemplateP.h, 4-2, 4-5
X111Text.h, 3-16
X111Xlib.h, 2-10
XawEditDone, 3-16
XawEditError, 3-16
XawPositionError, 3-16
XFetchBytes, 3-11
XrmParseCommand, 2-2
XtAddCallback, 2-9, 2-10
XtAsciiSinkCreate, 3-19
XtAsciiS inkDestroy, 3-20
XtCallbackList, 2-9
XtCallbackProc, 2-9
XtCallCallbacks, 2-9
XtCCursor, 3-23
XtChainBottom, 3-34, 3-35
XtChainLeft, 3-34, 3-35
XtChainRight, 3-34, 3-35
XtChainTop, 3-34, 3-35
XtCreateManagedWidget, 2-2, 2-10
XtCreateWidget, 1-5, 2-2, 2-9, 2-10,
3-4, 3-7, 3-11, 3-23, 3-27, 3-29,
3-31, 3-33, 3-34, 3-37, 3-40, 3-43
XtCTextSink, 3-20
XtCTextSource, 3-20
XtDestroyWidget, 2-3, 2-6, 2-7, 3-4,
3-7, 3-23, 3-28, 3-29, 3-31, 3-32,
3-35, 3-37, 3-40, 3-43
XtDialogGetValueString, 3-37
XtDiskS ourceCreate, 3-20
XtDiskS ourceDestroy, 3-20
XtEdgeType, 3-34
XtError, 2-3
Xtfont, 3-38
XtFormDoLayout, 3-35
XtGetSelectionValue, 3-11
XtGetValues, 2-7, 2-8, 3-18, 4-9,
4-10
XtInitialize, 2-1, 2-10
XtJustifyCenter, 3-2, 3-5

4 Index

XtJustifyLeft, 3-2, 3-5
XtJustifyRight, 3-2, 3-5
XtListChange, 3-40, 3-41
XtListHighlight, 3-41
XtListReturnStruct, 3-40, 3-42
XtListShowCurrent, 3-42
XtListUnhighlight, 3-41
XtMainLoop, 2-10
XtManageChild" 2-10
XtManageChild, 2-2, 2-10
XtManageChildren, 2-6, 3-32
XtMapWidget, 2-3, 2-5, 2-6
XtN, 2-10, 2-11
XtNallowHoriz, 3-27
XtNallowResize, 3-31, 3-32
XtNallowVert, 3-27
X tNbackground, 2-3, 3-4
XtNbackgroundPixmap, 2·3
XtNbetweenCursor, 3-30
XtNbitmap, 3-2, 3-5
XtNborderColor, 2-3
XtNborderPixmap, 2·3
XtNborderWidth, 2-3, 2-4
XtNbottom, 3-34
XtNcallback, 2-4, 2-10, 3-4, 3-40,
3-43, 4-4
XtNcolumnSpacing, 3-38
XtNcursor, 2-4
XtN defaultColumns, 3-38
XtNdefaultDistance, 3-33, 3-35
XtNdestroyCallback, 2-4, 2-9, 3-4,
3-7, 3-40
XtNdialogHOffset, 3-12
XtNdialogVOffset, 3-12
XtN displayPosition, 3-12
XtNeditType, 3-13
XtNediType, 3-12
XtNfile, 3-12, 3-13
XtNfont, 3-2, 3-5, 3-12, 3-13
XtNforceBars, 3-27
XtNforceColumns, 3-38
XtNforeground, 2-4, 2-11, 3-4
XtNfromHoriz, 3-34, 3-35
XtNfromVert, 3-34, 3-35

XtNgripCursor, 3-30
XtN griplndent, 3-30
XtN gripTranslations, 3-30
XtNheight, 2-3, 2-4, 3-2, 3-5, 3-23,
3-38
XtNhighlightThickness, 3-2
XtNhorizDistance, 3-33, 3-34, 3-35
XtNhSpace, 3-29
XtNinsensitiveBorder, 3-2, 3-5, 3-38
XtNinsertPosition, 3-12
XtNinternalHeight, 3-2, 3-5, 3-38
XtNinternalWidth, 3-2, 3-5, 3-38
XtNjumpProc, 3-22, 3-24, 3-25
XtNjustify, 3-2, 3-5
XtNlabel, 3-2, 3-5, 3-36
XtNleft, 3-34
XtNleftMargin, 3-12
XtNlength, 3-12, 3-13, 3-22, 3-23
XtNlist, 3-38
X tNlongest, 3-38
XtNlowerCursor, 3-30
XtNmappedWhenManaged, 2-3, 2-4
XtNmax, 3-29, 3-31, 3-32
XtNmaximumLength, 3-36
XtNmin, 3-29, 3-31, 3-32
XtNnumberStrings, 3-38
XtNorientation, 3-22
XtNpasteBuffer, 3-38
XtNrefigureMode, 3-30
XtNresizable, 3-34
XtNresize, 3-2, 3-5
XtNright, 3-34
XtNrowSpacing, 3-38
XtNscrollDCursor, 3-22
XtNscrollHCursor, 3-22
XtNscrollLCursor, 3-22
XtN scrollProc, 3-23, 3-24, 3-25
XtNscrollRCursor, 3-22
XtNscrollUCursor, 3-22
XtNscrollVCursor, 3-22
XtNselectionTypes, 3-13
XtNselectTypes, 3-12
XtNsensitive, 2-3, 2-4, 3-2, 3-5,
3-38

XtNshown, 3-22
XtNskipAdjust, 3-29, 3-31
XtNstring, 3-12, 3-13
XtNtextOptions, 3-12, 3-13
XtNtextSink, 3-12, 3-20
XtNtextSource, 3-12, 3-20
XtNthickness, 3-22, 3-23
XtNthumb, 3-22
XtNthumbProc, 3-24
XtNtop, 3-22, 3-34
XtNtranslations, 2-3, 2-4
XtNumber, 2-11, 2-12
XtNupperCursor, 3-30
XtNuseBottom, 3-27
XtNuseRight, 3-27
XtNvalue, 3-36, 3-37
XtNvertDistance, 3-33, 3-34, 3-35
XtNverticalList, 3-38
XtNvSpace, 3-29
XtNwidth, 2-3, 2-4, 3-2, 3-5, 3-23,
3-38
XtNx, 2-3, 2-4
XtNy, 2-3, 2-4
XtPanedAllowResize, 3-31
XtPanedSetMinMax, 3-32
XtPanedSetRefigureMode, 3-32
XtRealizeWidget, 2-2, 2-5, 2-10
XtRemoveAlICallbacks, 2-9
XtRemoveCallback, 2-9
XtRemoveCallbacks, 2-9
XtRubber, 3-34, 3-35
XtScrollbarSetThumb, 3-25
XtScrollbarThumb, 3-25
XtscrollProc, 3-22
XtSetArg, 2-12
XtSetMappedWhenManaged, 2-5,
2-6
XtSetValues, 2-7, 2-8, 3-2, 3-5,
3-18, 4-3, 4-5
XtStringSourceCreate, 3-20
XtStringSourceDestroy, 3-20
XttextAppend, 3-13, 3-16
XtTextBlock, 3-16, 3-17
XtTextChangeOptions, 3-18

Index 5

XtTextDisableRedisplay, 3-17
XtTextDisplay, 3-17, 3-18
XttextEdit, 3-13
XtTextEnableRedisplay, 3-17
XtTextGetlnsertionPoint, 3-19
XtTextGetOptions, 3-18
XtTextGetS electionPos, 3-15
XtTextGetSource, 3-19
XtTextGetValues, 3-13
XtTextInvalidate, 3-17
XttextRead, 3-13
XtTextReplace, 3-16, 3-17
XtTextSelectType, 3-13
XtTextSetInsertionPoint, 3-18
XtTextS etLastPos, 3-18
XtTextSetSelection, 3-15
XtTextSetSource, 3-19
XtTextSetValues, 3-13
XtTextTopPosition, 3-18
XtTextUnsetSelection, 3-15
XtUnmanageChild, 3-28, 3-29, 3-35,
3-37
XtUnmanageWidget, 3-31
XtWindow, 4-10
XT~IST_NONE, 3-42

6 Index

HOW TO ORDER ADDITIONAL DOCUMENTATION
DIRECT TELEPHONE ORDERS
In Continental USA
and New Hampshire,
Alaska or Hawaii

In Canada

call 800-267 -621 5

call 800-DIGITAL

DIRECT MAIL ORDERS (U.S. and Puerto Rico·)
DIGITAL EQUIPMENT CORPORATION
P.O. Box CS2008
Nashua, New Hampshire 03061

DIRECT MAIL ORDERS (Canada)
DIGITAL EQUIPMENT OF CANADA LTD.
100 Herzberg Road
Kanata, Ontario K2K 2A6
Attn: Direct Order Desk

I INTERNATIONAL I
DIGITAL EQUIPMENT CORPORATION
PSG Business Manager
c/o Digital's local subsidiary
or approved distributor
Intemal orders should be placed through the Software Distribution Center (SOC). Digital
Equipment Corporation. Westminster, Massachusetts 01473
*Any prepaid order from Puerto Rico must be placed
with the Local Digital Subsidiary:

809-754-7575

ULTRIX
W orksystem Software
Guide to the X Toolkit Widgets:
C Language Binding
AA-MF09A-TE

Reader's Comments

Note: This form is for document comments only. DIGITAL will use comments

submitted on this form at the company's discretion. If you require a written reply and are eligible to receive one under Software Performance
Report (SPR) service, submit your comments on an SPR form.
Did you find this manual understandable, usable, and well-organized? Please
make suggestions for improvement. ___________________

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent.

D
D

o
o
D
D
Name

Assembly language programmer
Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
Other (please specify) _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
Date ______________________

Organization _____________________________
Street _______________________________________________________
City ______________________________ State ___ Zipo~ode-------Country

·;D;~;~~ld Hen aad

Tape

--------------lr-l-n-----------;£~~v~---

on I ••
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POST AGE WILL BE PAID BY ADDRESSEE

Digital Equipment Corporation
Documentation Manager
ULTAIX Documentation Group
ZK03-3/X18
110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

11111'1111.1111 •• 1111111.11.1111.1111111.111.1.11111
- Do Not Tear - Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

ULTRIX
W orksystem Software
Guide to the X Toolkit Widgets:
C Language Binding
AA-MFOSA-TE

Reader's Comments

Note: This form is for document comments only. DIGITAL will use comments

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent.

o
o
o
o
o

Organization _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
Street ______________________________________________
City _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ State ___ Zipofode_ _ _ __
Country

- Do Not Tear • Fold Here and Tape

--------------lr-l-~-----------;~;;;--If Mailed
In the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POST AGE WILL BE PAID BY ADDRESSEE

Digital Equipment Corporation
Documentation Manager
ULTRIX Documentation Group
ZK03·3/X18
110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

111","11.11" •• 11""1.11.1"1.1111111.1 ••• 1.11"1
-

Do Not Tear· Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -