(navigation image)
Home American Libraries | Canadian Libraries | Universal Library | Community Texts | Project Gutenberg | Children's Library | Biodiversity Heritage Library | Additional Collections
Search: Advanced Search
Anonymous User (login or join us)
Upload
See other formats

Full text of "X toolkit intrinsics reference manual"

The Definitive Guides 
to the X Wi System 

Volume Five 

X Toolkit Insics 
Reference Manual 

for X Version 11 

O'Reilly & Associates, Inc. 

IABRARY COl 



Volume Five 

X Toolkit Intrinsics 
Reference Manual 

for Version 11 of the 
X Window System 

Edited by Tim O'Reilly 
Introduction by Mark Langley 

O'Reilly & Associates, Inc. 



Table of Contents 

Page 
Preface ...................................................................................................................................... vii 

Chapter I Introduction ...................................................................................................... 1 

Permuted Index .................................................................................................................... 19 

Section 1: X Toolkit Intrinsics Functions and Macros ..................................... 37 

Section 2: Prototype Procedures ............................................................................... 267 

Section 3: Intrinsics-mandated Widget Classes ................................................. 

Section 4: Athena Widgets ........................................................................................... 355 

Section 5: Appendices ..................................................................................................... 409 
A Alphabetical and Group Summaries .......................................................................... 411 
B X Toolkit Data Types ..................................................................................................... 423 
C Event Reference ............................................................................................................. 435 
D Standard Errors and Warnings ................................................................................... 491 
E Resource File Format .................................................................................................... 497 
F Translation Table Syntax .............................................................................................. 499 
G StringDefs.h Header File .............................................................................................. 507 
H Release Notes .................................................................................................................. 513 

Master Index ........................................................................................................................ 519 

Table of Contents v 



Preface 

About the X Toolkit 

The X Toolkit is the collective name for two C language subroutine libraries (Xt and Xaw) 
designed to simplify the development of X Window System applications using reusable com- 
ponents called widgets. Typical widgets include scrollbars, menus, dialog boxes, text-editing 
areas, drawing areas, etc. Each widget is made up of its own X window, but most of the work 
that goes on in that window has already been taken care of---all the application programmer 
has to do is assemble the widgets and write application-specific code that will be called in 
response to events in the widgets. 
The Xt library (the Intrinsics) consists of routines for using and building widgets. Widgets 
are defined using an object-oriented classing mechanism. The Xaw widget library is based 
on Xt and provides a small number of widgets that can be used to write simple application 
programs. 
The Xt Intrinsics are written using Xlib, the lowest level C language interface to the X Win- 
dow System. Both the Xt Intrinsics and Xlib are required by the X standard (established by 
the X Consortium) on any system that allows programming of X applications. 
Xaw was developed by MIT's Project Athena, and the acronym Xaw stands for Athena Widg- 
ets. Primarily, Xaw was designed as a simple demonstration and test of the Intrinsicsmnot 
as a complete set of widgets for writing demanding applications. There are numerous other 
widget sets provided by system vendors to implement particular user-interface styles. Most 
notably, HP has supplied a fairly extensive widget set (referred to as the HP Widgets) that is 
also provided on the MIT X release tape. In the future, though, the dominant widget set is 
likely to be one provided by OSF, as part of a product called OSF/Motif. Motif includes a 
widget set based on the I-IP Widgets and an extended version of the Intrinisics developed by 
Digital Equipment Corporation. There will also be widget sets that implement an AT&T user 
interface standard called OPEN LOOK. 
The X Toolkit Intrinsics will work the same way with any of these Xt-compatible widget sets. 
In fact, it is possible, though not always aesthetically or economically desirable, to combine 
widgets from different widget sets in the same application.* 
*Note that there are other X toolkits (note the lower-case "t" in "toolkits") that have nothing whatever to do with the 
X Toolkit (Xt), except that they have similar goals--namely, to make it easier to write standard X applications. 
These toolkits include Andrew (from Carnegie-Mellon University), InterViews (from Stanford), and Xview (from 
Sun). These are not merely different widget sets but are entirely different toolkits. They are not compatible with Xt. 

Preface vii 



About This Book 

This book is the fifth volume in the O'Reilly & Associates X Window System Series. It 
includes reference pages for each of the Xt Intrinsics functions, for useful macros and func- 
tion prototypes, for the base widget classes defined by the Intrinsics, and for the Athena 
Widgets. Reference pages are organized alphabetically for ease of access; a permuted index 
and numerous appendices and quick reference aids are also provided. 
Volumes Four and Five are designed to be used together. Volume 4 provides an explanation 
of the X Toolkit, including tutorial material and numerous programming examples. Arranged 
by task or topic, each chapter brings together a group of X Toolkit functions, describes the 
conceptual foundation they are based on, and illustrates how they are most often used in writ- 
ing applications. This volume is structured so as to be useful as a tutorial and also as a task- 
oriented reference. 
To get the most out of the examples in Volume Four, you will need the exact calling 
sequences of each function from Volume Five. To understand fully how to use each of the 
functions described in Volume Five, all but the most experienced Toolkit "hacker" will need 
the explanation and examples in Volume Four. 
Even though the Toolkit is intended to hide the low-level X interface provided by Xlib, there 
are times in writing widgets when Xlib functions will be necessary because no Xt feature 
exists to do the same thing. Volume Four describes the most common occasions for using 
Xlib but does not provide a reference to the particular functions involved. For that, see Vol- 
ume One, Xlib Programming Manual, and Volume Two, Xlib Reference Manual. 

How This Book is Organized 

Volume Five consists of reference pages for Toolkit functions. It also contains numerous 
helpful appendices. 
The book is organized as follows: 
Preface describes the organization of the book, and the conventions it follows. 
Chapter 1, Introduction, provides an overview of the functional areas the reference 
pages fall into. 
Permuted Index provides a standard UNIX ptx for all reference pages, regardless of section. 
Section 1, X Toolkit lntrinsics Functions and Macros, contains reference pages for the 
Intrinsics functions and macros. The header on each reference page states 
whether the function applies to using or building widgets, but all are organ- 
ized alphabetically. 
Section 2, Prototype Procedures, lists the prototypes used for declaring application 
callback routines, actions, widget methods, and other user-supplied func- 
tions. 
Section 3, lntrinsics-mandated Widget Classes, contains reference pages for the 
required widget classes--Core, Composite, Constraint, and Shell. 

viii X Toolkit Intrinsics Reference Manual 



Section 4, 
Appendix A, 

Appendix B, 

Appendix C, 

Appendix D, 

Appendix E, 
Appendix F, 

Appendix G, 
Appendix H, 
Master Index 

Athena Widgets, contains reference pages for the Athena widgets. 
Alphabetical and Group Summaries, provides quick reference tables that 
list each Intrinsics function alphabetically and by logical groups. 
X Toolkit Data Types, lists and explains, in alphabetical order, the struc- 
tures, enums and other typedefs used for arguments to Xt functions and 
macros. 
Event Reference, describes each event type in a reference page format. 
Each page includes information on how to select the events, when they are 
generated, the contents of the event structures, and notes on how to use 
them. 
Standard Errors and Warnings, lists the possible errors or warnings 
returned by the X Toolkit, along with their possible cause. 
Resource File Format, explains the EBNF syntax used the resource file. 
Translation Table Syntax, explains the EBNF syntax used the translation 
table. It discusses modifiers and event types. 
StringsDefs.h Header File, groups the identifiers found in StringDefs.h. 
Release Notes, summarizes the changes between these two releases. 
provides a thorough, combined index to Volumes Four and Five, making it 
easy to look up all the appropriate references to a topic, in either volume. 

Assumptions 

This book makes no assumptions about the reader's knowledge of object-oriented proam- 
ming or the X Window System. However, for many advanced topics, the reader will need to 
consult the earlier volumes in this series--Volume One, Xlib Programming Manual, and 
Volume Two, Xlib Reference Manual. 

Readers should be proficient in the C proamming language, although examples are pro- 
vided for infrequently used features of the language that are necessary or useful when pro- 
gramming with the X Toolkit. In addition, general familiarity with the principles of raster 
graphics will be helpful. 

Preface ix 



Bulk Sales Information 

This manual is being resold as the official X Window System documentation by many work- 
station manufacturers. For information on volume discounts for bulk purchase, call O'Reilly 
and Associates, Inc., at 800-338-6887 (in California, 800-533-6887), or send e-mail to 
linda@ora.com. 

For companies requiring extensive customization of the book, source licensing terms are also 
available. 

Obtaining the X Window System Software 

The X Window system is copyrighted but freely distributed. The only restriction this places 
on its use is that the copyright notice identifying the author and the terms of use must accom- 
pany all copies of the software or documentation. Thanks to this policy, the software is avail- 
able for nominal cost from a variety of sources. See Appendix G, Sources of Additional 
Information, in Volume Four, X Toolkit lntrinsics Programming Manual, for a listing of these 
sources. 

Acknowledgements 

As mentioned above, this manual is based in part on the Xt Toolkit lntrinsics---C Language 
Interface, by Joel McCormack, Paul Asente, and Ralph Swick, and on the X Toolkit Athena 
Widgets--C Language Interface, by Ralph Swick and Terry Weissman. We have done our 
best to incorporate all the useful information from these documents, while reorganizing them 
into alphabetical reference manual pages. We have clarified and expanded the descriptions 
of Intrinsics functions, added examples and cross references, and in general tried to make it 
useful for reference purposes. 
We would like to thank the authors of this document, and the X Consortium, for the copyright 
policy that allows others to build upon their work. Their generosity of spirit not only has 
made this book possible, but is the basis for the unparallelled speed with which the X Win- 
dow System has been adopted as a de facto standard. 
We would also like to thank the reviewers of the companion volume, X Toolkit Programming 
Manual. Even though they didn't directly review this book, their comments are often 
reflected in its pages. They were David Lewis and Peter Winston of Integrated Computer 
Solutions (ICS), Wendy Eisner of Sunquest Information Systems, Dan Heller of Island 
Graphics, Inc. (now working with O'Reilly and Associates), Miles O'Neal of Systems and 
Software Solutions, Inc., Chris Peterson of MIT Project Athena, and Ian Darwin of SoftQuad. 
Extra thanks are due to Ralph Swick and Chris Peterson, who answered many questions dur- 
ing the development of these books. 

Preface xi 



We are grateful to Sony Microsystems for the loan of a Sony NEWS workstation running their 
implementation of the X Window System. The speed and power of the Sony workstation, 
and the support of their staff, was a great help in developing these books. Additional devel- 
opment was done on a Sun-3 workstation running MIT's sample server, a Visual 640 X Dis- 
play Station, and an NCD16 Network Display Station. 

Mark Langley edited an early version of this book. He also authored the introduction to the 
current version and provided some of the examples on the reference pages. His help is 
greatly appreciated. 

Many staff members of O'Reilly and Associates assisted in producing this manual, particu- 
larly Donna Woonteiler, who coordinated the final production. The cover design is by Edie 
Freedman. Kathryn Ellis produced the master index. Other assistance came in many differ- 
ent forms from Daniel Gilly, Lenny Muellner, Linda Mui, Sue Willing, and Ruth Terry. 

Of course, we alone take responsibility for any errors or omissions that remain. 

--Tim O'Reilly 

xfi X Toolkit Intrinsics Reference Manual 



1 
Introduction 

The classic problem in constructing software manuals is how to resolve the conflicting needs 
of tutorial and reference. Over time, we have found that the alphabetical "man page"* 
approach of the UNIX Reference Manual has consistently made it the most accessible refer- 
ence manual we have ever used. However, as has often been pointed out by detractors of 
UNIX, this approach can make the manual impenetrable to a novice. 
We believe that the ideal solution is a programming manual/reference manual pair, in which 
the tutorial programming manual gives an understanding of the whole and the alphabetical 
reference manual supplies all of the additional details. However, in order to make this refer- 
ence manual more useful as a stand-alone document, we have also added a level of structure 
beyond alphabetization. 
First, the manual is divided into four major sections (plus appendices): the Xt Inlrinsics (and 
macros), function typedefs for widget methods and other internal routines, Inlrinsics- 
mandated widget classes, and the Athena widgets. Pages themselves are unnumbered; how- 
ever, cross-references to pages in other sections use the familiar UNIX parenthetical section 
notation--e.g., Core(3). Within the f'trst section, which includes Intrinsics function calls and 
macros, the page header indicates a general subject area for related routines. 
In this introduction, we have also provided a high-level discussion of various general topics, 
ranging from the Widget Lifecycle to Event Handling. Table 1-1 below associates various 
reference pages in Section 1 with the corresponding section in this introduction. In addition, 
the See Also section of each reference page refers back to the appropriate discussion in this 
introduction, as well as to relevant chapters in Volume Four, X Toolkit Intrinsics Program- 
ming Manual. 

*That is, manual pagcwor reference page, as we'll call it. 

Introduction I 



Table 1-1. Overview of the Intrinsics 

Introduction 
Topic 

Widget 
Lifecycle 

Classes and 
Subclasses 
Core, etc. 

Application 
Interface 

Events 

Using Wldgets 

XtCreateApplication- 
Shell 
XtCreateManaged- 
Widget 
XtCreateWidget 
XtDestroyWidget 
XtInitialize 
XtIsManaged 
XtIsRealized 
XtMainLoop 
XtManageChild 
XtManageChildren 
XtRealizeWidget 
XtUnmanageChild 
XtUnmanageChildren 

XtApplicationClass 
XtApplicationName 
XtClass 
XtCreateWidget 
XtIsSubclass 
XtSuperclass 

XtAddActions 
XtAddCallback 
XtAddCallbacks 
XtMergeArgLists 
XtOverrideCallback 
XtSetArg 
See also Resoue 
Management below 

Translations 
XtMainLoop 

Building Wldgets 

XtIsSubclass 

XtCallCallbacks 
XtHasCallbacks 
XtRemoveAllCallbacks 
XtRemoveCallback 

Function 
typedefs 

XtRemoveCallbacks 

XtExposeProc 

RemoveTimeOut 
XtAddEventHandler 
XtAddInput 
XtAddRawEvent- 
Handler 
XtAddTimeOut 
XtAppProcessEvent 
XtDispatchEvent 
XtHasInput 
XtNextEvent 
XtPeekEvent 
XtRemoveEvent- 
Handler 
XtRemoveInput 
XtRemoveRawEvent- 
Handler 

XtInitProc 
XtProc 
XtRealizeProc 
XtWidgetProc 

XtCallbackRec 

Event masks 
XEvent 

2 X Toolkit Intrinsics Reference Manual 



Table 1-1. Overview of the Intrinsics (continued) 

Introduction 
Topic 

Translations 
and 
ctions 

Graphics 

Popups 

Resource 
Management 

Geometry 
Management 

Using Wldgets 

Xlib 
Interface 

MenuPopup 
MenuPopdown 
XtAddActions 
XtAugment- 
Translations 
XtOverride- 
Translations 
XtParseTranslation- 
Table 

MenuPopdown 
MenuPopup 
XtCallbackExclusive 
XtCallbackNone 
XtCallback- 
Nonexclusive 
XtCallbackPopdown 
XtCreatePopupShell 
XtPopdown 
XtPopup 

XtGetValues 
XtSetValues 

XtConfigureWidget 
XtMakeGeometryRequest 
XtMakeResizeRequest 
XtMoveWidget 
XtQueryGeometry 
XtResizeWidget 
XtResizeWindow 
XtUnmanageChild 
XtUnmanageChildren 

Building Wldgets 

XtDestroyGC 
XtGetGC 
XtReleaseGC 

XtMoveWidget 
XtNameToWidget 

XtAddConverter 
XtConvert 
XtDirectConvert 
XtGetApplication- 
Resources 
XtGetResources 
XtGetSubResources 
XtGetSubvalues 
XtStringConversion- 
Warning 

XtAddExposureToRegion 

Function 
typede 

XtActionProc 

XtDisplay 
XtScreen 
XtWindow 

XtSetValuesFunc 

Composite 
XtArgsProc 

Introduction 3 



1.2 Classes and Subclasses 

The class mechanism allows X Toolkit programs to exploit object-oriented programming 
techniques. The widget is the basic object in the Toolkit; it is a template containing code and 
providing fields for data. In particular, a widget is defined by a class and instance structure. 
For more details on particular classes supplied with the X Toolkit, see Core, Composite, Con- 
straint, and Shell in Section 3 of this manual. 
For a detailed description of how widget class and instance structures are implemented, see 
Chapters 5 and 6 in Volume Four, X Toolkit lntrinsics Programming Manual. 

1.3 Application Interface 

An application program can communicate with widgets in several ways. A widget makes 
certain state information available through resources, which an application can both read and 
write. A widget can also pass control back to an application to handle some designated 
event. 
When an application creates a widget, it passes an argument list of resources that specify 
how a widget is to do its job. These argument lists can be created statically or can be con- 
trolled at run time with XtSetArg. (To see a complete example of this, see Chapter 3, 
Other Widget Programming Techniques, in Volume Four, X Toolkit lntrinsics Programming 
Manual.) 
The application program can write selected values inside a widget instance by using xt- 
SetValues and can read values using XtGetValues. Using XtSetValues causes 
the widget to be notified of changes asynchronously through the Core set values 
-- 
method, so the widget can be assured of working with current data. These same resource 
mechanisms can be used analogously with nonwidget data, as well. (See XtSet- 
Subvalues and XtGetSubvalues.) 

1.3.1 Callbacks 

A widget can return control to the application using Callbacks. Namely, by specifying a 
resource of type XtRCallback, an application can pass a list of procedures for the widget 
to invoke when certain things happen. (The types of events that result in a callback must be 
agreed upon between the widget and the application in advance.) 
The Intrinsics maintain callback lists in an internal format, so once a resource of type Xt- 
RCallback is passed to a widget, it cannot be accessed directly. To access callback lists, 
use one of the functions XtAddCallback, XtAddCallbacks, XtRemove- 
Callbacks, or XtRemoveAllCallbacks. 
The name of the resource for which the application can supply a callback list is often 
exported from the widget's public include file. If a widget has only one resource of type call- 
back, it will probably be called XtNcallback. 

6 X Toolkit Intrinsics Reference Manual 



1.6 Pop Ups 

A pop-up widget is a widget that bypasses geometry management and appears to pop up and 
pop down again when it is no longer needed. 
Pop ups are treated in detail in Chapter 12, Menus, Gadgets and Cascaded Pop Ups, in Vol- 
ume Four. 
Pop ups can be popped up or down as a result of a translation action (MenuPopup and 
MenuPopdown). They can also be popped up or down by specifying particular Intrinsics 
procedures in a callback list (namely, XtCallbackExclusive, XtCallback- 
Exclusive, XtCallbackNone, XtCallbackPopdown.) 
To use a pop up, first a shell must be created with XtCreatePopupShell. Then it can be 
popped up specifically using xtPopup or one of the aforementioned techniques. 
Any widget can have pop-up children: it does not need to be a subclass of Composite(3). 
Subsequently, the pop-up shell created with XtCreatePopupShell can be given its 
single normal child with XtCreateManagedWidget, specifying the pop-up shell as par- 
ent. It bypasses a widget's insert child method, even if it has one. 
A pop up can be spring-loaded so that it pops up as a result of a translation. A spring-loaded 
pop up invoked from a translation table already must exist at the time that the translation is 
invoked, so the translation manager can find the shell by name. Creating the pop-up shell 
and child in advance makes the user's act of popping up faster. 
Pop ups invoked expl'_'-citly with xtPopup or XtCallbackExclusive can be created as 
they are needed. Delaying the creation of the pop up is particularly useful when you pop up 
an unspecified number of them. The program does not have to create the shell until it is 
needed the first time, then after popping it down, it can preserve it until it is needed again. 

1.7 Resources 

Resources are a list of name-value pairs. The X server has a set of the name-value pairs that 
can be used as defaults. The Intrinsics maintain name-value pairs in the same form in the 
widget structure. Using resources, an application can communicate with a widget and vice 
versa. Arguments to widgets are also passed as resources. 
The X Window System maintains a database of resources and their values on the server. 
Individual program execution may override the values obtained from the server's database 
for the context of the program's execution. 
xt r nit i a li z e sets up the original context for program execution. 
The routines XtSetValues and XtGetValues use a resource list to set and get widget 
state. The updating of resource values from the widget class and the resource database 
occurs transparently to the widget. The Intrinsics update the widget class structure before 
calling the widget's Initialize method. 

8 X Toolkit Intrinsics Reference Manual 



Table 1-2. Overview of Resource Management Functions 

Procedure 

XtSetValues 
XtGetValues 
XtSetSubvalues 
XtGetSubvalues 
XtGetResourceList 
XtGetAppResources 
XtGetSubresources 

From 

ArgList 
Widget 
ArgLJst 
RList+Base 

Resource Manager 
Widget,ArgList 
Widget,ArgList 

Widget 
ArgList 
RList+Base 
ArgList 
Rnist (de) 
RList+Base 
RList+Base 

Used for/Lookup by 

Widget instance 
variables 

Nonwidget resources 

Default values 
By widget 
By name/class 

Each nction can be looked up sepately m understand e exact details of e routine. 
Routines to tch values of resources, le XtGetApplicationResources, accept a 
list of resources and a base poinmr. The portable and recommended way m access resources 
in a resource list is to decide a sucte that contains fields for values and to pass a pomr 
to is structe as e base address. Then xgoffseg can be used to demrmine e relative 
address of e field in the structure. 
Here is a short program that se up a resource gument list and accesses it. 
/* res.c - access application resources */ 
#include <stdio.h> 
#include <Xll/Xlib.h> 
#include <Xll/StringDefs.h> 
#include <Xll/IntrinsicP.h> 
#include <Xll/Intrinsic.h> 
/* 
* fields to be filled in from resources 
* Note that instance variables must be defined as a pointer... 
-- 
*/ 
typedef struct instance variables { 
-- -- 
String label; 
XFontStruct *font struct; 
-- 
long foreground; 
} instance variable rec, *instance variables; 
instance vriables nstanceVariabls; 
-- 
static XtResource resources[] = { 
{ 
XtNforeground, 
XtCForeground, 
XtRPixel, sizeof(Pixel), 
XtOffset(instance variables, foreground), 
-- 
XtRString, "XtDefaultForeground" 
}, 
{ 
XtNfont, 
XtCFont, 
XtRFontStruct, sizeof(XFontStruct *), 
XtOffset(instance variables, font struct), 
-- 
-- 
XtRString, "XtDefaultFont" 
}, 

10 X Toolkit Intrinsics Reference Manual 



The XtRImmediate type indicates that the value in the default address field is the 
resource value itself, not a resource. 

For the Intrinsics to find and correctly handle callback lists, they should be declared with a 
resource type of XtRCallback. Whenever a widget contains a callback list for use by cli- 
ents, it also exports in its public .h file the resource name of the callback list. Applications 
and client widgets never access callback list fields directly. Instead, they always identify the 
desired callback list by using the exported resource name. The callback manipulation func- 
tions described here check that the requested callback list is implemented by the widget 

1.7.4 

Command Line Arguments 

Command line arguments given to a program can be used to set resource values. Any 
resource in a program can be accessed from the command line using the -xrm argument For 
example, in the above program to change label, the following would work: 
ride% cc res.c -iXt -IXll 
ride% a.out -xrm '*label: New Label String' 

The standard command line arguments are shown in Table 1-4. 

Table 1-4. Command Line Arguments 

Option 

-background 
-bd 
-bw 
-borderwidth 
-bordercolor 
-display 
-fg 
-fn 
-font 
-foreground 
-geometry 
-iconic 
-name 
-reverse 
-selectionTimeout 
-synchronous 
+synchronous 
-title 
-xrm 

Resource 

*background 
*background 
*borderColor 
.borderWidth 
.borderWidth 
*borderColor 
.display 
*foreground 
*font 
*font 
*foreground 
.geometry 
.iconic 
.name 

Value 

next argument 
next argument 
next argument 
next argument 
next argument 
next argument 
next argument 
next argument 
next argument 
next argument 
next argument 
next argument 
"on" 
next argument 

Sets 

background color 
background color 
border color 
width of border in pixels 
width of border in pixels 
color of border 
server to use 
foreground color 
font name 
font name 
foreground color 
size and position 
start as an icon 
name of application 

*reverseVideo 
*reverseVideo 
*reverseVideo 
.selectionTimeout 
.synchronous 
.synchronous 
.title 
vueofargument 

' '0/I' ' 
"on" 
"off" 
Null 
"on" 
"off" 

next argument 
next argument 

reverse video 
reverse video 
No Reverse Video 
selection timeout 
synchronous debug mode 
synchronous debug mode 
title of application 
depends on argument 

Introduction 13 



The Intrinsics also provide a scheme to improve the efficiency of Graphics Contexts. See 
also xt_.Got_.GC and Xl:Dosl:-oyGC. Examples using these functions are presented in Vol- 
ume Four. 

--Mark Langley 

18 X Too/k# Intrinsics Reference Manual 



Permuted Index 

How to Use the Permuted Index 

The permuted index takes the brief descriptive string from the title of each command page 
and rotates (permutes) the string so that each keyword will at one point start the second, or 
center, column of the line. The beginning and end of the original string are indicated by a 
slash when they are in other than their original position; if the string is too long, it is trun- 
cated. 

To find the command you want, simply scan down the middle of the page, looking for a key- 
word of interest on the fight side of the blank gutter. Once you find the keyword you want, 
you can read (with contortions) the brief description of the command that makes up the entry. 
If things still look promising, you can look all the way over to the fight for the name of the 
relevant command page. 

The Permuted Index 

internal//compile an 
its descendants//'install all 
/'install a widget's 
/prototype procedure to 
/call a widget's 
XtResizeWindow: resize a widget 
MenuPopdown: built-in 
MenuPopup: built-in 
XtAppAddActions: declare an 
XtAddActions: register an 
procedure for registering 
/command button 
widget's/XtAddCallback: 
context/open, initialize, and 
procedures to a/XtAddCallbacks: 
list of managed/XtManageChild: 
[initialize a display and 
list of/XtManageChildren: 
XtAppCreateShell: create 
/create an 
dements to zero XtCalloc: 

accelerator table into its ............................ XtParseAcceleratorTable(1 ) 
accelerators from a widget and ................ XtInstallAllAccelerators(l) 
accelerators on another widget ................. XtInstallAccelerators(l) 
accept or reject keyboard focus ................ XtAcceptFocusProc(2) 
accept_focus procedure ............................ XtCallAcceptFocus(l) 
according to the values of its/ ................... XtResizeWindow(l) 
action for popping down a widget ........... MenuPopdown(1) 
action for popping up a widget ................ MenuPopup(l ) 
action table and register it/ ........................ XtAppAddActions(l) 
actaon table with the/ ................................. XtAddActions(l) 
action tables/prototype ............................ XtActionProc(2) 
activated by pointer click .......................... Command(4) 
add a callback procedure to a ................... XtAddCallback(l) 
add a display to an application ................. XtOpenDisplay(1) 
add a list of callback ................................. XtAddCaUbacks(l) 
add a widget to its parent's ....................... XtManageChild(l) 
add it to an application context ................ XtDisplayInitialize(l ) 
add widgets to their parent's .................... XtManageChildren(1) 
additional top-level widget ....................... XtAppCreateShell(l ) 
additional top-level widget ....................... XtCreateApplicationShetl(l) 
allocate an array and initialize .................. XtCalloc(l) 

Permuted Index 19 



widget Core Widget 
for a/Constraint Widget 
in DEBUG mode, verify a widget's 
Xtclass: obtain a widget's 
method used in Core widget 
resource list (by name or 
procedure for a widget 
subclass of the Composite widget 
of the Constraint widget 
a subclass of the Shell widget 
a widget is a subclass of a 
to initialize data for a widget 
XtRemoveTimeOut: 
button activated by pointer 
/by the Intrinsics when another 
from an/XtcloseDisplay: 
an application context and 
pointer/commandWidgetclass: 
button activated by pointer/ 
widget methods XtWidgetProc: 
XtDestroyGC: Release 2 
its/XtParseTranslationTable: 
into/XtParseAcceleratorTable: 
XtGetSelectionValue: obtain the 
called after a data transfer 
methods for geometry management 
a widget is a subclass of the 
/for ordering the children of 
to be called on fatal error 
to be called on fatal error 
to be called on nonfatal error 
to be called on nonfatal error 
to be called on fatal error 
to be called on nonfatal error 
to be called on nonfatal error 
to be called on nonfatal error 
provides data structures for a] 
a widget is a subclass of the 
/widget implementing 
list dynamically XtSetArg: 
/destroy an application 
/get the application 
remove it from an application 
/create an application 
and add it to an application 
add a display to an application 
XtMainLoop: 
scrollbarWidgetclass: widget to 
/perform resource 
/emit boilerplate string 
XtConvert: 
/prototype procedure called to 
/register a new resource 
/procedure passed as a resource 
/prototype of a resource 
register a new resource 
/register a case 
coordinates to//translate an x-y 

Class: fundamental, top-level ................... Core(3 ) 
Class: provides data structures ................. Constraint(3) 
class XtCheckSubclass: ........................... XtCheckSubdass(1) 
class ............................................................ Xtclass(1) 
class/prototype expose ............................ XtExposeProc(2) 
class)/update base-offset ......................... XtGetSubresources(1) 
class/prototype initialize ......................... XtInitProc(2) 
class/whether a widget is a ...................... XtlsComposite(1) 
class/a widget is a subclass ..................... XtlsConstraint(1) 
class/test whether a widget is .................. XtlsShell(1) 
class/determine whether .......................... XtlsSubclass(1) 
class/prototype procedure ....................... XtProc(2) 
clear a timeout value ................................. XtRemoveTimeOut(1) 
click/command ........................................ Command(4) 
client claims the selection ......................... XtLoseSelectionProc(2) 
close a display and remove it ................... XtcloseDisplay(1) 
close its displays/destroy ......................... XtDestroyApplicationContext(1) 
command button activated by .................. Command(4) 
commandWidgetclass: command ........... Command(4) 
common prototype procedure for ............ XtWidgetProc(2) 
compatible function to free up/ ................ XtDestroyGC(1) 
compile a translation table into ................ XtParseTranslationTable(1) 
compile an accelerator table ..................... XtParseAcceleratorTable(1) 
complete selection data ............................. XtGetSelectionValue(1) 
completes/prototype procedure .............. XtSelectionDoneProc(2) 
Composite Widget Class: defines ............ Composite(3) 
Composite widget class/whether ............ XtlsComposite(1) 
composite widget instances ...................... XtOrderProc(2) 
conditions/register a procedure .............. XtAppSetErrorHandler(1) 
conditions/register a procedure .............. XtAppSetErrorMsgHandler(1) 
conditions/register a procedure .............. XtAppSetWamingHandler(1) 
conditions./a procedure ........................... XtAppSetWamingMsgHandler(1) 
conditions/register a procedure .............. XtSetErrorHandler(1) 
conditions/register a procedure .............. XtSetErrorMsgHandler(1) 
conditions/register a procedure .............. XtSetWamingHandler(1) 
conditions /high-level procedure ............. XtSetWamingMsgHandler(1) 
Constraint Widget Class: .......................... Constraint(3) 
Constraint widget class/whether ............. XtlsConstraint(1) 
constraints on children .............................. Form(4) 
construct or modify an argument ............. XtSetArg(1) 
context and close its displays ................... XtDestroyApplicationContext(1) 
context for a given widget ........................ XtWidgetToApplicationContext(1) 
context/close a display and ..................... XtCloseDisplay(1) 
context ........................................................ XtCreateApplicationContext( 1 ) 
context/initialize a display ...................... XtDisplayInitialize(1) 
context/open, initialize, and .................... XtOpenDisplay(1) 
continuously process events ..................... XtMainLoop(l) 
control scrolling of viewing/ .................... Scrollbar(4) 
conversion and cache result ..................... XtDirectConvert(1) 
conversion error message ......................... XtStringConversionWaming(1) 
convert resource type ................................ XtConvert(1) 
convert the se of keysyms ..................... XtCaseProc(2) 
converter for an application ...................... XtAppAddConverter(1) 
converter of type XtRCallProc ................. XtResourceDefaultProc(2) 
converter procedure .................................. XtConverter(2) 
converter XtAddConverter: ..................... XtAddConverter(l) 
converter .................................................... XtRegisterCaseConverter(1) 
coordinate pair from widget ..................... XtTranslateCoords(l) 

22 X Toolkit Intrinsics Reference Manual 



XtNumber: determine the 
XtGetGC: 
XtClass: 
XtSuperclass: 
multiple/XtGetSelectionValues: 
data XtGetSelectionValue: 
for/XtAppGetErrorDatabaseText: 
for an/XtGetErrorDatabaseText: 
XtAppGetErrorDatabase: 
XtGetErrorDatabase: 
a particular/XtDatabase: 
XtOffset: determine the byte 
display to an/XtOpenDisplay: 
/prototype procedure for 
ones/merge new translations, 
/transhte an x-y coordinate 
data structures for a widget's 
XtMakeGeometryRequest: request 
XtMakeResizeRequest: request 
widget XtParent: return the 
/remove a list of children from a 
a widget is managed by its 
children/add a widget to its 
children/add widgets to their 
/remove a widget from its 
of type//prototype procedure 
XtWorkProc: 
cache result XtDirectConvert: 
gripWidgetClass: attachment 
/command button activated by 
XtDisplay: return the display 
XtScreen: return the screen 
/translate a window and display 
callback/XtCallbackPopdown: 
/callback function to 
/callback function to 
/callback function to 
MenuPopdown: built-in action for 
MenuPopup: built-in action for 
XtCreatePopupShell: create a 
XtPopdown: unmap a 
XtPopup: map a 
/que a child widget's 
XtRemoveEventHandler: rcmove a 
XtAppAddTimeOut: invoke a 
XtSelectionDoneProc: prototype 
XtLoseSelectionProc: prototype 
case of/XtCaseProc: prototype 
XtInputCalibackProc: prototype 
selection data//prototype 
XtRealizeProc: prototype 
application/register a work 
XtInitProc: prototype initialize 
XtAddWorkProc: register a work 
XtStringProc: prototype 
method XtArgsProc: prototype 
children/XtOrderProc: prototype 
tables XtActionProc: prototype 

number of elements in a/ .......................... XtNumber(1) 
obtain a read-only, sharable GC ............... XtGetGC(1) 
obtain a widget's class .............................. Xtclass(1) 
obtain a widget's superclass ..................... XtSuperclass(1) 
obtain selection data in ............................. XtGetSelectionValues(1) 
obtain the complete selection ................... XtGetSelectionValue(1) 
obtain the error database text ................... XtAppGetErrorDatabaseText(1) 
obtain the error database text ................... XtGetErrorDatabaseText(1 ) 
obtain the error database ........................... XtAppGetErrorDatabase(1 ) 
obtain the error database ........................... XtGetErrorDatabase(1) 
obtain the resource database for ............... XtDatabase(1) 
offset of a field within a/ ........................... XtOffset(1) 
open, initialize, and add a ......................... XtOpenDisplay(1) 
ordering the childrcn of/ ........................... XtOrderProc(2) 
overwriting widget's existing ................... XtOverrideTranslations(1) 
pair from widget coordinates to/ .............. XtTranslateCoords(1) 
parent/Widget Class: provides ................ Con straint(3) 
parent to change child's/ ........................... XtMakeGeometRequest(1 ) 
parent to change child's size .................... XtMakeResizeRequest(l ) 
parcnt widget for the specified ................. XtParcnt(1) 
parent widget's managed list .................... XtUnmanageChildren(1) 
parcnt/determine whether ....................... XtlsManaged(1) 
parcnt's list of managed ............................ XtManageChild(1) 
parcnt's list of managed ............................ XtManageChildren(1) 
parcnt's managed list ................................ XtUnmanageChild(1) 
passed as a rcsource converter ................. XtResourceDcfaultProc(2) 
perform background processing .............. XtWorkProc(2) 
perform rcsource conversion and ............. XtDircctConvert(1) 
point for dragging other widgets .............. Grip(4) 
pointer click ............................................... Command(4) 
pointer for the specified widget ................ XtDisplay(1) 
pointer for the specified widget ................ XtScrcen(1) 
pointer into a widget instance ................... XtWindowToWidget(1) 
pop down a widget from a ........................ XtCallbackPopdown(1) 
pop up a widget ......................................... XtCallbackExclusive(1) 
pop up a widget ......................................... XtCallbackNone(1) 
pop up a widget ......................................... XtCallbackNonexclusive(1) 
popping down a widget ............................ MenuPopdown(1) 
popping up a widget .................................. MenuPopup(1) 
pop-up shell ............................................... XtCrcatePopupShell(1) 
pop-up shell ............................................... XtPopdown(1) 
pop-up shell ............................................... XtPopup(1) 
preferred geomet .................................... XQueGeometry(1) 
previously rcgistercd event/ ..................... XtRemoveEventHandler(1 ) 
procedurc after a specified/ ...................... XtAppAddTimeOut(1) 
procedure called after a data/ ................... XtSelectionDoneProc(2) 
procedure called by the/ ............................ XtLoseSelectionProc(2) 
procedure called to convert the ................ XtCaseProc(2) 
procedure called to handle file/ ................ XtInputCallbackProc(2) 
procedurc called when requested ............. XtSelectionCallbackProc(2) 
procedurc called when widget is/ ............. XtRealizeProc(2) 
procedure for a given ................................ XtAppAddWorkProc(1) 
procedure for a widget class ..................... XtInitProc(2) 
procedure for an application ..................... XtAddWorkProc(1) 
procedure for/ ............................................ XtStringProc(2) 
procedure for get_values_hook ................ XtArgsProc(2) 
procedure for ordering the ........................ XtOrderProc(2) 
procedure for registering action ............... XtActionProc(2) 

Permuted Index 29 



table into its internal 
geometry XtMakeGeometryRequest: 
size XtMakeResizeRequest: 
/prototype procedure called when 
procedure to handle geometry 
XtResizeWidget: 
values of its/XtResizeWindow: 
XtConfigureWidget: move and/or 
result XtDirectConvert: perform 
application/register a new 
/prototype procedure passed as a 
XtConverter: prototype of a 
XtAddConverter: register a new 
XtDatabase: obtain the 
/update base-offset 
/update base-offset 
list/copy from base-offset 
/retrieve default values for a 
copy from ArgList to base-offset 
table and register it with the 
XtConvert: convert 
procedure to a widget's callback 
argument list XtGetValues: copy 
XtSetValues: copy 
Shell Widget Class: application 
XtBuildEventMask: 
resource/XtGetResourceList: 
application's/XtAppNextEvent: 
queue XtNextEvent: 
/prototype procedure to 
the specified widget XtDisplay: 
specified widget XtParent: 
the specified widget XtScreen: 
specified widget XtWindow: 
pair from widget coordinates to 
down a widget from a callback 
/widget for managing 
widget XtScreen: return the 
management viewportWidgetClass: 
control scrolling of viewing/ 
another//widget to control 
/an event handler without 
/procedure called when requested 
XtGetSelectionValues: obtain 
XtOwnSelection: indicate that 
XtDisownSelection: indicate that 
/prototype procedure to return 
/obtain the complete 
/get the current 
/get the current 
/set the htrinsics 
/set value of 
when another client claims the 
XtIsSensitive: check the current 
XtSetSensitive: set the 
XtAppSetSelectionTimeout: 
widget XtSetSensitive: 
XtSetSelectionTimeout: 

representation/a translation ..................... XtParseTranslationTable(1) 
request parent to change child's ............... XtMakeGeometryRequest(1) 
request parent to change child's ............... XtMakeResizeRequest(1 ) 
requested selection data arrives ................ XtSelectionCallbackProc(2) 
requests/prototype ................................... XtGeometryHandler(2) 
resize a child or sibling widget ................. XtResizeWidget(1) 
resize a widget according to the ............... XtResizeWindow(1) 
resize widget .............................................. XtConfigureWidget(1) 
resource conversion and cache ................ XtDirectConvert(1) 
resource converter for an .......................... XtAppAddConverter(1) 
resource converter of type/ ....................... XtResourceDefaultProc(2) 
resource converter procedure ................... XtConverter(2) 
resource converter ..................................... XtAddConverter(1) 
resource database for a/ ............................ XtDatabase(1 ) 
resource list (by application) .................... XtGetApplicationResources(1) 
resource list (by name or class) ................ XtGetSubresources(1) 
resource list to the argument .................... XtGetSubvalues(1) 
resource list ................................................ XtGetResourceList(1) 
resource list XtSetSubvalues: .................. XtSetSubvalues(1) 
Resource Manager/an action .................. XtAppAddActions(1) 
resource type ............................................. XtConvert(1 ) 
resource/add a callback ........................... XtAddCallback(1) 
resources from a widget to the ................. XtGetValues(1) 
resources from ArgList to widget ............ XtSetValues(1) 
resources linking window/ ........................ ShellO) 
retrieve a widget's event mask ................. XtBuildEventMask(l) 
retrieve default values for a ...................... XtGetResourceList(1) 
return next event from an ......................... XtAppNextEvent(l) 
return next event from input ..................... XtNextEvent(l) 
return selection data .................................. XtConvertSelectionProc(2) 
return the display pointer for .................... XtDisplay(1) 
return the parent widget for the ................ XtParent(l) 
return the screen pointer for ..................... XtScreen(l) 
return the window of the ........................... XtWindow(1) 
root coordinates/x-y coordinate .............. XtTranslateCoords(1) 
routine XtCallbackPopdown: pop ........... XtCailbackPopdown(1) 
row-column geometry ............................... List(4) 
screen pointer for the specified ................ XtScreen(1) 
scrollable widget for geometry ................. Viewport(4) 
scrollbarWidgetClass: widget to .............. Scrollbar(4) 
scrolling of viewing area in ...................... Scrollbar(4) 
selecting for the event ............................... XtAddRawEventHandler(l ) 
selection data arrives ................................. XtSelectionCallbackProc(2) 
selection data in multiple/ ......................... XtGetSelectionValues(1) 
selection data is available ......................... XtOwnSelection(1) 
selection data is no longer/ ....................... XtDisownSelection(1) 
selection data ............................................. XtConvertSelectionProc(2) 
selection data ............................................. XtGetSelectionValue(1) 
selection timeout value ............................. XtAppGetSelectionTimeout(1) 
selection timeout value ............................. XtGetSelectionTimeout(1) 
selection timeout ....................................... XtAppSetSelectionTimeout(l) 
selection timeout ....................................... XtSetSelectionTimeout(1) 
selection/by the Intrinsics ....................... XtLoseSelectionProc(2) 
sensitivity state of a widget ...................... XtIsSensitive(1) 
sensitivity state of a widget ...................... XtSetSensitive(1) 
set the Intrinsics selection/ ........................ XtAppSetSelectionTimeout(1) 
set the sensitivity state of a ....................... XtSetSensitive(1) 
set value of selection timeout .................. XtSetSelectionTimeout(1) 

32 X TooAkit Intrinsics Reference Manual 



/set the Intrinsics selection 
set value of selection 
callback procedure invoked when 
Xtlnitiallze: initialize 
fmitiallze the X 
Core Widget Class: fundamental. 
/create additional 
/create an additional 
procedure called after a data 
prototype procedure to 
widget instance XtNameToWidget: 
pointer into/XtWindowToWidget: 
from widget/XtTranslateCoords: 
an action table with the 
internal//compile a 
widget's existing//merge new 
/nondestructively merge new 
/remove existing 
register a key 
registered keycode-to-keysym 
registered keycode-to-keysym 
XtMergeArgLists: merge 
XtConvert: convert resource 
for one instance of a data 
as a resource converter of 
XtPopdown: 
XtUnmapWidget: 
(by/XtGetApplicationResources: 
(by name or/XtGetSubresources: 
XtConvertCase: determine 
back to/XtRemoveGrab: redirect 
XtAddGrab: redirect 
map_when_managed//change the 
XtSetSelectionTimeout: set 
XtAddTimeOut: create a timeout 
the current selection timeout 
the current selection timeout 
XtRemoveTimeOut: clear a timeout 
/retrieve default 
/resize a widget according to the 
XtCheckSubclass: in DEBUG mode, 
upper-case and lower-case 
/geometry-managing widget for 
/widget to control scrolling of 
widget for geometry management 
geometry-managing widget for/ 
/call the installed high-level 
call the installed low-level 
call the installed high-level 
for low-level error and 
for high-level error and 
database text for an error or a 
database text for an error or a 
of its/XtResizeWindow: resize a 
fmstall all accelerators from a 
/the windows associated with a 
/redirect user input from modal 
geometry-managing box 

time.out ....................................................... XtAppSetSelectionTimeout(1) 
time.out XtSetSelectionTimeout: ............ XtSetSelectionTimeout(1) 
timeouts expire/prototype ....................... XtTimerCallbackProc(2) 
toolkit and display ..................................... Xtlnitiallze(1) 
Toolkit internals ......................................... XtToolkitInitialize(1) 
top-level widget ......................................... Core(3) 
top-level widget ......................................... XtAppCreateShell(1) 
top-level widget ......................................... XtCreateAppllcationShell(1 ) 
transfer completes/prototype .................. XtSelectionDoneProc(2) 
translate a key XtKeyProc: ...................... XtKeyProc(2) 
translate a widget name to a ..................... XtNameToWidget(1) 
translate a window and display ................ XtWindowToWidget(1) 
translate an x-y coordinate pair ................ XtTranslateCoords(1) 
Translation Manager/register .................. XtAddActions(1) 
translation table into its ............................. XtParseTranslationTable(1) 
translations, overwriting ........................... XtOverrideTranslations (1) 
translations with widget's/ ........................ XtAugmentTranslations(1) 
translations ................................................. XtUninstallTranslation s (1) 
translator XtSetKeyTranslator: ................ XtSetKeyTranslator(1) 
translator fmvoke the currently ................ XtTranslateKey(1) 
translator fmvoke the currently ................ XtTranslateKeycode(1 ) 
two ArgList structures ............................... XtMergeArgLists(1) 
type ............................................................. XtConvert(1) 
type XtNew: allocate storage ................... XtNew(1) 
type XtRCallProc/passed ........................ XtResourceDefaultProc(2) 
unmap a pop-up shell ................................ XtPopdown(1) 
unmap a widget explicitly ........................ XtUnmapWidget(1) 
update base-offset resource list ................ XtGetApplicationResources(1) 
update base-offset resource list ................ XtGetSubresources(1) 
upper-case and lower-case/ ...................... XtConvertCase(1) 
user input from modal widget .................. XtRemoveGrab(1) 
user input to a modal widget .................... XtAddGrab(1) 
value of a widget' s .................................... XtSeLMappedWhenManaged(1 ) 
value of selection timeout ......................... XtSetSelectionTimeout(1) 
value ........................................................... XtAddTimeOut(1) 
value/get ................................................... XtAppGetSelectionTimeout(1) 
value/get ................................................... XtGetSelectionTimeout(1) 
value ........................................................... XtRemoveTimeOut(1) 
values for a resource list ........................... XtGetResourceList(1) 
values of its core dimensions ................... XtResizeWindow(1) 
verify a widget's class ............................... XtCheckSubclass(1) 
versions of a keysym/determine ............. XtConvertCase(1) 
vertical Kles ................................................ VPaned(4) 
viewing area in another widget ................ Scrollbar(4) 
viewportWidgetclass: scrollable ............. Viewport(4) 
vPanedWidgetclass: ................................. VPaned(4) 
warning handler ......................................... XtAppWamingMsg (1) 
warning handler XtWaming: ................... XtWaming(1) 
warning handler XtWamingMsg: ............ XtWamingMsg(1) 
warning handlers/prototype .................... XtErrorHandler(2) 
waming handlers/prototype .................... XtErrorMsgHandler(2) 
warning/obtain the error .......................... XtAppGetErrorDatabaseText(1) 
waming/obtain the error .......................... XtGetErrorDatabaseText(1) 
widget according to the values ................. XtResizeWindow(1) 
widget and its descendants onto/ .............. XtInstaHA11Accelerators(1) 
widget and its descendants ....................... XtUnrealizeWidget(1) 
widget back to normal/ ............................. XtRemoveGrab(1) 
widget boxWidgetclass: .......................... Box(4) 

34 X Toolkit Intrinsics Reference Manual 



resources linking window/Shell 
for geometry/Composite 
top-level widget Core 
structures for a/Constraint 
expose method used in Core 
initialize procedure for a 
is a subclass of the Composite 
is a subclass of the Constraint 
is a subclass of the Shell 
to initialize data for a 
/an x-y coordinate pair from 
Class: fundamental, top-level 
dialogWidgetclass: dialog Box 
XtUnmapWidget: unmap a 
viewportWidgetclass: scrollable 
geometry listWidgetclass: 
XtParent: return the parent 
/geometry-managing 
XtCallbackPopdown: pop down a 
list XtUnmanageChild: remove a 
/determine whether a 
on children/geometry-managing 
XtDestroyWidget: destroy a 
translate a widget name to a 
XtRealizeWidget: realize a 
and display pointer into a 
the children of composite 
/determine whether a 
XtIsComposite: test whether a 
XtsConstraint: test whether a 
Shell/XtIsShell: test whether a 
XtIsManaged: determine whether a 
/prototype procedure called when 
action for popping down a 
built-in action for popping up a 
common prototype procedure for 
XtNameToWidget: translate a 
XtMoveWidget: move a 
of viewing area in another 
widget to create a custom 
textWidgetclass: text-editing 
viewing/scrollbarWidgetclass: 
templateWidgetclass: 
string labelWidgetclass: 
XtMapWidget: map a 
managed/XtManageChild: add a 
/copy resources from a 
redirect user input to a modal 
create additional top-level 
callback function to pop up a 
callback function to pop up a 
callback function to pop up a 
move and/or resize 
/create an additional top-level 
create and manage a child 
create an instance of a 
pointer for the specified 
widget's accelerators on another 

Widget Class: application ......................... Shell(3) 
Widget Class: defines methods ................ Composite(3) 
Widget Class: fundamental ....................... Core(3) 
Widget Class: provides data ..................... Constraint(3) 
widget class/prototype ............................. XtExposeProc(2) 
widget class/prototype ............................. XtinitProc(2) 
widget class/whether a widget ................ XtIsComposite(1) 
widget class/whether a widget ................ XtIsConstraint(1) 
widget class/whether a widget ................ XtisShell(1) 
widget class/procedure ............................ XtProc(2) 
widget coordinates to root/ ....................... XtTranslateCoords(1) 
widget Core Widget .................................. Core(3) 
widget ......................................................... Dialog(4) 
widget explicitly ........................................ XtUnmapWidget(1) 
widget for geometry management ........... Viewport(4) 
widget for managing row-column ............ List(4) 
widget for the specified widget ................ XtParent(1) 
widget for vertical tiles ............................. VPaned(4) 
widget from a callback routine ................. XtCallbackPopdown(1) 
widget from its parent's managed ............ XtUnmanagcChild(1) 
widget has been realized ........................... XtIsRealized(1) 
widget implementing constraints ............. Form(4) 
widget instance .......................................... XtDestroyWidget(1) 
widget instance XNameToWidget: ........ XtNameToWidget(1) 
widget instance .......................................... XtRealizeWidget(1) 
widget instance/a window ....................... XtWindowToWidget(1) 
widget instances/for ordering ................. XtOrderProc(2) 
widget is a subclass of a class .................. XtIsSubclass(1) 
widget is a subclass of the/ ....................... XtIsComposite(1) 
widget is a subclass of the/ ....................... XtIsConstraint(1) 
widget is a subclass of the ........................ XtIsShell(1) 
widget is managed by its parent ............... XtIsManaged(1) 
widget is realized ....................................... XtRealizeProc(2) 
widget MenuPopdown: built-in ............... MenuPopdown(1) 
widget MenuPopup: ................................. MenuPopup(1) 
widget methods XtWidgetProc: .............. XtWidgetProc(2) 
widget name to a widget instance ............ XtNameToWidget(1) 
widget on the display ................................ XtMoveWidget(1) 
widget/to control scrolling ...................... Scrollbar(4) 
widget templateWidgetclass: .................. Template(4) 
widget ......................................................... Text(4) 
widget to control scrolling of ................... Scrollbar(4) 
widget to create a custom widget ............. Template(4) 
widget to display a non-editable .............. Label(4) 
widget to its display .................................. XtMapWidget(1) 
widget to its parent's list of ...................... XtManageChild(1) 
widget to the argument list ....................... XtGetValues(1) 
widget XtAddGrab: .................................. XtAddGrab(1) 
widget XtAppCreateShell: ....................... XtAppCreateShell(1) 
widget XtCallbackExclusive: .................. XtCallbackExclusive(1 ) 
widget. XtCallbackNone: ......................... XtCallbackNone(1) 
widget. XtCallbackNonexclusive: ........... XtCallbackNonexclusive(1) 
widget XtConfigureWidget: .................... XtConfigureWidget(1) 
widget ......................................................... XtCreateApplicationShell(1) 
widget XtCreateManagedWidget: ........... XtCreateManagedWidget(l) 
widget XtCreateWidget: ........................... XtCreateWidget(1) 
widget/retum the display ......................... XtDisplay(1) 
widget fmstall a ......................................... Xt/nstallAccelerators(1) 

Permuted Index 35 



X Toolkit Intrinsics 
Functions and Macros 

This section contains alphabetically-organized reference pages for each lntrinsics 
function and macro. 

Each page contains a synopsis of the routine's calling sequence, its arguments, a 
description of its function, and a reference to related routines. 



Xt- Pop Ups (continued) MenuPopup 

MenuPopup gets to the application widget and cannot find a matching shell, it generates an 
error. 

See Also 
MenuPopdown, XtPopDown, XtPopup. 

X Toolkit Intrinsics Reference Manual 41 



Xt- Callbacks (continued) XtAddCallback 

Callbacks differ from actions in the way that the registered function is invoked. For callbacks, 
the trigger is an abstract occurrence defined by the widget, which may or may not be event- 
related. The routines on a widget's callback lists are invoked by the widget code, using a call 
to XgCaZZCaZZbacks. Actions, on the other hand, are invoked directly by Xt, as the result 
of an event combination specified by the translations mechanism. 
Another major difference between an action function and a callback function is that action 
functions are called with an event as an argument, while actions do not have the 
c2ient daea or ca22 daea arguments present for callback functions. This means the 
__ -- 
only way to pass application data into an action function is through global variables. On the 
other hand, the presence of the event argument means that you can use the contents of the event 
structure in the action function. 

See Also 
Section 1.3, "Application Interface," 
Xt AddCa i iba c k s, Xt Ca 1 iCa 1 iba c k s, Xt RemoveAl iCa 1 iba c k s, Xt Remove- 
Cal iback, XtRemoveCallbacks, 
XtCa i ibac kP roc(2). 

X Toolkit Intrinsics Reference Manual 45 



Xt - Callbacks (continued) XtAddCallbacks 

to XtCallCallbacks. Actions, on the other hand, are invoked directly by Xt, as the result 
of an event combination specified by the translations mechanism. 
Another major difference between an action function and a callback function is that action 
functions are called with an event as an argument, while actions do not have the 
client_data or call_data arguments present for callback functions. This means the 
only way to pass application data into an action function is through global variables. On the 
other hand, the presence of the event argument means that you can use the contents of the event 
structure in the action function. 
There are many cases where you might want to add more than one callback function to the 
same callback list. The use of XtCallbackExclusive et al. provides a good case in point. 
There are Intrinsics-defined callback functions that can be used to pop up a widget However, 
they do not place the pop up. 
To pop up a dialog box upon the press of a command button, you would typically add two call- 
back functions to the Command widget's XtNcallback list: one of the Intrinsics-supplied 
XtCallback* functions, and one of your own to place the pop up. 
One way to add more then one callback function is to call XtAddCallback more than once. 
Another way is to call XtAddCallbacks, which takes an XtCallbackRect array as an 
argument This array is usually initialized at compile time, as shown in the example below. 
The final NULL, NULL entry terminates the list. (This particular list registers the functions 
place_popup and XtCallbackExclusive and passes them both 0 as client_data.) 
XtCallbackRec quit_callback_list [] = { 
{place_popup, 0 } 
{XtCallbackExclusive, 0}, 
{ (XtCallbackProc) NULL, (caddr t) NULL}, 
-- 
} 
This form of XtCallbackRec list can also be used to replace a callback list with XtSet- 
Values (but not to get a callback list, because Xt compiles the list into an internal form). 

Structures 
typedef struct XtCallbackRec* 
-- 
typedef struct XtCallbackRec { 
-- 
XtCallbackProc callback; 
caddr t client data; 
_ -- 
} XtCallbackRec, *XtCallbackList; 

XtCallbackList; 

See Also 
Section 1.3, "Application Interface," 
XtAddCallback, XtCallCallbacks, XtRemoveAllCallbacks, XtRemove- 
Callback, XtRemoveCallbacks, 
XtCa 1 ibackP ro c(2). 

X Toolkit Intrinsics Reference Manual 47 



XtAddConverter 

Xt - Resource Management--- 

Name 
XtAddConverter B register a new resource converter. 

Synopsis 
void XtAddConverter (from_type, to_type, 
num_args) 
String from_type; 
String to_type; 
XtConverter converter; 
XtConvertArgList convert_args; 
Cardinal num_args; 

converter, 

convert_args, 

Arguments 
from_type 

to_type 
converter 

Specifies the source type of the resource to be converted. 
Specifies the destination type to which the resource is to be converted. 
Specifies the converter procedure. See xtConverter(2). 

convert_args 
Specifies how to obtain additional arguments needed for the conversion; if no 
arguments are provided, this should be NULL. See the Structures section 
below for a detailed description of the format of convere_args. 
n um_a rgs Specifies the number of additional arguments to the convener or zero. 

Description 
XtAddConverter obtains the default application context and invokes XtAppAdd- 
Converter. XtAddConverter is a simplified interface to XtAppAddConverter, and 
the calling sequences are identical, except that you do not need to specify an application con- 
text. Since most applications have only one application context, XtAddConverter does not 
require the application to pass app_context explicitly. See XtAppAddConverter for 
additional details. See xtConverter(2) for a description of the contents of a resource con- 
vener. 

Structures 
typedef struct { 
XtAddressMode address mode; 
caddr t address id; 
_ -- 
Cardinal size; 
} XtConvertArgRec, *XtConvertArgList; 

See Also 
Xt AppAddConve rt e r, 
Xt Co nve rte r(2). 

48 X Toolkit Intrinsics Reference Manual 



XtAddGrab 

Xt - Pop Ups m 

Name 
XtAddGrab -- redirect user input to a modal widgeL 

Synopsis 
void XtAddGrab(w, exclusive, spring_loaded) 
Widget w; 
Boolean exclusive; 
Boolean spring_loaded; 

Arguments 

Specifies the widget to add to the modal cascade. 

excl usi ve 

Specifies whether user events should be dispatched exclusively to this widget 
or also to previous widgets in the cascade. 

spring_l oaded 
Specifies whether this widget was popped up because the user pressed a 
pointer button. 

Description 
XtAddGrab appends a widget to a modal cascade. Modal widgets are widgets that, except for 
the input directly to them, lock out user input to the application. XtAddGrab affects only Xt's 
event dispatching--it does not request a key or button grab on the server. 
When a modal menu or modal dialog box is popped up, user events (keyboard and pointer 
events) that occur outside the modal widget should be delivered to the modal widget or 
ignored. In no case should user events be delivered to a widget outside the modal widget. 
Menus can pop up submenus, and dialog boxes can pop up further dialog boxes to create a 
pop-up cascade. In this case, user events may be delivered to one of several modal widgets in 
the cascade. 
Display-related events should be delivered outside the modal cascade so that Expose events 
and the like keep the application's display up to date. Any event that occurs within the cascade 
is delivered as usual. The user events that are delivered to the most recent spring-loaded shell 
in the cascade when they occur outside the cascade are called remap events. These events are 
KeyPress, KeyRelease, ButtonPress, and ButtonRelease. The user events that are 
ignored whcn thcy occur outsidc thc cascadc arc MotionNotify, EnterNotify, and 
LeaveNotify. All other events are delivered normally. 
xtPopup uses the XtAddGrab and XtRemoveGrab functions to constrain user events to a 
modal cascade and subsequently to remove a grab when the modal widget goes away. Usually 
you should have no need to call them explicitly. XtAddGrab is called implicitly by Xt- 
CallbackExclusive and other calls. 
The XtAddGrab function appends the widget (and associated parameters) to the modal cas- 
cade and checks that exclusive is TRUE if spring_loaded is TRUE. If these are not both 
TRUE, XtAddGrab generates a warning and asserts an exc2 usive grab anyway. 

52 X Toolkit Intrinsics Reference Manual 



Xt- Pop Ups (continued) XtAddGrab 

When the modal cascade holds at least one widget, XtDispatchEvent determines if the 
event should be delivered or held. It starts with the last cascade entry and follows the cascade 
till it finds the youngest cascade entry added with exc2 us_/ve TRUE. If it finds a widget in the 
cascade interested in the event, it delivers the event to it. 

This modal cascade, along with all descendants of the widgets it contains, comprise the active 
subset. User events that occur outside the widgets in this subset are ignored or remapped. 
Modal menus generally add pop-up submenus to the cascade with exc2 us_/ve set to FALSE, 
SO that the submenu can receive input event after it pops up. Modal dialog boxes that resa'ict 
user input to the most deeply nested dialog box add a subdialog widget to the cascade with 
excl usi ve set to TRUE. User events that occur within the active subset are delivered to the 
appropriate widget, which is usually a descendant of the modal widget. 
Regardless of where they occur on the display, redirected events are always delivered to the 
most recent widget in the active subset of the cascade that has spring_loaded TRUE, if any 
such widget exists. 

See Also 
XtCallbackExclusive, XtCreatePopupShell, XtDispatchEvent, XtPopup, 
XtRemoveGrab. 

X Toolkit Intrinsics Reference Manual 53 



XtAddlnput 

Xt- Event Handling 

Name 
XtAddlnput -- register a new file as an input source for an application. 

Synopsis 
Xt Input Id XtAddInput (source, 
int source; 
caddr t condition; 
Xt InputCallbackProc proc; 
caddr t client data; 

condition, proc, 

client_data) 

Arguments 
source 

condition 

proc 

client data 

Specifies the source file descriptor (on a UNIX-based system) or other 
operating-system-dependent device specification. 

Specifies a mask that indicates a read, write, or exception condition or some 
operating-system-dependent condition. 

Specifies the procedure that is to be called when input is available. See Xt- 
Input Ca 1 ibac kP r oc(2). 

Specifies the argument to be passed to the specified procedure when input is 
available. 

Description 
XtAddInput obtains the default application context and invokes XtAppAddInput. Xt- 
AddInput is a simplified interface to XtAppAddInput, and except that you do not need to 
specify an application context, the calling sequences are identical. Since most applications 
have only one application context, XtAddTnput does not require the application to pass 
app_con t ext explicitly. 
While most applications are driven only by X events, some applications need to incorporate 
other sources of input. XtAppAddTnput allows an application to integrate notification of 
pending file data into the event mechanism. The application uses XtAppAddTnput tO regis- 
ter a file with the Intrinsics read routine. When I/O is pending on the file source, the regis- 
tered callback procedure proc is invoked, source is usually file input but can also be file 
output. (Note that "file" means any sink or source of data.) 
XtAppAddInput alSO specifies the condi ti on under which source can generate events. 
The legal values for condition are operating-system-dependent. On a UNIX-based system, 
the possible values are xt InputReadMask, Xt InputWriteMask, or Xt InputExcept- 
Mask. The masks cannot be ORed together. These limit the invocation of proc tO either a 
pending read, write, or exception condition on the source file. See the UNIX system select 
call for discussion of these conditions. 
Callback procedures that are used when there are file events are of type xt TnputCallback- 
Proc. 

54 X Toolkit Intrinsics Reference Manual 



Xt- Event Handling (continued) XtAddlnput 

Note that when reading from a socket, you should be careful not to close the end of the socket 
that is waiting before exiting the XtHainr,oop. If you do this, you will get an infinite loop, in 
which the proc is called repeatedly, while the Intrinsics wait for an EOF to be read. 

See Chapter 8, More Input Techniques, in Volume Four, X Toolkit Intrinsics Programming 
Manual, for a complete example using this function. 

See Also 
XtAppAddInput, XtRemoveInput, 
Xt InputCa llbackP roc(2). 

X Toolkit Intfinsics Reference Manual 55 



Xt - Event Handling (continued) XtAd d RawEventHan die r 

See Also 
Sectionl.4,"Even," 
XtAddEventHandler, XtRemoveRawEventHandler, 
XtEventHandler(2). 

X Toolkit Intrinsics Reference Manual 57 



--Xt- Event Handling 

XtAddWorkProc 

Name 
XtAddWorkProc -- register a work procedure for an application. 

Synopsis 
XtWorkProcId XtAddWorkProc (proc, client data) 
-- 
XtWorkProc proc; 
caddr t client data; 

Arguments 
proc 

Specifies the procedure to be called when the application is idle. 

client data Specifies the argument to be passed to the specified procedure when it is 
called. 

Description 
XtAddWorkProc obtains the default application context and invokes XtAppAddWork- 
Proc. It is a simplified interface to XtAppAddWorkProc. Since most applications have 
only one app_context, XtAddWorkProc does not require the application to pass an 
app_ c on t ex t explicitly. 
XtWorkProc(2) discusses the responsibilities of the application's background processing rou- 
tine. 

See Also 
XtAppAddWorkP roc, XtRemoveWorkP roc, 
XtWo rkP roc(2). 

X Toolkit Intrinsics Reference Manual 59 



XtAppAddConverter 

Xt - Resource Management m 

Name 
XtAppAddConverter -- register a new resource converter for an application. 

Synopsis 
void XtAppAddConverter ( app_context, from_type, to_type, 
converter, convert_args, num_args) 
XtAppContext app_context ; 
String from_type; 
String to_type; 
XtConverter converter; 
XtConvertArgList convert_args; 
Cardinal num_args; 

Arguments 
app_context 
from_type 
t o_ type 
converter 
convert_args 

n um_a rgs 

Specifies the application context. 
Specifies the source type of the resource to be converted. 
Specifies the destination type to which the resource is to be converted. 
Specifies the converter procedure. See xtConverter(2). 
Specifies how to obtain additional arguments needed for the conversion; if 
no arguments are provided, this should be NUT.T.. See the Structures sec- 
tion below for a detailed description of the format of convert_args. 
Specifies the number of additional arguments to the converter or zero. 

Description 
Resource converters provide a general way to pass specific data structures, and to hide the 
details of the data structures themselves. Using XtAppAddConverter or XtAdd- 
Converter, an application can register a converter to transform data of a given type to 
another specified type. The types themselves are arbitrary, and are specified by a string. For 
example, the converter mechanism can convert data of type String to an application data 
type of Menu if the application has registered the appropriate converter; to the application, the 
data type Menu is opaque. 

Some converters need additional arguments, which can be obtained from fields within the 
widget or as constants. The enumerated type XtAddressMode and the structure Xt- 
ConvertArgRec specify how each argument is delved. The are defined in 
<X11/ConverLh>, as follows: 

typedef enum { 
/* address mode parameter representation */ 
XtAddress, /* address */ 
XtBaseOffset, /* offset */ 
XtImmediate /* constant */ 
XtResourceString 
XtResourceQuark 
} XtAddressMode; 

/* resource name string */ 
/* resource name quark */ 

62 X Toolkit Intrinsics Reference Manual 



XtAppAddConverter (continued) Xt- Resource Management 

See Also 
XtAddConverter, XtDirectConvert, 
XtConverter(2). 

64 X Toolkit Intrinsics Reference Manual 



XtAppAddlnput (continued) Xt- Event Handling 

See Also 
XtAddInput, XtRemoveInput, 
XtInputCallbackProc(2). 

66 X Toolkit Intrinsics Reference Manual 



XtAppAddWorkProc 

Xt- Event Handling 

Name 
XtAppAddWorkProc -- register a work procedure for a given application. 
Synopsis 
XtWorkProcId XtAppAddWorkProc (app_context, proc, client data) 
XtAppContext app_context ; 
XtWorkProc proc; 
caddr t client data; 
Arguments 
app_context Specifies the application context that identifies the application. 
proc Specifies the procedure that is to be called when the application is idle. 
c2ient_data Specifies the argument to be passed to the specified procedure when it is 
called. 

Description 
Xt supports a limited form of background processing. Most applications spend most of their 
time waiting for input; to do useful work during this idle time, you can register a work proce- 
dure that will run when the application would otherwise block in XtAppNextEvent or Xt- 
AppP roces sEvent. 

XtAppAddWorkProc adds the specified proc for the application identified by 
app_context. XtWorkProcTd is an opaque identifier unique to this work procedure. 
Multiple work procedures can be registered, and the most recently added one is always the one 
that is called. However, if a work procedure itself adds another work procedure, the newly 
added one has lower priority than the current one. 

Passing the XtWorkProcId returned from the XtWorkProc to XtRemoveWorkProc 
causes proc tO stop being called. 

Work procedures are of type XtWorkProc. XtWorkProc discusses the responsibilities of 
the application's background processing routine. XtAddWorkProc is a simplified interface to 
this function. 

See Also 
Xt AddWo rkP roc, XtAppNext Event, XtAppP roce s s Event, Xt RemoveWo rkP roc, 
XtWorkProc(2). 

68 X Toolkit Intrinsics Reference Manual 



m Xt - Initialization 

XtAppCreateShell 

Name 
XtAppCreateShell m create additional top-level widgeL 
Synopsis 
Widget XtAppCreateShell (application_name, application_class, 
widget_class, display, args, num_args) 
String application name; 
String application class; 
-- 
WidgetClass widget_class; 
Display *display; 
ArgList args; 
Cardinal num_args; 

Arguments 
application name 
Specifies the name of the application instance. If this argument is NULL, the 
application name passed to XtDisplayTnitialize is used. 

application class 
-- 
Specifies the class name of this application. 

widget_class 
Specifies the widget class that the application top-level widget should be 
(normally app i i c at i onS he i iWidget C i a s s). 

di spl ay 
args 
hum args 
-- 

Specifies the display from which to get the resources. 

Specifies the argument list in which to set in the WM_COMMAND property. 

Specifies the number of arguments in the argument list. 

Description 
An application can have multiple top-level widgets, which can potentially be on many different 
screens. An application uses XtAppCreateShell if it needs to have several independent 
windows. (A help system that stayed on the screen and could be moved and resized indepen- 
dently of the application is an example of such an independent top-level window.) The Xt- 
AppCreateShell function creates a top-level widget that is the root of a widget tree. 
application name and application class become the left-most components in all 
widget resource names for this new application. They are used for qualifying all subsequent 
widget resource specifiers. 
XtAppCreateShell should be used to create a new logical application within a program or 
to create a shell on another display. In the first case, XtAppCreateShell allows the specifi- 
cation of a new root in the resource hierarchy. If XtAppCreateShell is used to create 
shells on multiple displays, it uses the resource database associated with display. 

X Toolkit Intrinsics Reference Manual 69 



Xt- Error Handling (continued) XtAppErrorMsg 

(XtAppWarning calls the corresponding non-fatal error handler. 
Xt AppWa rn ingMs g call the corresponding high-level handlers.) 

The Intrinsics internal errors all have class XtToolkitError. 

XtAppErrorMsg and 

See Also 
XtAppError, XtAppSetErrorHandler, XtAppSetErrorMsgHandler, XtAppSet- 
WarningHandler, XtAppSetWarningMsgHandler, XtAppWarning, XtApp- 
WarningMsg, XtError, XtErrorHandler, XtErrorMsg, XtErrorMsgHandler, 
XtSetErrorHandler, XtSetErrorMsgHandler, XtSetWarningHandler, XtSet- 
WarningMsgHandler, XtWarning, XtWarningMsg. 

X Toolkit Intrinsics Reference Manual 73 



XtAppGetErrorDatabaseText (continued) Xt - Error Handling 

Intrinsics. The first four arguments to XtAppGetErrorDatabaseText () are just passed 
in from the XtErrorMsg ( ) call in XtMalloc ( ). 

The XtMalloc ( ) call assumes that the default error database (errorDB) has an error message 
for resource name allocError.malloc of class XtToolkitError. If not found, the 
default error message "Cannot perform malloc" will be used instead. 

You do not need to use this function unless you are writing an Xt error message handler of your 

own. 

char * 
XtMalloc(size) 
unsigned 
{ 

size; 

char *ptr; 
if ((ptr = malloc(size)) == NULL) 
XtErrorMsg("allocError", "malloc", "XtToolkitError", 
"Cannot perform malloc", (String *) NULL, 
(Cardinal *) NULL); 
return (ptr); 
} 
void 
XtErrorMsg(name, type, class, defaultp, params, num_params) 
String name, type, class, defaultp; 
String *params; 
Cardinal *num_params; 
char buffer[1000], message[1000]; 
XtGetErrorDatabaseText(name, type, class, defaultp, buffer, I000); 
/* 
* Need better solution here, perhaps use lower-level 
* printf primitives? 
*/ 
if (num_params == NULL) 
XtError(buffer); 
else { 
(void) sprintf(message, buffer, params[0], params[l], 
params[2], params[3], params[4], params[5], 
params[6], params[7], params[8], params[9]); 
XtDefaultError(message); 
-- 

} 
} 

static void 

XtDefaultError(message) 
String message; 
extern void exit(); 

76 X Toolkit Intrinsics Reference Manual 



Xt - Error Handling 

(continued) XtAppGetErrorDatabaseText 

(void) fprintf(stderr, "X Toolkit Error: %s\n", message); 
exit(l); 
} 
void 
XtGetErrorDatabaseText(name, type, class, defaultp, buffer, nbytes) 
register char *name, *type, *class; 
char *defaultp; 
char *buffer; 
int nbytes; 
{ 
XtAppGetErrorDatabaseText(_XtDefaultAppContext(), 
name, type, class, defaultp, buffer, nbytes, NULL); 
) 

See Also 
XtAppGetErrorDatabase, XtGetErrorDatabase, XtGetErrorDatabaseText, 
XtErrorMsgHandler(2). 

X Toolkit Intrinsics Reference Manual 77 



XtAppGetSelectionTimeout 

Xt - Selections m 

Name 
XtAppGetSelectionTimeout m get the current selection timeout value. 

Synopsis 
unsigned int XtAppGetSelectionTimeout(app_context) 
XtAppContext app_context; 

Arguments 
app_c on t ex t Specifies the application context. 

Description 
XtAppGet Se lect ionTimeout returns the current selection timeout value for the specified 
application context, in milliseconds. (XtGetSelectionTimeout performs the same func- 
tion for the default application context.) The selection timeout is the time within which the two 
communicating applications must respond to one another. The initial timeout value is set by 
the selectionTimeout application resource, or if selectionTimeout is not specified, 
it defaults to 5000 milliseconds (5 seconds). A new value can be set by a call to XtAppSet- 
SelectionTimeout or XtSetSelectionTimeout. 

See Also 
XtAppSetSelectionTimeout, XtGetSelectionTimeout, XtSetSelection- 
Timeout. 

78 X Toolkit Intrinsics Reference Manual 



XtAppNextEvent 

Xt - Event Handling B 

Name 
XtAppNextEvent -- return next event from an application's input queue. 

Synopsis 
void XtAppNextEvent(app_context, 
XtAppContext app_context; 
XEvent *event return; 
-- 

event_ret urn) 

Arguments 
app_context 
event return 

Specifies the application context that identifies the application. 
Returns the event information from the dequeued event structure. 

Description 
If a server has queued an event for the specified application, XtAppNextEvent removes the 
event from the queue and returns it to the caller. 

If there are no events in the X input queue, XtAppNextEvent flushes the X output buffer and 
waits for an event from the X server or auxiliary input sources or for a timeout value to expire. 
If a timer pseudo-event or auxiliary input event occurs, XtAppNextEvent dispatches the 
designated callbacks. When an X event occurs, XtAppNextEvent removes it from the queue 
and returns it. The events returned by XtAppNextEvent should be dispatched with Xt- 
DispatchEvent. XtAppNextEvent dispatches XtWorkProcs and XtTimer- 
CallbackProcs dectly that are registered for app_context. See XtAppAddWork- 
Proc and XtAppAddTimeOut. 

XtAppNextEvent blocks until an event occurs. An application can instead use this wait 
time by interleaving background processing with calls to XtAppPending. 

Programs rarely need this much control over the event dispatching mechanism. Most programs 
use XtAppMainLoop or XtMainLoop. 

See Also 
XtAppAddWorkProc, XtAppMainLoop, XtAppPeekEvent, XtAppPending, XtApp- 
ProcessEvent, XtDispatchEvent, XtMainLoop, XtNextEvent, XtWorkProc. 

80 X Toolkit Intrinsics Reference Manual 



-- Xt - Event Handllng 

XtAppPeekEvent 

Name 
XtAppPeekEvent -- nondestructively examine the head of an application's input queue. 
Synopsis 
Boolean XtAppPeekEvent ( app_context, event_return) 
XtAppContext app_context; 
XEvent *event return; 

Arguments 
app_ c on t ext Specifies the application context that identifies the application. 

event return 
Returns the event information from the head event structure in the queue. 

Description 
XtAppPeekEvent returns the value from the head of a given application's event queue with- 
out removing the value from the queue. 

If a server has queued an event for the application, XtAppPeekEvent fills in the event and 
returns a nonzero value. It returns TRUE if the event returned is an X event and FALSE other- 
wise (i.e., if it is a Timer or alternate input event). 
If there is no X event in the queue, XtAppPeekEvent flushes the output buffer and waits for 
an event from the X server or auxiliary input sources or for a timeout value to expire. If timer 
pseudo-events expire, it dispatches them itself, the same way XtAppNextEvent does. If the 
input is an event, XtAppPeekEvent fills in the event and returns a nonzero value. Other- 
wise, if input is from an alternate input source, XtAppPeekEvent returns NULL for the event. 

Programs rarely need this much control over the event dispatching mechanism. Most programs 
use XtAppMainLoop or XtMainLoop. 

However, all event sources depend on idle time in the application to return XtMainLoop 
where Xt can check to see if input is available from any of the various sources. If an applica- 
tion has long calculations to make, the progrm may not return to XtMainLoop frequently 
enough to detect important input in a timely fahsion. The application itself should, if possible, 
suspend important calculations for a moment to check whether input is available. Then it can 
determine whether to process the input before continuing or finish the calculation. 

To detect whether input from any input source is available, you can call XtPending. 

To find out what the first event in the queue contains, you can call XtPeekEvent. This func- 
tion returns an event structure without removing the event from Xlib's queue. 

It is also possible to remove and process a single evenL XtProcessEvent combines some 
(but not all) of the functions from XtNextEvent and XtDispatchEvent. That is, while 
XtNextEvent takes the next event from the queue, whatever it is, XtProcessEvent 
allows you to specify as a mask a bitwise OR of the symbolic constants XtIMXEvent, Xt- 
rMTimer, and XtIMAlternateInput. This lets you select only some of these event types 

X Toolkit Intn'nsics Reference Manual 81 



XtAppPeekEvent (continued) Xt- Event Handling 

for processing. In addition, XtProcessEvent actually calls XtDispatchEvent to dis- 
patch X events, so only this one call is necessary. 

See Also 
XtAppMainLoop, XtAppNextEvent, XtAppPending, XtAppProcessEvent, Xt- 
DispatchEvent, XtPeekEvent. 

82 X Toolkit Intrinsics Reference Manual 



XtAppProcessEvent 

Xt - Event Handling m 

Name 
XtAppProcessEvent m process one input event. 

Synopsis 
void XtAppProcessEvent(app_context, mask) 
XtAppContext app_context; 
XtInputMask mask; 

Arguments 
app_context Specifies the application context for which to process input. 
mask Specifies what types of events to process. The mask is the bitwise inclusive 
OR of XtTMXEvont (X event), XtTHTiraor (timer events), or Xt- 
IMAlternateInput (alternate input events). The symbolic name Xt- 
IMAll is the bitwise inclusive OR of all event types. 

Description 
While most widgets will use the Resource Manager to handle events, the X Toolkit does pro- 
vide a mechanism for widgets or application code to handle X events directly. Every client 
interested in X events on a widget uses XtAddEventHandler to register which events it is 
interested in and a procedure (event handler) that is to be called when the event happens in that 
window. The handler can then use XtAppProcessEvent to actually handle the events. 
XtAppProcessEvent processes an X event, a timer event, or an alternate input event. If 
there is nothing to process, XtAppProcessEvent blocks until there is. If there is more than 
one type of event available, the one that will get processed is undefined. 

XtAppProcessEvent processes timer events and alternate input events by calling the 
appropriate callbacks, the same way XtAppPeekEvent and XtAppNextEvent do. Xt- 
AppProcessEvent calls XtDispatchEvent tO handle X events. 

When an X event is received, it is passed to XtDispatchEvent, which calls the appropriate 
event handlers and passes them the widget, the event, and client-specific data registered with 
each procedure. If there are no handlers registered for that event, the event is ignored and the 
dispatcher simply returns. The order in which the handlers are called is undefined. 

Programs rarely need this much control over the event dispatching mechanism. Most programs 
use XtAppMainLoop. 

See Also 
Section 1.5, "Translations and Actions," 
XtAppMainLoop, XtAppNextEvent, XtAppPeekEvent, XtAppPending, Xt- 
DispatchEvent, XtProcessEvent. 

84 X Toolkit Intrinsics Reference Manual 



XtAppSetErrorMsgHandler 

Xt- Error Handling m 

Name 
XtAppSetErrorMsgHandler -- register a procedure to be called on fatal error conditions. 

Synopsis 
void XtAppSetErrorMsgHandler (app_context, msg_handler) 
XtAppContext app_context; 
XtErrorMsgHandler msg_handl er; 

Arguments 
app_context Specifies the application context. 
msf_handler Specifies the new fatal error message handling procedure, which should not 
return. 

Description 
The default error handler provided by the Intrinsics constructs a string from the error resource 
database (see XtAppGetErrorDatabase) and cIs XtError. 

Using XtAppSetErrorMsgHandler (or XtSetErrorMsgHandler), you can replace 
the default handler with one of your own. Note that if you simply want to change the way the 
message is displayed (rather than the way the message database is used), you should probably 
replace the low-level error handler (using XtAppSetErrorHandler) instead. 
Fatal error message handlers should not return. If one does, subsequent X Toolkit behavior is 
undefined. See XtErrorMsgHandler(2) for details. Note that application-context-specific 
error handling is not implemented on many systems. Most implementations will have just one 
set of error handlers. If they are set for different application contexts, the one performed last 
will prevail. 

See Also 
XtAppError, XtAppErrorMsg, XtAppSetErrorHandler, XtAppSetWarning- 
Handler, XtAppSetWarningMsgHandler, XtAppWarning, XtAppWarningMsg, 
XtError, XtErrorHandler, XtErrorMsg, XtErrorMsgHandler, XtSetError- 
Handler, XtSetErrorMsgHandler, XtSetWarningHandler, XtSetWarningMsg- 
Handler, XtWarning, XtWarningMsg. 

86 X Toolkit Intrinsics Reference Manual 



XtAppWarningMsg (continued) Xt - Error Handling 

(XtAppWarning calls the corresponding non-fatal error handler. XtAppErrorMsg and 
Xt AppWa rn ingMs g call the corresponding high-level handle.) 

See Also 
XtAppError, XtAppErrorMsg, XtAppSetErrorHandler, XtAppSetErrorMsg- 
Handler, XtAppSetWarningHandler, XtAppSetWarningMsgHandler, XtApp- 
Warning, XtError, XtErrorHandler, XtErrorMsg, XtErrorMsgHandler, Xt- 
SetErrorHandler, XtSetErrorMsgHandler, XtSetWarningHandler, XtSet- 
WarningMsgHandler, XtWarning, XtWarningMsg. 

92 X Toolkit Intrinsics Reference Manual 



XtBuildEventMask (continued) Xt- Event Handling 

Event Mask Symbol 

ExposureMask 

VisibilityChangeMask 
StructureNotifyMask 
ResizeRedirectMask 
SubstructureNotifyMask 
SubstructureRedirectMask 
FocusChangeMask 
PropertyChangeMask 
ColormapChangeMask 
OwnerGrabButtonMask 

Circumstances 

Any exposure (except GraphicsExpose and 
NoExpose) 
Any change in visibility 
Any change in window configuration. 
Redirect resize of this window 
Notify about reconfiguration of children 
Redirect reconfiguration of children 
Any change in keyboard focus 
Any change in property 
Any change in colormap 
Modifies handling of pointer events 

See Also 
Section 1.4, "Events," Section 1.5, "Translations and Actions," 
Xt AddEvent Handle r, Xt AddRawEvent Handle r, XtRea i i zeWidget. 

96 X Toolkit Intrinsics Reference Manual 



-- Xt - Keyboard Handling 

XtCallAcceptFocus 

Name 
XtCallAcceptFocus -- call a widget's accept_focus procedure. 

Synopsis 
Boolean XtCallAcceptFocus (w, time) 
Widget w; 
Time *time; 

Arguments 
time 

Specifies the widget. 
Specifies the X time of the event that is causing the accept focus. 

Description 
XtCallAcceptFocus calls the specified widget's accept_focus method, passing it the 
specified widget and time, and rettLrns whatever the accept_focus method returns. If the 
accept_focus procedure is NULL, XtCallAcceptFocus returns FALSE. 
XtCallAcceptFocus does not actually set the keyboard focus; it is used to determine if the 
widget would take the focus if offered. XtSetKeyboardFocus and the Xlib function 
XSetInputFocus actually pass the focus to a child. 

The accept_focus method is part of the Core class structure. 

See Also 
XtSetKeyboardFocus, 
XtAcceptFocusProc(2). 

X Toolkit Intrinsics Reference Manual 97 



Xt - Pop Ups (continued) XtCallbackExclusive 

The callback list cb in Args is an argument to a widget. When the widget invokes XtCall- 
Callbacks on its XtNcallback resource, the polu p shell pshell will be popped up. 

A companion example to the one above is prentcd on XtCallbackPopdown. 

See Also 
Sdon 1.6, "Pop Ups," 
XtCallbackNone, XtCallbackPopdown, XtCallCallbacks, XtMoveWidget, Xt- 
Popdown, XtPopup, XtSetSensitive. 

X Toolkit Intrinsics Reference Manual 99 



Xt- Pop Ups (continued) XtCallbackPopdown 

When the widget invokes XtCallCallbacks on its resource XtNCallback, the pop-up 
shell pshell will be popped down. See the companion example in XtCallback- 
Exc lu s ire. 

See Also 
Section 1.6, "Pop Ups," 
XtCallbackExclusive, XtCallCallbacks, XtPopdown, XtSetSensitive. 

X Toolkit Intrinsics Reference Manual 103 



-- Xt - Memory Allocation 

XtCalloc 

Name 
XtCalloc B allocate an array and initialize elements to zero. 

Synopsis 
char *XtCalloc(num, size) ; 
unsigned int num; 
unsigned int size; 

Arguments 
num 
size 

Specifies the number of array elements to allocate. 
Specifies the size of an array element in bytes. 

Description 
XtCalloc allocates space for the specified number of array elements of the specified size and 
initializes the space to zero. If there is insufficient memory to allocate the new block, xt- 
Calloc terminates by calling Xt:ErrorMsg. 
xtCaZZoc differs from Xt:HaZZoc in that it stores zero in all the array elements. 

The function xtcalloc is implemented by the Toolkit independently of the particular envi- 
ronment, so programs ported to a system not supporting caZloc will still work. 
xtNew and xtNewSt ring provide slightly higher-level approaches to memory allocation. 

See Also 
XtErrorMsg, XtFree, XtMalloc, XtNew, XtNewSt ring, XtRealloc. 

X Toolkit Intrinsics Reference Manual 105 



XtCheckSubclass 

Xt - Widget Information 

Name 
XtCheckSubclass m in DEBUG mode, verify a widget's class. 

Synopsis 
void XtCheckSubclass(w, widget_class, message) 
Widget w; 
WidgetClass widget_class; 
String message; 

Arguments 
w 
wi dget_class 
message 

Specifies the widget. 
Specifies the widget class to test against. 
Specifies the message to be used. 

Description 
XtCheckSubclass determines if widget w belongs to a subclass of the specified 
widget_class. (Note that two widgets of the same class belong to mutual subclasses.) The 
widget can be any number of subclasses removed and need not be an immediate subclass of the 
specified widget class. 
If the w is not a subclass, XtCheckSubclass constructs an error message from the supplied 
message, the widget's actual class, and the expected class, and it calls XtErrorMsg. 
XtCheckSubclass should be used at the entry point of exported routines to ensure that the 
client has passed in a valid widget class for the exported operation. 
XtCheckSubclass is a macro. It is only executed when the widget has been compiled with 
the compiler symbol DEBUG defined; otherwise, it is defined as the empty string and generates 
no code. 
XtCheckSubclass uses the Core widget data structures to perform its checking. 

See Also 
XtClass, Xt IsSubclass, XtSuperclass, 
Core(3). 

106 X Toolkit Intrinsics Reference Manual 



XtConflgureWldget (continued) Xt - Geometry Management 

If a class need not recalculate anything when a widget is resized, it can specify NULL for the 
resize field in its class record. This is an unusual case and should occur only for widgets with 
very trivial display semantics. The resize method takes a widget as its only argument. 

See Also 
Stion 1.8, 'Geometry Management," 
XtMakeGeometryRequest, XtMakeResizeRequest, XtMoveWidget, XtResize- 
Widget, XtTranslateCoords. 

110 X Toolkit Intn'nsics Reference Manual 



XtConvertCase 

Xt- Keyboard Handling m 

Name 
XtConvertCase m determine upper-case and lower-case versions of a keysym. 

Synopsis 
void XtConvertCase (display, keysym, 
Display *display; 
KeySym keysym; 
KeySym *lower_return; 
KeySym * upper_return; 

lower return, 

upper_re t urn ) 

Arguments 
di spl ay 
keysym 
lower return 
-- 
upper_re t u rn 

Specifies the display that the keysym came from. 
Specifies the keysym to convert. 
Returns the lower-case equivalent of the keysym. 
Returns the upper-case equivalent of the keysym. 

Description 
XtConvertCase is used to determine upper-case and lower-case equivalents for a keysym. 
It calls the case converter that is currently registered to convert those keysyms and returns the 
results. This procedure can perform application-specific shifting of characters 

A user-supplied XtKeyProc may need to use this function. 

XtRegisterCaseConverter can be used to register a new case converter. 

For a more detailed discussion of processing keyboard input, see Chapter 13, Miscellaneous 
Toolkit Programming Techniques, in Volume Four, X Toolkit lntrinsics Programming Manual. 
See Chapter 9, The Keyboard and the Pointer, in Volume One, Xlib Programming Manual, for 
more information on keysyms. 

See Also 
XtRegisterCaseConverter, XtSetKeyTranslator, XtTranslateKey, Xt- 
TranslateKeycode, 
XtCaseProc(2),XtKeyProc(2). 

114 X Toolkit Intrinsics Reference Manual 



 Xt - Application Contexts 

XtCreateApplicationContext 

Name 
XtCreateApplicationContext m create an application context. 

Synopsis 
XtAppContext XtCreateApplicationContext() 

Description 
XtCreateApplicationContext returns an application context, which is an opaque type. 
Every application must have at least one application context. XtInitialize creates a 
default application context. 

XtInitialize is a simplified interface to XtToolkitInitialize, XtCreate- 
ApplicationContext, XtDisplayInitialize, and XtAppCreateShell; if it is 
not used, all four of these routines must be called. 

Routines that use an implicit context (like XtMainLoop and XtAddTimeOut) depend on the 
default context created by XtTnitialize. You cannot use these routines if you initialize a 
specific application context. 

Structures 
/. 
* Data structure for setting window attributes. 

./ 
typedef struct { 
Pixmap background_pixmap; 
unsigned long background_pixel; 
Pixmap border_pixmap; 
unsigned long border_pixel; 
int bit_gravity; 
int win_gravity; 
int backing_store; 
unsigned long backing_planes; 
unsigned long backing_pixel; 
Bool save under; 
-- 
long event mask; 
-- 
long do_not_propagate_mask; 
Bool override redirect; 
-- 
Colormap colormap; 
Cursor cursor; 
} XSetWindowAttributes; 

/* pixmap, None, or ParentRelative */ 
/* background pixel */ 
/* pixmap, None, or CopyFromParent */ 
/* border pixel value */ 
/* one of bit gravity values */ 
/* one of the window gravity values */ 
/* NotUseful, WhenMapped, Always */ 
/* planes to be preseved if possible */ 
/* value to use in restoring planes */ 
/* should bits under be saved (pop ups) */ 
/* set of events that should be saved */ 
/* set of events that should not propagate */ 
/* override redirected config request */ 
/* colormap to be associated with window */ 
/* cursor to be displayed (or None) */ 

/* Definitions for valuemask argument of CreateWindow and ChangeWindowAttributes */ 

#define CWBackPixmap 
#define CWBackPixel 
#define CWBorderPixmap 
#define CWBorderPixel 
#define CWBitGravity 
#define CWWinGravity 
#define CWBackingStore 
#define CWBackingPlanes 
#define CWBackingPixel 

(IL<<0) 
(IL<<I) 
(IL<<2) 
(IL<<3) 
(IL<<4) 
(IL<<5) 
(IL<<6) 
(IL<<7) 
(IL<<8) 

X Toolkit Intrinsics Reference Manual 115 



XtCreateApplicationContext (continued) Xt - Application Contexts 

#define CWOverrideRedirect 
#define CWSaveUnder 
#define CWEventMask 
#define CWDontPropagate 
#define CWColormap 
#define CWCursor 

See Also 
Section 1.1, "Widget Lifccycle" 

(IL<<9) 
(IL<<I0) 
(IL<<II) 
(IL<<I2) 
(IL<<I3) 
(IL<<I4) 

116 X Toolkit Intrinsics Reference Manual 



m Xt - Initialization 

XtCreateApplicationShell 

Name 
XtCreateApplicationShell m create an additional top-level widgeL 
Synopsis 
Widget XtCreateApplicationShell (application_name, widget_class, 
args, num_args) 
String application_name;/*unused in Release 3*/ 
WidgetClass widget_class; 
ArgList args; 
Cardinal num_args; 

Arguments 
application name 
Specifies the name of the application instance. 

w./. dge ._ c1 ass 
Specifies the widget class that the application top-level widget should be. 
args Specifies the argument list in which to set in the WM_COMMAND property. 
n um_a rgs Specifies the number of arguments in the argument list. 

Description 
XtCreateApplicationShell creates a new logical application within a program. This 
function is a simplified interface to XtAppCreateShell. Since most applications have only 
one display, XtCroatoApplicationSholl does not require the application to pass the 
display explicitly. It also does not allow the caller to specify the resource class of the applica- 
tion. To take advantage of the more general functionality, use XtAppCroatoSholl. 

See Also 
Section 1.1, "Widget Lifecycle," 
XtAppCreateShell. 

X Toolkit Intrinsics Reference Manual 117 



XtCreateManagedWidget 

Xt - Widget Lifecycle-- 

Name 
XtCreateManagedWidget m create and manage a child widget. 

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

widget_class, parent, args, 

Arguments 
name 
wi dget_cl a ss 
parent 
args 
num_args 
Description 

Specifies the text name for the created shell widget. 
Specifies the widget class pointer for the created widget. 
Specifies the parent widget. 
Specifies the argument list to override the resource defaults. 
Specifies the number of arguments in the argument list. 

XtCreateManagedWidget combines creation and management of a widget into one rou- 
tine. It calls XtCreateWidget and XtManageChild consecutively. XtCreate- 
ManagedWidget is the usual way to create new widget instances. 

See Also 
Section 1.1, "Widget Lifecycle," 
XtCreateWidget, XtManageChild, XtManageChildren. 

118 X Toolkit Intrinsics Reference Manual 



XtCreateWidget 

Xt - Widget Lifecycle  

Name 
XtCreateWidget -- create an instance of a widgeL 

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

args, 

Arguments 
name 

Specifies the resource name for the created widget, which is used for retriev- 
ing resources and, for that reason, should not be the same as any other widget 
that is a child of same parent. 

wi dget_ c1 ass 
Specifies the widget class pointer for the created widget. 

pa ren t 
args 
num_args 

Specifies the parent widget. 

Specifies the argument list to override the resource defaults. 

Specifies the number of arguments in the argument list. (Note that you can 
determine the number of arguments in a static argument list using the Xt- 
Numbe r macro.) 

Description 
XtCreateWidget creates a new widget instance of class widget_class. The usual way 
to access XtCreateWidget is to combine creation and management with XtCreate- 
ManagedWidget; you will normally use XtCreateWidget and XtManageChild only in 
cases where you wish to create a number of interrelated widgets, and bring them under parental 
management at the same time. 

XtCreateWidget creates a new widget instance structure and invokes the widget's initiali- 
zation method. XtCreateWidget resolves conflicts between values for the arguments sup- 
plied in the environment with those supplied in args in the new widget instance structure. 

XtCreateWidget performs many of the boilerplate operations of widget creation: 

Checks to see if the class_initialize procedure has been called for this class and 
for all superclasses and, if not, calls those necessary, in a superclass-to-subclass order. 

Allocates memory for the widget instance. 

If the parent is a subclass of constraintWidgetClass, memory is allocated for the 
parent's constraints, and stores the address of this memory into the constraints field 
of the widget. 

122 X Toolkit Intrinsics Reference Manual 



Xt - Widget Lifecycle (continued) XtCreateWIdget 

Initializes the core nonresource dam fields (for example, parent and vis ible). 

Initializes the resource fields (for example, background_pixel) by using the 
resource lists specified for this class and all superclasses. 

If the parent is a subclass of const ra intWidgetCla s s, initializes the resource fields 
of the constraint record by using the constraint resource list specified for the parent's 
class and all superclasses up to constraintwidgetClass. 

Calls the initialize procedures for the widget starting at the Core initialize procedure and 
descending to the widget's initialize procedure. 

If the parent is a subclass of compositeWidgetClass, puts the widget into its par- 
ent's children list by calling its parent's insert_child procedure. 
If the parent is a subclass of const raintWidgetClass, calls the constraint initialize 
procedures, starting at constraintWidgetClass and descending to the parent's 
constraint initialize procedure. 

Note that the XtCreateWidget function gets resources as a superclass-to-subclass opera- 
tion. That is, the resources specified in the Core resource list are fetched, then those in the sub- 
class, and so on down to the resources specified for this widget's class. Within a class, 
resources are fetched in the order they are declared. 

In general, if a widget resource field is declared in a superclass, that field is included in the 
superclass's resource list and need not be included in the subclass's resource list. For example, 
the Core class contains a resource entry for background_pixel. Consequently, the imple- 
mentation of Label need not also have a resource entry for background_pixel. However, a 
subclass, by specifying a resource entry for that field in its own resource list, can override the 
resource entry for any field declared in a superclass. This is most often done to override the 
defaults provided in the superclass with new ones. At class initialization time, resource lists for 
that class are scanned from the superclass down to the class to look for resources with the same 
offset. A matching resource in a subclass will be reordered to override the superclass entry. (A 
copy of the superclass resource list is made to avoid affecting other subclasses of the super- 
class.) 

Section 1.8, "Geometry Management," gives a more general account of the role of the widget 
parent The Intrinsic-supplied classes are described in Core(3), Constraint(3), and Compos- 
ite(3). 

See Also 
Section 1.1, "Widget Lifecycle," 
XtCreateManagedWidget. 

X Toolkit Intrinsics Reference Manual 123 



Xt - Window Manipulation (continued) XtCreateWlndow 

Structures 
/* Definitions for valuemask argument. These control which fields in 
* XSetWindowAttributes structure should be used. 
*/ 

typedef struct { 
Pixmap background_pixmap; 
unsigned long background_pixel; 
Pixmap border_pixmap; 
unsigned long border_pixel; 
int bit_gravity; 
int win_gravity; 
int backing_store; 
unsigned long backing_planes; 
unsigned long backing_pixel; 
Bool save under; 
long event mask; 
long do_not_propagate_mask; 
Bool override redirect; 
Colormap colormap; 
Cursor cursor; 
} XSetWindowAttributes; 

/* background or None or ParentRelative * / 
/* background pixel */ 
/* border of the window */ 
/* border pixel value */ 
/* one of bit gravity values */ 
/* one of the window gravity values */ 
/* NotUseful, WhenMapped, Always */ 
/* planes to be preserved if possible */ 
/* value to use in restoring planes */ 
/* should bits under be saved (popups) */ 
/* set of events that should be saved */ 
/* set of events that should not propagate */ 
/* boolean value for override-redirect */ 
/* colormap to be associated with window */ 
/* cursor to be displayed (or None) */ 

See Also 
Section 1.1, "Widget Lifecycle," 
XtRea 1 i zeP r o c(2). 

X Toolkit Intrinsics Reference Manual 125 



XtDestroyGC 

Xt - Memory Allocation-- 

Name 
XtDestroyGC m Release 2 compatible function to free up read-only GCs. 

Synopsis 
void XtDestroyGC (gc) 
GC gc; 

Arguments 
w 

gC 

Specifies the widgeL 
Specifies the GC to be deallocated. 

Description 
XtDestroyGC deallocates a shared (read-only) Graphics Context. References to shareable 
GCs are counted, and a free request is generated to the server when the last user of a given GC 
destroys it. Note that some earlier versions of XtDestroyGC had only a 9c argument. 
Therefore, this function is not very portable. In addition, XtDestroyGC is only guaranteed to 
work properly if there is exactly one open display in the application. 

Programs running under Release 3 should be converted to use XtReleaseGC. Programs run- 
ning under Release 2 can conditionally compile in code in expectation of Release 3. 

See Also 
XtGetGC, XtReleaseGC. 

128 X Toolkit Intrinsics Reference Manual 



XtDisplaylnitlalize (continued) Xt - Application Contexts 

St ructu res 
typedef enum { 

XrmoptionNoArg, 
XrmoptionIsArg, 
XrmoptionStickyArg, 
XrmoptionSepArg, 

XrmoptionSkipArg, 
XrmoptionSkipLine 
} XrmOptionKind; 

typedef struct { 
char *option; 
char *specifier; 

/* Value is ... */ 
/* specified in OptionDescRec.value */ 
/* the option string itself */ 
/* characters immediately following option */ 
/* next argument in argv */ 
/* Ignore this option and ... */ 
/* the next argument in argv */ 
/* the rest of argv */ 

/* Option name in argv */ 
/* Resource name (without application name) */ 

XrmOptionKind argKind; /* Which style of option it is */ 
caddr_t value; /* Value to provide if XrmoptionNoArg */ 
} XrmOptionDescRec, *XrmOptionDescList; 

See Also 
XtAppCreateShell, XtCreateApplicationContext, XtDatabase, Xt- 
Initialize. 

136 X Toolkit Intrinsics Reference Manual 



Xt - Error Handling (continued) XtErrorMsg 

Warning calls the corresponding nonfatal error handler. XtAppErrorMsg and XtApp- 
WarningMsg call the corresponding high-level handlers.) The Ininsics internal eors all 
have class XtToolkitError. 

See Also 
XtError, XtSetErrorHandler, XtSetWarningHandler, XtWarning, Xt- 
WarningMsg. 

X Toolkit Intn'nsics Reference Manual 139 



m Xt - Resource Management 

XtGetApplicationResources 

Name 
XtGetApplicationResources m update base-offset resource list (by application). 

Synopsis 
void XtGetApplicationResources (w, base, resources, 
num_resources, args, num_args) 
Widget w; 
caddr t base; 
XtResourceList resources; 
Cardinal num resources; 
ArgList args; 
Cardinal num_args; 

Arguments 

Specifies the widget that identifies the resource database to search. (The 
database is that associated with the display for this widget.) 
base Specifies the base address of the data structure where the resources should 
be written. 
resources Specifies the list of resources to be retrieved. 
num resources Specifies the number of resources in the resource list. 
args Specifies the argument list to override resources obtained from the 
resource database. 
n um._args Specifies the number of arguments in the argument list. 

Description 
XtGetApplicationResources can be used to retrieve resources that apply to an overall 
application, rather than to a particular widget. (Widget resources are automatically retrieved by 
XtCreateWidget.) 
First, XtGetApplicationResources UseS the passed widget, which is usually an applica- 
tion shell, to construct a resource name and class list. Then, it retrieves resources from the 
argument list, the resource database, or the resource list default values. After adding base to 
each address, XtGetApplicationResources copies the resource values into the corre- 
sponding base-offset address, num_args must be zero. However, if num_args is zero, the 
argument list is not referenced. 
The portable and recommended way to specify application resources is to declare them as 
structure members and pass a pointer to such a structure as base; then Xt0ffset can be 
used to specify resource_offset. (xt0ffset determines the relative address of a field.) 
This is how widget instance variables are accessed by the Resource Manager in widget 
instances. 
Here is a short program that sets up a resource argument list and accesses it. 

X Toolkit Intrinsics Reference Manual 141 



XtGetApplicationResources (continued) Xt - Resource Management 

/* res.c - access application resources */ 
#include <stdio.h> 
#include <Xll/Xlib.h> 
#include <Xll/StringDefs.h> 
#include <Xll/IntrinsicP.h> 
#include <Xll/Intrinsic.h> 
/* 
* fields to be filled in from resources 
* Note that instance variables must be defined as a pointer... 
-- 
*/ 
typedef struct instance variables { 
-- -- 
String label; 
XFontStruct *font struct; 
-- 
long foreground; 
} instance variable rec, *instance variables; 
-- _ -- 
instance variables InstanceVariables; 
-- 
static XtResource resources[] = { 
{ 
XtNforeground, 
XtCForeground, 
XtRPixel, sizeof(Pixel), 
XtOffset(instance variables, foreground), 
-- 
XtRString, "XtDefaultForeground" 
), 
{ 
XtNfont, 
XtCFont, 
XtRFontStruct, sizeof(XFontStruct *), 
XtOffset(instance variables, font struct), 
XtRString, "XtDe faultFont" 
), 
{ 
XtNlabel, 
XtCLabel, 
XtRString, sizeof(String), 
XtOffset(instance variables, label), 
-- 
XtRString, "Default Label" 
), 
); 
Arg args[] = { 
XtNlabel, (XtArgVal) "Stuff", 
); 
main(ac, av) 
int ac; 
char **av; 
{ 
Widget toplevel; 

142 X Toolkit Intrinsics Reference Manual 



XtGetErrorDatabase 

Xt- Error Handling-- 

Name 
XtGetErrorDatabase m obtain the error database. 

Synopsis 
XrmDatabase *XtGetErrorDatabase () 

Description 
Xt's high-level error and warning message handlers use a resource-like database for storing 
error messages. On UNIX-based systems, the database is usually stored in the file 
lusrlliblX111XtErrorDb. The XtGotErrorDatabaso function returns the address of the 
error database. The Intrinsics do a lazy binding of the error database and do not read in the 
database file until the first call to XtGetErrorDatabaseText. 
For a complete listing of all errors and warnings that can be generated by the Intrinsics, see 
Appendix D. 

Structures 
The type XrmDatabase is opaque and should not be manipulated directly. The return value 
can be manipulated with the Xlib functions XrmPutResource, XrmQPutResource, Xrm- 
GetResource, XrmQGetResource. 

See Also 
XtAppGetErrorDatabase, XtAppGetErrorDatabaseText, XtDatabase, 
XtGetErrorDatabaseText, 
XtErrorMsgHandler(2). 

144 X Toolkit Intrinsics Reference Manual 



XtGetGC 

Xt- Graphics Context-- 

Name 
XtGetGC D obtain a read-only, shamble GC. 

Synopsis 
GC XtGetGC(w, value_mask, values) 
Widget w; 
XtGCMask value mask; 
-- 
XGCValues *values; 

Arguments 
value mask 
values 

Specifies the widget with which the GC is to be associated. 
Specifies which fields of the GC are to be filled in with widget data. 
Returns the actual values for this GC. 

Description 
The Inlrinsics provide a mechanism whereby cooperating clients can share a graphics context 
(GC), thereby reducing both the number of GCs created and the total number of server calls in 
any given application. The mechanism is a simple caching scheme, and all GCs obtained by 
means of this mechanism must be treated as read-only. If a changeable GC is needed, the Xlib 
XCreateGC function should be used instead. 
The XtGetGC function returns a shamble, read-only GC. The parameters to this function are 
the same as those for XCreateGC except that a widget is passed instead of a display. 
XtGetGC shares only GCs in which all values in the GC are the same. In particular, it does not 
use the value mask provided to determine which fields of the GC a widget considers rele- 
-- 
vant. val ue_mask is used only to tell the server which fields should be filled in with widget 
data and which it should fill in with default values. 
For a more rigorous account of GCs, see Volume One, Xlib Programming Manual. 

Structures 
typedef unsigned long XGCMask; /* Mask of values that are used by widget*/ 

typedef struct { 
int function; /* logical operation */ 
unsigned long plane_mask; /* plane mask */ 
unsigned long foreground; /* foreground pixel */ 
unsigned long background; /* background pixel */ 
int line width; /* line width */ 
-- 
int line_style; /* LneSolid, LineOnOffDash, 
LineDoubleDash */ 
int cap_style; /* CapNotLast, CapButt, 
CapRound, CapProjecting */ 
int join_style; /* JoinMiter, JoinRound, JoinBevel */ 
int fill_style; /* FillSolid, FillTiled, 
FillStippled, FillOpaqueStippled */ 
int fill rule; /* EvenOddRule, WindingRule */ 
-- 
int arc mode; /* ArcChord, ArcPieSlice */ 
-- 

146 X Toolkit Intrinsics Reference Manual 



Xt - Graphics Context (continued) XtGetGC 

Pixmap tile; 
Pixmap stipple; 
int ts x origin; 
int ts_y_origin; 
Font font; 
int subwindow_mode; 
Bool graphics_exposures; 
int clip_x_origin; 
int clip_y_origin; 
Pixmap clip_mask; 
int dash offset; 
char dashes; 
} XGCValues; 

/* tile pixmap for tiling operations */ 
/* stipple 1 plane pixmap for stipping */ 
/* offset for tile or 
* stipple operations */ 
/* default text font for text operations */ 
/* ClipByChildren, IncludeInferiors */ 
/* should exposures be generated? */ 
/* origin for clipping */ 

/* bitmap clipping; other calls for rects */ 
/* patterned/dashed line information */ 

See Also 
XtReleaseGC 

X Toolkit Intrinsics Reference Manual 14 7 



XtGetSelectionTimeout 

Xt - Selectlons  

Name 
XtGetSelectionTimeout m get the current selection timeout value. 

Synopsis 
unsigned int XtGetSelectionTimeout() 

Description 
XtGetSelectionTimeout returns the current value of the selection timeout in mil- 
liseconds. The default value is 5000 milliseconds (five seconds). 

The selection timeout is the time within which the two communicating applications must 
respond to one another. If one of them does not respond within this interval, the Intrinsics abort 
the selection request. 

Chapter 10, Inter-Client Communications, in Volume Four, X Toolkit Intrinsics Programming 
Manual, presents a complete example widget that both sends and receives data using selection. 

See Also 
Xt Set Select ionTimeout 

150 X Toolkit Intrinsics Reference Manual 



Xt - Selections (continued) XtGetSelectionValues 

Chapter 10, Inter-Client Communications, in Volume Four, X Toolkit lntrinsics Programming 
Manual, presents a complete example widget that both sends and receives data using selection. 

See AIso 
XtGetSelectionValue, XtOwnSelection, 
XtSelectionCallbackProc(2). 

X Toolkit Intrinsics Reference Manual 153 



XtG etSu b resou rces 

Xt- Resource Management 

Name 
XtGetSubresources -- update base-offset resource list (by name or class). 

Synopsis 
void XtGetSubresources(w, base, name, class, 
num_resources, args, num_args) 
Widget w; 
caddr t base; 
-- 
String name; 
String class; 
XtResourceList resources; 
Cardinal num resources; 
ArgList args ; 
Cardinal num_args; 

resources, 

Arguments 
base 

name 
class 
resources 

Specifies the widget that wants resources for a subpart. 
Specifies the base address of the subpart data structure where the resources 
should be written. 
Specifies the name of the subpart. 
Specifies the class of the subpart. 
Specifies the resource list for the subpart. 

num resources 
-- 
Specifies the number of resources in the resource list. 
a rgs Specifies the argument list tO override resources obtained from the resource 
database. 
num._args Specifies the number of arguments in the argument list. 

Description 
A widget does not do anything to get its own resources; instead, XtCreateWidget does this 
automatically before calling the class initialize procedure. 
However, some widgets have subparts that are not widgets but for which the widget would like 
to fetch resources. For example, the Athena Text widget fetches resources for its source and 
sink. Such widgets call XtGetSubresources to accomplish this. 
XtGetSubresources constructs a name or class list from the application name or class, the 
names or classes of all its ancestors, and the widget itself. Then, it appends to this list the name 
or class pair passed in. resources is fetched from the argument list, the resource database, 
or the default values in the resource list. Then, resources is copied into the subpart record. 
If args is NULL, num_args must be zero. However, if num__args is zero, the argument list 
is not referenced. 

154 X Toolkit Intrinsics Reference Manual 



Xt - Resource Management (continued) XtGetSubvalues 

An krg is defined as foows: 
typedef struct { 
String name; 
XtArgVal value; 
} Arg, *ArgList; 

See Also 
Section 1.7, "Resources," 
XtSetArg, 
XtArgsP roc(2). 

X Toolkit Intrinsics Reference Manual 157 



Xt - Resource Management (continued) XtGetValues 

See Also 
Section 1.7, "Resources," 
Xt SetArg, Xt SetValues, 
XtArgsProc(). 

X Toolkit Intrin$ics Reference Manual 159 



XtlnstallAccelerators 

Xt- Translatlons and Actlons-- 

Name 
XtlnstallAccelerators m install a widget's accelerators on another widget. 

Synopsis 
void XtInstallAccelerators(destination, 
Widget destination; 
Widget source; 

source) 

Arguments 
destination Specifies the widget whose translations are to be augmented. 

source 

Specifies the widget whose actions are to be executed. 

Description 
It is often convenient to be able to bind events in one widget to actions in another. In particu- 
lar, it is often useful to be able to invoke menu actions from the keyboard. The Intdnsics pro- 
vide a facility, called accelerators, that let you accomplish this. Accelerators are simply trans- 
lation tables that map event sequences in one widget into actions in another. 
Every widget includes an XtNaccelerators resource, which is defined by the Core widget 
class. The actual value of this resource can be hardcoded by the application or set in a resource 
file, just like any other resource. 
However, in order for the XtNaccelerators resource to actually be used, the application 
must call XtInstallAccelerators (or XtInstallAllAccelerators). This call 
specifies two arguments. The test inat ion widget is the widget whose translation table will 
be augmented with the accelerator table from the Source widget. In other terms, you could 
think of the source as "source of actions" and the destination as "source of events." That is, 
events occurring in the destination widget will trigger actions in the source. (From the event 
point of view, the terminology seems backwards! However, the terms source and destination do 
make sense in terms of what is actually happening to the translation table of the destinaition 
widget.) 
For example, assume an application whose top-level shell widget was named topLevel, and 
which contained a Command widget instance named quit. Further assume that the quit 
widget had the following XtNaccelerators resource defined for it: 
*quit. accelerators: \n\ 
<KeyPress>q: Quit() 
The call: 
XtInitialize (topLevel, quit) ; 
would allow a "q" typed in the application's top-level window to invoke the quit widget's 
Quit action. 
If the display_accelerator method in the Core part of the source widget class is non- 
NULL, XtInstallAccelerators calls it with the source widget and a string representa- 
tion of the accelerator table. (The string representation of the accelerator table is a canonical 
translation table representation, not an exact replica of what was registered.) The method is 

166 X Toolkit Intrinsics Reference Manual 



XtlnstallAIIAccelerators 

'- Xt - Translations and Actions-- 

Name 
XtlnstallAllAccelerators m install all accelerators from a widget and its descendants onto a 
destination. 

Synopsis 
void XtInstallAllAccelerators(destination, 
Widget destination; 
Widget source; 

source) 

Arguments 
de s t i n a t i on Specifies the widget whose translations are to be augmented. 
source Specifies the widget from which the accelerators are to come. 

Description 
XtInstallAllAccelerators is a convenience function for installing all accelerators 
from a widget and all its descendants onto one destination widget It recursively traverses the 
widget tree rooted at source and installs the accelerators of each widget onto 
destination. A common use is to call XtInstallAllAccelerators and pass the 
application main window as the source. This will allow the events occurring anywhere in the 
application to be sent to a particular destination widget. 
Assuming the example shown under xt TnstallAccelerators, the difference between: 
XtInstallAccelerators (topLevel, quit) ; 
and 
xt InstallAl iAccelerators (topLevel, quit) ; 
is that in the second case, the quit widget's accelerator table will actually be merged with the 
translation table of every widget in the application, while in the first case, it will only be 
merged with the translation table for topLevel. Because of event propagation, the effect 
may be indistinguishable to the user in many cases. (By default, an event that is not selected in 
a widget will propagate through that widget to the widget's parent) However, it may make a 
difference if there are conflicting translations in a given widget, and you want the accelerator to 
override the existing translations (using the #Override directive in the accelerator table 
resource specification). 

See Also 
Section 1.5, 'l'ranslations and Actions," 
Xt InstallAccelerators. 

168 X Toolkit Intrinsics Reference Manual 



B Xt - Widget Information 

XtlsComposite 

Name 
XtlsComposite -- test whether a widget is a subclass of the Composite widget class. 

Synopsis 
Boolean XtIsComposite (w) 
Widget w; 

Arguments 

Specifies the widget whose class is to be tested. 

Description 
xtIscomposite tests whether a widget is a subclass of the Composite widget class. This is 
really just a convenience function equivalent to calling XtIsSubclass with composite- 
WidgetClass as the class argument. XtIsCornposite is defined as a macro in 
<X11/Intrinsic.h> : 
#define XtIsComposite(widget) XtIsSubclass(widget, (WidgetClass) \ 
compo s it eWidget C i a s s ) 

See Also 
Composite(3), Core(3). 

X Toolkit Intn'nsics Reference Manual 169 



XtlsConstraint 

Xt - Widget Information 

Name 
XtIsConstraint m test whether a widget is a subclass of the Consla'aint widget class. 

Synopsis 
Boolean XtIsConstraint(w) 
Widget w; 

Arguments 

Specifies the widget whose class is to be tested. 

Description 
Xt IsConstraint tests whether a widget is a subclass of the Consla'aint widget class. This is 
really just a convenience function equivalent to calling xt x s Subclass with constraint- 
WidgetClass as the class argument. XtIsConstraint is defined as a macro in 
<X11/Intrinsic.h> : 
#define XtIsConstraint (widget) XtIsSubclass(widget, (WidgetClass) \ 
constraintWidgetClass) 

See Also 
Consla'aint(3), Core(3). 

170 X Toolkit Intnsics Reference Manual 



m Xt - Widget Information 

XtlsManaged 

Name 
XtlsManaged m determine whether a widget is managed by its parenL 

Synopsis 
Boolean XtIsManaged(w) 
Widget w; 

Arguments 

Specifies the widget whose state is to be tested. 

Description 
XtlsManaged returns TRUE if the specified child widget is currently being managed and 
FALSE if it is not. 

XtlsManaged is a macro for programs that include <Xll/InstrinsicP.h>. It is a function for 
application programs that do not have access to the Core widget field names. 
xt IsManaged simply accesses the Core widget's managed field. 

See Also 
XtManageChi idren, XtUnmanageChi idren, 
Core(3). 

X Toolkit Intrinsics Reference Manual 171 



XtlsRealized 

Xt - Widget Information-- 

Name 
XtlsRealized b determine whether a widget has been realized. 

Synopsis 
Boolean XtIsRealized (w) 
Widget w; 

Arguments 

Specifies the widget whose state is to be tested. 

Description 
XtIsRealized returns TRUE if the widget has been realized, and FALSE otherwise. A widget 
is realized if it has a nonzero X window ID in its Core field window. 
Xt I s Rea li z ed is a macro for programs that include <X1 l llntrinsicP.h>. It is a function for 
application programs that do not have access to the Core widget field names, xt T s Rea lized 
accesses the window field from the Core widget structure, whose field definition is opaque 
from the point of view of application programmers. (Since the Core fields are opaque, they 
cannot be accessed by a macro.) 
Some widget methods (for example, set_values) might wish to operate differently depend- 
ing on whether or not the widget has been realized. 

See Also 
Section 1.1, "Widget Lifecycle" 

172 X Toolkit Innsics Reference Manual 



D Xt - Widget Information 

XtlsSubclass 

Name 
XtlsSubclass -- determine whether a widget is a subclass of a class. 

Synopsis 
Boolean XtIsSubclass(w, widget_class) 
Widget w; 
WidgetClass widget_class; 

Arguments 

Specifies the widget whose class is to be tested. 

widget_class Specifies the widget class to test against. 

Description 
If w belongs to a derived class of widget_class, then it is a subclass. XtIsSubclass 
returns TRUE if the specified widget is a subclass of the given class. 
A widget is trivially a subclass of its own widget class, or it can be any number of subclasses 
removed. XtTsSubclass starts with the widget_class field in the Core class part of w's 
widget structure and follows the superclass pointer until it reaches the top of the class hier- 
archy. 
Composite widgets that restrict the class of widgets they will adopt as children can use xt I s- 
S ubc l a s s to find out if a widget belongs to the desired widget class. 

See Also 
XtCheckSubclass, XtClass, XtSuperclass, 
Composite(3), Core(3). 

X Toolkit Intrinsics Reference Manual 175 



XtMakeGeometryRequest (continued) Xt - Geometry Management 

Otherwise, XtMakeGeometryRequest returns the resulting value from the parent's 
geometry manager. 
Children of primitive widgets are always unmanaged; thus, XtMakeGeometryRequest 
always returns XtGeometryYes when called by a child of a primitive widget. 
Structures 
The return codes from geometry managers are: 
typedef enum _XtGeometryResult { 
XtGeometryYes, /* Request accepted */ 
XtGeometryNo, /* Request denied */ 
XtGeometryAlmost,/* Request denied but willing to take reply */ 
XtGeometryDone /* Request accepted and done */ 
} XtGeometryResult; 
The XtWidgetGeometry structure is similar to but not identical to the corresponding Xlib 
structure: 
typedef unsigned long XtGeometryMask; 
typedef struct { 
XtGeometryMask request_mode; 
Position x, y; 
Dimension width, height; 
Dimension border width; 
-- 
Widget sibling; 
int stack mode; 
-- 
} XtWidgetGeometry; 
The request_mode definitions are from <XlllX.h>: 

#define CWX (i<<0) 
#define CWY (i<<i) 
#define CWWidth (1<<2) 
#define CWHeight (1<<3) 
#define CWBorderWidth (1<<4) 
#define CWSibling (1<<5) 
#define CWStackMode (1<<6) 

The Xt Intrinsics also support the following value: 
#define XtCWQueryOnly (1<<7) 
XtCWQueryOnly indicates that the corresponding geometry request is only a query as to what 
would happen if this geometry request were made and that no widgets should actually be 
changed. 
XtMakeGeometryRequest, like the Xlib XConfigureWindow function, uses 
request_mode to determine which fields in the XtWidgetGeometry structure you want 
to specify. 

178 X Toolkit Intrinsics Reference Manual 



XtMakeResizeRequest 

Xt - Geometry Management m 

Name 
XtMakeResizeRequest -- request parent to change child's size. 

Synopsis 
XtGeometryResult XtMakeResizeRequest (w, width, height, 
width_return, height_return) 
Widget w; 
Dimension width, height; 
Dimension *width_return, *height_return 

Arguments 
w Specifies the child widget making the request. 
width, height Specify the desired widget width and height. 
wi dth_re t urn, h e i gh t_re t urn 
Return the allowed widget width and height. 

Description 
XtMakeResizeRequest is a simplified version of XtMakeGeomet ryRequest. A child 
uses XtMakeRea i zeReque at to ask its parent to change its size. 

XtMakeResizeRequest creates an XtWidgetGeometry structure and specifies that 
width and height should change. The geometry manager is free to modify any of the other 
window attributes (position or stacking order) to satisfy the resize request. 

If the return value is XtGeometryAlmoat, width return and height_return contain 
a compromise width and height. If these are acceptable, the widget should immediately make 
another XtMakeResizeRequest and request that the compromise width and height be 
applied. If the widget is not interested in XtGeometryAlmoat replies, it can pass NULL for 
width return and height return. 

Structu res 
The return codes from geometry managers are: 

typedef enum _XtGeometryResult { 
XtGeometryYes, /* Request accepted */ 
XtGeometryNo, /* Request denied */ 
XtGeometryAlmost,/* Request denied but willing to take reply */ 
:-__ZtoetyDone__ /* Request accepted and done */ 
} XtGeometryResult; 

See Also 
Section 1.8, "Geometry Management," 
XtMakeGeomet ryRequest, 
Volume Four, X Toolkit lntrinsics Programming Manual, Chapter 11, Geometry Management. 

180 X Toolkit Intrinsics Reference Manual 



u Xt - Memory Allocatlon 

XtMalloc 

Name 
XtMalloc m allocate storage. 

Synopsis 
char *XtMalloc(size); 
unsigned int size; 

Arguments 
size 

Specifies the number of bytes desired. 

Description 
XtMalloc returns a pointer to a block of storage of at least the specified si ze bytes. If there 
is insufficient memory to allocate the new block, XtMalloc terminates by calling XtError- 
Msg. 

If a widget is passed a pointer to resource data, it is expected to recopy the actual data into 
space of its own, so the application can do whatever it wants with its own data. The best way to 
preserve data is to allocate memory with XtHalloc and copy the data there. 

makes no guarantee about the contents of the memory when it is allocated. 

Memory allocated with XtMalloc must be deallocated with XtFree. The function Xt- 
Malloc is implemented by the Toolkit independently of the particular environment, so pro- 
grams ported to a system not supporting malloc will still work. 

XtNew and XtNewSt ring provide slightly higher-level approaches to memory allocation. 

See Also 
XtCalloc, XtErrorMsg, XtFree, XtNew, XtNewSt ring, XtRealloc. 

X ToolkJt Innsics Reference Manual 181 



XtManageChild 

Xt - Wldget Llfecycle m 

Name 
XtManageChild m add a widget to its parent's list of managed children. 

Synopsis 
void XtManageChild (w) 
Widget w; 

Arguments 

Specifies the child widget to be managed. 

Description 
XtManageChild brings a child widget created with XtCreateWidget under the geometry 
management of its parent. A widget cannot be made visible until it is managed. 

XtManageChild constructs a WidgetList of length one and calls XtManageChildren. 
Cs]lng XtManageChild or XtManageChildren can be bypassed if widgets are crewed 
with xt CreateManagedWidget. 

Note at XtManageChild, XtManageChildren, XtUnmanageChild, nd Xt- 
UnmanageChildren are low-level routines that are used by generic composite widget build- 
ing routines. In addition, composite widgets can provide widget-specific, high-level conve- 
nience procedures to let applications create and manage children more easily. 

See Also 
Stn 1.1, "Widget fycle," 
XtCreateManagedWidget, XtIsManaged, XtManageChildren, XtSetMapped- 
WhenManaged, XtUnmanageChild, XtUnmanageChildren. 

182 X Toolkit Intrinsics Reference Manual 



XtManageChild ren (continued) Xt - Widgot Lifocycle 

XtManageChild, XtManageChildren, XtUnmanageChild, and XtUnmanage- 
Chi Idren are low-level routines that are used by generic composite widget building routines. 
In addition, composite widgets can provide widget-specific, high-level convenience procedures 
to let applications create and manage children more easily. 

Stctures 
typedef Widget *WidgetList; 

See Also 
Section 1.1, "Widget Lifycle," Section 1.8, "Geometry Management," 
XtCreateManagedWidget, XtIsManaged, XtManageChild, XtMoveWidget, Xt- 
RealizeWidget, XtResizeWidget, XtSetMappedWhenManaged, XtUnmanage- 
Child, XtUnmanageChildren. 

184 X Toolkit Intrinsics Reference Manual 



-- Xt - Wldget Llfecycle 

XtMapWidget 

Name 
XtMapWidget m map a widget to its display. 

Synopsls 
XtMapWidget(w) 
Widget w; 

Arguments 

Specifies the widget to be mapped. 

Description 
XtMapWidget maps a widget's window to its display, causing it to become visible. A widget 
must be realized before it can be mapped. 
If a widget's core map_when_anaged field is set to TRUe., the widget is automatically 
mapped when it is managed. This is the case for most widgets. Widgets that are not must be 
mapped explicitly with XtMapWidget. The map_when_managed field can al be set 
through a call to XtSetMapWhenManaged. 

See Also 
Section 1.1, "Widget Lifecycle," 
Xt SetMappedWhenManaged, XtUnmapWidget. 

X Toolkit Intn'nsics Reference Manual 185 



XtMergeArgLists 

Xt - Memory Allocation-- 

Name 
XtMergeArgLists -- merge two ArgLi s t structures. 

Synopsis 
ArgList XtMergeArgLists(argsl, 
ArgList argsl; 
Cardinal num_argsl; 
ArgList args2; 
Cardinal num_args2; 

num_argsl, args2, num_args2) 

Arguments 
argsl 
num_argsl 
args2 
num_args2 
Description 

Specifies the first ArgList. 
Specifies the number of arguments in the first argument list. 
Specifies the second ArgList. 
Specifies the number of arguments in the second argument list. 

XtMergeArgLists zllocates a new ArgList large enough to hold argsl d args2 d 
copies both into it. It does not check for duplicate entries. 
When the new ArgList is no longer needed, the application program can return it to the free 
pool with XtFree. 

Structures 
Arg is defined as follows in <X111IntMnsic.h>: 
typedef struct { 
String name; 
XtArgVal value; 
} Arg, *ArgList; 

See Also 
XtFree, XtMalloc, XtSetArg. 

186 X Toolkit Intrinsics Reference Manual 



XtNameToWidget 

Xt - Widget Information-- 

Name 
XtNameToWidget -- translate a widget name to a widget instance. 

Synopsis 
Widget XtNameToWidget(reference, name); 
Widget reference; 
String name; 

Arguments 
reference 

n ame 

Specifies the widget from which the search is to start. 
Specifies the fully qualified name of the desired widget 

Description 
XtNameToWidget searches for a widget instance by name. name can refer to a child (either 
pop-up or normal) of the reference widget, or it can refer to a distant descendant To look 
up a distant descendant, separate the names of ancestors with periods. There are no wildcard 
searches. 
The search for a fully specified name proceeds as follows. The first (leftmost) component of 
the name string is searched for as a direct descendant of the reference widget If a widget 
with the given name is found, it is used as the reference widget and the search repeats for 
the next component 
A widget's name is given to it when it is created. If XtNameToWidget cannot find the speci- 
fied widget, it returns NULL. 
The Intrinsics do not require widgets to have unique names. If more than one child of the refer- 
ence widget matches a name, XtNameToWidget may select any of the matching widgets. 
If the specified names contain more than one component and if more than one child matches the 
first component, XtNameToWidget can return NULL if the single branch that it follows does 
not contain the named widget That is, XtNameToWidget does not back up and follow other 
matching branches of the widget tree. A search involving an ambiguous component name is 
not guaranteed to succeed, even if a widget of the specified name exists. 
Chapter 12, Menus, Gadgets, and Cascaded Pop Ups, in Volume Four, X Toolkit Intrinsics Pro- 
gramming Manual, presents a discussion and an example of XtNameToWidget. 

See Also 
Section 1.5, "Translations and Actions," Section 1.6, "Pop Ups," 
XtCreateManagedWidget, XtCreatePopupShell, XtCreateWidget. 

188 X Toolkit Intrinsics Reference Manual 



XtOffset (continued) Xt - Argument Lists 

XtOffset is a macro defined in <Xll/Xt Intrinsic.h> as follows: 
#define Xt0ffset (type, field) ((unsigned int) (((char *) \ 
(&(((type)NULL)->field)))--((char *) NULL))) 

See Also 
Section 1.7, "Resources," 
XtGetResources. 

194 X Toolkit Intrinsics Reference Manual 



XtOpenDisplay (continued) Xt - Application Contexts 

XtOpenDisplay then calls the Xlib function XOpenDisplay tO open the display. If 
display_string was NULL, and no display was specified in argv, it uses the default 
display (on UNIX-based systems, this is the value of the DISPLAY environment variable). 

If XOpenDisplay succccds, XtOpenDisplay then calls XtDisplayInitialize with 
the opened display. If there was no -name option specified in argv and 
application_name is NULL, it uses the last component of argv [ 0 ]. 
XtOpenDi splay returns the newly opened display or NULL on failure. 

See Section 1.1, "Widget Lifecycle," for more general discussion, xtInitialize is a con- 
venience function that can be used if only one display is to be opened. Application contexts are 
constructed with XtAppCreateContext. Parsing the command line is discussed in Section 
1.7, "Resources," and in XtDisplayInitialize. There is example code in Chapter 9, 
Resource Management and Type Conversion, in Volume Four, X Toolkit Intrinsics Program- 
ming Manual. 

See Also 
XtDisplayInitialize, Xt Initialize. 

196 X Toolkit Intrinsics Reference Manual 



XtOwnSelection 

Xt - Selectlons 

Name 
XtOwnSelection -- indicate that selection data is available. 

Synopsis 
Boolean XtOwnSelection(w, selection, time, 
1 ose_lgroc , done_lgroc ) 
Widget w; 
Atom selection; 
Time time; 
XtConvert Select ionP roc convert_lgroc; 
XtLoseSelectionProc 1 ose_lgroc; 
XtSelectionDoneProc done_lgroc; 

convert_lgroc, 

Arguments 

Specifies the widget that wishes to become the owner. 
selection Specifies an atom that describes the type of the selection (for example, 
XA_PRIMARY, XA_SECONDARY; these two are declared beforehand in 
<X111Xatom.h>). 
time Specifies the times when selection ownership should commence. This should 
be the timestamp of the event that triggered ownership. It should be the 
time field taken directly from an XEvent structure. The value Current- 
T ime is not acceptable. 
c on vert_lgro c 
Specifies the procedure to call whenever someone requests the current value 
of the selection. 
1 ose_proc Specifies the procedure to call whenever the widget has lost selection owner- 
ship, or specifies NULL if the owner is not interested in being called back. 
done_proc Specifies the procedure to call after the transfer completes, or specifies NULL 
if the owner is not interested in being called back. 

Description 
Calling XtOwnSelection is a precursor to sending data through the selection mechanism. 
xtOwnSelection informs the Intrinsics of its claim on the selection, and its readiness to 
send data on request, xtOwnSelection returns TRUE if the widget has successfully become 
the owner and FALSE otherwise. 
The widget may fail to become the owner if some other widget has asserted ownership after this 
widget, as indicated by time. Widgets can lose selection ownership either because another 
client more recently asserted ownership of the selection, or because the widget voluntarily gave 
up ownership of the selection with XtDisownSelect ion. 
The 1 ose_proc procedure is invoked when another widget successfully claims the selection 
after w. The 1 ose_proc procedure is not called if the widget fails to obtain selection owner- 
ship in the first place. 

198 X Toolkit Intrinsics Reference Manual 



Xt - Selections (continued) XtOwnSelection 

If the widget successfully obtains the selection ownership, subsequent requests for data will be 
directed to convert_proc. 
XtConve rt Select ionP roc(2) describes the responsibilities of the widget or application 
sending data and its conversion duties. Chapter 10, Inter-CHent Communications, in Volume 
Four, X Toolkit Intrinsics Programming Manual, presents a complete example widget that both 
sends and receives data using selection. 

See Also 
XtDisownSelect ion, XtGet Select ionValue, Xt Select ionDone, 
XtConvert Select ionP roc(2), Xt LoseSelect ionP roc(2). 

X Toolkit Intrinsics Reference Manual 199 



Xt - Translations and Actions (continued) XtParseTranslatlonTable 

The Intrinsics use the compiled form of the translation table to register the necessary events 
with the Event Manager. Widgets need do nothing other than specify the action and translation 
tables for events to be processed by the Resource Manager. 

The facility to parse translation tables can also be accessed by converting a string resource into 
a resource of type XtRTranslationTable. If an empty translation table is required for any 
purpose, one can be obtained by calling XtParseTranslationTable and passing an 
empty sng. 

XtAugmentTranslations and XtOverrideTranslations both expect translations in 
this compiled form. 

See Also 
Section 1.5, "Translations and Actions," 
Volume Four, X Toolkit Intrinsics Programming Manual, Chapter 7, Events, Translations, and 
Accelerators. 

X Toollut InlTinsics Reference Manual 203 



XtPopup (continued) Xt- Pop Ups 

See Also 
Section 1.6, "Pop Ups," 
XtCheckSubclass, XtCreateManagedWidget, XtRealizeWidget. 
Volume Four, X Toolkit lntrinsics Programming Manual, Chapter 12, Menus, Gadgets, and 
Cascaded Pop Ups. 

208 X Toolkit Intrinsics Reference Manual 



XtQueryGeometry 

Xt - Geometry Management-- 

Name 
XtQueryGeometry B query a child widget's preferred geometry. 

Synopsis 
XtGeometryResult XtQueryGeometry(w, intended, preferred_return) 
Widget w; 
XtWidgetGeometry *intended; 
XtWidgetGeometry *preferred_return; 

Arguments 
w Specifies the widget whose geometry preferences are being queried. 
intended Specifies any changes the parent plans to make to the child's geometry, or 
NULL. 
preferred_return 
Returns the child widget's preferred geometry. 

Description 
Some parents may be willing to adjust their layouts to accommodate the preferred geometries 
of their children. They can use XtQueryGeometry to obtain the preferred geometry and, as 
they see fit, can use or ignore any portion of the response. 
To discover a child's preferred geometry, the child's parent sets any changes that it intends to 
make to the child's geometry in the corresponding fields of the intended structure, sets the 
corresponding bits in intended, request_mode, and calls XtQueryGeomet ry. 
XtQueryGeometry clears all bits in the preferred_return->request_mode and 
checks the query_geometry field of the specified widget's class record. If the widget's 
query_geometry method is not NULL, XtQueryGeometry calls the query_geometry 
method and passes w, intended, and preferred_return as arguments. If intended is 
NULL, XtQueryGeometry replaces it with a pointer to an XtWidgetGeometry structure 
with request_mode=0 before calling query_geometry. 
The query_geomet ry procedure pointer is of type XtGeomet ryHandler(2): 
The que ry_geomet ry procedure is expected to examine the bits set in 
request->request_mode, evaluate the preferred geometry of the widget, and store the 
result in geometry_return (setting the bits in geometry_return->request_mode 
corresponding to those geometry fields that it cares abouO. If the proposed geometry change is 
acceptable without modification, the query_geometry procedure should return Xt- 
GeometryYes. If at least one field in geometry_return is different from the correspond- 
ing field in request or if a bit was set in geometry_return that was not set in request, the 
query_geometry procedure should return XtGeometryAlmost. If the preferred 
geometry is identical to the current geometry, the query_geometry procedure should return 
XtGeomet ryNo. 

After calling the query_geometry procedure or if the query_geometry field is NULL, 
XtQue ryGeomet ry examines all the unset bits in geomet ry_retu rn-> request_mode 

210 X Toolkit Intn'nsics Reference Manual 



Xt - Geometry Management (continued) XtQueryGeometry 

and sets the corresponding fields in geometry_return to the current values from the widget 
instance. If the request_mode field is not set to CWStackMode, the stack_mode field is 
set to XtSMDontChange. XtQueryGeometry returns the value returned by the 
que ry_geomet ry procedure or XtGeomet ryYe s if the que ry_geomet ry field is NULL. 
Therefore, the caller can interpret a return of XtGeometryYes as not needing to evaluate the 
contents of the reply and, more importantly, not needing to modify its layout plans. A return of 
XtGeomet ryAlmost means either that both the parent and the child expressed interest in at 
least one common field and the child's preference does not match the parent's intentions or that 
the child expressed interest in a field that the parent might need to consider. A return value of 
XtGeometryNo means that both the parent and the child expressed interest in a field and that 
the child suggests that the field's current value is its preferred value. In addition, whether or 
not the caller ignores the return value or the reply mask, it is guaranteed that the reply structure 
contains complete geometry information for the child. 

Parents are expected to call XtQueryGeometry in their layout routine and wherever other 
information is significant after change_managed has been called. The change_managed 
method may assume that the child's current geometry is its preferred geometry. Thus, the child 
is still responsible for storing values into its own geometry during its initialize method. 

Structures 
The return codes from geometry managers are: 
typedef enum { 
XtGeometryYes, /* Request accepted */ 
XtGeometryNo, /* Request denied */ 
XtGeometryAlmost,/* Request denied but willing to take reply */ 
XtGeometryDone /* Request accepted and done */ 
} XtGeometryResult ; 
The XtWidgetGeometry structure is similar to but not identical to the corresponding Xlib 
structure: 

typedef unsigned long XtGeometryMask; 
typedef struct { 
XtGeometryMask request_mode; 
Position x, y; 
Dimension width, height; 
Dimension border width; 
-- 
Widget sibling; 
int stack mode; 
-- 
} XtWidgetGeometry; 
The request_mode definitions are from <Xll/X.h>: 
#define CWX (i<<0) 
#define CWY (i<<i) 
#define CWWidth (1<<2) 
#define CWHeight (1<<3) 

X Toolkit Intfinsics Reference Manual 211 



XtQueryGeometry (continued) Xt - Geometry Management 

#define CWBorderWidth ( 1<<4 ) 
#define CWS ibling ( 1<<5 ) 
#define CWStackMode (1<<6) 
The Xt Intdnsics also support the following value: 
#define Xt CWQueryOnly ( 1<<7 ) 
XtCWQueryOnly indicates that the corresponding geometry request is only a query as to what 
would happen if this geometry request were made and that no widgets should actually be 
changed. 
XtMakeGeometryRequest, like the Xlib XConfigureWindow function, uses 
request_mode to determine which fields in the XtWidgetGeometry structure you want 
to specify. 
The stack mode definitions are from <Xll/X.h>: 
-- 
#define Above 0 
#define Below 1 
#define TopIf 2 
#define BottomIf 3 
#define Opposite 4 
The Intdnsics also support the following value: 
#define XtSMDontChange 5 
For precise definitions of Above, Below, TopIf, BottomIf, and Opposite, see Volume 
Two, Xlib Reference Manual. XtSMDontChange indicates that the widget wants its current 
stacking order preserved. 

See Also 
Section 1.8, "Geometry Management," 
XtMakeGeomet ryRequest, 
Core(3), Composite(3). 

212 X Toolkit intrinsics Reference Manual 



XtRegisterCaseConverter 

Xt- Keyboard Handllngm 

Name 
XtRegisterCaseConverter m register a case converter. 

Synopsis 
void XtRegisterCaseConverter (display, proc, 
Display *display; 
XtCaseProc proc; 
KeySym start; 
KeySym stop; 

start, stop) 

Arguments 
di spl ay 
proc 
start 
stop 

Specifies the display from which the key events are to come. 
Specifies the XtCaseProc that is to do the conversions. 
Specifies the first keysym for which this converter is valid. 
Specifies the last keysym for which this converter is valid. 

Description 
XtRegisterCaseConverter registers the spified case converter ( XtCase- 
Proc(2)). start and stop provide the inclusive range of keysyms for which this converter 
is to be called. The new converter overrides any previous converters for keysyms in that range. 
The only way to remove a converter is to register a new one. For example, the default key 
translator (_xtConvertCase) can be explicidy reinstalled. 
The default converter understands case conversion for all keysyms defined in the X11 protocol. 
The keysyms defining a keysym range are defined in <Xlllkeysym.h>. 
A related keyboard example is presented in Chapter 13, Miscellaneous Toolkit Programming 
Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual. 

Structures 
typedef XID KeySym; 

See Also 
XtSetKeyTranslator, XtTrans lateKeycode, 
XtCaseProc(2), XtKeyProc(2). 

216 X Toolkit Intrinsics Reference Manual 



XtRemoveAllCallbacks 

Xt - Callbacks-- 

Name 
XtRemoveAllCallbacks m delete all procedures from a callback list. 

Synopsis 
void XtRemoveAllCallbacks(w, callback name) 
Widget w; 
String callback name; 

Arguments 

Specifies the widget whose callbacks are to be deleted. 

callback_name Specifies the callback list to be removed. 

Description 
XtRemoveAllCallbacks removes all the widget's callback procedures identified by 
ca22back_name, regardless of the value of its c2ient_data. This is in contrast to Xt- 
RemoveCa 1 lbac k and XtRemoveCa 1 lbac ks, which remove the specified callback only if 
a specified cli en t_data argument also matches. 
Calling any of these routines implicitly frees all storage associated with the Inlrinsics' internal 
representation of the callback list. 

See Also 
Secfionl.3,"Applicafionlnfface," 
XtAddCallbacks, XtCallCallbacks, XtRemoveCallback, XtRemove- 
Callbacks. 

218 X Toolkit InlTinsics Reference Manual 



XtRemoveCallbacks 

Xt - Callbacks 

Name 
XtRemoveCallbacks m delete a list of procedures from a callback list. 

Synopsis 
void XtRemoveCallbacks(w, callback_name, callbacks) 
Widget w; 
String callback name; 
XtCallbackList callbacks; 

Arguments 
W 

Specifies the widget. 

callback name 
Specifies the callback list from which the procedure is to be deleted. 

callbacks Specifies the NULL-terminated list of callback procedures and corresponding 
client data to be deleted. 

Description 
XtRemoveCallbacks removes a list of procedures from the callback list identified by the 
rcsourcc callback name. 
The procedure is removed only if both the procedure callback and client data match a 
callback on the list. No warning message is generated if a procedure to be removed fails to 
match a callback on the list. Use XtRemoveAllCallbacks if you want to remove a partic- 
ular callback regardless of the value of its cliene.._data. 

Structures 
typedef struct XtCallbackRec* XtCallbackList; 

See Also 
Sfionl.3,"Applicationlntefface," 
XtAddCallbacks, XtCallCallbacks, XtRemoveAllCallbacks, XtRemove- 
Callback. 

220 X Toolkit Intrinsics Reference Manual 



XtRemoveEventHandler (continued) Xt- Event Handling 

Event Mask Symbol 

NoEventMask 
KeyPressMask 
KeyReleaseMask 
ButtonPressMask 
ButtonReleaseMask 
EnterWindowMask 
LeaveWindowMask 
PointerMotionMask 
PointerMotionHintMask 
ButtonlMotionMask 
Button2MotionMask 
Button3MotionMask 
Button4MotionMask 
Button5MotionMask 
ButtonMotionMask 
KeymapStateMask 

ExposureMask 

VisibilityChangeMask 
StructureNotifyMask 
ResizeRedirectMask 
SubstructureNotifyMask 
SubstructureRedirectMask 
FocusChangeMask 
PropertyChangeMask 
ColormapChangeMask 
OwnerGrabButtonMask 

Circumstances 

No events 
Keyboard down events 
Keyboard up events 
Pointer button down events 
Pointer button up events 
Pointer window entry events 
Pointer window leave events 
All pointer motion events 
Fewer pointer motion events 
Pointer motion while button 1 down 
Pointer motion while button 2 down 
Pointer motion while button 3 down 
Pointer motion while button 4 down 
Pointer motion while button 5 down 
Pointer motion while any button down 
Any keyboard state change on EnterNotify, 
LeaveNotify, Focus In or FocusOut 
Any exposure (except GraphicsExpose and 
NoExpose) 
Any change in visibility 
Any change in window configuration. 
Redirect resize of this window 
Notify about reconfiguration of children 
Redirect reconfiguration of children 
Any change in keyboard focus 
Any change in property 
Any change in colormap 
Modifies handling of pointer events 

See Also 
Section 1.4, "Events," 
Xt AddEvent Handle r, Xt Remove RawE vent Handle r, 
XtEventHandler(2). 

222 X Toolkit Intrinsics Reference Manual 



Xt - Pop Ups 

XtRemoveGrab 

Name 
XtRemoveGrab m redirect user input from modal widget back to normal destination. 

Synopsis 
void XtRemoveGrab(w) 
Widget w; 

Arguments 

Specifies the widget to remove from the modal cascade. XtRemoveGrab 
does not terminate a grab requested through the server; it simply changes Xt's 
event dispatching. 

Description 
XtRemoveGrab removes widgets from the modal cascade (a set of widgets that lock out user 
input to the application except through themselves). It issues an error if the specified widget 
was not in the modal cascade. 
The modal cascade is a data structure used by XtDispatchEvent when it tries to dispatch a 
user event. It is a list of widgets which have issued a request, from the Intrinsics, for events 
that would ordinarily be outside their jurisdiction. 
When the modal cascade is not empty, XtDispatchEvent delivers the event to the most 
recent modal cascade entry, with the exclusive parameter TRUE. 
XtPopup UseS XtAddGrab and XtRemoveGrab to constrain user events to a modal cas- 
cade. It is unusual to call XtAddGrab or XtRemoveGrab explicitly. 

See Also 
XtAddGrab, XtDispatchEvent, XtPopup. 

X Toolkit Intrinsics Reference Manual 223 



XtRemovelnput 

Xt- Event Handllngm 

Name 
XtRemovelnput m cancel source of alternate input events. 

Synopsis 
void XtRemoveInput (id) 
Xt Input Id id; 

Arguments 
id 

Specifies the ID returned from the corresponding XtAddInput call. 

Description 
XtRemoveInput causes the Intrinsics to stop watching for events from an alternate input 
source registered with XtAddInput. Alternate input events are usually operating system 
reads, but they can be any I/O operation supported by the operating system. 
For more general discussion of alternate input events, see Chapter 13, Miscellaneous Toolkit 
Programming Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual. 

See Also 
XtAddInput, XtAppAddInput. 

224 X Toolkit Intrinsics Reference Manual 



--Xt- Event Handllng 

XtRemoveRawEventHandler 

Name 
XtRemoveRawEventHandler -- remove a raw event handler. 

Synopsis 
void XtRemoveRawEventHandler (w, event_mask, 
client data) 
Widget w; 
EventMask event mask; 
Boolean nonmaskable; 
XtEventHandler proc; 
caddr t client data; 

nonmaskable, proc, 

Arguments 
event mask 
n onma skabl e 

proc 
client data 

Specifies the widget for which this handler is registered. 
Specifies the events for which to unregister this handler. 
Specifies a Boolean value that indicates whether this procedure should be 
unregistered for the nonmaskable events (Graphicsgxpose, Nogxpose, 
SelectionClear, SelectionRequest, SelectionNotify, 
ClientMessage, and MappingNotify). 
Specifies the procedure to be registered. 
Specifies the client data to match on the registered event handler. 

Description 
XtRemoveRawEventHandler stops the Rcified pcedure from receiving any more of the 
specified events. 

A handler is removed only if both the procedure proc and client data match a previously 
registered handler. If a handler to be removed fails to match a procedure, or if it has been regis- 
tered with a different value of client_data, XtRemoveEventHandler returns without 
reporting an error. 

Because the procedure is a raw event handler, it does not affect the widget's mask and never 
calls the Xlib xSelect Tnput function. 

Structures 
The event_mask is formed by combining the event mask symbols listed in the first column of 
the table below using the bitwise OR operator (I). Each mask symbol sets a bit in the 
event mask. 
The table also describes briefly the circumstances under which you would want to specify each 
symbol. 

X Toolkit Intrinsics Reference Manual 225 



XtRemoveRawEventHandler (continued) Xt- Event Handling 

Event Mask Symbol 

NoEventMask 
KeyPressMask 
KeyReleaseMask 
ButtonPressMask 
ButtonReleaseMask 
EnterWindowMask 
LeaveWindowMask 
PointerMotionMask 
PointerMotionHintMask 
ButtonlMotionMask 
Button2MotionMask 
Button3MotionMask 
Button4MotionMask 
Button5MotionMask 
ButtonMotionMask 
KeymapStateMask 

ExposureMask 

VisibilityChangeMask 
StructureNotifyMask 
ResizeRedirectMask 
SubstructureNotifyMask 
SubstructureRedirectMask 
FocusChangeMask 
PropertyChangeMask 
ColormapChangeMask 
OwnerGrabButtonMask 

Circumstances 

No events 
Keyboard down events 
Keyboard up events 
Pointer button down events 
Pointer button up events 
Pointer window entry events 
Pointer window leave events 
All pointer motion events 
Fewer pointer motion events 
Pointer motion while button 1 down 
Pointer motion while button 2 down 
Pointer motion while button 3 down 
Pointer motion while button 4 down 
Pointer motion while button 5 down 
Pointer motion while any button down 
Any keyboard state change on EnterNotify, 
LeaveNotify, FocusIn or FocusOut 
Any exposure (except GraphicsExpose and 
NoExpose) 
Any change in visibility 
Any change in window configuration. 
Redirect resize of this window 
Notify about reconfiguration of children 
Redirect reconfiguration of children 
Any change in keyboard focus 
Any change in property 
Any change in colormap 
Modifies handling of pointer events 

See Also 
Stionl.4,"Events,'" 
XtRemoveEventHandler. 
XtEventHandler(2). 

226 X Toolkit Intn'nsics Reference Manual 



XtRemoveWorkProc 

Xt- Event Handllngm 

Name 
XtRemoveWorkProc m remove a work procedure. 

Synopsis 
void XtRemoveWorkProc (id) 
XtWorkProcId id; 

Arguments 
id 

Specifies which work procedure to remove. 

Description 
XtRemoveWorkP roc explicitly removes the specified background work procedure. The Xt- 
WorkP roc I d is returned from a corresponding XtAddWorkP roc call. 

AJ1 XtWorkP roc is removed automatically once it returns TRUE. 

See Also 
Xt AddWo rkP roc, XtAppAddWorkP roc, 
XtWorkP roc(2). 

228 X Toolkit Intrinsics Reference Manual 



XtResizeWindow 

Xt - Window Manipulation 

Name 
XtResizeWindow m resize a widget according to the values of its core dimensions. 

Synopsis 
void XtResizeWindow(w) 
Widget w; 

Arguments 
W 

Specifies the widget. 

Description 
XtRes i zeWindow calls the XConfigureWindow Xlib function to make the window of the 
specified widget match its Core width, height, and border width. 
The call to XConfigureWindow is done unconditionally because there is no way to tell if 
these values match the current values. 
XtResJ.zeWS.ndow does not cause the widget's resize method to be called. 
There are very few occasions when you need to use XtRes i zeWindow; it is more diplomatic 
to use XtRes i zeWidget. 

See Also 
Section 1.8, "Geometry Management," 
XtRes i zeWidge t. 

230 X Toolkit Intn'nsics Reference Manual 



XtSetArg 

Xt - Argument Llsts 

Name 
XtSetArg m construct or modify an argument list dynamically. 

Synopsis 
void XtSetArg(arg, resource_name, value) 
Arg arg; 
String resource name; 
XtArgVal value; 

Arguments 
arg Specifies the argument to seL 
resource name 
Specifies the name of the resource. 
value Specifies the value of the resource, or else its address. (If the size of the 
resource is less than or equal to the size of an XtArgVal, the resource value 
is stored directly in val ue; otherwise, a pointer to it is stored in val ue.) 

Description 
Many Intdnsics functions need to be passed pairs of resource names and values. These are 
passed as an ArgList (see the Structures section below). To dynamically change values in an 
existing ArgList. use XtSetArg. 
XtSetArg sets the value of the arg structure. Arg structures are passed to widgets and 
resource routines setting or overriding resource values. 
Note that XtSetArg is a macro. Expressions involving autoincrement and autodecrement 
operations are unsafe in its argument list, since XtSetArg evaluates its first argument twice. 
XtSetArg is usually used in a highly stylized manner to minimize the probability of making a 
mistake; for example: 
Arg args [20] ; 
int n; 
n = 0; 
XtSetArg(args[n], XtNheight, i00); n++; 
XtSetArg(args[n], XtNwidth, 200); n++; 
XtSetValues(widget, args, n); 
Volume Four, X Toolkit lntrinsics Programming Manual, presents several examples using 
Args, setting them both with values initialized at compile time and using XtSetArg. 

Structures 
Arg is defined as foows in <Xll/Intrinsic.h>: 
typedef struct { 
String name; 
XtArgVal value; 
} Arg, *ArgList; 

232 X Toolkit Innsics Reference Manual 



XtSetErrorHandler 

Xt - Error Handling--- 

Name 
XtSetErrorHandler m register a procedure to be called on fatal error conditions. 

Synopsis 
void XtSetErrorHandler (handler) 
XtErrorHandler handler; 

Arguments 
handler 

Specifies the new low-level fatal error procedure, which should not return. 

Description 
The Intrinsics let a client register procedures that are to be called whenever a fatal or nonfatal 
error occurs. These facilities are intended for both error reporting and logging and for error 
correction or recovery. 

Two levels of interface are provided: 

A high-level interface that takes an error name and class and looks the error up in an 
error resource database. The high-level fatal error handler is invoked by a call to Xt- 
ErrorMsg or XtAppErrorMsg; the high-level nonfatal error handler is invoked by a 
call to XtWarningMsg or XtAppWarningMsg. A new handler can be registered by 
calling Xt SetErrorMsgHandler or Xt SetWarningMsgHandler. 

A low-level interface that takes a simple string, which is printed out as the error message. 
The low-level fatal error handler is invoked by a call to Xt.rror or XtAppError; the 
low-level nonfatal error handler is invoked by a call to Xtwarning or XtApp- 
Warning. A new handler can be registered by calling XtSetErrorHandler or Xt- 
SetWarningHandler. 

The high-level functions construct a string to pass to the lower-level interface. On UNIX-based 
systems, the error database is usually lusrlliblXlllXtErrorDB. 

To obtain the error database (for example, to merge with an application or widget-specific data- 
base), use XtAppGetErrorDatabase. 

Application-context-specific error handling is not implemented on many systems. Most imple- 
mentations will have just one set of error handlers. If they are set for different application con- 
texts, the one performed last will prevail. 

The default low-level fatal error handler provided by the Intrinsics is _XtError. On UNIX- 
based systems, it prints the message to standard error and terminates the application. Using 
XtSetErrorHandler, you can replace this default error handler with one of your own. 

Fatal error message handlers should not return. If one does, subsequent Toolkit behavior is 
indeterminate. See xt Set Er ro rHandle r(2) for more details. 

See Also 
XtSetErrorMsgHandler, XtSetWarningHandler, 
XtErrorHandler(2). 

234 X Toolkit Intrinsics Reference Manual 



Xt- Keyboard Handling (continued) XtSetKeyboardFocus 

parent can give the focus to another widget. Widgets that need to know when they lose the 
keyboard focus must use the Xlib focus notification mechanism explicitly (typically by specify- 
ing translations for Focus In and FocusOut events). Widgets that need the keyboard focus 
can call xSet InputFocus explicitly. Widgets that never want the keyboard focus should set 
their accept_focus procedure pointer to NULL. 

See Also 
XtAcceptFocusProc, XtAddGrab, XtCallAcceptFocus, XtDispatchEvent, 
Composite(3). 

X Toolkit Intrinsics Reference Manual 237 



XtSetSelectionTimeout 

Xt - Selections-- 

Name 
XtSetSelectionTimeout -- set value of selection timeout. 

Synopsis 
void XtSetSelectionTimeout(timeout) 
unsigned long timeout; 

Arguments 
timeout 

Specifies the selection timeout in milliseconds. 

Description 
timeout is the time within which the two communicating applications must respond to one 
another. If one of them does not respond within this interval, Xt aborts the selection request. 
The default value of t./meout is 5000 milliseconds (five seconds). 

Chapter 10, Inter-Client Communications, in Volume Four, X Toolkit Intrinsics Programming 
Manual, presents a complete example widget that both sends and receives data using selections. 

See Also 
XtGet SelectionTimeout 

240 X Toolkit Innsics Reference Manual 



m Xt - Resource Management 

XtSetSensitive 

Name 
XtSetSensitive -- set the sensitivity state of a widgeL 

Synopsls 
void XtSetSensitive(w, 
Widget w; 
Boolean sensitive; 

sensi ti ve) 

Arguments 
sensi ti ve 

Specifies the widget. 
Specifies a Boolean value that indicates whether the widget should receive 
keyboard and pointer events. 

Description 
Many widgets have a mode in which they assume a different appearance (for example, grayed 
out or stippled), do not respond to user events, and become dormant. 
When dormant, a widget is insensive. This means the Event Manager does not dispatch any 
events to the widget with an event type of KeyPress, KeyRelease, ButtonPress, 
ButtonRelease, MotionNotify, EnterNotify, LeaveNotify, FocusIn, or 
FocusOut. 
Widget sensitivity is controlled by the sensitive and ancestor_sensitive fields in 
the Core class record. A widget can be insensitive because its sensitive field is FALSE or 
because one of its ancestors is insensitive; therefore, the widget's ancestor sensitive 
-- 
field is also FALSE (sensitive is always set to FALSE if ancestor sensitive is 
FALSE). A widget can, but does not need to, distinguish these two cases visually. 
xtSetSensitive first calls xtSetValues on the current widget with an argument list 
specifying that the sensitive field should change to the new value. It then recursively propa- 
gates the new value down the managed children tree by calling xtsetvalues on each child 
to set ancestor sensitive to the new value if the new values for sensitive and the 
child's ancestor sensitive are not the same. 
XtSetSensitive calls XtSetValues to change the sensitive and ancestor_sen- 
sitive fields in Core. Therefore, when one of these changes, the widget's set_values 
procedure should take whatever display actions are needed (for example, graying or stippling 
the widget). 
xtSetSensitive ensures that if a parent has either sensitive or ancestor_sensi- 
tive set to FALSE, then all children have ancestor_sensitive set to FALSE. 
Both sensitive and the ancestor sensitive field are maintained as Booleans in the 
Core instance record, defined in <X111CoreP.h>. 

See Also 
Xt GetVa lue s, Xt I s Sens it ive, Xt SetVa lue s. 

X Toolkit Intnnsics Reference Manual 241 



Xt- Resource Management (continued) XtSetSubvalues 

Arg is defined as follows in <X111Intnsic.h>: 
typedef struct { 
String name; 
XtArgVal value; 
} Arg, *ArgList; 

See Also 
Secfionl.7,'esoces," 
XtSetArg, 
XtArgsFunc(2). 

X Toolkit Intrinsics Reference Manual 243 



XtSetValues 

Xt - Resource Management 

Name 
XtSetValues -- copy resources from ArgList tO widget 

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

Arguments 

a rgs 

num_args 

Specifies the widget whose values are to be written and their new values. 

Specifies the argument list of name/value pairs that contain the resources to 
be modified. The resources and values passed are dependent on the widget 
being modified. 

Specifies the number of arguments in the argument list. 

Description 
XtSetValues modifies the current state of resources associated with a widget instance. 
(Actually, the widget decides what changes it will actually allow and updates all derived fields 
appropriately.) 
The name fields in args contain the names of resources. The value fields in args contain the 
new values of resources. 
xtSetValues starts with the resources specified for the Core widget fields and descends the 
subclass chain to the widget At each stage, it writes the new value (if specified by one of the 
arguments) or the existing value (if no new value is specified) to a new widget data record. 
xtSetValues then calls the set_values methods for the widget in superclass-to-subclass 
order. If the widget has any nOn-NULL set_values_hook fields, these methods are called 
immediately after the corresponding set_values method. This permits access to nonwidget 
resource data from xtSetValues. 
If the widget's parent is a subclass of constraintWidgetClass, XtSetValues also 
updates the widget's constraints. It starts with the constraint resources specified for 
constraintWidgetClass and proceeds down the subclass chain to the parent's class. At 
each stage, it writes the new value or the existing value to a new constraint record. It then calls 
the constraint set values methods from constraintWidgetClass down to the par- 
ent's class. The constraint set_values methods are called with widget arguments, as for all 
set_values methods, not just the constraint record arguments, so that they can make adjust- 
ments to the desired values based on full information about the widget 
xtSetValues determines if a geometry request is needed by comparing the current widget to 
the new widget If any geometry changes are required, it makes the request, and the geometry 
manager returns XtGeometryYes, XtGeometryAlmost, or XtGeometryNo. If Xt- 
GeometryYes is returned, XtSetValues calls the widget's resize method. If Xt- 
GeometryNo is returned, xtSetValues resets the geometry fields to their original values. 
If XtGeometryAlmost is rettlmed, XtSetValues calls the set_values_almost 

244 X Toolkit Intrinsics Reference Manual 



Xt - Resource Management (continued) XtSetValues 

method, which determines what should be done and writes new values for the geometry fields 
into the new widget, xtSetValues then repeats this process, deciding once more whether 
the geometry manager should be called. 
Finally, if any of the set_values methods returned TRUE, XtSetValues causes the 
widget's expose procedure to be invoked by calling the Xlib XClearArea function on the 
widget's window. 
The conjugate function XtGetValues retrieves a widget's values. 

Structures 
Arg is defined as follows in <X11/Intrinsic.h>: 
typedef struct { 
String name; 
XtArgVal value; 
} Arg, *ArgList; 

See Also 
Section 1.7, "Resources," 
XtSetArg, 
XtargsFunc(2). 

X Toolkit Intrinsics Reference Manual 245 



XtSetWarningHandler 

Xt- Error Handling m 

Name 
XtSetWarningHandler m register a procedure to be called on nonfatal error conditions. 

Synopsis 
void XtSetWarningHandler (handler) 
XtErrorHandler handler; 

Arguments 
handler 

Specifies the new low-level nonfatal error procedure, which usually returns. 

Description 
The Intrinsics let a client register procedures that are to be called whenever a fatal or nonfatal 
error occurs. These facilities are intended for both error reporting and logging and for error 
correction or recovery. 

Two levels of interface are provided: 

A high-level interface that takes an error name and class and looks the error up in an 
error resource database. The high-level fatal error handler is invoked by a call to Xt- 
ErrorMsg or XtAppErrorMsg; the high-level nonfatal error handler is invoked by a 
call to XtWarningMsg or XtAppWarningMsg. A new handler can be registered by 
calling XtSetErrorMsgHandler or XtSetWarningMsgHandler. 

A low-level interface that takes a simple string, which is printed out as the error message. 
The low-level fatal error handler is invoked by a call to XtError or XtAppError; the 
low-level nonfatal error handler is invoked by a call to XtWarning or XtApp- 
Warning. A new handler can be registered by calling XtSetErrorHandler or Xt- 
SetWarningHandler. 

The high-level functions construct a string to pass to the lower-level interface. On UNIX-based 
systems, the error database is usually lusrlliblX111XtErrorDB. 

To obtain the error database (for example, to merge with an application or widget-specific data- 
base), use XtAppGetErrorDatabase. 

Application-context-specific error handling is not implemented on many systems. Most imple- 
mentations will have just one set of error handlers. If they are set for different application con- 
texts, the one performed last will prevail. 

The default warning handler provided by the Intrinsics is _XtWarning. On UNIX-based sys- 
tems, it prints the message to standard error and returns to the caller. Using XtSetWarning- 
Handler, you can replace this handler with one of your own. 
Warning message handlers should return. If an error is non-recoverable, an application should 
generate a fatal error. 

See Also 
XtErrorMsgHandler, XtSetErrorHandler, XtSetWarningMsgHandler, Xt- 
Warning, 
XtWarningHandler(2). 

246 X Toolkit Intrinsics Reference Manual 



Xt - Keyboard Handling (continued) XtTranslateKey 

ModlMask 

Key defined as Modl was depressed. 

Mod5Mask 
StandardMask 

Keydefined as Mod5 wasdepssed. 
(ShiftMask I LockMask). 

See Also 
XtRegiste rCa seConverte r, XtSetKeyTranslator, 
XtKeyP roc(2). 

X Toolkit Intrinsics Reference Manual 253 



Xt - Keyboard Handling (continued) XtTranslateKeycode 

Mod5Mask 
StandardMask 

Keydefined  Mod5 wasdepssed. 
(ShiftMask I LockMask). 

See Also 
XtRegisterCaseConverter, XtSetKeyTranslator, XtTranslateKey, 
XtKeyP roe(2). 

X Toolkit Intrinsics Reference Manual 255 



m Xt - Geometry Management 

XtUnmanageChild 

Name 
XtUnmanageChild m remove a widget from its parent's managed list. 

Synopsis 
void XtUnmanageChild(w) 
Widget w; 

Arguments 

Specifies the child widget to be unmanaged. 

Description 
XtUnmanageChild constructs 
UnmanageChildren. 

a widget list containing one element and calls Xt- 

No that XtManageChild, XtManageChildren, XtUnmanageChild, and Xt- 
UnmanageChi idren are low-level routines that are used by generic composite widget build- 
ing routines. In addition, composite widgets can provide widget-specific, high-level conve- 
nience procedures to let applications create and manage children more easily. 

See Also 
Section l.l,"WMgetLicycle," 
XtDestroyWidget, XtIsManaged, XtManageChild, XtManageChildren, Xt- 
UnmanageChildren. 

X Toolkit Intrinsics Reference Manual 257 



XtUnmanageChildren 

Xt - Geometry Management m 

Name 
XtUnmanageChildren n remove a l.ist of children from a parent widget's managed list. 

Synopsis 
void XtUnmanageChildren(children, num children) 
WidgetList children; 
Cardinal num children; 

Arguments 
chil dren 

Specifies a list of child widgets. 

num_children Specifies the number of children. 

Description 
XtUnmanageChildren removes a list of widgets from a parent widget's geometry manage- 
ment list. It performs the following: 

Issues an error if children do not all have the same parent or if the parent is not a sub- 
class of compos iteWidgetClas s. 

Returns immediately if the common parent is being destroyed; otherwise, for each unique 
child on the list, XtUnmanageChildren performs the following: 

Marks children viable if they are not being destroyed and are currently man- 
aged. For each viable child, if the child is realized, it makes it invisible by unmap- 
ping it. 

If the parent is realized, it calls the change__managed routine of the widgets' 
parent. 

XtUnmanageChildren does not destroy children. Removing widgets from a parent's man- 
aged set is often a temporary banishmentmsome time later, they may be managed again. To 
destroy widgets entirely, see XtDest royWidget. 

Note dmt XtManageChild, XtManageChildren, XtUnmanageChild, and Xt- 
UnmanageChildren are low-level routines that are used by generic composite widget build- 
ing routines. In addition, composite widgets can provide widget-specific, high-level conve- 
nience procedures to let applications create and manage children more easily. 

Structures 
typedef widget *WidgetList ; 

See Also 
Secfionl.l,"WidgetLifycle," 
XtDestroyWidget, XtIsManaged, XtManageChild, XtManageChildren, Xt- 
UnmanageChild. 

258 X Toolkit Intrinsics Reference Manual 



B Xt - Widget Information 

XtWi d g etTo App I icatio n Co nte xt 

Name 
XtWidgetToApplicationContext B get the application context for a given widgeL 

Synopsis 
XtAppContext XtWidgetToApplicationContext(w) 
Widget w; 

Arguments 

Specifies the widget for which you want the application context. 

Description 
XtWidgetToApplicationContext returns the application context for the specified 
widget 

It locates the application context by following the chain of Core widget Parent structures 
until it finds one that is a subclass of the fundamental widget class windowObjClass. Then 
it accesses the application context associated with the display for that widget 

See Also 
XtCreateApplicat ionContext 

X Toolkit Intrinsics Reference Manual 263 



-- Xt - Widget Information 

XtWindowToWidget 

Name 
XtWindowToWidget -- translate a window and display pointer into a widget instance. 

Synopsis 
Widget XtWindowToWidget (display, window) 
Display *display; 
Window window; 

Arguments 
di spl ay 
window 

Specifies the display on which the window is defined. 
Specify the window for which you want the widget. 

Description 
XtWindowToWidget takes a display pointer and a window and returns the associated widgeL 
The widget must be within the same application as the caller. 

On fzilme, XtWindowToWidget returns NULL. 

See Also 
XtNameToWidget, XtWindow. 

X Toolkit Intrinsics Reference Manual 265 



Prototype Procedures 

This section contains alphabetically-organized reference pages for function proto- 
types (typedefs) used for widget methods and other handlers. 

Each page contains a synopsis of the routine's calling sequence, its arguments, a 
description of its function, and a reference to related routines. 



m Xt - Keyboard Handling 

XtAcceptFocusProc 

Name 
XtAcceptFocusProc B prototype procedure to accept or reject keyboard focus. 

Synopsis 
typedef Boolean 
Widget w; 
Time *time; 

(*XtAcceptFocusProc) (Widget, Time) ; 

Arguments 
time 

Specifies the widget. 
Specifies the X time of the event causing the accept focus. 

Description 
When the keyboard focus is given to a widget, Xt invokes the widget's accept_focus pro- 
cedure. The procedure should return a Boolean to indicate whether or not it will accept the 
focus, so that the parent can give the focus to another widget if necessary. 
The accept_focus procedure is part of the Core class structure. A widget that never wants 
the keyboard focus should set its accept_focus procedure to NU,, when it initializes its 
class record. 
A widget can usurp the keyboard focus by calling the Xlib function :<Set TnputFocus expli- 
citly. Similarly, widgets can be notified of the loss of keyboard focus by specifying translations 
or event handlers for Focus In and FocusOut events. 
XtSetKeyboardFocus and the Xlib XSetlnputFocus must be used to actually pass the 
focus to a child. 

See Also 
XtCa 1 iAcceptFocus, Xt SetKeyboa rdFocus. 

X Toolkit Intrinsics Reference Manual 269 



XtActionProc (continued) Xt - Translations and Actions 

newy = (w->bitmapEdit.cur_y + ((XMotionEvent *)event)->y) / 
w->bitmapEdit.cell size in pixels; 
-- 
else 
XtWarning("BitmapEdit: ToggleCell called with wrong 
event type\n"); 

Notice that some code is repeated to cast the event structure to the two different event types. 
With the current MIT implementation of Xlib, the positions of the x and y fields in the 
XButtonEvent and XMotionEvent suctures are the me, and therefore this casting is 
unnecessary. However, it is improper to depend on any particular implementation of Xlib. The 
order of the fields in one of these events could be different in a vendor's implementation of 
Xlib. 

272 X Toolkit Intrinsics Reference Manual 



XtAImostProc (continued) Xt- Geometry Management 

Position x, y; 
Dimension width, height; 
Dimension border width; 
-- 
Widget sibling; 
int stack mode; 
-- 
} XtWidgetGeometry; 
The request_mode definitions are from <XIIIX.h>: 

#define CWX (i<<0) 
#define CWY (i<<i) 
#define CWWidth (1<<2) 
#define CWHeight (1<<3) 
#define CWBorderWidth (1<<4) 
#define CWSibling (1<<5) 
#define CWStackMode (1<<6) 

The Xt Intdnsics also support the following value: 
#define XtCWQue ryOnly ( 1<<7 ) 

XtCWQueryOnly indicates that the corresponding geometry request is only a query as to what 
would happen if this geometry request were made and that no widgets should actually be 
changed. 

XtMakeGeometryRequest, le the Xlib XConfigureWindow function, uses 
request_mode to determine which fields in the XtWidgetGeometry structure you want 
to specify. 

The stack mode definitions are from <XllIX.h>: 

#define Above 0 
#define Below 1 
#define TopIf 2 
#define BottomIf 3 
#define Opposite 4 

The Intrinsics also support the following value: 

#define XtSMDontChange 5 

For precise definitions of Above, Be low, Top I f, BottomI f, and Oppos it e, see the refer- 
ence page for Configurewindow in Volume Two, Xlib Reference Manual. XtSMDont- 
Change indicates that the widget wants its current stacking order preserved. 

See Also 
Co(3) 

274 X Toolkit Intrinsics Reference Manual 



-- Xt - Resource Management 

XtArgsFunc 

Name 
XUgsFunc -- prototype set values hook method. 

Synopsis 
typedef Boolean (*XtArgsFunc) (Widget, ArgList, Cardinal *); 
Widget w; 
ArgList args; 
Cardinal *num_args; 

Arguments 
args 
n um_a rgs 

Specifies the widget whose nonwidget resource values are to be changed. 
Specifies the argument list that was passed to XtCreateWidget. 
Specifies the number of arguments in the argument list. 

Description 
An XtArgsFunc procedure returns a Boolean indicating whether, based on the values passed 
in a rgs, the widget needs to be redrawn. Widgets can set subpart resource values when the 
application calls xtSetValues by supplying an XtArgsFunc procedure in the core widget 
class set_values_hook method. To set the actual subvalues of the nonwidget data, the 
widget should call XtSetSubvalues and pass the appropriate resource list. 

The set__values_hook method is similar to the set_values method, except that it is 
passed only the current widget instance structure and the arglist, instead of the old and new 
copies of the widget instance structure which are passed to set_values. As a result, 
set values hook needs to use a different technique for comparing the current subresource 
values with the values set by xtSetValues. 

There are two ways to do this. One is to loop through the widget's resource list, using strcmp 
to compare each resource name in the argument list with the subresource names, and then com- 
paring each argument value with the current value of the subresource. 
The other way is to copy the instance structure passed in using bcopy (after allocating mem- 
ory for the new copy with XtNew, described in Chapter 13, Miscellaneous Toolkit Program- 
ming Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual). Then call Xt- 
SetSubvalues to set the actual values to those in the argument list. After this process, you 
can compare the old and new values the same way this is done in the set_values method. 
As of Release 4, the initialize_hook and set_values_hook methods are stl called 
for backwards compatibility but are obsolete because the same information (the argument lists) 
has been added as arguments to the initialize and set_values methods. 

Structures 
Arg is defined as follows in <X11/Intrinsic.h>: 
typedef struct { 
String name; 
XtArgVal value; 
} Arg, *ArgList; 

X Toolkit Intrinsics Reference Manual 275 



XtArgsFunc (continued) Xt - Resource Management 

See Also 
Section 1.7, "Resources," 
XtCreat eWidget, Xt Set Subva lues, Xt SetVa lues, 
Core(3). 

276 X Toolkit Intrinsics Reference Manual 



--Xt- Resource Management 

XtArgsProc 

Name 
XtArgsProc- prototype procedure for get_values_hook method. 

Synopsis 
typedef void (*XtArgsProc) (Widget, ArgList, Cardinal *); 
Widget w; 
ArgList args; 
Cardinal *num_args; 

Arguments 
args 
num_args 

Specifies the widget whose nonwidget resource values are to be retrieved. 
Specifies the argument list that was passed to XtCreateWidget. 
Specifies the number of arguments in the argument list. 

Description 
Widgets can return resource values from subparts for XtGetValues by supplying a pointer to 
an XtArgsProc procedure in the Core widget class get_values_hook field. To obtain 
the actual subvalues of the nonwidget data, the widget should call XtGetSubvalues and 
pass the appropriate resource list. 

The initialize hook method is also of t)e XtArgsProc. The initialize hook 
-- -- 
method allows a widget instance to initialize nonwidget data using information from the speci- 
fied argument list. For example, the Text widget has subparts that are not widgets, yet these 
subparts have resources that can be specified by means of the resource file or an argument list. 

The hook methods are called with different arguments than their nonhook counterparts. They 
are passed a single copy of the widget instance structure (the new copy already modified in the 
nonhook methods), and the argument list passed to the Xt routine that triggered the method. 
The set_values_hook and get_values_hook methods simply take this widget ID and 
argument list and pass them to XtSetSubvalues or XtGetSubvalues respectively. The 
initialize_hook method uses the contents of the argument list to validate resource set- 
tings for subparts and set nonresource subpart data. 

As of Release 4, the initialize hook and set values hook methods are stl called 
for backwards compatibility but are obsolete because the same information (the argument lists) 
has been added as arguments to the initialize and set_values methods. However, 
get_values_hook is still necessary. The example below shows the get_values_hook 
method for the AsciiSrc subpart of the Text widget (somewhat simplified to show only the 
essential elements). 

static void 
GetValuesHook(src, args, num_args) 
XawTextSource src; 
ArgList args; 
Cardinal * num_args; 
{ 

X Toolkit Intrinsics Reference Manual 277 



XtArgsProc (continued) Xt - Resource Management 

XtGetSubvalues((caddr t) src, 
-- 
sourceResources, 
XtNumber(sourceResources), 
args, 
*num_args); 

See Also 
Section 1.7, "Resources," 
XtCreateWidget, XtGetSubvalues, XtGetValues, 
Core(3). 

278 X Toolkit Intrinsics Reference Manual 



m Xt - Keyboard Handling 

XtCaseProc 

Name 
XtCaseProc m prototype procedure called to convert the case of keysyms. 

Synopsis 
typedef void (*XtCaseProc) (KeySym *, 
KeySym *keysym; 
KeySym *lower return; 
KeySym *upper_return; 

KeySym *, 

KeySym *); 

Arguments 
keysym 

lower return 

upper_ret urn 

Specifies the keysym to convert. 
Specifies the lower-case equivalent for the keysym. 
Specifies the upper-case equivalent for the keysym. 

Description 
To handle capitalization of nonstandard keysyms, the Intrinsics allow clients to register case 
conversion routines. Case converter procedure pointers are of type xtCaseProc. 
An xtCaseProc allows an application to specify its own upper-case and lower-case transla- 
tions for keyboard keys. 
If there is no case distinction, the procedure should store the input keysym into both return 
values. The case converter can be registered with XtRegisterCaseConverter. 
Here is the default case converter from the R3 Intrinsics: 

/* ARGSUSED */ 
void _XtConvertCase(dpy, keysym, lower_return, upper_return) 

Display *dpy; 
KeySym keysym; 
KeySym *lower return; 
KeySym *upper_return; 

if ((keysym >= XK_a && keysym <= XK_z) II 
(keysym >= XK_ssharp && keysym <= XK_odiaeresis) 
(keysym >= XK oslash && keysym <= XK_ydiaeresis)) 
-- 
*lower return = keysym; 
-- 
*upper_return = keysym-0x20; 
return; 
} 
if ((keysym >= XK_A && keysym <= XK_Z) II 
(keysym >= XK_Agrave && keysym <= XK_Odiaeresis) 
(keysym >= XK_Ooblique && keysym <= XK_Thorn)) { 
*upper_return = keysym; 
*lower return = keysym+0x20; 
-- 
return; 
} 

X Toolkit Intrinsics Reference Manual 281 



XtCaseProc (continued) Xt- Keyboard Handling 

*lower return = keysym; 
-- 
*upper_return = keysym; 

A related keyboard example is presented in Chapter 13, Miscellaneous Toolkit Programming 
Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual. 

See Also 
XtRegisterCaseConverter, XtTranslateKeycode. 

282 X Toolkit Intrinsics Reference Manual 



XtConvertSelectionProc (continued) Xt - Selections 

The Inlrinsics call the selection owner's XtConvertSelectionProc to obtain selection 
data when another client requests it. The XtConvertSelectionProc is registered when 
the selection owner asserts its ownership. 

The XtConvertSelectionProc should return TRUE if the owner successfully converted 
the selection to the target type or FALSE otherwise. If the procedure returns FALSE, the values 
of the return arguments are undefined. 

Each XtConvertSelectionProc should respond to larget value TARGETS by returning a 
value containing the list of the targets they are prepared to convert their selection into. This is 
used by the selection owner. The list of targets should be an array of interned Atoms, and 
return_type should be XA_ATOM. 
Most type Atoms are defined in <XlllXatom.h>. Those that are not (for example, TARGETS) 
must be interned explicitly as Atoms by calling the Xlib function XInternAtom. 

See Also 
XtFree, XtGetSelectionValue, XtOwnSelection, XtSelectionDoneProc. 

The example below shows code to handle standard selection targets. This code is taken from 
the BitmapEdit widget developed in Volume Four, X Toolkit lntrinsics Programming Manual; 
however, this portion of it is adapted from the standard client xclipboard, and can be copied 
almost directly into your widget. 

static Boolean 
convert_proc(w, selection, target, type_return, value_return, 
length_return, format_return) 
BitmapEditWidget w; 
Atom *selection; 
Atom *target; 
Atom *type_return; 
caddr t *value return; 
-- -- 
unsigned long *length_return; 
int *format return; 
-- 

int x, y; 
int width, height; 
/* handle TARGETS target */ 
if (*target == XA TARGETS(XtDisplay(w))) { 
-- 
Atom* targetP; 
Atom* std_targets; 
unsigned long std_length; 
XmuConvertStandardSelection(w, CurrentTime, selection, 
target, type_return, 
(caddr_t*)&std_targets, 
&std_length, format_return); 
*value return = XtMalloc(sizeof(Atom)*(std_length + I)); 
-- 
targetP = *(Atom**)value return; 
-- 
*length_return = std_length + I; 
*targetP++ = w->bitmapEdit.target_atom; 

284 X Toolkit Intrinsics Reference Manual 



XtConverter (continued) Xt- Resource Management 

define a symbolic constant (for example, XtDefaultForeground, XtDefault- 
Background, orXtDefaultFont). 
The foHowg example shows a convener that takes a string and converts it to a pixel vue: 
static void CvtStringToPixel(args, num_args, fromVal, toVal) 
XrmValuePtr args; 
Cardinal *num_args; 
XrmValuePtr fromVal; 
XrmValuePtr toVal; 

static XColor screenColor; 
XColor exactColor; 
Screen *screen; 
Colormap colormap; 
Status status; 
char message[1000]; 
XrmQuark q; 
String params[l]; 
Cardinal num_params = i; 
if (*num_args != 2) 
XtErrorMsg("cvtStringToPixel","wrongParameters", 
"XtToolkitError", 
"String to pixel conversion needs screen and 
colormap arguments", 
(String *)NULL, (Cardinal *)NULL); 

screen = *((Screen **) args[0].addr); 
colormap = *((Colormap *) args[l].addr); 
LowerCase((char *) fromVal->addr, message); 
q = XrmStringToQuark(message); 
if (q == XtQExtdefaultbackground) { done(&screen->white_pixel, Pixel); 
return; } 
if (q == XtQExtdefaultforeground) { done(&screen->black_pixel, Pixel); 
return; } 

if ((char) fromVal->addr[0] == '#') { /* some color rgb definition */ 

status = XParseColor(DisplayOfScreen(screen), colormap, 
(String) fromVal->addr, &screenColor); 
if (status != 0) status = XAllocColor(DisplayOfScreen 
(screen), colormap, &screenColor); 
} else /* some color name */ 
status = XAllocNamedColor(DisplayOfScreen(screen), colormap, 
(String) fromVal->addr, &screenColor, &exactColor); 

if (status == 0) { 

params[0]=(String)fromVal->addr; 
XtWarningMsg("cvtStringToPixel","noColormap", 
"XtToolkitError", 

288 X Toolkit Intrinsics Reference Manual 



Xt- Resource Management (continued) XtConverter 

"Cannot allocate colormap entry for \\"%s\\ .... , params, &num_params) ; 
else { 
done(&(screenColor.pixel), Pixel) 

See Also 
Section 1.7, "Resources," 
Xt AppAddConve rt e r, Xt Convert, XtD i rect Convert, Xt S t r ingCo nver s i on- 
Warning. 

X Toolkit Intrinsics Reference Manual 289 



XtErrorHandler 

Xt- Error Handling m 

Name 
XtErrorHandler -- prototype for low-level error and warning handlers. 

Synopsis 
typedef void (*XtErrorHandler) (String) ; 
String message; 

Arguments 
message 

Specifies the error message. 

Description 
The error handler should display the message string in some appropriate fashion. Some appli- 
cations may wish to log errors to a file as well. 
The default handlers simply print a message to standard error, and exit (for errors) or return (for 
warnings), as shown below: 
static void XtDefaultError(message) 
String message; 

extern void exit(); 
(void)fprintf(stderr, "X Toolkit Error: %s\n", message); 
exit(l); 
} 
static void _XtDefaultWarning(message) 
String message; 
{ 
(void)fprintf(stderr, "X Toolkit Warning: %s\n", message); 
return; 
} 

See Also 
XtError, XtSetErrorHandler, XtSetWarningHandler, XtWarning. 

290 X Toolkit Intrinsics Reference Manual 



-- Xt - Error Handling 

XtErrorMsgHandler 

Name 
XtErrorMsgHandler m prototype for high-level error and warning handlers. 

Synopsis 
typedef void (*XtErrorMsgHandler)(String, String, 
String, String *, Cardinal *); 
String name; 
String type; 
String class; 
String defaultp; 
String *params; 
Cardinal *num_params; 

Arguments 
n ame 

type 

class 
defaultp 
params 
n um_pa rams 

String, 

Specifies the name that is concatenated with the specified type to form the 
resource name of the error message. 
Specifies the type that is concatenated with the name to form the resource 
name of the error message. 
Specifies the resource class of the error message. 
Specifies the default message to use if no error database entry is found. 
Specifies a pointer to a list of values to be substituted in the message. 
Specifies the number of values in the parameter list. 

Description 
Application-supplied error handling functions, for both warnings and fatal errors, are of type 
XtE r ro rMsgHandle r. 

The specified name can be a general nd of enr, le invalidParameters or invalid- 
Window, and the specified type gives exa information. Standard printf notation is used to 
substitute the parameters into the message. 

The default Toolkit-supplied XtErrorMsgHandler routines construct a string and pass the 
result to XtError and XtWarning, respectively. Low-level handlers are of type XtError- 
Handler(2). 

The error handler should make a call to XtGetErrorDatabase or XtAppGetError- 
Database to retrieve the address of the loaded error database (if a database other than the 
default is being used), and XtGetErrorDatabaseText or XtAppGetErrorDatabase- 
Text to actually retdeve the message from the database. 
The example below shows the default error message handler from the MIT R3 In/nsics. 

static void _XtDefaultErrorMsg (name,type,class,defaultp,params,num_params) 
String name, type, class,defaultp; 
String* params; 
Cardinal* num_params; 

X Toolkit Intfinsics Reference Manual 291 



XtErrorMsgHandler (continued) Xt- Error Handling 

char buffer[1000],message[1000]; 
XtGetErrorDatabaseText(name,type,class,defaultp, buffer, I000); 
if (num_params == NULL) XtError(buffer); 
else { 
(void) sprintf(message, buffer, params[0], params[l], params[2], 
params[3], params[4], params[5], params[6], params[7], 
params[8], params[9]); 
XtError(message); 

See Also 
XtSetErrorHandler, XtSetMsgHandler. 

292 X Toolkit Intnsics Reference Manual 



m Xt - Event Handling 

XtEventHandler 

Name 
XtEventHandler D prototype procedure to handle input events. 

Synopsis 
typedef void (*XtEventHandler) (Widget, 
Widget w; 
caddr t client data; 
XEvent *event; 

caddr t, XEvent *) ; 

Arguments 
w Specifies the widget for which to handle events. 
client data Specifies the client-specific information registered with the event handler, 
which is usually NULL if the event handler is registered by the widget itself. 

even t 

Specifies the triggering event for this handler. 

Description 
Event handlers are of type XtEventHandler. A widget expresses interest in an event by 
calling XtAddEventHandler, specifying as the handler argument a pointer to a proce- 
dure of this type. 
Most widgets need not use event handlers explicitly. Instead they use the Xt Resource Man- 
ager to accept events and invoke procedures based on the interpretation of multiple events. 
The example below shows the code from xterm that registers an event handler for Focus In 
and FocusOut events, and a gutted version of the event handler itself. 
extern void HandleFocusChange(); 
static void VTInitialize (request, new) 
XtermWidget request, new; 
{ 

XtAddEventHandler(topLevel,/* widget */ 
FocusChangeMask, /* event mask */ 
FALSE,/* non-maskable events */ 
HandleFocusChange,/* event handler */ 
(Opaque)NULL);/* client_data */ 

/*ARGSUSED*/ 
void HandleFocusChange(w, unused, event) 
Widget w; 
register XFocusChangeEvent *event; 

X Toolkit Intrinsics Reference Manul 293 



XtEventHandler (continued) Xt- Event Handling 

caddr t unused;/* client data */ 
_ -- 
if (event->type == FocusIn) 
/* process FocusIn */ 

else { 
/* process FocusOut */ 

} 
) 

See Also 
Section 1.4, "Events," Section 1.5, "Translations and Actions," 
XtAddEventHandler. 

294 X Toolkit Intrinsics Reference Manual 



XtExposeProc (continued) Xt - Methods 

BitmapEdit widgets take advantage of this, too. They manufacture an artificial event contain- 
ing the bounding box of the cell to be toggled, and pass it when they call expose. This causes 
the expose method to copy only that one cell that was just updated to the window. 
The example below shows the expose method from the BitmapEdit widget described in Vol- 
ume Four, X Toolkit lntrinsics Programming Manual. 
/* ARGSUSED */ 
static void 
Redisplay(cw, event) 
BitmapEditWidget cw; 
XExposeEvent *event; 
{ 
register int x, y; 
unsigned int width, height; 
if (:XtIsRealized(cw)) 
return; 
if (event) { /* called from btn-event */ 
x = event->x; 
y = event->y; 
width = event->width; 
height = event->height ; 
} 
else { /* called because of expose */ 
x = O; 
y= O; 
width = cw->bitmapEdit .pixmap_width_in_pixels; 
height = cw->bitmapEdit.pixmap_height in pixels; 
} 
if (DefaultDepthOfScreen(XtScreen(cw)) == i) 
XCopyArea (XtDisplay (cw), cw->bitmapEdit.big_picture, 
XtWindow (cw), 
cw->bitmapEdit.copy_gc, x + cw->bitmapEdit.cur_x, y + 
cw->bitmapEdit.cur_y, width, height, x, y); 
else 
XCopyPlane (XtDisplay (cw), cw->bitmapEdit.big_picture, 
XtWindow (cw), 
cw->bitmapEdit.copy_gc, x + cw->bitmapEdit.cur_x, y + 
cw->bitmapEdit.cur_y, width, height, x, y, I); 
} 
Note that the expose method first checks to see that the widget is realized using Xt- 
IsRealized. This is a precaution against the unlikely event that an instance of this widget is 
suddenly destroyed or unrealized by an application while Expose events are still pending. If 
this did happen, drawing on the nonexistent window would cause an X protocol error. 
Next, BitmapEdit's expose method sets the rectangle it will redraw based on the event passed 
in by Xt. We also call this method directly from the action that processes button presses. That 
action routine creates a pseudo-event to pass to expose to describe the area to be drawn. 

296 X Toolkit Intn'nsics Reference Manual 



XtExposeProc (continued) Xt - Methods 

typedef struct { 
short xl, x2, yl, y2; 
} Box, BOX, BoxRec, *BoxPtr; 

typedef struct _XRegion { 
long size; 
long numRects; 
BOX *rects; 
BOX extents; 
} REGION; 

See Also 
Core(3) 

298 X Toolkit Intrinsics Reference Manual 



XtGeometryHandler (continued) Xt - Geometry Management 

typedef enum _XtGeometryResult { 
XtGeometryYes, /* Request accepted */ 
XtGeometryNo, /* Request denied */ 
XtGeometryAlmost,/* Request denied but willing to take reply */ 
XtGeometryDone /* Request accepted and done */ 
} XtGeometryResult; 
The XtWidgetGeometry structure is similar to but not identical m the coesponding Xlib 
structure: 
typedef unsigned long XtGeometryMask; 
typedef struct { 
XtGeometryMask request_mode; 
Position x, y; 
Dimension width, height; 
Dimension border width; 
-- 
Widget sibling; 
int stack mode; 
-- 
} XtWidgetGeomet ry; 
The request_mode definitions are from <XlllX.h>: 

#define CWX (i<<0) 
#define CWY (i<<i) 
#define CWWidth (1<<2) 
#define CWHeight (1<<3) 
#define CWBorderWidth (1<<4) 
#define CWSibling (1<<5) 
#define CWStackMode (1<<6) 

The Xt Intrinsics also support the following value: 
#define Xt CWQue ryOn ly ( 1<<7 ) 
xtCwQueryOnly indicas that the coesponding geometry request is only a query s to what 
would happen if this geometry request were made and that no widgets should actually be 
changed. 
XtMakeGeometryRequest, le the Xlib XConfigureWindow function, us 
request_mode to determine which fields in the xtwidgetGeometry sucture you want 
to specify. 
The stack mode definitions are from <X111X.h>: 
#define Above 0 
#define Below 1 
#define TopIf 2 
#define BottomIf 3 
#define Opposite 4 
The Intrinsics also support the following value: 
#define XtSMDontChange 5 

300 X Toolkit Intrinsics Reference Manual 



Xt - Geometry Management (continued) XtGeometryHandler 

For precise definitions of Above, Below, TopIf, BottomIf, and Opposite, see the refer- 
ence page for XConfigureWindow in Volume Two, Xlib Reference Manual. XtSMDont- 
Change indicates that the widget wants its current stacking order preserved. 

See Also 
Section 1.8, "Geometry Management,'" 
Chapter 11, Geometry Management, in Volume 4, X Toolkit lntrinsics Programming Manual. 

X Toolkit Intrinsics Reference Manual 301 



Xt - Methods (continued) XtlnitProc 

whatever size is explicitly given, but they should compute a reasonable size if no size is 
requested. 

The request and new arguments provide the necessary information for how a subclass 
knows the difference between a specified size and a size computed by a superclass. The 
request widget is the widget as originally requested. The new widget starts with the values 
in the request, but it has been updated by all superclass initialization procedures called so far. 
A subclass initialize procedure can compare these two to resolve any potential conflicts. 

In the above example, the subclass with the visual surround can see if the width and height in 
the request widget are zero. If so, it adds its surround size to the width and height fields in 
the new widget. If not, it must make do with the size originally specified. 

The new widget will become the actual widget instance record. Therefore, the initialization 
procedure should do all its work on the new widget (the request widget should never be 
modified), and if it needs to call any routines that operate on a widget, it should specify new as 
the widget instance. 

See Also 
Section 1.1, "Widget Lifecycle," 
Core(3). 

X Toolkit Intrinsics Reference Manual 303 



XtlnputCallbackProc 

Xt- Event Handling 

Name 
XtlnputCallbackProc -- prototype procedure called to handle file events. 

Synopsis 
typedef void (*XtInputCallbackProc)(caddr_t, int *, XtInputId *); 
caddr t client data; 
int *source; 
Xt Input Id *id; 

Arguments 
client data Specifies the client data that was registered for this procedure in XtApp- 
AddI nput. 
source Specifies the source file descriptor generating the event. 
i d Specifies the ID returned from the corresponding XtAppAddInput call. 

Description 
An XtInputCallbackProc is registered by calling XtAddInput or XtAppAddInput. 
i d is the return value from the procedure that registered it. 

An Xt InputCallbackProc is called when there is activity in file source. A procedure of 
this type is called to handle the type of file activity (input, output) it was registered for. 

The example below shows an XtInputCallbackProc named get_file_input togeer 
with the application used to register it. 

/* header files */ 

/* ARGSUSED */ 
get_file_input(client_data, fid, id) 
caddr t client data;/* unused */ 
_ -- 
int *fid; 
XtInputId *id; 
( 
char buf[BUFSIZ]; 
int nbytes; 
int i; 
if ((nbytes = read(*fid, buf, BUFSIZ)) == -I) 
perror("get_file_input"); 
if (nbytes) 
for (i = 0; i < nbytes; i++) 
putchar (buf [i] ) ; 
main(argc, argv) 
int argc; 

304 X Toolkit Intrinsics Reference Manual 



Xt- Event Handling (continued) XtlnputCallbackProc 

char **argv; 
{ 
Widget topLevel, goodbye; 
FILE *fid; 
String filename; 

topLevel = XtInitialize(argv[0], "XFileInput", NULL, 
0, &argc, argv); 

if (argv[l] == NULL) { 
fprintf(stderr, "xfileinput: filename must be specified on\ 
command line.\n"); 
exit(l); 
} 
filename = argv[l]; 

/* open file */ 
if ((fid = fopen(filename, "r")) == NULL) 
fprintf(stderr, "xfileinput: couldn't open input file"); 
/* register function to handle that input, NULL arg is client data */ 
-- 
XtAddInput(fileno(fid), XtInputReadMask, get_file_input, NULL); 
XtRealizeWidget(topLevel); 

XtMainLoop(); 

See Also 
XtAddInput, XtAppAddInput. 

Xt Intrinsics Reference Manual 305 



XtKeyProc 

Xt - Keyboard Handling 

Name 
XtKeyProc -- prototype procedure to translate a key. 

Synopsis 
typedef void (*XtKeyProc)(Display *, 
Modifiers *, KeySym *) ; 
Display *display; 
KeyCode *keycode; 
Modifiers *modifiers; 
Modifiers *modifiers return; 
-- 
KeySym *keysym_return; 

KeyCode *, Modifiers *, 

Arguments 
display 
keycode 
modifiers 

Specifies the display from which to translate the events. 
Specifies the keycode that is to be translated. 
Specifies the mask that indicates what modifier keys (Shift, Meta, Control, 
etc.) are pressed. 

modifiers return 
-- 
Specifies the mask of modifier keys that the function actually evaluated in 
making the conversion. 

keysym_return 
Specifies the resulting keysym. 

Description 
The Resource Manager provides support for automatically translating keycodes in incoming 
key events into keysyms. Keycode-to-keysym translator procedure pointers are of type Xt- 
KeyP roc. 

This procedure takes a keycode and modifiers and produces a keysym. For any given key trans- 
lator function, modifiers return will be a constant that indicates the subset of all modifi- 
ers that are examined by the key translator. 

The default wanslator is XtTranslateKey, an XtKeyProc that uses Shift and Lock modifi- 
ers with the interpretations defined by the core protocol. The MIT R3 code for Xt- 
TranslateKey and associated internal routines is shown below. 

void _XtBuildKeysymTable(dpy, pd) 
Display* dpy; 
XtPerDisplay pd; 

int count; 
KeySym lower_return, upper_return, nbd,*bd; 
count = dpy->max_keycode-dpy->min_keycode+l; 
pd->keysyms = XGetKeyboardMapping( 
dpy, dpy->min_keycode,count,&pd->keysyms_per_keycode); 
if (pd->keysyms_per_keycode > I) 

306 Xt Inn'nsics Reference Manual 



Xt- Keyboard Handling (continued) XtKeyProc 

nbd = (dpy->max_keycode - dpy->min_keycode + i) 
* pd->keysyms_per_keycode; 
for (bd = pd->keysyms; bd < (pd->keysyms + nbd); 
bd += pd->keysyms_per_keycode) { 
if ((*(bd+l)) == NoSymbol) { 
XtConvertCase(dpy,*bd, &lower_return, &upper_return); 
*bd = lower return; 
-- 
*(bd+l) = upper_return; 

} 
} 
} 

KeySym _XtKeyCodeToKeySym(dpy, pd, keycode,col) 
Display* dpy; 
XtPerDisplay pd; 
KeyCode keycode; 
int col; 
/* copied from Xlib */ 
int ind; 
if (pd->keysyms == NULL) { 
_XtBuildKeysymTable(dpy,pd); /* pd->keysyms*/ 
} 
if (col < 0 II col >= pd->keysyms_per_keycode) return (NoSymbol); 
if (keycode < dpy->min_keycode I I keycode > dpy->max_keycode) 
return(NoSymbol); 
ind = (keycode - dpy->min_keycode) * pd->keysyms_per_keycode + col; 
return (pd->keysyms[ind]); 
) 
void XtTranslateKey(dpy, keycode, modifiers, 
modifiers_return, keysym_return) 
Display *dpy; 
KeyCode keycode; 
Modifiers modifiers; 
Modifiers *modifiers return; 
-- 
KeySym *keysym_return; 

XtPerDisplay perDisplay; 
perDisplay = XtGetPerDisplay(dpy); 
-- 
*modifiers return = StandardMask; 
-- 
if ((modifiers & StandardMask) == O) 
*keysym_return =_XtKeyCodeToKeySym(dpy, perDisplay, keycode, 0); 
else if ((modifiers & (ShiftMask I LockMask)) != 0) 
*keysym_return =_XtKeyCodeToKeySym(dpy, perDisplay, keycode, l); 
else 
*keysym_return = NoSymbol; 

Xt Innsics Reference Manual 307 



XtKeyProc (continued) Xt- Keyboard Handling 

The XtPerDisplay structure referenced in the example is an internal structure used to keep 
track of variables that may differ on a display-by-display basis. 

Structures 
typedef unsigned int Modifiers; 
Modifiers will be made up of the bitwise OR the following masks: 

ShiftMask 
LockMask 
ControlMask 
ModlMask 

Shift key was depressed. 
Caps Lock key was depressed. 
Control key was depressed. 
Key defined as Modl was depressed. 

Mod5Mask Key defined as Mod5 was depressed. 
StandardMask (ShiftMask I LockMask). 
For a more detailed discussion of processing keyboard input, see Chapter 13, Miscellaneous 
Toolkit Programming Techniques, in Volume Four, X Toolkit lntrinsics Programming Manual. 
See Also 
XtSetKeyTranslator, XtTranslateKeycode, XtTranslateKey. 

308 Xt Intrinsics Reference Manual 



 Xt - Selectlons / 

XtLoseSelectionProc 

Name 
XtLoseSelectionProc m prototype procedure called by the Intrinsics when another client 
claims the selection. 

Synopsis 
typedef void (*XtLoseSelectionProc) (Widget, Atom *); 
Widget w; 
Atom *selection; 

Arguments 
sel ecti on 

Specifies the widget that has lost selection ownership. 
Specifies the atom that describes the selection type. 

Description 
This procedure is called by the Intrinsics when the specified widget loses the selection. The 
XtLoseSelectionProc is registered when a widget asserts selection ownership with Xt- 
OwnSelection. 
The Intrinsics use this procedure to inform the former selection owner after the selection 
changes hands. Note that this procedure does not ask the widget to lose the selection owner- 
ship. 
Chapter 10, Inter-Client Communications, in Volume Four, X Toolkit Intrinsics Programming 
Manual, presents a complete example widget that both sends and receives data using selections. 

See Also 
XtDisownSelection, XtGet SelectionValues, XtOwnSelection. 

X Toolkit Intdnsics Reference Manual 309 



XtOrderProc 

Xt - Geometry Management m 

Name 
XtOrderProc b prototype procedure for ordering the children of composite widget instances. 

Synopsis 
typedef Cardinal (*XtOrderProc) (Widget) ; 
Widget w; 

Arguments 

Specifies the widget 

Description 
Instances of composite widgets need to specify about the order in which their children are kept. 
For example, an application may want a set of command buttons in some logical order grouped 
by function, and it may want buttons that represent file names to be kept in alphabetical order. 

The inse rt_po s it ion method in a composite widget instance is of type XtOrde rP roc. 
Composite widgets that allow clients to order their children (usually homogeneous boxes) can 
call their widget instance's insert_position method from the class' insert child 
method to determine where a new child should go in its children array. Thus, a client of a com- 
posite class can apply different sordng criteria to widget instances of the class, passing in a dif- 
ferent insert_position method when it creates each composite widget instance. 
The return value of the insert_position method indicates how many children should go 
before the widget Returning zero indicates that the widget should go before all other children, 
and returning hum children indicates that it should go after all other children. The default 
-- 
insert_position method returns num_children and can be overridden by a specific 
composite widget's resource list or by the argument list provided when the composite widget is 
created. 

310 X Toolkit Intrinsics Reference Manual 



-- Xt - Methods 

' XtProc 

Name 
XtProc -- prototype procedure to initialize data for a widget class. 

Synopsis 
typedef void (*XtProc) ; 

Description 
An XtProc is a procedure to initialize data at program startup time. One-time initialization 
can be performed here, such as parsing accelerator tables, registering type converters, run-time 
alterations to data structures, or other actions that cannot be performed at compile time. 

The Core class_init method is of this type. 

See Also 
Core(3) 

X Toolkit Innsics Reference Manual 311 



Xt - Methods (continued) XtRealizeProc 

A widget class can inherit its realize method from its superclass during class initialization. 
The realize method defined for Core calls XtCreateWindow with the passed 
value mask and attributes and with windowClass and visual set to CopyFrom- 
-- 
Parent. Both CompositeWidgetClass and ConstraintWidgetClass inherit this 
realize method, and most new widget subclasses can do the same. 

The most common noninherited realize methods set bit_gravity in the mask and attri- 
butes to the appropriate vnlue and then create the window. For example, depending on its justi- 
fication, Label sets bit_gravity to WestGravity, CenterGravity, or East- 
Gravity. Consequently, shiJnking it just moves the bits appropriately, and no Expose event 
is needed for repainting. 

If a composite widget's children should be realized in a particular order (typically to control 
the stacking order), the widget should call XtRealizeWidget on its children itself in the 
appropriate order from within its own tea l i ze method. 

Widgets that have children and that are not a subclass of compositeWidgetClass are 
responsible for calling XtRealizeWidget on their children, usually from within the 
realize method. 

Structures 
/* Definitions for valuemask argument. These control which fields in 
* XSetWindowAttributes structure should be used. 
*/ 

typedef struct { 
Pixmap background_pixmap; 
unsigned long background_pixel; 
Pixmap border_pixmap; 
unsigned long border_pixel; 
int bit_gravity; 
int win_gravity; 
int backing_store; 
unsigned long backing_planes; 
unsigned long backing_pixel; 
Bool save under; 
-- 
long event mask; 
-- 
long do_not_propagate_mask; 
Bool override redirect; 
-- 
Colormap colormap; 
Cursor cursor; 
} XSetWindowAttributes; 

/* background or None or ParentRelative * / 
/* background pixel */ 
/* border of the window */ 
/* border pixel value */ 
/* one of bit gravity values */ 
/* one of the window gravity values */ 
/* NotUseful, WhenMapped, Always */ 
/* planes to be preserved if possible */ 
/* value to use in restoring planes */ 
/* should bits under be saved (popups) */ 
/* set of events that should be saved */ 
/* set of events that should not propagate */ 
/* boolean value for override-redirect */ 
/* colormap to be associated with window */ 
/* cursor to be displayed (or None) */ 

See Also 
Section 1.1, "Widget Lifecycle," 
XtC tea t eWindow, Xt Rea i i zeWidget, 
Core(3). 

X Toolkit Intrinsics Reference Manual 313 



Xt Resou rce Defau ItProc 

Xt- Resource Management 

Name 
XtResourceDefaultProc m prototype procedure passed as a resource converter of type Xt- 
RCalIProc. 

Synopsis 
typedef void (*XtResourceDefaultProc)(Widget, 
Widget w; 
int offset; 
XrmValue *value; 

int, XrmValue *) 

Arguments 
offset 
value 

Specifies the widget whose resource is to be obtained. 
Specifies the offset of the field in the widget record. 
Specifies the resource value to fill in. 

Description 
Every resource has a representation type. There are 26 types defined by the Intrinsics, and 
additional user types can be created by registering a type converter for them (see XtAdd- 
Converter). 
Two special representation types (XtRImmediate and XtRCallProc) are usable only as 
default resource types. XtRImmediate indicates that the value in the default address 
field of the XtResource structure is the actual value of the resource rather than the address of 
the value. The value must be in correct representation type for the resource. No conversion is 
possible since there is no source representation type. XtRCallProc indicates that the value 
in the default_address field of the XtResource structure is a procedure variable. This 
procedure is automatically invoked with the widget, resource offset, and a pointer to the 
XrmValue in which to store the result and is an XtResourceDefaultProc. 
The XtResourceDefaultProc procedure should fill in the addr field of the value with a 
pointer to the default data in its correct type. 
The default address field in the resource structure is declared as a caddr t. On some 
machine architectures, this may be insufficient to hold procedure variables. 
The example below shows an XtResourceDefaultProc used to obtain a pointer to the 
current screen at runtime. 
/ *ARGSUSED* / 
void XtCopyScreen(widget, offset, value) 
Widget widget ; 
int offset ; 
XrmValue *value; 
{ 
value->addr = (caddr t) (&widget->core.screen) ; 

314 X Toolkit Intrinsics Reference Manual 



Xt- Resource Management (continued) XtResourceDefaultProc 

See Also 
Section 1.7, "Resources" 

X Toolkit Intrinsics Reference Manual 315 



Xt - Selections (continued) XtSelectionCall backProc 

Chapter 10, Inter-Client Communications, in Volume Four, X Toolkit Intrinsics Programming 
Manual, presents a complete example widget that both sends and receives data using selections. 

See Also 
XtDisownSelection, XtGetSelectionValue, XtGetSelectionValues, XtOwn- 
Selection. 

X Toolkit Intrinsics Reference Manual 317 



-- Xt - Methods 

XtSetValuesFunc 

Name 
XtSetValuesFunc n prototype procedure for various set va lue s methods. 
-- 

Synopsis 
typedef Boolean (*XtSetValuesFunc) (Widget, Widget, Widget); 
Widget current; 
Widget request; 
Widget new; 

Arguments 
current 

request 

new 

Specifies a copy of the widget as it was before the xt Setva lues call. 
Specifies a copy of the widget with all values changed as asked for by the 
xtSetValues call before any class set values procedures have been 
-- 
called. 
Specifies the widget with the new values that are actually allowed. 

Description 
The Core set values method and Constraint set values method are both of type xt- 
-- -- 
SetValuesFunc. The Constraint set values method operates in the context of the child. 
-- 
This means its widget arguments are instances of the child, not the parent, even though they are 
class fields of the (Constrain0 Parent. 
current, request, and new are widget instance records of the appropriate widget class. 
new reflects values that have been modified by superclass set values methods, request 
-- 
reflects changes made only by the xtSetValues call itself, current was the widget 
instance at the time of the call, reflecting no changes. A widget can refer to request, to 
resolve conflicts between current and new. Any changes that the widget needs to make 
should be made to new. 

An XtSetValuesFunc returns a Boolean indicating TRUE if the widget should be 
redisplayed and FALSE otherwise, set_values methods should not do any work in response 
to anticipated changes in geometry because xtSetValues will eventually perform a geome- 
try request. The request might be denied. If the widget actually changes size in response to a 
xtSetValues, its resize method is called. Widgets should make geometry-related 
changes there. 

An XtSetValuesFunc cannot assume that the widget is realized, since it is permissible for 
an application to call XtSetValues before a widget is realized. 

See Also 
XtSetValues, 
Constraint(3), Core(3). 

X Toolkit Intrinsics Reference Manual 319 



XtStringProc 

Xt - Methods 

Name 
XtSJngproc  protype procedure for display_accelerator meod. 

Synopsis 
typedef void (*XtStringProc) (Widget, 
Widget w; 
String string; 

String) 

Arguments 

string 

Specifies the widget instance requiring redisplay. 
Provides the string representation of the accelerators currently registered for 
the widget. 

Description 
This is the type of the display_accelerator method in the Core class. 
The string may not be an exact replica of the event it was registered with. Instead, it represents 
a translation in canonical form. 

See Also 
XtD i sp i a yAc ce le rat o r 

320 X Toolkit Intrinsics Reference Manual 



--Xt- Event Handling 

XtTimerCallbackProc 

Name 
XtTimerCallbackProc n prototype callback procedure invoked when timeouts expire. 

Synopsis 
typedef void (*XtTimerCallbackProc)(caddr_t, XtIntervalId *); 
caddr t client data; 
XtIntervalId *id; 

Arguments 
client data Specifies the client data that was registered for this procedure in XtApp- 
-- 
AddT imeOut. 

id 

Specifies the ID returned from the corresponding XtAppAddTimeOut call. 

Description 
An XtTimerCallbackProc is invoked in response to an expired timing interval, as set by 
XtAddT imeOut. 

For a periodic wakeup, the callback procedure must call XtAddTimeOut again from this pro- 
cedure. 

See Also 
Xt AddT imeOut, Xt AppAddT imeOut, 
Chapter 8, More Input Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual. 

X Toolkit Intrinsics Reference Manual 321 



XtWorkProc (continued) Xt- Prototype Procedures 

"dialog",/* widget name */ 
dialogWidgetClass,/* widget class */ 
pshell,/* parent widget*/ 
NULL,/* argument list*/ 
0/* arglist size */ 
); 
dialogDone = XtCreateManagedWidget( 
"dialogDone",/* widget name */ 
commandWidgetClass,/* widget class */ 
dialog,/* parent widget*/ 
NULL,/* argument list*/ 
0/* arglist size */ 
); 
XtAddCallback(dialogDone, XtNcallback, DialogDone, dialog); 
return(TRUE);/* makes Xt remove this work proc automatically */ 
} 
Remember that Xt canna interrupt a work procedure while it is runng; e procedure must 
voluntarily give up conol by returning, and it must do so quicy to avoid slowg ur 
respond. 

See Also 
XtAppAddWorkProc 

324 X Toolkit Intrinsics Reference Manual 



Intrinsics-mandated 
Widget Classes 

This section contains reference pages for the Intrinsics-mandated widget classes: 
Core, Composite, Constraint, and Shell. It describes the class and instance records 
for these widget classes, and provides a detailed description of each of their meth- 
ods. 

As an exception to the general rule that reference pages are organized alphabeti- 
cally, in this section they are presented in order of inheritance: Core, Composite, 
Constraint, and Shell. 



m Xt - Widget Types 

Core 

Name 
Core Widget Class -- fundamental, top-level widgeL 

Synopsis 
#include StringDefs.h 
#include Intrinsic.h 

Description 
The Core widget class is the most fundamental type of widgeL All other widgets are subclasses 
of it. Widgets consist of two data structures: a class record (CoreClassPart) and an 
instance record (CorePart). Both records are defined in <X11/CoreP.h>. Volume Four, X 
Toolkit Intrinsics Programming Manual, discusses how Inlrinsics support object-oriented pro- 
gramming. The Core widget itself is described there also, as is a template widget. 
The Release 3 data structures are described here. They differ only in minor ways from the 
Release 2 structures. 
The class and instance structure are defined in <X111CoreP.h>. 
The ClassPart is defined below: 
typedef struct CoreClassPart { 
WidgetClass superclass; /* pointer to superclass ClassRec */ 
String class name; /* widget resource class name */ 
-- 
Cardinal widget_size; /* size in bytes of widget record */ 
XtProc class initialize; /* class initialization proc */ 
-- 
XtWidgetClassProc class_part_initialize; 
/* dynamic initialization */ 

Boolean class inited; 
-- 
XtInitProc initialize; 
XtArgsProc initialize hook; 
XtRealizeProc realize; 
XtActionList actions; 
Cardinal num actions; 
XtResourceList resources; 
Cardinal num resources; 
-- 
XrmClass xrm class; 
Boolean compress_motion; 
Boolean compress_exposure; 
Boolean compress_enterleave; 
Boolean visible interest; 
XtWidgetProc destroy; 
XtWidgetProc resize; 
XtExposeProc expose; 
XtSetValuesFunc set values; 
XtArgsFunc set_values_hook; 
XtAlmostProc set values almost; 
_ -- 
XtArgsProc get_values_hook; 
XtAcceptFocusProc accept_focus; 
XtVersionType version; 

/* has class been initialized? */ 
/* initialize subclass fields */ 
/* notify that initialize called */ 
/* XCreateWindow for widget */ 
/* widget semantics name to proc map */ 
/* number of entries in actions */ 
/* resources for subclass fields */ 
/* number of entries in resources */ 
/* resource class quarkified */ 
/* compress MotionNotify for widget */ 
/* compress Expose events for widget*/ 
/* compress enter and leave events */ 
/* select for VisibilityNotify */ 
/* free data for subclass pointers */ 
/* geom manager changed widget size */ 
/* redisplay window */ 
/* set subclass resource values */ 
/* notify that set values called */ 
-- 
/* set values got "Almost" geo reply */ 
-- 
/* notify that get_values called */ 
/* assign input focus to widget */ 
/* version of Intrinsics used */ 

X Toolkit Intrinsics Reference Manual 327 



Core (continued) Xt - Widget Types 

struct _XtOffsetRec *callback_private; 
/* list of callback offsets */ 
String tm table; /* state machine */ 
-- 
XtGeometryHandler query_geometry; 
/* return preferred geometry */ 
XtStringProc display_accelerator; 
/* display your accelerator */ 
caddr t extension; /* pointer to extension record */ 
-- 
} CoreClassPart; 
The core instance record is defined as foows: 

typedef struct CorePart { 
-- 
Widget self; 
WidgetClass widget_class; 
Widget parent; 
XrmName xrm name; 
-- 

/* pointer to widget itself */ 
/* pointer to widget's ClassRec */ 
/* parent widget */ 
/* widget resource name quarkified */ 

Boolean being_destroyed; /* marked for destroy */ 
XtCallbackList destroy_callbacks;/* who to call when widget destroyed */ 
caddr t constraints; /* constraint record */ 

/* window position */ 
/* window dimensions */ 
/* window border width */ 
/* is widget geometry managed? */ 
/* is widget sensitive to user events */ 
/* are all ancestors sensitive? */ 
/* private to event dispatcher */ 
/* translation management */ 
/* accelerator translations */ 
/* window border pixel */ 
/* window border pixmap or NULL */ 
/* list of pop ups */ 
/* how many pop ups */ 
/* widget resource name */ 
/* window's screen */ 
/* colormap */ 
/* window ID */ 
/* number of planes in window */ 
/* window background pixel */ 
/* window background pixmap or NULL */ 
/* is window mapped and not occluded? */ 
/* map window if it is managed? */ 

Position x, y; 
Dimension width, height; 
Dimension border width; 
-- 
Boolean managed; 
Boolean sensitive; 
Boolean ancestor sensitive; 
-- 
XtEventTable event table; 
-- 
XtTMRec tm; 
XtTranslations accelerators; 
Pixel border_pixel; 
Pixmap border_pixmap; 
WidgetList popup_list; 
Cardinal num_popups; 
String name; 
Screen *screen; 
Colormap colormap; 
Window window; 
Cardinal depth; 
Pixel background_pixel; 
Pixmap background_pixmap; 
Boolean visible; 
Boolean mapped_when_managed; 
} CorePart; 

The default values for the core fields, which are filled in by the Core resource list and the Core 
initialize method, are: 

328 X Toolkit Intdnsics Reference Manual 



Xt - Widget Types (continued) Core 

Field 

self 
widget_class 

parent 

xrm name 
-- 

being_destroyed 
destroy_callbacks 
constraints 
X 
Y 
width 
height 
border width 
-- 
managed 
sensitive 
ancestor sensitive 
-- 

event table 
-- 
tm 
accelerators 
border_pixel 
border_pixmap 
popup_list 
num_popups 
name 

screen 

colormap 
window 
depth 
background_pixel 
background_pixmap 
visible 
mapped_when_managed 

Default Value 

Address of the widget structure (may not be changed). 
widget_class argument to XtCreateWidget (may not 
be changed). 
parent argument to XtCreateWidget (may not be 
changed). 
Encoded name argument to XtCreateWidget (may not be 
changed). 
Parent's bein g_des t toyed value. 
NULL 
NULL 
0 
0 
0 
0 
FALSE 
TRUE 
Bitwi AND of parent's sensitive and ances- 
tor sensitive. 
Initialized by the Event Manager. 
Initialized by the Resource Manager. 
NULL 
XtDe fau it Fo reground 
NULL 
NULL 
0 
name argument to XtCreateWidget (may not be 
changed). 
Parent's screen; top-level widget gets it from display specifier 
(may not be changed). 
Default colormap for the screen. 
NULL 
Parent's depth; top-level widget gets root window depth. 
XtDefaultBackground 
NULL 
TRUE 
TRUE 

X Toolkit Intrinsics Reference Manual 329 



Xt - Widget Types (continued) Core 

all superclass data as well as its own. 
Sometimes it is possible to anticipate the display needs of several levels of subclass widgets. 
For example, rather than maintaining separate display procedures for the widgets Command, 
Label, and Toggle, they could share a single redisplay routine that uses display state informa- 
tion as follows: 
Boolean invert 
Boolean highlight 
Dimension highlight_width 
Label would have invert and highlight always FALSE and have highlight_width 
zero. Command would dynamically set highlight and highlight_width, but it would 
leave invert always FALSE. Finally, Toggle would dynamically set all three. In this case, the 
expose methods for Command and Toggle inherit their superclass' expose method. 
Some widgets may use substantial computing resources to display data. However, this effort is 
wasted if the widget is not actually visible on the screen and is obscured by another application 
or is iconified. 
The visible field in the Core widget instance structure provides a hint to the widget that it 
need not display data. This field is guaranteed TRUE by the time an Expose event is processed 
if the widget is visible but is usually FALSE if the widget is not visible. 
Widgets can use or ignore the visible hint. If they ignore it, they should have visi- 
ble interest in their widget class record set FALSE. In such cases, the visible field is 
-- 
initialized TRUE and never changes. If visible_interest is TRUE, the Event Manager 
asks for VisibilityNotify events for the widget and updates the visible field accord- 
ingly. 
resize 
The resize method is of type XtWidgetProc. It takes a widget as its only argumenL The 
x, y, width, height and border width fields of the widget contain the new values. The 
-- 
resize method should recalculate the layout of internal data as needed. 
If a widget simply draws itself from whatever size is placed in the core height and width 
instance variables, it does not need a resize method. If nothing needs to be recalculated, it 
can specify NULL for the resize field in its class record. 
Other widgets need to know when they have changed size so that they can change the layout of 
their displayed data to match the new size. (For example, a widget may choose a new smaller 
font, if its size has been diminished.) The widget must treat resize as a command, not as a 
request. Nor can a widget appeal by issuing an XtMakeGeometryRequest or XtMake- 
ResizeRequest from its resize method. 
When a-parent widget is resized, it should reconfigure its children. When a parent resizes a 
child, it updates the geometry fields in the widget, configures the window if the widget is real- 
ized, and calls the child's resize method to notify the child. (See XtConfigureWidget.) 

X Toolkit Intnsics Reference Manual 333 



Core (continued) Xt - Widget Types 

initialize hook 
This method is of type XtArgsProc. It is passed the new created widget instance, the Arg- 
List passed to XtCreateWidget, and its size. 
If this method is not NULL, it is called immediately after the corresponding initialize 
method or in its place if the initialize method is NULL. 
The initialize_hook method allows a widget instance to initialize nonwidget data using 
information from the specified argument list. For example, the Text widget has subparts that 
are not widgets, yet these subparts have resources that can be specified by means of the 
resource file or an argument list. 
display_accelerator 
The display_accelerator method is of type XtSt ringProc. The 
display_accelerator method is used to notify the widget that the Inllinsics have aug- 
mented another widget's translations with its accelerators. 
The accelerators themselves are specified as a translation table in the class accelerators field. 
They must refer to actions that either are global or are valid in the context of the widget 
When the Intlinsics invoke the display_acclerator method, it is passed the accelerator 
table in an internal canonical form. This form is still text, but it differs.from the original source 
of the accelerator table itself. 
query_geometry 
The query_geometry procedure pointer is of type XtGeomet ryHandler: 
typedef XtGeometryResult (*XtGeometryHandler) (Widget, 
XtWidgetGeometry *, XtWidgetGeometry *) ; 
Widget w; 
XtWidgetGeometry *request; 
XtWidgetGeometry * geometry_ret urn; 
The query_geomet ry method is expected to examine the bits set in 
request->request_mode, evaluate the preferred geometry of the widget, and store the 
result in geometry_return (setting the bits in geometry_return->request_mode 
corresponding to those geometry fields that it cares about). If the proposed geometry change is 
acceptable without modification, the query_geometry method should return Xt- 
GeometryYes. If at least one field in geometry_return is different from the correspond- 
ing field in request or if a bit was set in geometry_return that was not set in request, the 
query_geometry method should return XtGeomet ryAlmost. If the preferred geometry 
is identical to the current geometry, the query_geometry method should return Xt- 
Geomet ryNo. 
After calling the query_geomet ry method or if the que ry_geomet ry field is NULL, Xt- 
QueryGeometry examines all the unset bits in geometry_return->request_mode 
and sets the corresponding fields in geomet ry_return to the current values from the widget 
instance. If CWStackMode is not set, the stack mode field is set to XtSMDontChange. 
-- 
XtQueryGeometry returns the value returned by the query_geometry method or Xt- 
Geomet ryYes if the query_geomet ry field is NULL. 

336 X Toolkit Intrinsics Reference Manual 



Xt - Widget Types (continued) Core 

Therefore, the caller can interpret a return of XtGeomet ryYes as not needing to evaluate the 
contents of reply and, more importantly, not needing to modify its layout plans. A return of 
XtGeometryAlmost means either that both the parent and the child expressed interest in at 
least one common field and the child's preference does not match the parent's intentions or that 
the child expressed interest in a field that the parent might need to consider. A return value of 
XtGeometryNo means that both the parent and the child expressed interest in a field and that 
the child suggests that the field's current value is its preferred value. In addition, whether or 
not the caller ignores the return value or the reply mask, it is guaranteed that the geome- 
try_return structure contains complete geometry information for the child. 
Parents are expected to call XtQueryGeometry in their layout routine and wherever other 
information is significant after change_managed has been called. The change_managed 
method may assume that the child's current geometry is its preferred geometry. Thus, the child 
is still responsible for storing values into its own geometry during its in it iali z e method. 

X Toolkit Intrinsics Reference Manual 337 



Composite 

Xt - Widget Types 

Name 
Composite Widget Class m defines methods for geometry management. 

Synopsis 
#include StringDefs.h 
#include Intrinsic.h 

Description 
The Composite widget defines methods for geometry management. Any widget that is capable 
of managing child widgets should be a subclass of the Composite widget. (See also Sec- 
tion 1.8, "Geometry Management.") 

The class and instance structures are defined in <X11/CompositeP.h>. 

The composite class part is defined as follows: 

typedef struct _CompositeClassPart { 
XtGeometryHandler geometry_manager;/* geometry manager for children */ 
XtWidgetProc change_managed; /* change managed state of child */ 
XtWidgetProc insert child; /* physically add child to parent */ 
-- 
XtWidgetProc delete child; /* physically remove child */ 
-- 
caddr t extension; /* pointer to extension record */ 
-- 
} CompositeClassPart,*CompositePartPtr; 

The composite instance record is defined as follows: 

typedef struct _CompositePart { 
WidgetList children; 
Cardinal num children; 
-- 
Cardinal num slots; 
-- 
XtOrderProc insert_position; 
} CompositePart,*CompositePtr; 

/* array of ALL widget children */ 
/* total number of widget children */ 
/* number of slots in children array */ 
/* compute position of new child */ 

Note that this instance record contains a method. (Methods are generally kept in the class 
record, but many different subclasses of Composite may need a private XtOrderProc, so it is 
kept in the instance record.) 

The predefined class record and pointer for CompositeClassRec are: 

extern CompositeClassRec compositeClassRec; 
extern WidgetClass compositeWidgetClass; 

The opaque types CompositeWidget and CompositeWidgetClass and the opaque 
variable compositeWidgetClass are defined for generic operations on widgets that are a 
subclass of Compo s it eWidget. 

338 X Toolkit Intrinsics Reference Manual 



Xt - Widget Types (continued) Com posite 

inform XtMakeGeometryRequest that it does not need to do the configuration itself. 
Although XtMakeGeometryRequest resizes the widget's window, it does not call the 
widget class' resize procedure if the geometry manager returns XtGeometryYes. The 
requesting widget must perform whatever resizing calculations are needed explicitly. 

If the geometry manager chooses to disallow the request, the widget cannot change its geome- 
try. The value of the reply parameter is undefined, and the geometry manager returns Xt- 
Geomet ryNo. 

Sometimes the geometry manager cannot satisfy the request exactly, but it may be able to sat- 
isfy a similar request. That is, it could satisfy only a subset of the requests (for example, size 
but not position) or a lesser request (for example, it cannot make the child as big as the request 
but it can make the child bigger than its current size). In such cases, the geometry manager fills 
in reply with the actual changes it is willing to make, including an appropriate mask, and 
returns XtGeometryAlmost. If a bit in reply, request_mode is zero, the geometry 
manager does not change the corresponding value if the reply is used immediately in a new 
request. If a bit is one, the geometry manager does change that element to the corresponding 
value in geometry_return. More bits may be set in reply, request_mode than in the 
original request if the geometry manager intends to change other fields should the child accept 
the compromise. 

When XtGeomet ryAlmost is returned, the widget must decide if the compromise suggested 
in reply is acceptable. If it is, the widget must not change its geometry directly; rather, it 
must make another call to XtMakeGeomet ryRequest. 

If the next geometry request from this child uses the reply filled in by an XtGeometry- 
Almost return and if there have been no intervening geometry requests on either its parent or 
any of its other children, the geometry manager must grant the request, if possible. That is, if 
the child asks immediately with the returned geometry, it should get an answer of Xt- 
GeometryYes. However, the user's window manager may affect the final outcome. 

To return an XtGeometryYes, the geometry manager frequently rearranges the position of 
other managed children by calling XtMoveWidget. However, a few geometry managers may 
sometimes change the size of other managed children by calling XtResizeWidget or Xt- 
ConfigureWidget. If XtCWQueryOnly is specified, the geometry manager must return 
how it would react to this geometry request without actually moving or resizing any widgets. 

Geometry managers must not assume that the request and reply arguments point to inde- 
pendent storage. The caller is permitted to use the same field for both, and the geometry man- 
ager must allocate its own temporary storage, if necessary. 

insert_position 
Instances of composite widgets need to specify information about the order in which their chil- 
dren are kept. For example, an application may want a set of command buttons in some logical 
order grouped by function, and it may want buttons that represent file names to be kept in 
alphabetical order. 

X Toolkit Intrinsics Reference Manual 341 



Com posite (continued) Xt - Widget Types 

The insert_position method pointer in a composite widget instance is of type Xt- 
Orde rP roc." 
typedef Cardinal (*XtOrderProc) (Widget) ; 
Widget w; 
w specifies the widget. 
Composite widgets that allow clients to order their children (usually homogeneous boxes) can 
call their widget instance's insert_position method from the class' insert_child 
method to determine where a new child should go in its children array. Thus, a client of a com- 
posite class can apply different sorting criteria to widget instances of the class, passing in a dif- 
ferent insert_position method when it creates each composite widget instance. 
The return value of the insert_position method indicates how many children should go 
before the widget. Returning zero indicates that the widget should go before all other children, 
and returning num._children indicates that it should go after all other children. The default 
insert_position method returns num__children and can be overridden by a specific 
composite widget's resource list or by the argument list provided when the composite widget is 
created. 

See Also 
Core(3) 

342 X Toolkit Intrinsics Reference Manual 



m Xt - Widget Types 

Constraint 

Name 
Constraint Widget Class -- provides data structures for a widget's parent. 

Synopsis 
#include StringDefs.h 
#include Intrinsic.h 

Description 
Constraint widgets are a subclass of compositeWidgetClass. Their name is derived from 
the fact that they may manage the geometry of their children based on constraints associated 
with each child. These constraints can be as simple as the maximum width and height the par- 
ent will allow the child to occupy or as complicated as how other children should change if this 
child is moved or resized. Constraint widgets let a parent define resources that are supplied for 
their children. For example, if the Constraint parent defines the maximum sizes for its children, 
these new size resources are retrieved for each child as if they were resources that were defined 
by the child widget. Accordingly, constraint resources may be included in the argument list or 
resource file just like any other resource for the child. 

Constraint widgets have all the responsibilities of normal composite widgets and, in addition, 
must process and act upon the constraint information associated with each of their children. 

To make it easy for widgets and the Intrinsics to keep track of the constraints associated with a 
child, every widget has a constrains field, which is the address of a parent-specific structure that 
contains constraint information about the child. If a child's parent is not a subclass of 
constraintWidgetClass, then the child's constraints field is NULL. 

Note that the constraint data structures are transparent to the child; that is, when a child is man- 
aged by a parent that is a subclass of a constraint widget, there is no difference, as far as the 
child is concerned, from being managed by a normal composite widget. 

The values passed to the parent's constraint set_values method are the same as those pas- 
sed to the child's class set_values method. A class can specify NULL for the set_values 
field of the ConstraintPart if it need not compute anything. 

The constraint set_va lues method should recompute any constraint fields derived from con- 
straint resources that are changed. Further, it should modify the widget fields as appropriate. 
For example, if a constraint for the maximum height of a widget is changed to a value smaller 
than the widget's current height, the constraint set_values method should reset the height 
field in the widget. 

The class and instance structures are defined in <X11/ConstraintP.h>. 

X Toolkit Intrinsics Reference Manual 343 



Shell 

Xt - Wldget Types-- 

Name 
Shell Widget Class -- application resources linking window managers. 

Synopsis 
#include StringDefs.h 
#include Intrinsic.h 

Description 
Widgets negotiate their size and position with their parent widget, that is, the widget that 
directly contains them. Widgets at the top of the hierarchy do not have parent widgets. 
Instead, they must deal with the outside world. To provide for this, each top-level widget is 
encapsulated in a special widget, called a Shell. 

Shell widgets, a subclass of the Composite widget, encapsulate other widgets and can allow a 
widget to avoid the geometry clipping imposed by the parent/child window relationship. They 
also can provide a layer of communication with the window manager. 

Shells have been designed to be as nearly invisible as possible. Clients have to create them (the 
top-level widget returned by a call to XtInitialize or XtCreateApplication- 
Context is a Shell widget, as is a pop-up widget created with XtPopup), but they should 
never have to worry about their sizes. 

If a shell widget is resized from the outside (typically by a window manager), the shell widget 
also resizes its child widget automatically. Similarly, if the shell's child widget needs to 
change size, it can make a geometry request to the shell, and the shell negotiates the size 
change with the outer environment. Clients should never attempt to change the size of their 
shells directly. 

There are seven different types of shells. Only four of these are public (i.e., should be instan- 
tiated by applications): 

OverrideShell 

TransientShell 

TopLevelShell 

ApplicationShell 

Used for shell windows that completely bypass the window manager 
(for example, pop-up menu shells). A subclass of Shell (see below). 

Used for shell windows that can be manipulated by the window 
manager but are not allowed to be iconified separately (for example, 
Dialog boxes that make no sense without their associated applica- 
tion). They are iconified by the window manager only if the main 
application shell is iconified. A subclass of VendorShell (see 
below). 

Used for normal top-level windows (for example, any additional top- 
level widgets an application needs). A subclass of VendorShell (see 
below). 

Used by the window manager to define a separate application 
instance, which is the main top-level window of the application. A 
subclass of TopLevelShell. 

346 X Toolkit Intrinsics Reference Manual 



Shell (continued) Xt - Widget Types 

int vendor_specific; 
} VendorShellPart; 
typedef struct { int empty; } TransientShellPart; 
typedef struct { 
String icon name; 
-- 
Boolean iconic; 
} TopLevelShellPart; 
typedef struct { 
char *class; 
XrmClass xrm class; 
-- 
int argc; 
char **argv; 
} ApplicationShellPart; 
The furl definitions of e various shell widge have shell fields foflowg composite fields: 
typedef struct { 
CorePart core; 
CompositePart composite; 
ShellPart shell; 
} ShellRec, *ShellWidget; 
typedef struct { 
CorePart core; 
CompositePart composite; 
ShellPart shell; 
OverrideShellPart override; 
} OverrideShellRec, *OverrideShellWidget; 
typedef struct { 
CorePart core; 
CompositePart composite; 
ShellPart shell; 
WMShellPart wm; 
} WMShellRec, *WMShellWidget; 
typedef struct { 
CorePart core; 
CompositePart composite; 
ShellPart shell; 
WMShellPart wm; 
VendorShellPart vendor; 
} VendorShellRec, *VendorShellWidget; 
typedef struct { 
CorePart core; 
CompositePart composite; 
ShellPart shell; 
WMShellPart wm; 
VendorShellPart vendor; 
TransientShellPart transient; 

350 X Toolkit Intrinsics Reference Manual 



Xt - Widget Types (continued) Shell 

TopLevel shells have the the following additional resources: 
Field Default Value 
icon_name Shell widget's name 
iconic FALSE 

The icon_name field is the string to display in the shell's icon, and the iconic field is an alter- 
native way to set the initialState resource to indicate that a shell should be initially displayed as 
an icon. 
Application shells have the following additional resources: 
Field Default Value 
argc 0 
argv NULL 

The a rgc and a rgv fields are used to initialize the standard property te COMMAND. 
-- 

X Toolkit Innsics Reference Manual 353 



Athena Widgets 

This section contains alphabetically-organized reference pages for the Athena 
widgets. This widget set is not part of the Intrinsics but was developed by MIT's 
Project Athena to demonstrate their use. It is documented here, since the Athena 
Widgets are used in the examples for Volume Four. 

Each reference page provides a description of the widget class and documents the 
include files for the widget, its class hierarchy, resources, translations and actions, 
and its programmatic interface, including both the Intrinsics calls to create or man- 
age the widget and any functions the widget itself exports. 



--Xt - Athena Widgets 

Box 

Name 
boxWidgetClass -- geometry-managing box widgeL 

Synopsis 
#include <Xll/StringDefs.h> 
#include <Xll/Intrinsic.h> 
#include <Xll/XawMisc.h> /* <Xll/Misc.h> in R2 */ 
#include <Xll/Box.h> 
widget = XtCreateWidget(widget, boxWidgetClass,... ); 

Class Hierarchy 
Core - Composite - Box 

Description 
The Box widget provides geometry management of arbiu'ary 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 fre- 
quently 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. 

Resources 
When creating a Box widget instance, the following resources are retrieved from the argument 

list or from the resource database: 

NalTle 

XtNbackground 

XtNbackground- 
Pixmap 
XtNborderColor 

XtNborderPixmap 
XtNborderWidth 
XtNdestroy- 
Callback 
XtNhSpace 
XtNheight 
XtNmappedWhen- 
Managed 
XtNtranslations 
XtNvSpace 

Type 

Pixel 

Pixmap 
Pixel 

Pixmap 
Dimension 
XtCallbackList 

Dimension 
Dimension 
Boolean 

TranslationTable 
Dimension 

Default 

XtDefault- 
Background 
None 

XtDefault- 
Foreground 
None 
1 
NULL 

4 
See below 
TRUE 

None 

Description 

Window background color 
Window background pixmap 
Window border color 
Window border pixmap 
Border width on button box 
Callbacks for XtDe st royWi dget 
Pixel distance left and right of children 
Viewing height of inner window 
Whether XtMapWidget is automatic 
Event-to-action translations 
Pixel distance top and bottom of chil- 
dren 

X Toolkit Intrinsics Reference Manual 357 



-- Xt - Athena Widgets 

Command 

Name 
commandWidgetClass -- command button activated by pointer click. 

Synopsis 
#include <Xll/StringDefs.h> 
#include <Xll/Intrinsic.h> 
#include <Xll/XawMisc.h> /* <Xll/Misc.h> in R2 */ 
#include <Xll/Command.h> 
widget = XtCreateWidget(widget, commandWidgetClass,... ); 

Class Hierarchy 
Core -- Simple -- Label -- Command 

Description 
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 (specified by the XtNcallback resource) is 
invoked. 

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

Name 

XtNbackground 

XtNbackground- 
Pixmap 
XtNbitmap 
XtNborderColor 

XtNborderPixmap 
XtNborderWidth 
XtNcallback 
XtNcursor 
XtNdestroy- 
Callback 
XtNfont 
XtNforeground 

XtNheight 
XtNhighlight- 
Thickness 
XtNinsensitive- 
Border 

Pixel 

Pixmap 
Pixmap 
Pixel 

Default 

XtDefault- 
Background 
None 

None 
XtDefault- 
Foreground 

Description 

Window background color 
Window background pixmap 
Pixmap to display in place of the label 
Window border color 

Pixmap 
Dimension 
XtCallbackList 
Cursor 
XtCallbackList 

None 
1 
NULL 
None 
NULL 

Window border pixmap 
Width of button border 
Callback for button select 
Pointer cursor 
Callbacks for XtDestroyWidget 

XFontStruct* 
Pixel 

Dimension 
Dimension 

Pixmap 

XtDefaultFont 
XtDefault- 
Foreground 
Text height 
2 

Gray 

Label font 
Foreground color 
Button height 
Width of border to be highlighted 
Border when not sensitive 

X Toolkit Intrinsics Reference Manual 359 



Command (continued) Xt - Athena Widgets 

Na.nle 

XtNinternal- 
Height 
XtNinternalWidth 
XtNjustify 
XtNlabel 
XtNmappedWhen- 
Managed 
XtNresize 
XtNsensitive 
XtNtranslations 

XtNwidth 
XtNx 
XtNy 

Dimension 

Dimension 
XtJustify 
String 
Boolean 

Boolean 
Boolean 
Translation- 
Table 
Dimension 
Position 
Position 

Default 

4 
XtJustifyCenter 
Button name 
TRUE 

TRUE 
TRUE 
See below 

Text width 
0 
0 

Descdpfion 

Internal border height for highlighting 

Internal border width for highlighting 
Type of text alignment 
Button label 
Whether XtMapWidget is automatic 

Whether to auto-resize in SetVa lue s 
Whether widget receives input 
Event-to-action translations 

Button width 
x coordinate 
y coordinate 

Note that the Command widget supports two callback lists: XtNdestroyCallback and 
XtNcallback. The notify action executes the callbacks on the XtNcallback list. The 
call data argument is unused. 
-- 
The new resources (not inherited from superclasses) 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. 
XtNheight Specifies the height of the Command widget. The default value is the 
minimum height that will contain: 

XtNinternalheight + height ofXtNlabel + XtNinternalHeight 

If the specified height is larger than the minimum, the label string is cen- 
tered vertically. 

XtN Int erna iHe ight 
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 

XtNjustify 

Represents the distance in pixels between the ends of the label text or bit- 
map and the vertical edges of the Command widget. Highlight- 
Thickness can be larger or smaller than this value. 
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. 

360 X Toolkit Intrinsics Reference Manual 



m Xt - Athena Widgets 

Dialog 

Name 
dialogWidgetClass -- dialog box widget. 

Synopsis 
#include <Xll/StringDefs.h> 
#include <Xll/Intrinsic.h> 
#include <Xll/XawMisc.h> /* <Xll/Misc.h> in R2 */ 
#include <Xll/Dialog.h> 
widget = XtCreatewidget(widget, dialogwidgetClass .... ); 

Class Hierarchy 
Core - Composite - Consla'aint - Form -o Dialog 

Description 
The Dialog widget implements a commonly used interaction semantic to prompt for auxiliary 
input from a user. For example, you can use a Dialog widget when an application requires a 
small piece of information, such as a filename, from the user. A Dialog widget is simply a spe- 
cial case of the Form widget that provides a convenient way to create a preconfiguredform. 

The typical Dialog widget contains three areas. The first line contains a description of the func- 
tion 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. 

Resources 
When creating a Dialog widget instance, the following resources are retrieved from the argu- 
ment list or from the resource database: 

Nalnc 

XtNbackground 

XtNbackground- 
Pixmap 
XtNborderColor 

XtNborderPixmap 
XtNborderWidth 
XtNdestroy- 
Callback 
XtNheight 

XtNlabel- 
XtNmappedWhen- 
Managed 
XtNmaximumLength 
XtNsensitive 
XtNtranslations 

Pixel 

Pixmap 
Pixel 

Pixmap 
Dimension 
XtCallbackList 

Dimension 

String 
Boolean 

int 
Boolean 
TranslationTable 

Default 

XtDefault- 
Background 
None 

XtDefault- 
Foreground 
None 
1 
NULL 

Computed 
atcreate 
Label name 
TRUE 

256 
TRUE 
None 

Description 

Window background color 
Window background pixmap 
Window border color 
Window border pixmap 
Width of border in pixels 
Callbacks for XtDestroyWidget 
Height of dialog 
S-ing to be displayed 
Whether XtMapWidget  automatic 
Maximum number of input characters 
Whether widget receives input 
Event-to-action translations 

X ToolkR Intrinsics Reference Manual 363 



mXt - Athena Widgets 

Form 

Name 
formWidgetClass m geometry-managing widget implementing constraints on children. 

Synopsis 
#include <Xll/StringDefs.h> 
#include <Xll/Intrinsic.h> 
#include <Xll/XawMisc.h> /* <Xll/Misc.h> in R2 */ 
#include <Xll/Form.h> 
widget = XtCreateWidget(widget, formWidgetClass,... ); 

Class Hierarchy 
Core -- Composite -- Constraint - Form 

Description 
The Form widget can contain an arbitrary number of children or subwidgets. The Form pro- 
vides 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. 

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

NalTle 

XtNbackground 

XtNbackground- 
Pixmap 
XtNborderColor 

XtNborderPixmap 
XtNborderWidth 
XtNdefault- 
Distance 
XtNdestroy- 
Callback 
XtNheight 

XtNmappedWhen- 
Managed 
XtNsensitive 

Type 

Pixel 

Pixmap 
Pixel 

Default 

XtDefault- 
Background 
None 

XtDefault- 
Foreground 

Description 

Window background color 
Window background pixmap 
Window border color 

Pixmap 
Dimension 
int 

XtCallbackList 

Dimension 

Boolean 

Boolean 

None 
1 
4 

NULL 
Computed 
at realize 
TRUE 

TRUE 

Window border pixmap 
Width of border in pixels 
Default value for XtNho ri zDi stance 
and XtNvert Di stance 
Callbacks for XtDestroyWidget 

Height of form 

Whether XtMapWidget is automatic 

Whether widget receives input 

X Toolkit Intrinsics Reference Manual 365 



Form (continued) Xt - Athena Widgets 

NaiTle 

XtNtranslations 
XtNwidth 

XtNx 
XtNy 

Type 

TranslationTable 
Dimension 

Position 
Position 

Default 

None 
Computed 
at realize 
NULL 
NULL 

Description 

Event-to-action translations 
Width of form 

x position of form 
y position of form 

Constraints 
When creating children to be added to a Form, the following additional resources are retrieved 
from the argument list or from the resource database. Note that these resources are maintained 
by the Form widget even though they are stored in the child. 

Nalne 

XtNbottom 
XtNfromHoriz 
XtNfromVert 
XtNhorizDistance 
XtNleft 
XtNresizable 
XtNright 
XtNtop 
XtNvertDistance 

Type 

XtEdgeType 
Widget 
Widget 
int 
XtEdgeType 
Boolean 
XtEdgeType 
XtEdgeType 
int 

Default 

XtRubber 
NULL 
NULL 
XtdefaultDistance 
XtRubber 
FALSE 
XtRubber 
XtRubber 
XtdefaultDistance 

Description 

See text 
See text 
See text 
See text 
See text 
TRUE if allowed to resize 
See text 
See text 
See text 

These resources are called constraints, and 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 Xt- 
NfromVert equals NULL, then XtNvertDistance is measured from the top of the Form. 
Form provides a StringToWidget 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 posi- 
tion the child when the Form is resized. XtEdgeType is defined in <X11IF0rm.h> and is one 
of XtChainTop, XtChainBottom, XtChainLeft, XtChainRight, or XtRubber. 

366 X Toolkit Intrinsics Reference Manual 



Grip 

Xt - Athena Widgets-- 

Name 
gripWidgetClass m attachment point for dragging other widgets. 

Synopsis 
#include 
#include 
#include 
#include 
widget = 

<Xll/StringDefs.h> 
<Xll/Intrinsic.h> 
<Xll/XawMisc.h> 
<Xll/Grip.h> 
XtCreateWidget(widget, 

/* <Xll/Misc.h> in R2 */ 

gripWidgetClass,... ); 

Class Hierarchy 
Core -- Simple -- Grip 

Description 
The Grip widget provides a small region in which user input events (such as ButtonPress or 
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. 
Resources 
When creating a Grip widget instance, the following resources are retrieved from the argument 
list or from the resource database: 
Name Type Default Description 
XtNborderColor Pixel XtDefault- Window border color 
Foreground 

XtNborderPixmap 
XtNborderWidth 
XtNcallback 
XtNcursor 
XtNdestroy- 
Callback 
XtNforeground 

Pixmap 
Dimension 
XtCallbackList 
Cursor 
XtCallbackList 

None 
0 
None 
None 
NULL 

Pixel 

XtDefault- 
Foreground 

Window border pixmap 
Width of the border in pixels 
Action routine 
Cursor for the grip 
Callback for x t De s t r oyWi dge t 

Window background color 

XtNheight 
XtNmappedWhen- 
Managed 
XtNsensitive 
XtNtranslations 
XtNwidth 
XtNx 
XtNy 

Dimension 
Boolean 

Boolean 
TranslationTable 
Dimension 
Position 
Position 

8 
TRUE 

TRUE 
None 
8 
0 
0 

Height of the widget 
Whether XtMapWidget is automatic 

Whether widget should receive input 
Event-to-action translations 
Width of the widget 
x coordinate within parent 
y coordinate within parent 

Note that the Grip widget displays its region with the foreground pixel only. 

368 X Toolkit Intrinsics Reference Manual 



Label 

Xt - Athena Widgets m 

Name 
labelWidgetClass -- widget to display a non-editable string. 

Synopsis 
#include <Xll/StringDefs.h> 
#include <Xll/Intrinsic.h> 
#include <Xll/XawMisc.h> 
#include <Xll/Label.h> 
widget = XtCreateWidget(widget, 

Class Hierarchy 
Core --> Simple --> Label 

/* <Xll/Misc.h> in R2 */ 

labelWidgetClass,... ); 

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

Resources 
When creating a Label widget instance, the following resources are retrieved from the argu- 

ment list or from the resource database: 

Nalne 

XtNbackground 

XtNbackground- 
Pixmap 
XtNbitmap 

XtNborderColor 

Class Type 

Pixel 

Pixmap 
Pixmap 

Pixel 

Pixmap 
Dimension 
Cursor 
XtCallbackList 

XFontStruct* 
Pixel 

Dimension 
Pixmap 
Dimension 
Dimension 
XtJustify 
String 

Default 

XtDefault- 
Background 
None 

None 

XtDefault- 
Foreground 
None 
1 
None 
NULL 

XtDefaultFont 
XtDefault- 
Foreground 
Text height 
Gray 

XtJustifyCenter 
Label name 

Description 

Window background color 
Window background pixmap 
Pixmap to display in place of the 
label 
Window border color 
Window border pixmap 
Border width in pixels 
Pointer cursor 
Callbacks for x t De s t royWi dge t 
Label font 
Foreground color 
Height of widget 
Border when not sensitive 
See note 
See note 
Type of text alignment 
String to be displayed 

XtNborderPixmap 
XtNborderWidth 
XtNcursor 
XtNdestroy- 
Callback 
XtNfont 
XtNforeground 

XtNheight 
XtNinsensitive- 
Border 
XtNinternal- 
Height 
XtNinternalWidth 
XtNjustify 
XtNlabel 

370 X Toolkit Intrinsics Reference Manual 



BXt - Athena Wldgets 

List 

Name 
listWidgetClass m widget for managing row-column geometry. 

Synopsis 
#include <Xll/StringDefs.h> 
#include <Xll/Intrinsic.h> 
#include <Xll/XawMisc.h> 
#include <Xll/List.h> 
widget = XtCreatewidget(widget, listWidgetClass,... ); 

Class Hierarchy 
Core  Simple  Grip 

/* <Xll/Misc.h> in R2 */ 

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

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

NalTIC 

XtNbackground 

XtNbackground- 
Pixmap 
XtNborderColor 

XtNborderPixmap 
XtNborderWidth 
XtNcallback 
XtNcolumnSpacing 
XtNcursor 
XtNdefaultColumns 
XtNdestroy- 
Callback 
XtNfont 
XtNforceColumns 

XtNforeground 

XtNheight 

XtNinsensitive- 
Border 

Pixel 

Pixmap 
Pixel 

Pixmap 
Dimension 
XtCallbackList 
Dimension 
Cursor 
int 
XtCallbackList 

XFontStruct* 
Boolean 

Pixel 

Dimension 

Pixmap 

Default 

XtDefault- 
Background 
None 

XtDefault- 
Foreground 
None 
1 
NULL 
6 
left_ptr 
2 
NULL 

XtDefaultFont 
FALSE 

XtDefault- 
Foreground 
Contaslist 
exactly 
Gray 

Description 

Window background color 

Window background pixmap 

Window border color 

Window border pixmap 
Width of border 
Selection callback function 
Space between columns in the list 
Pointer cursor 
Number of columns to use 
Callbacks for xt De st royWidge t 

Font for list text 
Force the use of XtNdefault- 
Columns 
Foreground (text) color 

Height of widget 

Border when not sensitive 

X Toolkit Intrinsics Reference Manual 373 



List (continued) Xt - Athena Widgets 

NaTne 

XtNinternalHeight 

XtNinternalWidth 

XtNlist 
XtNlongest 

XtNmappedWhen- 
Managed 
XtNnumberStrings 

XtNpasteBuffer 
XtNrowSpacing 
XtNsensitive 
XtNtranslations 

XtNverticalList 
XtNwidth 

XtNx 
XtNy 

Type 

Dimension 

Dimension 

String * 
int 

Boolean 

int 

Boolean 
Dimension 
Boolean 
Translation- 
Table 
Boolean 
Dimension 

Position 
Position 

Default 

List name 
Longest item 

TRUE 

Number of 
strings 
FALSE 
4 
TRUE 
None 

FALSE 
Contains list 
exactly 
0 
0 

Description 

Spacing between list and widget 
edges 
Spacing between list and widget 
edges 
An array of swings that is the list 
Length of the longest list item 
in pixels 
Whether XtMapWidget is automatic 

Number of items in the list 

Copy the selected item to cut buffer 0 
Space between rows in the list 
Whether widget receives input 
Event-to-action translations 

Specify the layout of list items 
Width of widget 

Widget x coordinate 
Widget y coordinate 

The new resources associated with the List widget are: 
XtNcolumnSpacLng Specify the amount of space between each of the rows and columns in 
XtNrowSpacing the list. 
XtNdefaultColumns Specifies the default number of columns, which is used when neither 
the width nor the height of the List widget is specified or when xt- 
NforceColumns is TRUE. 
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 mini- 
mum 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 comer. 
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 

374 X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets (continued) List 

The XtListShowCurrent function returns a pointer to an XtListReturnStruct 
structure that 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. 

X Toolkit Intrinsics Reference Manual 377 



Scrollbar 

Xt - Athena Widgets-- 

Name 
scrollbarWidgetClass -- widget to control scrolling of viewing area in another widget. 

Synopsis 
#include <Xll/StringDefs.h> 
#include <Xll/Intrinsic.h> 
#include <Xll/XawMisc.h> /* <Xll/Misc.h> in R2 */ 
#include <Xll/Scroll.h> 
widget = XtCreateWidget(widget, scrollbarWidgetClass,... ); 

Class Hierarchy 
Core --) Simple --) Scroll 

Description 
The Scrollbar widget is a rectangular area that contains a slide region and a thumb (slide bar). 
A Scrollbar can be uscd alone, as a valuator, or 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 scrollbar action. That is, given either a vertical or hori- 
zontal 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 is moved, the thumb follows the pointer. 
The cursor in the scroll region changes depending on the current action. When no pointer but- 
ton 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, client data, and 
-- 
the pixel position of the pointer when the button was released. For smooth scrolling, the call- 
back routine returns the scroll bar window, cl i ent_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. 

Resources 
When creating a Scrollbar widget instance, the following resources are retrieved from the argu- 
ment list or from the resource database: 

378 X TooAkit Intrinsics Reference Manual 



Xt - Athena Widgets (continued) Scrollbar 

Name 

XtNbackground 
XtNbackground- 
Pixmap 
XtNborderColor 

XtNborderPixmap 
XtNborderWidth 
XtNdestroy- 
Callback 
XtNforeground 
XtNheight 
XtNjumpProc 
XtNlength 

XtNmappedWhen- 
Managed 
XtNorientation 

XtNscrollDCursor 
XtNscrollHCursor 

XtNscrollLCursor 
XtNscrollProc 
XtNscrollRCursor 
XtNscrollUCursor 
XtNscrollVCursor 

XtNsensitive 
XtNshown 
XtNthickness 

XtNthumb 
XtNtop 
XtNtranslations 

XtNwidth 
XtNx 
XtNy 

Pixel 
Pixmap 

Pixel 

Pixmap 
Dimension 
XtCallbackList 

Pixel 
Dimension 
XtCallbackList 
Dimension 

Boolean 

XtOrientation 

Cursor 
Cursor 

Cursor 
XtCallbackList 
Cursor 
Cursor 
Cursor 

Boolean 
float 
Dimension 

Pixmap 
float 
Translation- 
Table 
Dimension 
Position 
Position 

Default 

White 
None 

XtDefault- 
Foreground 
None 
NULL 

Black 
See below 
NULL 
None 

TRUE 

XtorientVertical 

XC sb down arrow 
_ 
XC sb h double 
_ 
arrow 
XC sb left arrow 
_ 
NULL 
XC sb right_arrow 
XC_sb_up_arrow 
XC sb v double 
_ 
arrow 
TRUE 
NULL 
14 

Gray 
NULL 
See below 

See below 
NULL 
NULL 

Description 

Window background color 
Window background pixmap 

Window border color 

Window border pixmap 
Width of button border 
Callbacks for xt De s t royWi dge t 

Thumb color 
Height of scroll bar 
Callback for thumb select 
Major dimension (height of 
XtorientVertical) 
V/hether XtMapWidget is auto- 
matic 
Orientation (vertical or horizon- 
tal) 
Cursor for scrolling down 
Idle horizontal cursor 

Cursor for scrolling left 
Callback for the slide region 
Cursor for scrolling right 
Cursor for scrolling up 
Idle vertical cursor 

Whether widget receives input 
Percentage the thumb covers 
Minor dimension (height if 
XtorientHorizontal) 
Thump pixmap 
Position on scroll bar 
Event-to-action translations 

Width of scroll bar 
x position of scroll bar 
y position of scroll bar 

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 Xt- 
Nwidth and XtNheight resources. In addition, you can use an alternative method that is 
independent of the vertical or horizontal orientation: 

X Toolkit Intrinsics Reference Manual 379 



Scrollbar (continued) Xt - Athena Widgets 

w Specifies the Scrollbar widget ID. 
t o/9 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. 
XtScrollbarThumb moves the visible thumb to position (0.0- 1.0)and length (0.0- 
1.0). Either top or shown 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, XtScrollbarSetThumb has no effect. 

382 X Toolkit Intrinsics Reference Manual 



Tem plate (continued) Xt - Athena Widgets 

#define XtNdrawingColorl 
#define XtNdrawingColor2 
#define XtNexposeCallback 

"drawingColorl" 
"drawingColor2" 
"exposeCallback" 

extern Pixel WindowColorl(/* Widget */); 
extern Pixel WindowColor2(/* Widget */); 
extern Font WindowFont(/* Widget */); 

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. 

Private Header File 
The private header file contains the complete declaration of the class and instance structures for 
the widget and any additional private dam that will be requid by anticipated subclasses of the 
widget. Information in the private header file is normally hidden om the application and is 
designed to be accessed only through oer public procedures, such as xt S e tva l ue s. 
The contents of the Template private header file, <XlllTemplateP.h>, are: 
#include <Xll/copyright.h> 
/* XConsortium: TemplateP.h,v 1.2 88/10/25 17:31:47 swick Exp $ */ 
/* Copyright Massachusetts Institute of Technology 1987, 1988 */ 
#ifndef _TemplateP_h 
#define _TemplateP_h 
#include "Template.h" 
/* include superclass private header file */ 
#include <Xll/CoreP.h> 
/* define unique representation types not found in <Xll/StringDefs.h> */ 

#define XtRTemplateResource 
typedef struct { 
int empty; 
} TemplateClassPart; 
typedef struct _TemplateClassRec { 
CoreClassPart core class; 
-- 
TemplateClassParttemplate_class; 
} TemplateClassRec; 
extern TemplateClassRec templateClassRec; 
typedef struct { 
/* resources */ 
char* resource; 
/* private state */ 
} TemplatePart; 

"TemplateResource" 

typedef struct _TemplateRec { 

386 X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets (continued) Tern plate 

CorePart core; 
TemplatePart template; 
} TemplateRec; 
#endif _TemplateP_h 
The private header file includes the priva header file of i superclass, theby exposing the 
entke internal sucture of the widget. It may not ways be advantageous to do this; your own 
prect development style will dictate the appropria level of detl to expose in each module. 
The Window widget needs to declare two fields in i instance sucture to hold the drawing 
colors, a source field for the font and a field for the expose and user input callback lists: 
typedef struct { 
/* resources */ 
Pixel color I; 
-- 
Pixel color 2; 
-- 
XFontStruct* font; 
XtCallbackList expose_callback; 
XtCallbackList input_callback; 
/* private state */ 
/* (none) */ 
} WindowPart; 

Widget Source File 
The source code file implemen the widget class ielf. The unique put of this file is the decla- 
ration and initialization of the widget class record sucture and the declaration of all resources 
and action routines added by the widget class. 
The contents of the Templa implementation file, <X11/Template.c>, are: 
#include <Xll/copyright.h> 
/* XConsortium: Template.c,v 1.2 88/10/25 17:40:25 swick Exp $ */ 
/* Copyright Massachusetts Institute of Technology 1987, 1988 */ 
#include <Xll/IntrinsicP.h> 
#include <Xll/StringDefs.h> 
#include "TemplateP.h" 
static XtResource resources[] = { 
#define offset(field) XtOffset(TemplateWidget, template.field) 
/* {name, class, type, size, offset, default_type, default_addr}, */ 
{ XtNtemplateResource, XtCTemplateResource, XtRTemplateResource, \\e 
sizeof(char*), offset(resource), XtRString, "default" }, 
#undef offset 
}; 
static void TemplateAction(/* Widget, XEvent*, String*, Cardinal* */); 
static XtActionsRec actions[] = 
( 
/* (name, procedure}, */ 

X Toolkit Intrinsics Reference Manual 387 



Tem plate (continued) Xt - Athena Widgets 

{"template", TemplateAction}, 
}; 
static char translations[] = 
" <Key>: template() \\en\\e 
" ; 
TemplateClassRec templateClassRec = { 
{ /* core fields */ 
/* superclass */ 
/* class name */ 
-- 
/* widget_size */ 
/* class initialize */ 
-- 
/* class_part_initialize */ 
/* class inited */ 
-- 
/* initialize */ 
/* initialize hook */ 
-- 
/* realize */ 
/* actions */ 
/* num actions */ 
-- 
/* resources */ 
/* num resources */ 
-- 
/* xrm class */ 
-- 
/* compress_motion */ 
/* compress_exposure */ 
/* compress_enterleave */ 
/* visible interest */ 
-- 
/* destroy */ 
/* resize */ 
/* expose */ 
/* set values */ 
-- 
/* set values hook */ 
-- -- 
/* set values almost */ 
-- -- 
/* get_values_hook */ 
/* accept_focus */ 
/* version */ 
/* callback_private */ 
/* tm table */ 
-- 
/* query_geometry */ 
/* display_accelerator */ 
/* extension */ 
}, 

{ /* template fields */ 
/* empty */ 
} 

}; 

(WidgetClass) &widgetClassRec, 
"Template", 
sizeof(TemplateRec), 
NULL, 
NULL, 
FALSE, 
NULL, 
NULL, 
XtInheritRealize, 
actions, 
XtNumber(actions), 
resources, 
XtNumber(resources), 
NULLQUARK, 
TRUE, 
TRUE, 
TRUE, 
FALSE, 
NULL, 
NULL, 
NULL, 
NULL, 
NULL, 
XtInheritSetValuesAlmost, 
NULL, 
NULL, 
XtVersion, 
NULL, 
translations, 
XtInheritQueryGeometry, 
XtInheritDisplayAccelerator, 
NULL 

WidgetClass templateWidgetClass = (WidgetClass)&templateClassRec; 

388 X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets (continued) Tem plate 

The resource list for the Window widget might look le the following: 
static XtResource resources[] = { 
#define offset(field) XtOffset(WindowWidget, window.field) 
/* {name, class, type, size, offset, default_type, default addr}, */ 
-- 
{ XtNdrawingColorl, 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 implemend by an action procedure that passes the event 
pointer as ca22_data. The action procedu is declared as: 
/* ARGSUSED */ 
static void InputAction(w, event, params, num_params) 
Widget w; 
XEvent *event; 
String *params;/* unused */ 
Cardinal *num_params;/* unused */ 

XtCallCallbacks(w, XtNcallback, (caddr t)event) ; 
-- 
} 
static XtActionsRec actions[] = 
{ 
/* {name, procedure}, */ 
{"input", InputAction}, 
}; 
and the default input binding will be to execute the input callbacks on KeyPress and 
ButtonPress: 
static char translations[] = 
" <Key>:input() \\en\\e 
<BtnDown>:input ( ) \\e 
In the class record declaration and initialization, the only field that is different from the Tem- 
plate is the expose procedure: 
/* ARGSUSED */ 
static void Redisplay(w, event, region) 
Widget w; 
XEvent *event; /* unused */ 
Region region; 

X Toolkit Intrinsics Reference Manual 389 



Text (continued) Xt - Athena Widgets 

XtselectParagraph 
XtselectPosition 
XtselectWord 

Selects the entire paragraph (delimited by newline characters). 
Selects the current pointer position. 
Selects whole words (delimited by Whitespace) as the pointer moves 
onto them. 

The deult 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. 

Translations and Actions 
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 
New Line 
newline-and-indent 
newline-and-backup 
newline 
Kill 
kill-word 
backward-kill-word 
kill-selection 

Delete 

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 
Miscellaneous 
redraw-display 
insert-file 
do-nothing 
Unkill 
unkill 
stuff 
insert-selection 

394 X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets (continued) Text 

Cursor Movement 

kill-to-end-of-line 
kill -to-end-of-paragraph 

Delete 

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: 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\ 
kill-word() \n\ 
delete-previous-word() \n\ 
backward-kill-word() \n\ 
beginning-of-file() \n\ 
end-of-file() \n\ 
forward-paragraph() \n\ 

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>O: 
Ctrl<Key>P: 
Ctrl<Key>V: 
Ctrl<Key>W: 
Ctrl<Key>Y: 
Ctrl<Key>Z: 
Meta<Key>F: 
Meta<Key>B: 
Meta<Key>I: 
Meta<Key>K: 
Meta<Key>V: 
Meta<Key>Y: 
Meta<Key>Z: 
:Meta<Key>d: 
:Meta<Key>D: 
:Meta<Key>h: 
:Meta<Key>H: 
:Meta<Key>\<: 
:Meta<Key>\>: 
:Meta<Key>]: 

X Toolkit Intrinsics Reference Manual 395 



Text (conhnued) Xt - Athena Widgets 

typedef long XtTextPosition; 
void XtTextSetSelection(w, left, right) 
Widget w; 
XtTextPosition left, right; 

where: 
left 
ri gh t 

Specifies the window ID. 
Specifies the character position at which the selection begins. 
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. 
To unhighlight previously highlighted text in a window, use XtTextUnset Select ion. 
void XtTextUnsetSelection(w) 
Widget w; 

To enable the application to get the character positions of the selected text, use XtText- 
GetSelectionPos. 

void XtTextGetSelectionPos(w, posl, pos2) 
Widget w; 
XtTextPosition *posl, *pos2; 

where: 
posl 

Specifies the window ID. 
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. 
To enable an application to replace text, use XtTextReplace. 
int XtTextReplace(w, start_pos, end_pos, text) 
Widget w; 
XtTextPosition start_pos, end_pos; 
XtTextBlock *text; 

where: 
W 
start_pos 
end_pos 
text 

Specifies the window ID. 
Specifies the starting character position of the text replacement. 
Specifies the ending character position of the text replacement. 
Specifies the text to be inserted into the file. 

398 X Toolkit Intrinsics Reference Manual 



Text (continued) Xt - Athena Widgets 

ArgList args; 
Cardinal 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 deal|ocate s text stng source, use Xt St ringSourceDest roy. 
void XtStringSourceDestroy (source) 
XtTextSource source; 
The source must not be in use by any widget or an error will result. 

402 X Toolkit Intrinsics Reference Manual 



 Xt - Athena Widgets 

VPaned 

Name 
vPanedWidgetClass -- geometry-managing widget for vertical tiles. 

Synopsis 
#include <Xll/StringDefs.h> 
#include <Xll/Intrinsic.h> 
#include <Xll/XawMisc.h> /* <Xll/Misc.h> in R2 */ 
#include <Xll/VPaned.h> 
widget = XtCreateWidget(widget, vPanedWidgetClass,... ); 

Class Hierarchy 
Core --> Composite --> Constraint --> VPaned 

Description 
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 constraJn on the other panes. With the default 
bindings, button I reshes the pane above the selected grip, button 3 resizes the pane below the 
selected grip and button 2 reposifions the border between two panes only. 

Resources 
When creating a VPaned widget instance, the following resources are retrieved from the argu- 
ment list or from the resource database: 

NalTle 

XtNbackground 
XtNbackground- 
Pixmap 
XtNbetweenCursor 

XtNborderColor 

Type 

Pixel 

Default 

XtDefault- 
Background 
None 

Pixmap 
Cursor 

Pixel 

Pixmap 
Dimension 

XtCallbackList 

Pixel 

XC sb left arrow 
-- 

XtDefault- 
Foreground 
None 

NULL 

Black 

XtNborderPixmap 
XtNborderWidth 
XtNdestroy- 
Callback 
XtNforeground 

Description 

Window background color 

Window background pixmap 

Cursor for changing the bound- 
ary between two panes 
Window border color 

Window border pixmap 
Border width (pixels) 
Callbacks for XtDestroy- 
Widget 
Pixel value for the foreground 
color 

X Toolkit Intrinsics Reference Manual 405 



VPaned (continued) Xt - Athena Widgets 

To delete an entire VPaned widget and all associated data structures, use XtDestroy- 
Widget and specify the widget ID of the VPaned widget. All the children of the VPaned 
widget are automatically destroyed at the same time. 

408 X Toolkit Intrinsics Reference Manual 



Table A-1. Alphabetical Listing of Functions (continued) 

Function 

XtApp ... 
AddActions 
AddConverter 
AddInput 
AddTimeOut 
AddWorkProc 
CreateShell 
Error 
ErrorMsg 
GetErrorDatabase 
GetErrorDatabaseText 
GetSelectionTimeout 
MainLoop 
NextEvent 
PeekEvent 
Pending 
ProcessEvent 
SetErrorHandler 
SetErrorMsgHandler 
SetSelectionTimeout 
SetWarningHandler 
SetWarningMsgHandler 
Warning 
WarningMsg 
XtArgsFunc 
XtArgsProc 
XtAugmentTranslations 
XtBuildEventMask 
XtCallAcceptFocus 
XtCallbackExclusive 
XtCallbackNone 
XtCallbackNonexclusive 
XtCallbackPopdown 
XtCallbackProc 
XtCallCallbacks 
XtCalloc 
XtCaseProc 
XtCheckSubclass 
XtClass 
XtCloseDisplay 
XtConfigureWidget 
XtConvert 
XtConvertCase 
XtConverter 

Description 

Declare an action table and register it with the Resource Manager. 
Register a new resource convener for an application. 
Register a new file as an input source for a given application. 
Invoke a procedure after a specified timeout. 
Register a work procedure for a given application. 
Create additional top-level widget. 
Call the installed fatal error procedure. 
Call the high-level fatal error handler. 
Obtain the error database. 
Obtain the error database text for an error or a warning. 
Get the current selection timeout value. 
Process input from a given application. 
Return next event from an application's input queue. 
Nondestructively examine the head of an application's input queue. 
Determine if there are any events in an application's input queue. 

Process one input event. 
Register a procedure to be 
Register a procedure to be 
Set the Intnsics selection 
Register a procedure to be 

called on fatal error conditions. 
called on fatal error conditions. 
timeout. 
called on nonfatal error conditions. 

Register a procedure to be called on nonfatal error conditions. 
Call the installed nonfatal error procedure. 
Call the installed high-level warning handler. 
Protopc set values hook method. 
Protopc procedure for get_values_hook method. 
Nondestructively merge new translations with widget's existing ones. 
Retrieve a widget's event mask. 
Call a widget's accept_focus procedure. 
Callback function to pop up a widget. 
Callback function to pop up a widget. 
Callback function to pop up a widget. 
Pop down a widget from a callback routine. 
Prototype callback procedure. 
Execute the procedures in a widget's callback list. 
Allocate an array and initialize elements to zero. 
Prototype procedure called to convert the case of keysyms. 
In DEBUG mode, verify a widget's class. 
Obtain a widget's class. 
Close a display and remove it from an application context. 
Move and/or resize widget. 
Convert resource type. 
Determine upper-case and lower-case versions of a keysym. 
Prototype of a resource convener procedure. 

412 X Toolkit Intrinsics Reference Manual 



Table A- 1. Alphabetical Listing of Functions (continued) 

Funcdon 

XtConvertSelectionProc 
XtCreate . . . 
ApplicationContext 
ApplicationShell 
ManagedWidget 
PopupShell 
Widget 
Window 
XtDatabase 
XtDestroy . . . 
ApplicationContext 
GC 
Widget 
XtDirectConvert 
XtDisownSelection 
XtDispatchEvent 
XtDisplay 
XtDisplayInitialize 
XtError 
XtErrorHandler 
XtErrorMsg 
XtErrorMsgHandler 
XtEventHandler 
XtExposeProc 
XtFree 
XtGeometryHandler 
XtGet ... 
ApplicationResources 
ErrorDatabase 
ErrorDatabaseText 
GC 
ResourceList 
SelectionTimeout 
SelectionValue 
SelectionValues 
Subresources 
Subvalues 
Values 
XtHasCallbacks 
XtInitialize 
XtInitProc 
XtInputCallbackProc 

Description 

Prototype procedure to return selection data 

Create an application context. 
Create an additional top-level widget. 
Create and manage a child widget. 
Create a pop-up shell. 
Create an instance of a widget. 
Create widget's working window. 
Obtain the resource database for a particular display. 

Destroy an application context and close its displays. 
Release 2 compatible function to free up read-only GCs. 
Destroy a widget instance. 
Perform resource conversion and cache result. 
Indicate that selection data is no longer available. 
Dispatch registered handlers for an event. 
Return the display pointer for the specified widget. 
Initialize a display and add it to an application context. 
Call the low-level fatal error handler. 
Prototype for low-level error and warning handlers. 
Call the high-level fatal error handler. 
Prototype for high-level error and warning handlers. 
Prototype procedure to handle input events. 
Prototype expose method used in Core widget class. 
Free an allocated block of storage. 
Prototype procedure to handle geometry requests. 

Update base-offset resource list (by application). 
Obtain the error database. 
Obtain the error database text for an error or a warning. 
Obtain a read-only, sharable GC. 
Retrieve default values for a resource list. 
Get the current selection timeout value. 
Obtain the complete selection data. 
Obtain selection data in multiple formats. 
Update base-offset resource list (by name or class). 
Copy from base-offset resource list to the argument list. 
Copy resources from a widget to the argument list. 
Determine the status of a widget's callback list. 
Initialize toolkit and display. 
Prototype initialize procedure for a widget class. 
Prototype procedure called to handle file events. 

Appendix A: Alphabetical and Group Summaries 413 



Table A- 1. Alphabetical Listing of Functions (continued) 

Function 

XtInstall . . . 
Accelerators 
AllAccelerators 

XtIsComposite 
XtIsConstraint 
XtIsManaged 
XtIsRealized 
XtIsSensitive 
XtIsShell 
XtIsSubclass 
XtKeyProc 
XtLoseSelectionProc 

XtMainLoop 
XtMakeGeometryRequest 
XtMakeResizeRequest 
XtMalloc 
XtManageChild 
XtManageChildren 
XtMapWidget 
XtMergeArgLists 
XtMoveWidget 
XtNameToWidget 
XtNew 
XtNewString 
XtNextEvent 
XtNumber 
XtOffset 
XtOpenDisplay 
XtOrderProc 

XtOverrideTranslations 
XtOwnSelection 
XtParent 
XtParse . . . 
AcceleratorTable 
TranslationTable 
XtPeekEvent 
XtPending 
XtPopdown 
XtPopup 
XtProc 
XtProcessEvent 

Description 

Install a widget's accelerators on another widget. 
Install all accelerators from a widget and its descendants onto a desti- 
nation. 
Test whether a widget is a subclass of the Composite widget class. 
Test whether a widget is a subclass of the Constraint widget class. 
Determine whether a widget is managed by its parent. 
Determine whether a widget has been realized. 
Check the current sensitivity state of a widget. 
Test whether a widget is a subclass of the Shell widget class. 
Determine whether a widget is a subclass of a class. 
Prototype procedure to translate a key. 
Prototype procedure called by the Intrinsics when another client 
claims the selection. 
Continuously process events. 
Request parent to change child's geometry. 
Request parent to change child's size. 
Allocate storage. 
Add a widget to its parent's list of managed children. 
Add widgets to their parent's list of managed children. 
Map a widget to its display. 
Merge two ArgList structures. 
Move a widget on the display. 
Translate a widget name to a widget instance. 
Allocate storage for one instance of a data type. 
Copy an instance of a string. 
Return next event from input queue. 
Determine the number of elements in a fixed-size array. 
Determine the byte offset of a field within a structure. 
Open, initialize, and add a display to an application context. 
Prototype procedure for ordering the children of composite widget 
instances. 
Merge new translations, overwriting widget's existing ones. 
Indicate that selection data is available. 
Return the parent widget for the specified widget. 

Compile an accelerator table into its internal representation. 
Compile a translation table into its internal representation. 
Nondestructively examine the head of an application's input queue. 
Determine if there are any events in an application's input queue. 
Unmap a pop-up shell. 
Map a pop-up shell. 
Prototype procedure to initialize data for a widget class. 
Process one input event. 

414 X Toolkit Intrinsics Reference Manual 



Boolean 
A typedef from <X11/lntrinsic.h> used to indicate TRUE (1) or FALSE (0). Use either the 
symbols TRUE or FALSE, defined in <X11/Xlib.h> or TRUE or FALSE, defined in 
<X11/Intrinsic.h>. 
Cardinal 
A typedef from <Xll/Intrinsic.h> used to specify any unsigned numeric value. 
Dimension 
A typedef from <X]]/Intrinsic.h> used to specify window sizes. The Dimension data 
type was introduced in R3 to increase portability. R2 applications that specified dimen- 
sions as int should use Dimension instead. 
Display 
A structure defined in <Xll/Xlib.h> that contains information about the display the pro- 
gram is running on. Display structure fields should not be accessed directly; Xlib pro- 
vides a number of macros to return essential values. In Xt, a pointer to the current 
Display is returned by a call to XtDisplay. XtOpenDisplay can be used to 
explicitly open more than one Display. 
EventMask 
A typedef from <Xllllntrinsic.h> used to specify which events are selected by an event 
handler. Specify the value as the bitwise OR of any of the following symbols defined in 
<X111X.h> : 

Event Mask Symbol 

NoEventMask 
KeyPressMask 
KeyReleaseMask 
ButtonPressMask 
ButtonReleaseMask 
EnterWindowMask 
LeaveWindowMask 
PointerMotionMask 
PointerMotionHintMask 
ButtonlMotionMask 
Button2MotionMask 
Button3MotionMask 
Button4MotionMask 
Button5MotionMask 
ButtonMotionMask 
KeymapStateMask 

ExposureMask 

VisibilityChangeMask 
StructureNotifyMask 
ResizeRedirectMask 
SubstructureNotifyMask 

Circumstances 

No events 
Keyboard down events 
Keyboard up events 
Pointer button down events 
Pointer button up events 
Pointer window entry events 
Pointer window leave events 
All pointer motion events 
Fewer pointer motion events 
Pointer motion while button 1 down 
Pointer motion while button 2 down 
Pointer motion while button 3 down 
Pointer motion while button 4 down 
Pointer motion while button 5 down 
Pointer motion while any button down 
Any keyboard state change on EnterNotify, 
LeaveNotify, Focus In, or FocusOut 
Any exposure (except GraphicsExpose and 
NoExpose) 
Any change in visibility 
Any change in window configuration 
Redirect resize of this window 
Notify about reconfiguration of children 

424 X Toolkit Intrinsics Reference Manual 



struct XDlsplay *display;l* 
Window root; /* 
int width, height; /* 
int mwidth, mheight; /* 
int ndepths; /* 
Depth *depths; /* 
int root_depth; /* 
Visual *root visual; /* 
GC default_gc; /* 

Colormap cmap; /* 
unsigned long white_pixel; 
unsigned long black_pixel;/* 
int max_maps, min_maps; /* 
int backing_store; /* 
Bool save unders; 
long root_input_mask; /* 
Screen; 

back pointer to display structure */ 
root window ID */ 
width and height of screen */ 
width and height of in millimeters */ 
number of depths possible */ 
llst of allowable depths on the screen */ 
bits per pixel */ 
root visual */ 
GC for the root root visual */ 
default colormap */ 

white and black pixel values */ 
max and min colormaps */ 
Never, WhenMapped, Always */ 

initial root input mask */ 

The xtScreen macro can be used in Xt to return the current screen. 
String 
A typedef for c h a r * 
An unsigned long value containing a time value in milliseconds. The constant 
CurrentTime is interpreted as the time in milliseconds since the server was started. 
The Time data type is used in event structures and as an argument to XtAddTimeOut. 
Widget 
A sucture returned by calls to create a widget such as xtInitialize, XtCreate- 
widget, XtCreateManagedwidget, and XtCreatePopupShell. The mem- 
bers of this structure should not be accessed dkecdy from applications; they should 
regard it as an opaque pointer. Type widget is actually a pointer to a widget instance 
structure. Widget code accesses instance variables from this structure. 
Window 
A structure mazined by the server, and known on the client side only by an integer ID. 
In Xt, a widget's window can be returned by the XtWindow macro. Given the window, 
the corresponding widget can be returned by XtWindowToWidget. 
XEvent 
A union of all flrly event structures. The fst member is always the type, so it is pos- 
sible to branch on the type, and do event-specific processing in each branch. For more 
information on the individual event structures, see Appendix C, Event Reference. 
XGCValues 
A structure defined in <XlllXlib.h> that is used to set the values in a Graphics Context 
using the XtGetGC function, or the Xlib functions XCreateGC, XChangeGC, or 
XGetGCValues. 
typedef struct { 
int function; /* logical operation */ 
unsigned long plane_mask; /* plane mask */ 
unsigned long foreground; /* foreground pixel */ 
unsigned long background; /* background pixel */ 

426 X Toolkit Intfinsics Reference Manual 



int line width; 
-- 
int line_style; 

int cap_style; 

int join_style; 
int fill_style; 

int fill rule; 
-- 
int arc mode; 
-- 
Pixmap tile; 
Pixmap stipple; 
int ts x origin; 
int ts y origin; 
Font font; 
int subwindow mode; 
-- 

/* line width / 
/* LineSolld, LineOnOffDash, 
LineDoubleDash */ 
/* CapNotLast, CapButt, 
CapRound, CapProjecting */ 
/* JoinMiter, JoinRound, JoinBevel */ 
/* FillSolid, FillTiled, 
FillStippled, FillOpaqueStippled */ 
/* EvenOddRule, WindingRule */ 
/* ArcChord, ArcPieSllce */ 
/* pixmap for tiling operations */ 
/* 1 plane plxmap for stippling */ 
/* offset for tile or stipple operations */ 

/* default text font for text operations */ 
/* ClipByChildren, IncludeInferiors */ 

Bool graphics_exposures; /* should exposures be generated? */ 
int clip x origin; /* origin for clipping */ 
int clip y origin; 
Pixmap clip_mask; /* bitmap clipping; other calls for rects */ 
int dash offset; /* patterned/dashed line information */ 
-- 
char dashes; 
} XGCValues; 
For more information on e meaning and use of each of e members, see Chapter 5, The 
Grapcs Conte, in Volume One, Xlib Programmg Manual. The second gument of 
XgGegGC is a mask that specifies whh members of e structure e being t. See 
XgGCMask below for details. 
XrmDatabase 
A poter to an inrnal resource manager damtype. Members of is structure should not 
be cesd dkecdy. An XrmDatabase can be returned by e Xt c XtDatabase 
(a resoce damba) or XtGetE rro rDat abase (an eor mesge database). 
XrmOptionDescRec 
A sucture ud to define command le opfiom, pd to XtInitialize, Xt- 
DisplayInitialize, or XtOpenDisplay. The structure is defined  follows in 
<X111Xresource.h> : 
typedef struct { 
char *option; /* Option abbreviation in argv */ 
char *specifier;/* Resource specifier */ 
XrmOptionKind argKind; /* Which style of option it is */ 
caddr t value; /* Val to provide if XrmoptionNoArg */ 
} XrmOptionDescRec, *XrmOptionDescList; 
The vMue for e argKind element is specified by one of e foHowg enum vMues, 
defined in e me fde: 
typedef enum { 
XrmoptionNoArg, /* Value specified in OptionDescRec.value */ 
XrmoptionIsArg, /* Value is the option string itself */ 
XrmoptionStickyArg,/* Value immediately follows option */ 
XrmoptionSepArg, /* Value is next argument in argv */ 
XrmoptionResArg, /* Resource and value in next arg in argv */ 
XrmoptionSkipArg, /* Ignore this opt and next arg in argv */ 

Appendix B: X TooAkit Data Types 427 



XrmoptionSkipLine /* Ignore this opt and rest of argv */ 
} XrmOptionKind; 

XrmOptionKind 
SeeXrmOptionDescRec. 

XrmValue 
A structure defined in <XlllXresource.h>, used in XtConvert and other resource con- 
version routines. 

typedef struct { 
unsigned int size; 
caddr t addr; 
} XrmValue, *XrmValuePtr; 

XrmValuePt r 
See XrmVa lue. 

XtAccelerators 
A pointer to an opaque internal type, a compiled accelerator table. A pointer to an Xt- 
Accelerators sUmcture is returned by a cl to XtParseAcceleratorTable. 
Usually, the compiled accelerator table is produced automatically by resource conversion 
of a string accelerator table stored in a resource file. 
XtActionList 
A typedef for _XtActionsRec, defined as follows in <X111Intrinsic.h>: 
typedef struct XtActionsRec *XtActionList; 
-- 
typede f struct XtActionsRec { 
-- 
char *string; 
XtActionProc proc; 
} XtActionsRec; 
Actions are added by cIs to XtAddActions or XtAppAddActions. By conven- 
tion, the string and the function name are identical, except that the function name begins 
with an upper-case letter, as in the example: 
static XtActionsRec two_quits [] = { 
{"confirm", Confirm}, 
{"quit", Quit}, 
}; 
This mapping from strings to function pointers is necessary to allow translation tables to 
be specified in resource t-des, which are made up entirely of strings. 
XtActionProc 
The typedef for an action procedure. See XtActionProc(2) for defils. 
XtAddressMode 
An enumerated type that specifies the possible values for the address mode field of 
an XtConvertArgRec. See XtConvertArgRec below for details. 
XtAppContext 
A pointer  an internal structure used to hold data specific to a particular application 
context. An XtAppContext can be returned by a call to 

428 X rooR Intnsics Reference Manual 



XtCreateApplicationContext. The application Context being used by a widget 
can be returned by XtWidgetToApplicationContext. All standard Xt routines 
use a default application context; routines for handling explicit application contexts 
almost all have names containing the string App. 
XtCallbackLi st 
A structure defined as follows in <X111Intrinsic.h>: 
typedef struct XtCallbackRec* XtCallbackList ; 
typedef struct XtCallbackRec { 
-- 
XtCallbackProc callback; 
caddr t closure; 
} XtCallbackRec; 
An XtCallbackList is statically defined just after the callback function itself is 
declared or defined. Then the callback list is used to set a callback resource with any of 
the calls lhat set resources, including XtCreateWidget. In most documentation, the 
closure member is refecd to as client_data. In application code, when Xt- 
AddCallback and XtRemoveCallback are used, an XtCallbackList is not 
required. 
XtCallbackProc 
The typedef for callback functions. See XtCallbackProc(2) for details. 
XtCallbackStatus 
An enumerated type that defines the return values from XtHasCallbacks: 
typedef enum { 
XtCallbackNoList, /* Callback resource doesn't exist */ 
XtCallbackHasNone, /* Resource exists, but no callbacks on it */ 
XtCallbackHasSome /* Resource exists, and callbacks 
are registered for it */ 
} XtCallbackStatus; 

XtConvertArgList 
A structure ud in calls to XtAddConverter  speci how the convener will access 
the values m be convened. The structure is defined as llows in <Xllntrinsic.h>: 
typedef struct ' 
XtAddressMode address mode; 
caddr t address id; 
Cardinal size; 
} XtConvertArgRec, *XtConvertArgList; 
The enumered type XtAddressMode specifies the possible vues r the 
address mode field, which consols how the address id field should be inter- 
preted. 
typedef enum { 
XtAddress, /* address */ 
XtBaseOffset, /* offset */ 
XtImmediate, /* constant */ 
XtResourceString, /* resource name string */ 
XtResourceQuark /* resource name quark */ 
} XtAddressMode; 

Appendix B: X Toolkit Data Types 429 



By specifying the address mode as XtBaaeOffaet, you can use xtoffset to find 
the appropriate widget resource, much as you do in a resource list. 
XtConvertArgRec 
See XtConvertArgList. 
XtConverter 
The typedef for resource converters. See XtConverter(2) for details. 
XtConvert SelectionProc 
The typedef for the selection conversion procedure registered by a call to xtown- 
Selection. See xtConvertSelectionproc(2) for derails. 
XtErrorHandler 
The typedef for low-level error or warning handle/s. See XtErrorHandler(2) for 
details. 
XtErrorMsgHandler 
The typedef for high-level error or warning message handlers. See XtErrorMsg- 
Handler(2) for details. 
XtEventHandler 
The typedef for event handlers. See XtEventHandler(2) for details. 
XtGCMask 
A mask used in calls to XtGetGC that indicates which fields in the XGCValues struc- 
ture are to be used. The mask consists of a bitwise OR of the following symbols: 

Member 

function 
plane_mask 
foreground 
background 
line width 
line_style 
cap_style 
Join_style 
fill_style 
fill rule 
tile 

stipple 
ts x origin 
ts_y_origin 
font 

subwindow mode 
graphlcs_exposures 
cllp x origin 
clip_y_origin 
cllp_mask 

Nhsk 

GCFunction 
GCPlaneMask 
GCForeground 
GCBackground 
GCLineWidth 
GCLineStyle 
GCCapStyle 
GCJoinStyle 
GCFillStyle 
GCFilIRule 
GCTile 

GCStipple 
GCTileStipXOrigin 
GCTileStipYOrigin 
GCFont 

GCSubwindowMode 
GCGraphicsExposures 
GCClipXOrigin 
GCClipYOrigin 
GCCllpMask 

Default 

GXcopy 
all l's 
o 
1 
o 
LineSolid 
CapButt 
JoinMiter 
FillSolid 
EvenOddRule 
pixmap f'dled with 
foreground pixel 
pixmap f'dled with l's 
0 
0 
(implementation 
dependent) 
ClipByChildren 
TRUE 
0 
0 
None 

430 X Toolkit Intrinsics Reference Manual 



XtWorkProc 
The typedef for the work procedure registered by a call to XtAddWorkProc. See xt- 
wo rkP roc(2) for details. 
XtWorkProcId 
The unique identifier returned by a call to XtAddWorkProc and used as an argument 
in XtRemoveWorkProc. 

434 X Toolkit Intrinsics Reference Manual 



C 
Event Reference 

This appendix describes each event in detail. It covers how the event is selected, what trans- 
lation table symbols are valid for each event type, when each event occurs, the information 
contained in each event structure, and the side effects of the event, if any. Each event is 
described on a separate reference page. 

Table C-1 lists each event mask, its associated event types, and the associated structure defi- 
nition. See Chapter 7, Events, in Volume One, Xlib Programming Manual, for more informa- 
tion on events. See also Chapter 7, Events, Translations, and Accelerators, in Volume Four, 
X Toolkit Intrinsics Programming Manual. 

Table C-1. Event masks, event types, and event structures 

Event Mask 

KeyPressMask 
KeyReleaseMask 
ButtonPressMask 

ButtonReleaseMask 

OwnerGrabButtonMask 

KeymapStateMask 
PointerMotionMask 
PointerMotionHintMask 
ButtonMotionMask 
ButtonlMotionMask 
Button2MotionMask 
Button3MotionMask 
Button4MotionMask 
Button5MotionMask 

EnterWindowMask 

LeaveWindowMask 

FocusChangeMask 

Event Type 

KeyPress 
KeyRelease 
ButtonPress 
ButtonRelease 
a 
KeymapNotify 
MotionNotify 

EnterNotify 
LeaveNotify 
FocusIn 

Structure 

XKeyPressedEvent 
XKeyReleasedEvent 
XButtonPressedEvent 
XButtonReleasedEvent 
a 
XKeymapEvent 
XPointerMovedEvent 

XEnterWindowEvent 
XLeaveWindowEvent 
XFocusInEvent 

Appendix C: Event Reference 435 



Table C- 1. Event Masks, Event Types, and Event Structures (continued) 

Event Mask 

ExposureMask 
(selected in GC by 
graphics_expose membeO 
ColormapChangeMask 
PropertyChangeMask 
VisibilityChangeMask 
ResizeRedirectMask 
StructureNotifyMask 

SubstructureNotifyMask 

SubstructureRedirectMask 

Event Type 

FocusOut 
Expose 
GraphicsExpose 
NoExpose 
ColormapNotify 
PropertyNotify 
VisibilityNotify 
ResizeRequest 
CirculateNotify 
ConfigureNotify 
DestroyNotify 
GravityNotify 
MapNotify 
ReparentNotify 
UnmapNotify 
CirculateNotify 
ConfigureNotify 
CreateNotify 
DestroyNotify 
GravityNotify 
MapNotify 
ReparentNotify 
UnmapNotify 
CirculateRequest 

Structure 

XFocusOutEvent 
XExposeEvent 
XGraphicsExposeEvent 
XNoExposeEvent 
XColormapEvent 
XPropertyEvent 
XVisibilityEvent 
XResizeRequestEvent 
XCirculateEvent 
XConfigureEvent 
XDestroyWindowEvent 
XGravityEvent 
XMapEvent 
XReparentEvent 
XUnmapEvent 
XCirculateEvent 
XConfigureEvent 
XCreateWindowEvent 
XDestroyWindowEvent 
XGravityEvent 
XMapEvent 
XReparentEvent 
XUnmapEvent 
XCirculateRequestEvent 

(always selected) 
(always selected) 
(always selected) 
(always selected) 
(always selected) 

ConfigureRequest 
MapRequest 
MappingNotify 
ClientMessage 
SelectionClear 
SelectionNotify 
SelectionRequest 

XConfigureRequestEvent 
XMapRequestEvent 
XMappingEvent 
XClientMessageEvent 
XSetSelectClearEvent 
XSelectionEvent 
XSelectionRequestEvent 

436 X Toolkit Intrnsics Reference Manual 



Meaning of Common Structure Elements 

Example C-1 shows the XEvent union and a simple event structure that is one member of 
the union. Several of the members of this structure are present in nearly every event struc- 
ture. They are described here before we go into the event-specific members (see also Section 
8.2.2 in Volume One, Xlib Programming Manual). 

Examp C- 1. XEvent unn and XAnyEvent structure 
typedef union XEvent { 
int type; /* must not be changed; first member */ 
XAnyEvent xany; 
XButtonEvent xbutton; 
XCirculateEvent xcirculate; 
XCirculateRequestEvent xcirculaterequest; 
XCllentMessageEvent xclient; 
XColormapEvent xcolormap; 
XConfigureEvent xconfigure; 
XConflgureRequestEvent xconfigurerequest; 
XCreateWindowEvent xcreatewindow; 
XDestroyWindowEvent xdestroywindow; 
XCrossingEvent xcrossing; 
XExposeEvent xexpose; 
XFocusChangeEvent xfocus; 
XNoExposeEvent xnoexpose; 
XGraphicsExposeEvent xgraphicsexpose; 
XGravityEvent xgravity; 
XKeymapEvent xkeymap; 
XKeyEvent xkey; 
XMapEvent xmap; 
XUnmapEvent xunmap; 
XMappingEvent xmapping; 
XMapRequestEvent xmaprequest; 
XMotionEvent xmotion; 
XPropertyEvent xproperty; 
XReparentEvent xreparent; 
XResizeRequestEvent xresizerequest; 
XSelectlonClearEvent xselectionclear; 
XSelectionEvent xselection; 
XSelectionRequestEvent xselectionrequest; 
XVisibilityEvent xvisibility; 
} XEvent; 
typedef struct { 
int type; 
unsigned long serial;/* # of last request processed by server */ 
Bool send event; /* TRUE if this came from SendEvent request */ 
Display *display; /* display the event was read from */ 
Window window; /* window on which event was requested in 
* event mask */ 
} XAnyEvent; 

Appendix C: Event Reference 437 



xcllent (continued) ClientMessage 

format Specifies the format of the property specified by rues sage_type. This will be on 
of the values 8, 16, or 3 2. 

X Toolkit Intrinsics Reference Manual 445 



ConflgureNotlfy (continued) xconfigure 

above 

If this member is None, then the window is on the bottom of the stack with respect 
to its siblings. Otherwise, the window is immediately on top of the specified sib- 
ling window. 

override redirect 
The override_redirect a[L6bute of the reconfigured window. If TRUE, it 
instates at the c|ient wants ds window to be immune to interception by the 
window manager of configuration requests. Window managers nonn1|y shou|d 
inore hs event if override_redirect is TRUE. 

448 X Toolkit Intrinsics Reference Manual 



ConfigureRequest (continued) xconfigurerequest 

width, height 
The requested width and height in pixels for the window. 

border width 
The requested border width for the window. 

above 

None, Above, Below, TopIf, BottomIf, or Opposite. Spifies the sibHng 
window on top of which the specified window should be placed. If this member 
has the constant None, then the specified window should be placed on the bottom. 

Notes 
The geometry is derived from the XConfigureWindow request that triggered the event. 

450 X Toolkit Intrinsics Reference Manual 



CreateNotify (continued) xcreatewindow 

Notes 
For descriptions of these members, see the XCreateWindow function and the XSet- 
WindowAtt ributes sucture. 

452 X Toolkit Intrinsics Reference Manual 



xfocus (continued) Focusln, FocusOut 

detail 

The det a il member identifies the relationship between the window that receives 
the event and the origin and destination windows. It will be described in detail 
after the description of which windows get what types of events. 

Notes 
The keyboard focus is a window that has been designated as the one to receive all keyboard 
input irrespective of the pointer position. Only the keyboard focus window and its descendants 
receive keyboard events. By default, the focus window is the root window. Since all windows 
are descendants of the root, the pointer controls the window that receives input. 

Most window managers allow the user to set a focus window, to avoid the problem where the 
pointer sometimes gets bumped into the wrong window and your typing doesn't go to the 
intended window. If the pointer is pointing at the root window, all typing is usually lost since 
there is no application for this input to propagate to. Some applications may set the keyboard 
focus so that they can get all keyboard input for a given period of time, but this practice is not 
encouraged. 
Focus events are used when an application wants to act differently when the keyboard focus is 
set to another window or to itself. FocusChangeMask is used to select FocusIn and 
FocusOut events. 

When a focus change occurs, A FocusOut event is delivered to the old focus window and a 
Focus In event is delivered to the window which receives the focus. Windows in between in 
the hierarchy are virtually crossed and receive one focus change event each depending on the 
relationship and direction of transfer between the origin and destination windows. Some or all 
of the windows between the window containing the pointer at the time of the focus change and 
that window's root window can also receive focus change events. By checking the detail 
member of Focus Tn and FocusOut events, an application can tell which of its windows can 
receive input. 
The detail member gives clues about the relationship of the event receiving window to the 
origin and destination of the focus. The detail member of FocusOut and Focus In events 
is analogous to the detail member of LeaveNotify and EnterNotify events, but with 
even more permutations to make life complicatexl. 

Virtual Focus Crossing and the detail Member 
We will now embark on specifying the types of events sent to each window and the detail 
member in each event, depending on the relative position in the hierarchy of the origin window 
(old focus), destination window (new focus), and the pointer window (window containing 
pointer at time of focus change). Don't even try to figure this out unless you have to. 

X Toolkif Intrinsics Reference Manual 463 



Focusln, FocusOut (continued) xfocus 

Table C-4 shows the event types generated by a focus transition from window A to window B 
when window C is the least common ancestor of A and B, and P is the window containing the 
pointer. This table includes most of the events generated, but not all of them. It is quite pos- 
sible for a single window to receive more than one focus change event from a single focus 
change. 
Table C-4. Focusln and FocusOut Events and Window Relationship 

FocusOut 

Origin window (A) 
Windows between A and B exclusive if 
A is inferior 
Windows between A and C exclusive 
Root window on screen of origin if dif- 
ferent from screen of destination 
Pointer window up to but not including 
origin window if pointer window is 
descendant of origin 
Pointer window up to and including 
pointer window's root if transfer was 
from PointerRoot 

FocusIn 

Destination window (B) 
Windows between A and B exclusive if 
B is inferior 
Windows between B and C exclusive 
Root window on screen of destination if 
different from screen of origin 
Pointer window up to but not including 
destination window if pointer window is 
descendant of destination 
Pointer window up to and including 
pointer window's root if transfer was to 
PointerRoot 

Table C-5 lists the detail members in events generated by a focus transition from window A 
to window B, with P being the window containing the pointer. 

Table C-5. Event detail Member and Window Relationship 

detail]ag 

NotifyAncestor 
NotifyInferior 
NotifyVirtual 

NotifyNonlinear 

NotifyNonlinearVirtual 

Window Delivered To 

Origin or destination when either is descendant. 
Origin or destination when either is ancestor. 
Windows between A and B exclusive if either is 
descendant. 

Origin and destination when A and B are two or more 
windows distant from least common ancestor C. 

Windows between A and C exclusive and between B 
and C exclusive when A and B have least common 
ancestor C. Also on both root windows if A and B 
are on different screens. 

464 X Toolkit Intrinsics Reference Manual 



KeyPress, KeyRelease (continued) xkey 

Keyboard events are analogous to button events, though of course there are many more keys 
than buttons, and the keyboard is not automatically grabbed between press and release. 
All the structure members have the same meaning as described for ButtonPress and 
ButtonRelease events except that button is replaced by keycode. 

474 X Toolkit Intn'nsics Reference Manual 



VlslbllltyNotlfy (continued) xvislbility 

Table C-6. The State Element of the XVisibilityEvent Structure 

Visibility Status Before 

Partially obscured, fully 
obscured, or not view- 
able 
Viewable and com- 
pletely unobscured, or 
not viewable 
Viewable and com- 
pletely unobscured, or 
viewable and partially 
obscured, or not view- 
able 

Visibility Status After 

Viewable and com- 
pletely unobscured 

Viewable and partially 
obscured 

Viewable and partially 
obscured 

State Member 

VisibilityUnobscured 

VisibilityPartially- 
Obscured 

VisibilityPartially- 
Obscured 

490 X Toolkit Intn'nsics Reference Manual 



translationParseError 
showLine 
parseError 
parseString 
typeConversionError 
noConverter 
versionMmatch 
widget 
wrongParameters 
cvtIntToBool 
cvtIntToBoolean 
cvtIntToFont 
cvtIntToPixel 
cvtIntToPixmap 
cvtIntToShort 
cvtStringToBool 
cvtStringToBoolean 
cvtStringToDisplay 
cvtStringToFile 
cvtStringToInt 
cvtStringToShort 
cvtStringToUnsignedChar 
cvtXColorToPixel 

... found while parsing "'%s" 
Translation table syntax error:. %s 
Missing "'.LP 

No type converter registered for "%s'" to "%s" conversion 

Widget class %s version mismatch: widget %d vs. inu'insics %d 

Integer-to-Bool conversion needs no extra arguments 
Integer-m-Boolean conversion needs no extra arguments 
Integer-to-Font conversion needs no extra arguments 
Integer-to-Pixel conversion needs no extra arguments 
Integer-to-Pixmap conversion needs no extra arguments 
Integer-m-Short conversion needs no extra arguments 
String-to-Bool conversion needs no extra arguments 
String-to-Boolean conversion needs no extra arguments 
String-to-Display conversion needs no extra arguments 
String-to-File conversion needs no extra arguments 
Suing-m-Integer conversion needs no extra arguments 
String-to-Integer conversion needs no extra arguments 
Suing-m-Integer conversion needs no extra arguments 
Color-to-Pixel conversion needs no extra arguments 

Appendix D: Standard Errors and Warnings 495 



F 
Translation Table Syntax 

Notation 

Syntax is specified in EBNF notation with the following conventions: 
[ a ] Means either nothing or "a" 
{ a } Means zero or more occurrences of "a" 
All terminals are enclosed in double quotation masks ( .... ). Informal descriptions are 
enclosed in angle brackets (< >). 

Syntax 

The translation table file has the following syntax: 

translationTable = [directive ] { production } 
directive = { "#replace" I "#override" I "#augment" } 'Nn" 
production = lhs ":" rhs 'Nn" 
lhs = (event I keyseq ) { "," (event I keyseq) } 
keyseq =' ..... keychar {keychar} ...... 
keychar = [ ..... I "$" I '" ] <ISO Latin 1 character> 
event = [modifier_list] "<"event_type">" [ "(" count["+"] ")" ] {detail} 
modifier_list = (["!" I ":"] {modifier} )] "None" 
modifier = [ ..... ] modifier_name 
count = ("1" I "2" 1"3" I "4" ] ...) 
modifier_name = "@" <keysym> I <see ModifierNames table below> 
event_type = <see Event Types table below> 
detail = <event specific details> 
rhs = { name "(" [params] ")" } 
name = namechar { namechar } 
namechar = { "a"-"z" I "A"-"Z" I "0"-"9" I "$" I "_" } 
params = string {"," string}. 
string = quoted_string I unquoted_string 

Appendix F: Translation Table Syntax 499 



The supported abbreviations are listed in Table F-3. 

Table F-3. Modifier Key Abbreviations 

Abbreviation 

Ctrl 
Meta 
Shift 
BtnlDown 
BtnlUp 
Btn2Down 
Btn2Up 
Btn3Down 
Btn3Up 
Btn4Down 
Btn4Up 
Btn5Down 
Btn5Up 
BtnMotion 
BtnlMotion 
Btn2Motion 
Btn3Motion 
Btn4Motion 
Btn5Motion 

Meaning 

KeyPress with conol modifier 
KeyPress with meta modifier 
KeyPress with shift modifier 
ButtonPress with Btnl detail 
ButtonRelease with Btnl detail 
ButtonPress with Btn2 detail 
ButtonRelease with Btn2 detail 
ButtonPress with Btn3 detail 
ButtonRelease with Btn3 detail 
ButtonPress with Btn4 detail 
ButtonRelease with Btn4 detail 
ButtonPress with Btn5 detail 
ButtonRelease with Btn5 detail 
MotionNotify with any button modifier 
MotionNotify with Buttonl modifier 
MotionNotify with Button2 modifier 
MotionNotify with Button3 modifier 
MotionNotify with Buon4 m0fier 
MotionNotify with Buon5 m0fier 

The detail field is event-specific and normally corresponds to the detail field of an 
XEvent, for example, <Key>A. If no deta il field is specified, then ANY is assumed. 

A keysym can be specified as any of the standard keysym names, a hexadecimal number pre- 
fixed with Ox or OX, an octal number prefixed with 0, or a decimal number. A keysym 
expressed as a single digit is interpreted as the corresponding Latin 1 keysym. For example, 
0 is the keysym XK_0. Other single character keysyms are treated as literal constants from 
Latin 1, for example, ! is treated as 0x21. Standard keysym names are as defined in 
<Xll/keysymdefh> with the XK_ prefix removed. (See Appendix H, Keysyms, in Volume 
Two, Xlib Reference Manual.) 

Appendix F: Translation Table Syntax 503 



Canonical Representation 

Every translation table has a unique, canonical text representation. This representation is pas- 
sed to a widget's displa._aceelerat:or method to describe the accelerators installed 
on that widget. The table below shows the canonical representation of a translation table file. 
(See also the section on "Syntax" earlier in this appendix.) 

translationTable 
production 
lhs 
event = 
modifier_list = 
modifier = 
count = 
modifier_name = 
event_type = 
detail = 
rhs = 
name = 
namechar -- 
params -- 
string - 
quoted_string 
The canonical modifier names are: 

= { production } 
= lhs ":" rhs 
event { "," event } 
[modifier__st] "<"evenUtype">" ["C count["+"] ")" ] {detail} 
["!" I ":"] {modifier} 
[ ..... ] modifier_name 
C1" 1"2" I "3" I "4" I ...) 
"@" <keysym> ] <see canonical modifier names below> 
<see canonical event types below> 
<event specific details> 
{ name "C [params] ")" } 
namechar { namechar } 
{ "a"-"z" I "A"-"Z" I "0"-"9" I "$" I "_" } 
string {"," string}. 
quoted_string 
...... {<Latin 1 character>} ...... 

Buttonl Modl 
Button2 Mod2 
Button3 Mod3 
Button4 Mod4 
Button5 Mod5 

The canonical event types are: 

DestroyNotify 
EnterNotify 
Expose 
FocusIn 
FocusOut 
GraphicsExpose 
GravityNotify 
KeymapNotify 

ButtonPress 
ButtonRelease 
CirculateNotify 
CirculateRequest 
ClientMessage 
ColormapNotify 
ConfigureNotify 
ConfigureRequest 
CreateNotify 

Ctrl 
Shift 
Lock 

KeyPress 
KeyRelease 
LeaveNotify 
MapNotify 
MappingNotify 
MapRequest 
MotionNotify 
NoExpose 

PropertyNotify 
ReparentNotify 
ResizeRequest 
SelectionClear 
SelectionNotify 
SelectionRequest 
UnmapNotify 
VisibilityNotify 

504 X Toolkit Inttnsics Reference Manual 



G 
StringDefs.h Header File 

This appendix lists the contents of the StringDefs.h header f'de. The contents are classified 
by resource names, class types, representation types, and constants. 

Table G-1. Resource Names 

Resource Name 

XtNaccelerators 
vXtNallowHoriz 
XtNallowVert 
XtNancestorSensitive 
XtNbackground 
XtNbackgroundPixmap 

Value 

"accelerators" 
"allowHoriz" 
"allowVert" 
"ancestorSensitive" 
"background" 
"backgroundPixmap" 

XtNborderColor 
XtNborder 
XtNborderPixmap 
XtNborderWidth 
XtNcallback 
XtNcolormap 
XtNdepth 
XtNdestroyCallback 
XtNeditType 
XtNfont 
XtNforceBars 
XtNforeground 
XtNfunction 
XtNheight 
XtNhSpace 
XtNindex 
XtNinnerHeight 
XtNinnerWidth 
XtNinnerWindow 
XtNinsertPosltion 
XtNinternalHelght 

"borderColor" 
"borderColor" 
"borderPixmap" 
"borderWidth" 
"callback" 
"colormap" 
"depth" 
"destroyCallback" 
"editType" 
"font" 
"forceBars" 
"foreground" 
"function" 
"height" 
"hSpace" 
"index" 
"innerHeight" 
"InnerWidth" 
"innerWindow" 
"InsertPosition" 
"InternalHelght" 

Appendix G: StringDefs.h Header File 507 



Table G-1. Resource Names (continued) 

Resource Name 

XtNinternalWidth 
XtNJustlfy 
XtNknobHeight 
XtNknobIndent 
XtNknobPixel 
XtNknobWidth 
XtNlabel 
XtNlength 
XtNlowerRight 
XtNmappedWhenManaged 
XtNmenuEntry 
XtNname 
XtNnotify 
XtNorientation 
XtNparameter 
XtNpopupCallback 
XtNpopdownCallback 
XtNreverseVideo 
XtNscreen 
XtNscrollProc 
XtNscrollDCursor 
XtNscrollHCursor 
XtNscrollLCursor 
XtNscrollRCursor 
XtNscrollUCursor 
XtNscrollVCursor 
XtNselection 
XtNselectionArray 
XtNsensitive 
XtNshown 
XtNspace 
XtNstring 
XtNtextOptions 
XtNtextSink 
XtNtextSource 
XtNthickness 
XtNthumb 
XtNthumbProc 
XtNtop 
XtNtranslations 
XtNuseBottom 
XtNuseRight 
XtNvalue 
XtNvSpace 

Value 

"internalWidth" 
"Justify" 
"knobHeight" 
"knobIndent" 
"knobPixel" 
"knobWidth" 
"label" 
"length" 
"lowerRight" 
"mappedWhenManaged" 
"menuEntry" 
"name" 
"notify" 
"orientation" 
"parameter" 
"popupCallback" 
"popdownCallback" 
"reverseVideo" 
"screen" 
"scrollProc" 
"scrollDownCursor" 
"scrollHorizontalCursor" 
"scrollLeftCursor" 
"scrollRightCursor" 
"scrollUpCursor" 
"scrollVerticalCursor" 
"selection" 
"selectionArray" 
"sensitive" 
"shown" 
"space" 
"string" 
"textOptions" 
"textSink" 
"textSource" 
"thickness" 
"thumb" 
"thumbProc" 
"top" 
"translations" 
"useBottom" 
"useRight" 
"value" 
"vSpace" 

508 X Too&# Intfinsics Reference Manual 



Table G-3. Representation Types (continued) 

Representation Type 

XtRFont 
XtRFontStruct 
XtRFunction 
XtRGeometry 
XtRImmedlate 
XtRInt 
XtRJustify 
XtRLongBoolean 
XtROrientation 
XtRPixel 
XtRPixmap 
XtRPointer 
XtRPosition 
XtRShort 
XtRString 
XtRStringTable 
XtRUnsignedChar 
XtRTranslationTable 
XtRWindow 

Value 

"Font" 
"FontStruct" 
"Function" 
"Geometry" 
"Immediate" 
"Int" 
"Justify" 
"LongBoolean" 
"Orientation" 
"Pixe1" 
"Pixmap" 
"Pointer" 
"Position" 
"Short" 
"String" 
"StringTable" 
"UnsignedChar" 
"TranslationTable" 
"Window" 

Table G-4. Constants 

Constant 

Boolean Enumeration: 
XtEoff 
XtEfalse 
XtEno 
XtEon 
XtEtrue 
XtEyes 
Orientation Enumeration: 
XtEvertical 
XtEhorizontal 
Text Edit Enumeration: 
XtEtextRead 
XtEtextAppend 
XtEtextEdit 

Value 

"off" 
"false" 
"no" 
" o n " 
"true" 
"yes" 

"vertical" 
"horizontal" 

"read" 
"append" 
"edit" 

Appendix G: StringDefs.h Header File 511 



Table G-4. Constants (continued) 
Co.rant 

Color Enumeration: 
XtExtdefaultbackground 
XtExtdefaultforeground 
Fon 
XtExtdefaultfont 

Value 

"xtdefaultbackground" 
"xtdefaultforeground" 

"xtdefaultfont" 

512 X Toolkit Inttnsics Reference Manual 



Master Index 

The Master Index combines Volumes Four and Five index entries, makino it 
easy to look up the appropriate references to a topic in either volume. PM 
refers to the X Toolkit Intrinsics Programming Manual. RM refers to the X 
Too/kit Intrinsics Reference Manual. 



Index 

The Master Index combines Volumes Four and Five index entries, making it easy to look up 
the appropriate references to a topic in either volume. PM refers to the X Toolkit Intrinsics 
Programming Manual. RM refers to the X Toolkit Intrinsics Reference Manual. 

The alphabetical sequence of the index is highlighted by the bolding of primary entries. 

# directive (see translations) 
! (see modifiers) 
- options (see options) 

accelerators, about PM:53, 150, 189, 205-211, 
253, 495 
(see also display_accelerator) 
(see also XtInstallAccelerators) 
(see also XtInstallAllAccelerators) 
compiling accelerator table PM:210; RM:201 
defining default table in code PM:210 
display_accelerator method PM:211; RM:320 
event propagation PM:207 
for gadgets PM:371 
for menus PM:367, 371 
installing PM:205; RM:166-168; in multiple 
widgets PM:209 
not usable in gadgets PM:373 
parsing (see compiling) 
translations; conflicts with PM:209; transla- 
tion table limitations PM:206 
accept_focus method, about PM:154, 389,391, 
495 
AcceptFocusProc RM:328 
access control list PM:495 
actions PM:30, 495 
(see also XtAddActions, XtAppAddActions) 

actions, about PM:27, 39; RM:7, 428 
action proc; format PM:46 
actions table, PM:495; adding PM:43-45; 
RM:42-43, 60-61; declaring/registering 
with Resource Manager RM:60-61; 
example PM:45; format PM:45; XtAc- 
tionProc RM:270-272 
adding; from application PM:43; in widget 
itself PM:184-186 
arguments to PM:ll3 
contrasted with callbacks PM:46, 112 
defined in widget implementation file 
PM:145-147 
gadget parent; example PM:380-381 
in gadgets PM:373 
naming conventions PM:42 
passing arguments to PM:ll3 
registering (see adding) 
using event data PM:222; example 
RM:271-272 
widget instance pointer PM: 185 
widget/application conflicts PM:146 
(see also XtAddActions, XtAppAddActions) 
aliasing font names PM:443 
AlmostProc RM:328 
Alt key (see modifiers) 
ancestor PM:496 
anonymous ttp PM:34 
application contexts, about PM:97-99, 
393-396, 496 

Index 519 



caching, old size PM:179 
standard atoms PM:299 
type conversions PM:260 
Xmu; initializing PM:300 
callbacks, about PM:26, 30, 39, 497; RM:6, 
330, 429 
adding PM:40, 42; more than one at a time 
PM:80; to callback list RM:46-47; to call- 
back resource RM:44-45 
arguments to PM:42 
callback list, about PM:79, RM:6; deleting 
method RM:219; deleting method list 
RM:220; determining status RM:160; 
executive methods RM:104; popping 
down widget RM:102-103; popping up 
widget RM:98-101; XtCallbackExclusive 
RM:98-99; XtCallbackNone RM:100; 
XtCallbackNonexclusive RM: 101; 
XtCallbackPopdown RM:102-103; XtCall- 
Callbacks RM:104; XtHasCallbacks 
RM:160; XtRemoveCallback RM:219; 
XtRemoveCallbacks RM:220 
conta-asted with actions PM:46 
format PM:42 
naming conventions PM:42 
passing data PM:77-79 
pop-up functions PM:79 
procedure RM:279-280 
(see also XtAddCallback, XtCallbackoc) 
(see also XtTimerCallbackProc) 
Caption widget, about PM:409 
cascading pop ups, about PM:345-347, 
362-367 
example PM:363-365 
case converter PM:200 
registering RM:216 
(see also XtRegisterCaseConverter) 
chained methods (see inheritance) 
change_managed method PM:306-308, 319, 
497; RM:340 
in consta-alm widgets PM:338-339 
ClrculateNotffy events RM:442 
ClrculateRequest events RM:443 
class, about PM:18, 498 
class name; defined in Core class part PM:150 
class part PM:137; combining into class 
record PM:138; lack of new fields 
PM:138 
class record PM:136; allocating storage 
PM: 140; BitmapEdit widget PM:138-139; 
contents PM:136 

class_initialize method PM:153, 258, 381, 
498; RM:331 
class_part_init method PM:153, 331; RM:331 
hierarchy (see widget classes); Athena widgets 
PM:153; gadgets PM:375 
sla-uctures PM:136-162 
subclass; about RM:14 
client, about PM:6, 498 
ClientMessage events RM:444-445 
client-server model PM:6 
clipping region PM:498 
color PM:53, 56, 120, 156-158, 253-254, 276 
color names PM:433 
colorcell, about PM:436, 498; read-only 
PM:438; read/write PM:438; shared 
PM:437 
colormap, about PM:53,436, 498; installing 
PM:276; window attribute PM:156 
ColormapNotify events RM:446 
determining available PM:436 
displaying PM:436 
false PM:277 
hexadecimal specification PM:434 
RGB model PM:435 
specifying PM:433 
command buttons PM:404, 406, 417; 
RM:359-362 
command line options (see options) 
compiling PM:34 
Command widget PM:206-210, 353-359, 362, 
366, 404-406, 417; RM:359-362 
creating RM:362 
desla'oying RM:362 
resources RM:359-361 
compiling Xt PM:34 
composite widgets, 
as parent and child PM:320 
change_rnanaged method RM:340 
class, about PM:16, 21,137; XtNinsertPosi- 
tion resource PM:324 
composite widget class; about PM:61 
delete_child method RM:340 
general purpose PM:409, 421 
geometry_manager method RM:340-341 
insert_child method RM:339-340 
insert_position method RM:342 
importance PM:408 
initial size PM:309 
inserting children PM:323 
menus and control areas PM:418 
ordering method; XtOrderProc RM:310 
reasons for writing PM:305 
resources (see resources) 

Index 521 



due to set_values method changes PM:175 
in expose method PM:166 
into Core widget PM:117-119 
window attributes PM:156-157 
drop-down menu (see menus) 

elements (see array) 
encapsulation PM:29, 500 
enter/leave compression PM:234 
EnterNotffy events PM:195-196, 234, 353; 
RM:454-459 
EnterWindow events PM:216 
environment variables, DISPLAY PM:53 
XAPPLRESDIR PM:245 
XENVIRONMENT PM:245 
errors, error database; obtaining RM:74, 75-77, 
144; XtAppGetErrorDatabase RM:74, 
145; XtAppGetErrorDatabaseText 
RM:75-77, 144 
error handling PM:91.93; and application 
contexts PM:387; calling error resource 
database PM:386; calling fatal error han- 
dler RM:71-73, 85-86, 137-139. 234; .XF 2 
listing RM:491 
sfng conversion error message RM:248 
events, event loop (see main loop) 
events, (see also exposure) 
(see also XtDispatchEvent) 
(see also XtMainLoop. XtNextEvent) 
about PM:10, 191,501; RM:7 
accessing specific data RM:437 
as argument of action PM:46 
border crossing RM:454-459 
ButtonPress RM:439-441 
ButtonRelease RM:439-441 
cancelling source RM:224 
CirculateNotify RM:442 
CirculateRequest RM:443 
ClientMessage RM:444-445 
ColormapNotify RM:446 
ConfigureNotify RM:447-448 
ConfigureRequest RM:449-450 
CreateNotify RM:451-452 
Desla'oyNotify RM:453 
dispatching handlers RM: 133 
EnterNotify PM:234; RM:454-459 
EnterWindow PM:216 
event compression PM:501 
event data; using in an action PM:222 
event filters PM:150, 234 

event handelrs, about PM:28, 30, 215-220, 
501; RM:7; adding PM:216; dispatching 
RM:133; for nonmaskable events 
PM:219-220; procedure RM:293-294, 
304-305; raw PM:220; reasons to use 
PM:216; registering RM:49-50; register- 
ing raw RM:56-57; removing 
RM:221-222; removing raw RM:225-226; 
XtAddEventHandler RM:49-50; XtAd- 
dRawEventHandler RM:56-57; 
XtEventHandler RM:293-294; Xtln- 
putCallbackProc RM:304-305; XtRemo- 
veEventHandler RM:221-222; XtRemo- 
veRawEventHandler RM:225-226 
event masks, about PM:216, 501; RM:424; 
retrieving RM:95-96; table PM:216; 
Xt]3uildEventMask RM:95-96 
event members; common RM:438 
event processing RM:84; XtAppProcessEvent 
RM:84 
event propagation PM:501 
event queue PM:234; peeking PM:234 
event sequences; sharing initial events 
PM:204; sharing noninitial events PM:204 
event source PM:501 
event structure PM:221 
event-driven programming, about PM: 10-11 
event_mask window attribute PM: 157 
expose PM:10 
Expose PM:23, 153,235; RM:460-461 
FocusIn PM:216; RM:462-467 
FocusOut PM:216; RM:462-467 
frozen event PM:502 
GraphicsExpose PM:193,220; RM:468-469 
GravityNotify RM:470 
in action routines PM:124 
in gadgets PM:373 
input events; XtRemoveInput RM:224 
KeymapNotify RM:471 
KeyPress RM:472-474 
KeyRelease RM:472-474 
LeaveNotify PM:234; RM:454-459 
LeaveWindow PM:216 
list of types and structure names PM:223 
MapNotify RM:475-476 
MappingNotify RM:477-478 
MapRequest RM:479 
mocking up from action PM:171; RM:295 
MotionNotify PM:216, 234; RM:480-482 
next event; retuming RM:191 
NoExpose PM:193; RM:468-469 
nonmaskable PM:191o 207. 218 
processing RM:176 

524 X Toolkit Intdnsics Reference Manual 



processing one event; XtProcessEvent 
RM:209 
propagation PM:207 
PropertyNotify RM:483 
ReparentNotffy RM:484 
ResizeRequest RM:485 
returning next event RM:80 
selecting PM:207 
SelectionClear PM:280, 289; RM:486 
SelectionNotify PM:280, 290, 295; RM:487 
SelectionRequest PM:280, 282, 290-291; 
RM:488 
structures RM:438 
translation table abbreviations PM:192-193 
UnmapNotify RM:475-476 
using inside actions or event handlers PM:221; 
RM:271 
VisibilityNotify RM:489-490 
XEvent; example PM:221; RM:271 
(see also XtAppNextEvent, XtAppPending) 
examples, actions; actions table PM:45; adding 
actions PM:43-45; in gadget parent 
PM:380-381; using event datain PM:222; 
widget actions PM:184-185 
adding; accelerators PM:206; event handler 
PM:218-219; RM:294; resource list to class 
structure PM:145; scrollbars to application 
PM:109, 111; work procedure 
PM:231-232 
application resource data structure PM:81 
BitmapEditClassRec PM:138-139, 138 
BitmapEditRec PM: 139 
calculating scrollbar thumb size PM: 113-116 
cascading pop-up menu PM:3630 365 
constraint resources PM:68-69 
constraint widget change_rnanaged method 
PM:338-339 
constraint widget; refiguring child locations 
PM:333-335 
converting; default value of resource 
PM:254-255; selection PM:293-294; stan- 
dard selections PM:300-301; RM:284-285 
creating; argument list PM:92; argument lists 
with XtSetArg PM:93, 94; GCs from ini- 
tialize method PM:169-170; icon pixmap 
PM:278-279 
creating pop up; work procedure RM:323 
creating; widget hierarchy PM:61-63 
declaring; resource list PM:240; widget class 
record pointer PM:155 
destroy method PM:183 
drawing into Core widget PM:118-119 
explicitly invoking converter PM:261 

expose method PM:171-172; RM:296; in gad- 
get parent PM:378-379 
gadget class structure PM:376 
gadget instance structure PM:377 
geometry_manager method in constraint 
widget PM:332-333 
get_values_hook method PM:265; RM:277 
hardcoding resources PM:92 
highlighting selection PM:284-288 
initialize method PM:166-168; in constraint 
widget PM:330 
initializing; Core class part PM:148-149; 
Xmu atom caching PM:300 
installing accelerators in multiple widgets 
PM:209 
interactions between resources PM:55 
laying out child widgets PM:317-319 
main loop (custom) PM:233 
menu using SimpleMenu widget PM:368-370 
nonmaskable event handlers PM:219-220 
obtaining; atom PM:291-292; source code 
availability PM:34 
options table PM:88-89 
passing arguments to converter PM:259 
passing data PM:77-79 
pasting selection PM:295-296 
placing; drop-dowrtmenu PM:360,361; 
pop-up menu PM:354, 357 
pop ups; work procedure to create PM:232 
pop-up menu (spring-loaded); using Box 
widget PM:354-358 
public function to get widget data PM:105 
query_geometry method PM: 182; in compos- 
ite widget PM:316-317; in constraint 
widget PM:339 
reading; from f'de PM:224-226; from pipe 
PM:226-227 
registering resource converter PM:258 
removing timeouts PM:229-230 
resize method PM:177, 179; in composite 
widget PM:316; in constraint widget 
PM:336-337; in gadget parent PM:380 
resource definition in widget PM: 143-145 
resource list PM:82-83 
resource value; getling PM:51 
retrieving; application resources PM:85-86; 
resource default at run-time PM:256 
settg; resources for widget hierarchy PM:64; 
resources with XtSetValues PM:50; win- 
dow attributes in realize method PM:157; 
XtNinput PM:276 
set_values method PM:174-175; in composite 
widget PM:316 

Index 525 



timeouts PM:228-229 
translation table PM:47 
using; argument lists PM:92-93; event data in 
an action PM:222; RM:271-272; pop ups 
PM:71-74; timeouts PM:229 
writing type converter PM:262-263 
xbitrnapl PM:104-107 
xbitrnap2 PM:107-116 
xbitrnap3 PM:116-122 
xbitrnap4 PM:123-132 
XEvent RM:271 
XEvent casting PM:221 
xfarewell.c PM:43-45 
xgoodbye.c PM:40 
xhello.c PM:31-32 
XrmOptionDescRec PM:88-89 
(see also XtResourceDefaultProc) 
expo.lcs.mit.edu PM:34 
Expose events PM:10, 23, 114, 122, 124, 150, 
153, 165, 172, 230, 235,353; RM:51,297, 
460-461 
expose method PM:29, 153, 165-166, 170-174, 
220, 501; RM:296-297, 332-333 
in gadget parent PM:378-379 
in gadgets PM:373,378 
(see also XtExposeProc) 
exposure PM:501 
(see also Expose events, XtAddExposureToRe- 
gion) 
compression PM: 172, 235; RM:297 
exposure (see Expose events) 
extensions, about PM:12, 502 

fatal error handllng (see errors) 
fatal error (see errors) 
file Input, registering file RM:65-66 
files, f'rie events (see event handlers) 
f'rie input PM:224-226; registering f'rie 
RM:54-55; source masks PM:224; XtAd- 
dInput RM:54-55; XtAppAddInput 
RM:65-66 
f'rienames; character limit PM:136 
using names in resources PM:253 
floating point numbers PM:253 
Focusln events PM:195-196, 216, 390; 
RM:462-467 
FocusOut events PM:195-196, 216, 390; 
RM:462-467 
font conventions (in this book), bolding 
PM:xxviii; RM:viii 

italics PM:xxviii; RM:viii 
typewriter font PM:xxviii; RM:viii 
fonts PM:502 
aliasing PM:442 
creating databases (mldontdir) PM:44 
directories PM:438 
display (xfd) PM:438 
families PM:438, 441 
fonts.dir Fries PM:444 
naming convention PM:439 
printer PM:438 
screen PM:438 
specifying PM:433; as resources PM:253 
using frie name as alias PM:443 
wildcarding PM:441 
foreground PM:502 
Form widget, about PM:20, 67-70, 325-340, 
409, 421; RM:365-367 
adding children RM:367 
child resources RM:366 
creating RM:367 
deleting children RM:367 
destroying RM:367 
example PM:421 
layout method PM:329 
resources RM:365-366 (see also resources) 
freeing storage block (see storage block) 
ftp PM:34 
function typedefs, overlapping use PM:148 

gadgets, about PM:155,345 
accelerators PM:371; not usable PM:373 
actions in PM:373 
class hierarchy PM:374-375 
class structure PM:376 
composite parent PM:373,378-381 
Core class structure PM:375 
drawbacks PM:373 
event handling in PM:373 
expose method PM:378 
implementation file PM:377 
instance structure PM:377 
internals PM:375-378 
private header file PM:376-377 
public header file PM:378 
query_geometry method PM:378 
reason for PM:372 
set_values_almost method PM:378 
Sme PM.'367-378 
SmeBSB PM:367-378 

526 X Toolkit Intrinsics Reference Manual 



SmeLine PM:367-378 
superclass PM:377 
unused Core fields in PM:377-378 
games PM:227 
GC (see graphics contexts) 
geometry management, about PM:33, 65-66, 
177, 180-182, 273,305-341,502; RM:14, 
338-342, 431 
(see also XtDestroyWidget) 
(see also XtGeometryAlmost) 
(see also XtGeometryDone return value) 
(see also XtGeometryNo return value) 
(see also XtGeometryResult enum) 
(see also XtGeometryYes return value) 
(see also XtInheritDeleteChild constant) 
(see also XtInheritGeometryManager constant) 
(see also XtInheritInsertChild constant) 
(see also XtInheritSetValuesAlmost constant) 
(see also XtMakeGeometryRequest) 
(see also XtMakeResizeRequest) 
(see also XtMapWidget, XtMoveWidget) 
(see also XtNinsertPosition composite 
resource) 
(see also XtNmappedWhenManaged Core 
resource) 
(see also XtQueryGeometry) 
(see also XtResizeWidget) 
(see also XtUnmanageChild, XtUn- 
manageChildren) 
(see also XtUnmapWidget) 
(see also XtWidgetGeometry structure) 
almost right PM:323 
border width PM:306 
Box widget RM:357-358 
change_managed method PM:306, 308, 319 
changes PM:456; RM:177-179 
changing; XtMakeGeometryRequest 
RM:177-179 
compound widgets PM:340-341 
conswaint class part PM:329 
conswaint management PM:325 
conswaints on children RM:365-367 
delaying recalculation PM:340 
delete_child method PM:306, 323-324 
geometry handler; procedure RM:299-301 
geometry manager RM:341 
geometry_manager method PM:306, 311, 
320-322; RM:340-341; in consaint widget 
PM:332-336 
height PM:308 
initial geometry negotiation PM:308, 310 
initial size PM:308 
initialize method PM:315 

inserting children PM:323; insert_child 
method PM:306, 323-324 
minimal useful size PM:317 
querying RM:210-212; preferred geometry 
PM:320; query_geometry method PM:306, 
321; XtQueryGeometry RM:210-212; 
XtQueryOnly constant PM:322 
realize method PM:310, 315 
resizing PM:305, 311; by application 
PM:312; by user PM:311; by widget 
request PM:311-312; resize method 
PM:306, 309 
scope PM:306 
scrollable widget RM:403-404 
set_values method PM:311-312, 315 
set_values_almost method PM:312, 322, 323 
size preferences PM:320 
stacking order PM:306, 341 
clde-down PM:320 
unmanaging widget PM:319 
what if requests PM:322 
widget for vertical tiles RM:405-408 
width PM:308 
get_values_hook method PM:154, 265-266, 
502; RM:158, 275-278, 335 
(see also XtArgsProc) 
global variables PM:75, 77 
glyph PM:502 
grabs PM:351,495, 502; RM:431 
(see also XtAddGrab) 
(see also XtRemoveGrab) 
active vs. passive PM:352 
adding or removing explicitly PM:372 
exclusive vs. nonexclusive PM:352, 365 
grab modes PM:365 
in dialog boxes PM:371 
keyboard PM:351 
passive PM:507 
pointer PM:351 
reasons for in menus PM:353 
graphics contexts PM:119, 140, 157, 502 
(see also XtDestroyGC) 
(see also XtGetGC) 
(see also XtReleaseGC) 
caching PM:166, 168 
changing PM:168, 176 
creating PM: 166-170 
deallocating RM:217 
destroying RM:128 
exclusive or logical function PM:287 
freeing PM:176, 183 
freeing (R2) RM:128 
hardcoding values in PM: 170 

Index 527 



placing pop-up PM:357 
pointer grabbing PM:351 
popping down PM:351,359, 367; MenuPop- 
down RM:39 
popping up PM:352, 358; MenuPopup 
RM:40-41 
popping up with callbacks PM:360 
pull down PM:347 
SimpleMenu widget, example PM:368, 370 
spring-loaded PM:347 
messages, about PM:29, 505 
OOP vs. Xt PM:29 
Meta key (see modifiers) 
methods, about PM: 153-154, 505 
accept_focus PM: 154, 389, 391 
and instance structure PM:136 
change_managed PM:306-308, 319; RM:340 
class_initialize PM:153, 258, 381; RM:331 
class_part_initialize PM: 153; RM:331 
constraint widgets; destroying PM:329; 
geometry_manager PM:332; initializing 
PM:329; resizing PM:336 
declarations in widget implementation file 
PM: 147-148 
delete_child PM:306, 323-324; RM:340 
destroy PM:154, 165, 183 
display_accelerators PM:211 
drawing; due to changes in set_values 
PM:175; in expose PM:166 
expose PM:29, 153, 165-166, 170-174. 220; 
RM:296 
Form layout PM:329 
gadget; expose PM:378; query_geometry 
PM:378; set_values_almost PM:378 
geometry_manager PM:306, 311,320-322; 
RM:340 
get_values_hook PM: 154, 265-266; 
RM:275-277; example PM:265; example 
of RM:275, 277 
in OOP PM:29 
inheritance; adding to superclass PM:157; of 
superclass PM:155 
initialize PM:153, 165-170, 315 
initialize_hook PM:153, 265 
insert_child PM:306, 323-324; RM:339 
layout Form PM:329 
not known to Xt PM:329 
query_geometry PM:154, 165, 180-182, 306, 
321 
realize PM:153,274, 310, 315; RM:331 
reconciliation PM: 157 
resize PM:154, 165, 177-180, 306, 309 
resources, and set_values PM: 174-176 

set_values PM:154, 165-166, 174-176, 
311-315 
set_values_almost PM: 154, 312, 322-323 
set_values_hook PM:154, 265-266; RM:275 
minimal useful size PM:317 
mkfontdir PM:444 
Mod n key (see modifiers) 
modal cascade (see menus, cascading) 
modal pop ups (see pop ups) 
modifiers, ! PM:200 
adding PM:198 
and event sequences PM:202 
case-specifics PM:200 
colon PM:200-201 
displaying list PM:198 
for button events PM:202 
keys, about PM:196-201,506;/klt key 
PM:197; Ctrl key PM:197; Hyper key 
PM: 197; key modifier RM:500-506; Meta 
key PM:197; Mod n key PM:197; Super 
key PM: 197 
matching exactly PM:200 
negating PM:199 
None PM:200 
tilde PM:199 
monochrome PM:506 
Motif PM:349, 399, 402 
motion compression PM:234 
MotionNotlfy events PM: 196, 202, 216, 234, 
353; RM:480-482 
multiple toplevel shells PM:395 

naming conventions, (see also conventions) 
widgets PM:449 
newllnes, in translations PM: 190 
NoExpose events PM: 193; RM:468-469 
nonfatal error (see errors) 
nonmaskable events PM: 191,207, 218-220, 
506 
example of handlers PM:219-220 
notify modes (see translations) 

0 

object, about PM:28,506 
Object class PM:374 
object-oriented programming PM:28-29 

530 X Toolkit Inttnsics Reference Manual 



single-line input field PM:280 
sink, in Athena Text widget PM:264 
size PM:305 
hints PM:273 
preferences PM:320 
sizeof PM:150 
Sme gadgets PM:367-378 
SmeBSB gadgets PM:367-378 
SmeLine gadget PM:367-378 
software architecture, about PM:8 
source code, obtaining; example PM:34 
source files for widget PM:I35 
source, in Athena Text widget PM:264 
spring-loaded pop up (see pop ups) 
stacking order PM:306, 341,513 
StatlcColor PM:513 
StatlcGray PM:513 
status PM:513 
stdlo.h PM:I41 
stipple PM:513 
storage, storage block 
allocating RM:I81; for datatype RM:I89; 
XtNew RM:I89 
freeing RM:I40; (see also XtFree) 
resizing RM:215 
(see also XtMalloc) 
string, copying; XtNewStrlng RM:I90 
StringDefs.h PM:83 
StringDefs.h header file PM:30, 50, 141; 
RM:507 
string, error message; XtStringConver- 
slonWarning RM:248 
StrlngToWldget resource converter PM:69 
structure, (see also XtOffset) 
determining field's byte offset RM:193-194 
of Xt applications PM:30 
subclass, about PM:I9, 513 
submenus (menus, cascading) 
subparts PM:150, 154, 264-266 
subresources PM:150, 154, 264-266 
Super key (see modifiers) 
superclass, about PM:19, 149, 513 
syntax functions PM:91 

TCP/IP PM:280 
templateWldgetCiass RM:383-390 
Text widget, about PM:lg, 414, 424; 
RM:391-402 
creating RM:397 
default bindings RM:395-396 

edit modes RM:392 
resources RM:392-394 
tight bindings PM:244, 513 
tiling, about PM:53. 513 
time PM:513 
timeouts, about PM:227 
adding PM:227 
and visibility interest PM:230 
callback method RM:321 
example PM:228-229 
invoking procedure after tirneout RM:67 
removing PM:229-230 
selection tirneout; setting RM:240; value 
RM:78, 87, 150 
(see also XtAddTimeout, XtAppAddTimeOut) 
(see also XtAppSetSelectionTimeoul, XtGet- 
SelectionTimeout) 
(see also XtRemoveTimeOut, XtSetSelection- 
Timeout) 
(see also XtTimerCallbackProc) 
toolklts, initializing internals RM:250 
initializing toolkit and display RM: 161-165 
(see also XtIrLitialize, XtToolkitIrLitialize) 
top-level widget (see Shell widget) 
top-level window PM:514 
topLevelShell widget class PM:270; 
RM:346-353 
training In Xllb PM:489 
TranslentShell widget class PM:70, 74, 270; 
RM:346-353 
Translation Manager (see actions) 
translations, # augment directive PM:48 
! modifier symbol PM:200 
# override directive PM:48 
# replace directive PM:48 
(see also accelerators) 
(see also actions) 
(see also XtOverrideTranslations) 
about PM:27, 39, 43, 47, 53, 514; RM:7 
augmenting PM:48 
colon modifier symbol PM:200-201 
compiling; table RM:202-203; when widget 
class initialized PM: 147; XtParseTransla- 
tionTable RM:202-203 
def'ming; default in Core class part PM:150; 
in source PM:49 
details in PM:194-196 
differences between directives PM: 191 
directives PM:191 
double-clicks PM:201 
event abbreviations PM:192-193 
event sequences PM:201-203 
hardcoding PM:48 

Inclox 535 



child widget; about RM:15; creating/manag- 
ing PM:61,307;RM:118; layoutof 
PM:317 
class; composite widget subclass PM: 16; 
determining subclass RM:175; name 
defined PM:150; obtaining RM:107; veri- 
fying RM:106; widgetClass class pointer 
PM:119; XtCheckSubclass RM:106; 
XtClass RM:107; XtlsComposite 
RM:169; XtlsConstraint RM:170; Xtls- 
Shell RM:174; XtlsSubclass RM:175 
Command widget PM:19, 38-39, 40-42, 75, 
104; RM:359-362 
composite widget, about PM:21,305; RM:14, 
169, 338-342; management PM:306; rea- 
sons forwriting PM:305; writing PM:312 
compound PM:340-341 
constraint widget, about PM:22, 305; RM: 16, 
170, 343-345; management PM:325; writ- 
ing PM:325 
converting (2 to 3) PM:453 
Core widget PM:17, 116; RM:383 
creating PM:30, 80; RM:122-123; additional 
top-level widget RM:69-70, 117; child 
widget RM:14; custom widget 
RM:383-390, 384; working window 
RM:124-125 
declaring widget class record pointer; example 
PM:155 
default size PM:180 
defining conventions PM:136, 244; summary 
PM:162 
destroying PM:26, 79, 183; RM:129-130; 
XtDestroyWidget RM: 129-130 
Dialog widget PM:20, 75, 340; RM:363-364 
display pointer RM: 134 
displaying non-editable string RM:370-372 
dragging PM:20; attachment point 
RM:368-369 
Exclusive and Nonexclusive PM:407 
Form widget PM:20, 104, 326, 421; 
RM:365-367 
framework of code PM:135-162 
geometry (see geometry management) 
getting data; example PM:105 
getting widget data via public function 
PM:105 
Grip widget PM:19; RM:368-369 
implementation frie PM:135, 141-158; actions 
table PM:145-147; declaration of methods 
PM:147-148; resources PM:143-145; 
translation table PM:145-147 
installing accelerators (see accelerators) 

instance structure PM:166 
internals PM:135-162 
Label widget PM:28, 116, 177, 258; 
RM:370-372 
lifecycle RM:4 
List widget PM:19; RM:373-377 
macros for getting widget information PM:388 
management PM:61,180-182; RM:171; row- 
column geometry RM:373-377; 
XtlsManaged RM:171 
(see also XtManageChild, XtManageChildren) 
mapping PM:53; changing map_when_man- 
aged field RM:239; windows PM:33; 
XtMapWidget RM:185; XtSetMap- 
pedWhenManaged RM:239 
merging translations RM:93-94 
methods (see XtCreateWidge0 
modal widget; redirecting input RM:52-53, 
223; XtAddGrab RM:52-53; XtRemo- 
veGrab RM:223 
moving/resizing PM:53; RM: 109-110; 
XtConfigureWidget RM: 109-110; XtMo- 
veWidget RM: 187 
naming conventions PM:449 
necessary include fries PM:136 
parent widget PM:lll; returning RM:200; 
XtParent RM:200 
popping down; Menupopdown RM:39 
popping up PM:75-76; Menupopup 
RM:40-41 
private header file PM:135, 136-140 
procedure RM:322 
public header file PM:135, 158-160 
realizing PM:176; RM:172, 213-214; method 
RM:312-313; XtlsRealized RM:172; 
XtRealizeProc RM:312-313; XtReal- 
izeWidget RM:213-214 
record size PM:150 
removing PM:17; XtUnmanageChildren 
RM:258; XtUnmanageChild RM:257 
resizing PM:65, 177-180, 306-314; RM:333; 
by application PM:312; by parent 
PM:311; per core dimensions RM:230; 
reasons for PM:322; resize method 
PM:336; XtMakeResizeRequest RM:180; 
XtResizeWidget RM:229; XtResizeWin- 
dow RM:230 
retrieving event mask RM:95-96; XtBuil- 
dEventMask RM:95-96 
returning screen pointer, XtScreen RM:231 
Scroll widget PM:257 
Scrollbar widget PM:19, 66, 108; RM:378-382 
ScrollBox widget PM:314 

Index 537 



X Consortium address PM:490 
X protocol PM:5,280 
X source software PM:485 
X Toolkit (see toolldts) 
X, about PM:3 
XA CLIPBOARD (see selections) 
XA_MULTIPLE property (see selections) 
XA MULTIPLE property (see selections) 
XAPLRESDIR environment variable 
PM:245 
XA_PRIMARY property (see selections) 
XA PRIMARY (see selections) 
XA SECONDARY (see selections) 
XA TARGETS atom (see selections) 
Xatom.h PM:288, 290 
Xaw; PM:36 
xbltmap application; PM:461 
xbitmap I; example PM: 104-107 
xbitmap2; example PM: I07-I 16 
xbitmap3: example PM: I 16-122 
xbitmaIM; example PM:123-132 
XChangeGC Xllb function PM:I68 
XChangeKeyboardMapplng RM:477 
XClearArea Xllb function PM:I75 
xcllpboard PM:300-302 
XConflgureWlndow PM:341, RM:449-450, 
485 
XConvertSelectlon RM:487 
XCopyArea Xllb function PM: 122, 174, 193; 
RM:297 
XCopyColormapAndFree Xllb function 
PM:277 
XCopyPlane Xllb function PM:I22, 174, 193; 
RM:297 
XCreateGC Xllb function PM: 120, 166 
XCreateWlndow Xlib function PM: 158 
Xdefaults file PM:55, 245 
xedlt PM:280 
XENVIRONMENT envlronment varlable 
PM:245 
xev PM:I98 
XEvent unlon RM:437 
xfarewell.c, example PM:43-45 
xfd (font displayer) PM:441 
XFlush Xllb function PM:394 
XGCValues structure PM: 168 
XGetIconSlzes Xllb function PM:279 
XGetModlflerMapplng RM:478 
XGetMotlonEvents RM:481 

XGetPointerMapping RM:478 
XGetStandardColormap Xllb function 
PM:277 
xgoodbye.c, example PM:40 
XGrabButton Xllb function PM:353 
XGrabKey Xllb function PM:353 
XGrabPointer Xllb function PM:352 
xhello.c, example PM:31-32 
XInternAtom Xlib function PM:290-291 
Xlib PM:36, 170, 172, 176 
Xlib Interface RM:17 
xload PM:275 
XLookupString Xllb function PM:391 
XLowerWlndow Xlib function PM:341 
XMapRalsed RM:479 
XMapWindow RM:479 
xmh PM:68,280 
xmodmap PM:198 
XMoveResizeWindow RM:485 
Xmu PM:36, 259, 299 
XmuConvertStandardSelection PM:300-301; 
RM:285 
XmuConvertStandardSelection Xmu function 
PM:299 
XmuInternAtom PM:299 
XmuInternAtom Xmu function PM:299 
Xmu, resource converters in PM:253 
XNextEvent Xllb function PM:311 
XParseGeometry Xllb function PM:274 
XQueryPointer RM:481 
XRaiseWindow Xllb function PM:341 
xrdb PM:55, 243, 245 
XRectlnRegion Xllb function PM: 172; 
RM:297 
XRefreshKeyboardMapping RM:478 
XResizeWindow RM:485 
XRestackWindows Xllb function PM:341 
XrmOptionDescRec RM:163 
example PM:88-89 
format PM:89 
structure PM:88 
XrmoptionlsArg argument style PM:90 
XrmOptionKind enum values PM:90 
XrmoptionNoArg argument style PM:90; 
RM: 165 
XrmoptionResArg argument style PM:90 
XrmoptionSepArg argument style PM:90 
XrmoptionSklpArg argument style PM:90 
XrmoptionSklpLine argument style PM:90 
XrmoptionStickyArg argument style PM:90 
XrmStringToQuark Xllb function PM:262 

index 530 



PM:253 
XtRUnslgnedChar representation type 
PM:253 
XtRWldget representation type PM:257 
XtScreen RM:231 
XtScrollbarSetThumb RM:381 
XtSelectionCallbackProc PM:282; 
RM:316-317 
XtSelectionDoneProc PM:282; RM:318 
XtSetArg PM:50, 51, 93, 119; RM:232-233 
XtSetErrorHandler PM:387, 393; RM:234 
XtSetErrorMsgHandler PM:387, 393; 
RM:235 
XtSetKeyboardFocus PM:391; RM:236-237 
XtSetKeyTranslator RM:238 
XtSetMappedWhenManaged RM:239 
XtSetSelectionTlmeout PM:302, 393; RM:240 
XtSetSensitive PM:75,371; RM:241 
XtSetSubvalues PM:266; RM:242-243,275 
XtSetValues PM:23, 49-51,136, 140, 154, 157, 
165-166, 174-176, 319, 338; RM:244-245, 
334-335,345 
XtSetValuesFunc RM:319, 334 
XtSetValuesFunc function prototype PM:175 
XtSetWarningHandler PM:387, 393; RM:246 
XtSetWarningMsgHandler PM:387, 393; 
RM:247 
XtStringConverslonWarning PM:263, 387; 
RM:248 
XtStringProc RM:320, 336 
XtStringSourceCreate RM:401 
XtStringSourceDestroy RM:402 
XtSuperclass RM:249 
XtTextBIock RM:399 
XtTextChangeOptlons RM:400 
XtTextDisableRedisplay RM:399 
XtTextDisplay RM:400 
XtTextEnableRedisplay RM:399 
XtTextGetInsertionPoint RM:400 
XtTextGetOptions RM:400 
XtTextGetSelectionPos RM:398 
XtTextGetSource RM:401 
XtTextInvalldate RM:399 
XtTextReplace RM:398 
XtTextSetlnser tionPolnt RM:400 
XtTextSetLastPos RM:400 
XtTextSetSelection RM:397 
XtTextSetSource RM:401 
XtTextTopPosltion RM:400 
XtTextUnsetSelection RM:398 
XtTimeOut PM:393 

XtTimerCallbackProc RM:321 
XtToolkltInltiallze PM:30, 98, 243; RM:250 
XtTranslateCoords PM:75,360-361; RM:25 
XtTranslateKey PM:392; RM:252-253 
XtTranslateKeycode PM:392; RM:254-255 
XtUninstallTranslations RM:256 
XtUnmanageChild PM:319; RM:257 
XtUnmanageChildren PM:319; RM:258 
XtUnmapWldget PM:319; RM:259 
XtUnreallzeWldget RM:260 
XtVaCreateArgsList PM:428 
XtVaGetApplicationResources PM:260 
XtVaGetSubresources PM:260 
XtVerslon constant PM: 151 
XtVerslonDontCheck constant PM: 151 
XtWarnlng PM:386-387, 393; RM:261 
XtWarningMsg PM:386-387, 393; RM:262 
XtWidgetGeometry PM:320-323 
XtWldgetGeometry structure PM: 180-182 
XtWldgetProc PM:148; RM:322, 332-345 
XtWldgetToAppllcationContext RM:263 
XtWindow PM:176, 378; RM:264 
XtWindowToWldget PM:389; RM:265 
XtWorkProc PM:393; RM:323-324 
XUnGrabPointer Xllb function PM:352 
XVlew PM:10 
XYPlxmap PM:515 

Z 
zoomed window PM:515 
ZPlxmap PM:515 

Index 543 



Please send me the information 
1 have asked for on the reverse 
side of this card. 

PLACE 
STAMP 
HERE 

Name 

Company 

Address 

City _ 

State, ZIP 
(Fill out or tape 
business card here) 

Nutshell Handbooks 
NUtS.ELL O'Reilly & Associates. Inc. 
I t 632 Petaluma Avenue 
.A.DBOO,S Sebastopol CA 95472 

Please send me the information 
I have asked for on the reverse 
side of this card. 

Name 

PLACE 
STAMP 
HERE 

Company 

Address 

City 

State, ZIP 
(Fill out or tape 
business card here) 

Nutshell Handbooks 
.UrSELL O'Reilly & Associates, Inc. 
](1 632 Petaluma Avenue 
A.DBOOKS Sebastopol CA 95472 



Overseas Distributors 

Effective January i. 1990, customers outside the U.S. and Canada will be able to order 
Nutshell Handbooks and the X Window System Series through distributors near them. These 
overseas locations offer international customers faster order processing, more local bookstores 
and local distributors, an increased representation at trade shows worldwide, as well as the high 
level, quality service our customers have always received. 

AUSTRALIA & NEW ZEALAND 
(orders and inquiries1 
Addison-Wesley Publishers. Pty. Ltd. 
6 Byfield Street 
North Ryde. N.S.W. 2113 
AUSTRALIA 
Telephone: 61-2-888-2733 
FAX: 6 I-2-888-94(14 

ASIA inquiries (excluding Japan) 
Addison-Wesley Singapore Pte. Ltd. 
15 Beach Road #05-09/10 
Beach Centre 
Singapore 0718 
SINGAPORE 
Telephone: 65-339-7503 
FAX: 65-339-9709 

UNITED KINGDOM & AFRICA 
(orders and inquiries) 
Addison-Wesley Publishers. Ltd. 
Finchampstead Road 
Wokin,,ham Berkshire RGI I 2NZ 
ENGLAND 
Telephone: 44-734-794-00(I 
FAX: 44-734-794-035 

EUROPE & THE MIDDLE EAST 
(orders and inquiries) 
Addison-Wesley Publishers B.V. 
De Lairessestraat 9(I 
1071 PJ Arnsterdan 
THE NETHERLANDS 
Telephone: 31-20-764-044 
FAX: 3 I-2(I-664-5334 

ASIA orders (excluding Japan 
Addison-Wesley Publishing Co.. Inc. 
International Order Department 
Route 128 
Reading. Massachusetts ()1867 U.S.A. 
Telephone: 1-617-944-3700 
FAX: 1-617-942-2829 

JAPAN 
(orders and inquiries) 
Toppan Compan 3. Ltd. 
Ochanomizu Square B. I-6 
Kanda Surugadai 
Chiyoda-ku. Tokyo I01 
JAPAN 
Telephone: 81-3-295-3461 
FAX: 81-3-293-5963