(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 : for version 11 of the X window system"

The Definitive Guides 
to the X Window System 



Volume Five 




X Toolkit Intrinsics 
Reference Manual 



for X Version 11 




O Reilly & Associates, Inc. 



^LIBRARY COPY 



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. 



Copyright 1990 O Reilly & Associates, Inc. 
All Rights Reserved 



The X Window System is a trademark of the Massachusetts Institute ofTechnology 

OPEN LOOK is a trademark of AT&T 

XView and SunView are trademarks of Sun Microsystems, Inc. 

OSF/Motif is a trademark of the Open Software Foundation, Inc. 

DECwindows is a trademark of Digital Equipment Corporation 

Genera is a registered trademark of Symbolics, Inc. 

Cedar is a trademark of Xerox, Inc. 

Explorer is a trademark of Texas Instruments, Inc. 

Tetris is at trademark of AcademySoft-ELORG 

UNIX is a registered trademark of AT&T 

Macintosh is a trademark ofMdntosh Laboratory, Inc. licensed to Apple Computer, Inc. 

C++ is a trademark of AT&T 



Revision and Printing History 

January 1990: First Printing. 

Small Print 

This document is based in part on X Toolkit Intrinsics-C Language Interface, by Joel McCoimack, Paul Asente, and 
Ralph Swick, and on X Toolkit Athena Widgets-C Language Interface, by Ralph S wick and Terry Wcissman, both of 
which are copyright 1985, 1986, 1987, 1988, 1989, 1990 the Massachusetts Institute ofTechnology, Cambridge, 
Massachusetts, and Digital Equipment Corporation, Maynard, Massachusetts. 

We have used this material under the terms of its copyright, which grants free use, subject to the following condi 
tions: 

"Permission to use, copy, modify and distribute this documentation (i.e., the original MIT 
and DEC material) for any purpose and without fee is hereby granted, provided that the 
above copyright notice appears in all copies and that both that copyright notice and this per 
mission notice appear in supporting documentation, and that the name of MIT or Digital not 
be used in advertising or publicity pertaining to distribution of the software without specific, 
written prior permission. MIT and Digital make no representations about the suitability of 
the software described herein for any purpose. It is provided as is without expressed or 
implied warranty." 

Note, however, that those portions of this document that are based on the original XI 1 documentation and other 
source material have been significantly revised, and that all such revisions are copyright 1989, 1990 O Reilly & 
Associates, Inc. Inasmuch as the proprietary revisions cannot be separated from the freely copyable MIT source 
material, the net result is that copying of this document is not allowed. Sorry for the doublespeak! 

While every precaution has been taken in the preparation of this book, we assume no responsibility for errors or 
omissions. Neither is any liability assumed for damages resulting from the use of the information contained herein. 

ISBN 0-937 175-35-8 



The X Window System Series 

The books in the X Window System series from O Reilly and Associates 
are based in part on the original MIT X Window System documentation, 
but are far more comprehensive and easy to use. Over 20 computer 
vendors recommend or license volumes in the series. In short, these are the 
definitive guides to the X Window System. 

Volume 0, X Protocol Reference Manual. A complete programmer s 
reference to the X Network Protocol, the language in which computers 
communicate all the information between the X server and X clients. 414 
pages, $30.00 

Volumes 1 and 2, Xlib Programming Manual and Xlib 
Reference Manual. Complete guides to programming with the X library 
(Xlib), the lowest level of programming interface to X. 664 and 725 pages, 
$34.95 each, or $60.00 as a set. 

Volume 3, X Window System User s Guide. Describes window 
system concepts and the most common client applications available for X, 
Release 3. For experienced users, later chapters explain customizing the X 
environment and include an alternate .uwmrc file. 576 pages, $26.95 

Volumes 4 and 5, X Toolkit Intrinsics Programming Manual and 
X Toolkit Intrinsics Reference Manual. Complete guides to 
programming with the Xt Intrinsics, the library of C language routines 
created to facilitate the design of user interfaces, with reusable compon 
ents called widgets. 582 and 545 pages, $30.00 each, or $55.00 as a set. 

Volume 7, XView Programming Manual. XView is an easy-to-use 
toolkit, not just for Sun developers. This volume provides complete 
information on the XView toolkit, from concepts to creating XView 
applications to reference pages. 566 pages. $30.00. 

For orders or a free catalog of all our books, please contact us. For 
international orders (outside U.S. or Canada) see our list of distributors in 
the back of this book. 

O Reilly & Associates, Inc. 

Creators and publishers of Nutshell Handbooks 
HANDBOOKS 632 Petaluma Avenue Sebastopol CA 95472 

email: uunet!ora!nuts 1-800-338-6887 in CA 1-800-533-6887 +1 707-829-0515 





Table of Contents 

Page 

Preface vii 

Chapter 1 Introduction l 

Permuted Index 19 

Section 1: X Toolkit Intrinsics Functions and Macros 37 

Section 2: Prototype Procedures 267 

Section 3: Int rinsics-mandated Widget Classes 325 

Section 4: Athena Widgets 355 

Sections: 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 Intrinsics not 
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 HP 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 Intrinsics 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, Intrinsics-mandated Widget Classes, contains reference pages for the 

required widget classes Core, Composite, Constraint, and Shell. 



viii X Toolkit Intrinsics Reference Manual 



Section 4, Athena Widgets, contains reference pages for the Athena widgets. 

Appendix A, Alphabetical and Group Summaries, provides quick reference tables that 
list each Intrinsics function alphabetically and by logical groups. 

Appendix B, 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. 

Appendix C, 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. 

Appendix D, Standard Errors and Warnings, lists the possible errors or warnings 
returned by the X Toolkit, along with their possible cause. 

Appendix E, Resource File Format, explains the EBNF syntax used the resource file. 

Appendix F, Translation Table Syntax, explains the EBNF syntax used the translation 
table. It discusses modifiers and event types. 

Appendix G, StringsDefs.h Header File, groups the identifiers found in StringDefs.h. 
Appendix H, Release Notes, summarizes the changes between these two releases. 

Master Index 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 program 
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 programming 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 



Conventions Used in This Book 



Italics are used for: 

UNIX pathnames, filenames, program names, user command names, and options for user 
commands. 

New terms where they are defined. 

Typewriter Font is used for: 

Anything that would be typed verbatim into code, such as examples of source code and 
text on the screen. 

The contents of include files, such as structure types, structure members, symbols 
(defined constants and bit flags), and macros. 

Xt functions. 

Names of subroutines of the example programs. 

Italic Typewri t er Fon t is used for: 

Arguments to Xt functions, since they could be typed in code as shown but are arbitrary 
names that could be changed. 

Helvetica Italics are used for: 

Titles of examples, figures, and tables. 

Boldface is used for: 

Chapter and section headings. 



Requests for Comments 

Please write to tell us about any flaws you find in this manual or how you think it could be 
improved in order to help us provide you with the best documentation possible. 

Our U.S. mail address, e-mail address, and telephone numbers are as follows: 

O Reilly and Associates, Inc. 
632 Petaluma Avenue 
Sebastopol, CA 95472 
800-338-6887, in CA 800-533-6887 
international +1 707-829-0515 

UUCP: uunet!ora!tim ARPA: tim@ora.com 



X Toolkit Intrinsics R&f&rence Manual 



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 Intrinsics Programming Manual, for a listing of these 
sources. 



Acknowledgements 

As mentioned above, this manual is based in part on the Xt Toolkit Intrinsics 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 



xii 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 Intrinsics (and 
macros), function typedefs for widget methods and other internal routines, Intrinsics- 
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 first 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 page or reference page, as we ll call it. 



Introduction 



Table 1-1. Overview of the Intrinsics 



Introduction 
Topic 



Using Widgets 



Building Widgets 



Function 
typedefs 



Widget 
Lifecycle 



Xt Great eAppli cat ion- 
Shell 
XtCreateManaged- 

Widget 

XtCreateWidget 
XtDestroyWidget 
Xtlnitialize 
XtlsManaged 
XtlsRealized 
XtMainLoop 
XtManageChild 
XtManageChildren 
XtRealizeWidget 
XtUnmanageChild 
XtUnmanageChildren 



XtExposeProc 

XtlnitProc 
XtProc 

XtRealizeProc 
XtWidgetProc 



Classes and 
Subclasses 
Core, etc. 



XtApplicationClass 

XtApplicationName 

XtClass 

XtCreateWidget 

XtlsSubclass 

XtSuperclass 



XtlsSubclass 



Application 
Interface 



XtAddActions 

XtAddCallback 

XtAddCallbacks 

XtMergeArgLists 

XtOverrideCallback 

XtSetArg 

See also Resource 

Management below 



XtCallCallbacks 

XtHasCallbacks 

XtRemoveAllCallbacks 

XtRemoveCallback 

XtRemoveCallbacks 



XtCallbackRec 



Events 



Translations 
XtMainLoop 



RemoveTimeOut 
XtAddEventHandler 
XtAddlnput 
XtAddRawEvent- 

Handler 
XtAddTimeOut 
XtAppProcessEvent 
XtDispatchEvent 
XtHasInput 
XtNextEvent 
XtPeekEvent 
XtRemoveEvent- 

Handler 
XtRemove Input 
XtRemoveRawEvent- 

Handler 



Event masks 
XEvent 



X Toolkit Intrinsics Reference Manual 



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



Introduction 
Topic 



Using Widgets 



Building Widgets 



Function 
typedefs 



Translations 

and 

Actions 



Graphics 



MenuPopup 

MenuPopdown 

XtAddActions 

XtAugment- 

Translations 

XtOverride- 
Translations 

XtParseTr an si at ion- 
Table 



XtActionProc 



XtDestroyGC 
XtGetGC 

XtReleaseGC 



Popups 



MenuPopdown 

MenuPopup 

XtCallbackExclusive 

XtCallbackNone 

XtCallback- 

Nonexclusive 
XtCallbackPopdown 
Xt Great ePopupShell 
XtPopdown 
XtPopup 



XtMoveWidget 
XtNameToWidget 



Resource 
Management 



XtGetValues 
XtSetValues 



XtAddConverter 

XtConvert 

Xt Direct Convert 

Xt Get Application- 
Resources 

XtGetRe sources 

Xt Get SubRe sources 

XtGetSubvalues 

XtStringConver si on- 
Warning 



XtSetValuesFunc 



Geometry 
Management 



XtConfigureWidget 

XtMakeGeometryRequest 

XtMakeResizeRequest 

XtMoveWidget 

XtQueryGeometry 

XtResizeWidget 

XtResizeWindow 

XtUnmanageChild 

XtUnmanageChildren 



XtAddExposureToRegion 



Composite 
XtArgsProc 



Xlib 
Interface 



XtDisplay 

XtScreen 

XtWindow 



Introduction 



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



Introduction 
Topic 



Using Widgets 



Building Widgets 



Function 
typedefs 



Misc. 



XtlsSensitive 

XtNameToWidget 

XtWindowToWidget 



XtAddGrab 

XtCalloc 

XtError 

XtErrorMsg 

XtFree 

XtMalloc 

XtParent 

XtRealloc 

XtRemoveGrab 

XtSetWarningHandler 

XtWarning 

XtWarningMsg 



1.1 Widget Lifecycle 

A widget goes through several distinct stages in its lifetime. It is consecutively created, man 
aged, realized, mapped (this is usually performed automatically), and destroyed. 

For any program to use the X Toolkit, it must first create and initialize the Toolkit itself, cre 
ate an application context, and open the display. These operations can be combined using 
xtlnitialize. Xtlnitialize returns a top-level shell widget that can be the parent 
of the rest of the application. If an application wishes to open windows on multiple screens 
simultaneously, these operations can be done individually. (See xtlnitialize- 
Toolkit, XtAppCreateContext, and XtDisplaylnitialize). 

Next, the application is ready to create widgets. It does this with xtCreateWidget or 
xtCreateManagedWidget. Widget creation causes the Intrinsics to invoke the 
widget s private initialize method. The methods, or procedures, associated with a widget are 
summarized in Core(3). 

In the initialize method, the widget performs customized initialization and processes the 
arguments that are passed to it as resource arguments in the call that created it. (See Sec 
tion 1.7, "Resources.") 

XtCreateManagedWidget combines creation with the obligatory step of bringing the 
widget s placement under the dominion of its parent s geometry manager. (See Section 1.8, 
"Geometry Management.") A widget created with XtCreateWidget must be separately 
managed with a call to XtManageWidget. 

Finally, widgets must be realized; this step causes them to be displayed. (Realization is sepa 
rate from creation in order to allow all geometry negotiation between widgets to occur before 
anything is drawn.) To cause all widgets in an application to be realized, it is sufficient to 
realize the top-level widget with xtRealizeWidget. The Intrinsics recursively realize 
children before their parents. (See XtRealize, xtRealizeProc, and Core(3) for more 
on realization.) 



X Toolkit Intrinsics Reference Manual 



Most widgets are mapped automatically by virtue of having a mapped_when_managed 
Boolean set in the Core instance record. Otherwise, mapping can be controlled by xtMap- 
Widget and XtUnmapWidget. 

Before a widget can actually draw anything on the display, it must receive events telling it to 
do so. When an application calls xtMainLoop, the Intrinsics begin to process the events 
sent by the server and dispatch the appropriate handlers. This is how the widget s other 
methods get invoked: namely, they are called in response to some server event 

Most widgets are not explicitly destroyed. When a program exits and the connection is 
closed, the widget s data structures on the server vanish. 

1.1.1 Example Program 

The following program fragment is sufficient to create, manage, and display a single Label 
widget. 

tinclude <stdio.h> 
tinclude <Xll/Xlib.h> 
#include <Xll/Intrinsic.h> 
#include <Xll/StringDef s .h> 
linclude "Label. h" 

Arg args [ ] = { 

XtNlabel, (XtArgVal) "Stuff", 
}; 

main(argc, argv) 
int argc; 
char **argv; 

! < 

Widget toplevel, label; 
WidgetClass we; 
int i; 

toplevel = Xtlnitialize (argv[0] , "my-widget", NULL, 0, &argc, argv) 
we = labelWidgetClass; /* ... from widget include file */ 
I label = XtCreateManagedWidget (label, /* widget name */ 

we, /* widget class */ 

toplevel,/* parent widget*/ 

args, /* argument list*/ 

XtNumber (args) /* arglist size */ 
i ); 

fprintf (stderr, "status of creating label widget %d\n", label); 
XtRealizeWidget (toplevel) ; 
XtMainLoop ( ) ; 



Introduction 



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



X Toolkit Intrinsics Reference Manual 



Callbacks are described in detail with example code in Chapter 2, Introduction to the X 
Toolkit, in Volume Four, X Toolkit Intrinsics Programming Manual. 



1.4 Events 



In Xlib, all the synchronization between server and client is done with events. Events can 
range from input typed at the keyboard to notifications from the server that a window is now 
available to receive input. The Toolkit default event processor loop is invoked after widgets 
are created and realized (see Section 1.1, "Widget Lifecycle") by calling xtMainLoop. 

Using the X Toolkit, widgets can process events in one of two ways. The first way resembles 
the low-level X event mechanism. They can set up event handlers to capture events as they 
come in. To do this, a widget declares a handler with xtAddEventHandler and specifies 
the event mask that should cause the handler to be invoked. (This approach is discussed in 
depth in Chapter 8, More Input Techniques, in Volume Four, X Toolkit Intrinsics Program 
ming Manual. 

The second way involves setting up event translations for events. See Section 1.5, 
"Translations and Actions." 



1.5 Translations and Actions 



The translation manager allows an application or a widget to indicate interest in higher level 
user behavior. That is, instead of having to parse individual events in the widget, the widget 
can ask to be notified when the user performs a certain type of mouse click or types some 
thing in particular from the keyboard. 

Translations can also be overrided by an application program or a widget s subclass. 

MenuPopup and MenuPopdown are examples of translation actions that can be invoked 
directly. XtOverrideTranslations and Xt Augment Translations allow a 
widget s translations to be appropriately manipulated. 

Actions (the entities on the right-hand side of a translation) can also be added and aug 
mented, either for a particular widget or for the application at large. 

For more details, see Chapter 7, Events, Translations and Accelerators, in Volume Four, X 
Toolkit Intrinsics Programming Manual. 



Introduction 



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

To use a pop up, first a shell must be created with xtCreatePopupShell. Then it can be 
popped up specifically using xt Popup 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 explicitly 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 Initialize 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. 



X Toolkit Intrinsics Reference Manual 






The use of resources is not limited to widgets. Nonwidget structures can maintain lists of 
resources and make calls to the Intrinsics functions xtGetResourceList and XtGet- 
ApplicationResources explicitly to get the resource list updated from the resource 
database and the current execution context. 

The Intrinsics also allow extensive conversion of resources and their types. While most con 
versions are performed transparently, it is possible to use explicit conversion of resources 
profitably in data structures that are not widgets. 

1.7.1 Data Structures 

The resource data structure can be thought of as a template. It lists a set of names, default 
values, and offsets. Subsequently, values for a whole resource list can be determined with 
reference to a single base address. 

XtResource is defined in <X11 /Intrinsic. h>. 

typedef struct _XtResource { 

String resource_name; /* Resource name */ 

String resource_class /* Resource class */ 

String resource_type; /* Representation type desired */ 

Cardinal resource_size; /* Size in bytes of representation */ 

Cardinal resource_of f set; /* Offset from base to put resource value */ 

String default_type; /* Representation type of specified * 

* default */ 

caddr_t default_addr; /* Address of resource default value */ 

} XtResource, XtResourceList; 

The ArgList data structure is also defined there. ArgLists are used for taking values to 
and from a base offset resource list. In some Intrinsics routines, ArgLists also provide a 
set of values that can override whatever values the resource mechanism nominates. xtGet- 
Values and XtGetSubvalues returns its values in an ArgList. 

typedef struct { 

String name; 

XtArgVal value; 
} Arg, *ArgList; 

ArgVal is a typedef for a longword/pointer quantity. 

There are several routines that get and set resource values in widgets, resource data struc 
tures, and ArgLists. Since the names of the routines are not particularly mnemonic, Table 
1-2 below contrasts and summarizes the different functions. 

In the table, Rlist+Base indicates that a resource list is used to offset a base address to 
obtain the actual location for a value. This is how resources are stored in widgets, using the 
xtOf f set macro. 



Introduction 



Table 1-2. Overview of Resource Management Functions 



Procedure 


From 


To 


Used for/Lookup by 


XtSetValues 
XtGetValues 


ArgList 
Widget 


Widget 
ArgList 


Widget instance 
variables 


XtSetSubvalues 
XtGetSubvalues 


ArgList 
RList+Base 


RList+Base 
ArgList 


Nonwidget resources 


XtGetResourceList 


Resource Manager 


RList (defaults) 


Default values 


XtGetAppRe sources 
XtGetSubre sources 


Widget, ArgList 
Widget, ArgList 


RList+Base 
RList+Base 


By widget 
By name/class 



Each function can be looked up separately to understand the exact details of the routine. 

Routines to fetch values of resources, like xtGetApplicationResources, accept a 
list of resources and a base pointer. The portable and recommended way to access resources 
in a resource list is to declare a structure that contains fields for values and to pass a pointer 
to this structure as the base address. Then xtof f set can be used to determine the relative 
address of the field in the structure. 

Here is a short program that sets up a resource argument list and accesses it. 

/* res.c - access application resources */ 
#include <stdio.h> 

tinclude <Xll/Xlib.h> 
tinclude <Xll/StringDef s .h> 
#include <Xll/IntrinsicP .h> 
tinclude <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 [] = { 
{ 

XtN foreground, 
XtCForeground, 
XtRPixel, sizeof (Pixel) , 

XtOffset (instance_variables, foreground) , 
XtRString, "XtDefaultForeground" 



XtN font, 

XtCFont, 

XtRFontStruct, sizeof (XFontStruct *), 
XtOffset (instance_variables, font_struct) 
XtRString, "XtDefaultFont" 



10 



X Toolkit Intrinsics Reference Manual 



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; 

instance_variable_rec iv; 

toplevel = Xtlnitialize (av [0] , "my-widget", NULL, 0, &ac, av) 
XtGetApplicationResources (toplevel, /* widget */ 

&iv, /* base address */ 
resources, /* resource */ 
XtNumber (resources) ,/* how many */ 
NULL, 0); /* ArgList to merge */ 

printf ("label-%s\n", iv. label); 



1.7.2 Resource Names 

The complete resource name for a field of a widget instance is the concatenation of the appli 
cation name (from argv[0]) or the -name command-line option (see xtDisplay- 
initialize), the instance names of all the widget s parents, the instance name of the 
widget itself, and the resource name of the specified field of the widget. Likewise, the full 
resource class of a field of a widget instance is the concatenation of the application class 
(from xtAppCreateShell), the widget class names of all the widget s parents (not the 
superclasses), the widget class name of the widget itself, and the resource name of the speci 
fied field of the widget 

1.7.3 Resource Types 

Resource data types are represented as strings. The actual string definitions are in 
<XlllStringDefs.h> The data types represented by the string identifiers are described in 
Table 1-3 below. 

The type of a resource is specified by a string. Existing types include XtRString, xt- 
Rlnt, and XtRPointer. 



Introduction 1 1 



If an application needs to invent new data types, it merely must define a string to represent 
the data type. (See Volume Four, X Toolkit Intrinsics Programming Manual?) Just use a 
string of the form xtRMyType. 

For more information, see XtGetApplicationResources, XtGetResources, 
XtSetResources, XtSetValues, XtGetValues, XtSetSubvalues, and Xt- 
GetSubvalues. XtDisplaylnitialize describes more details of command line 
parsing. 

Table 1-3. Resource Types 



Resource Type Name 


Data Type 


Defined in <X11I ...> 


XtRAcceleratorTable 


Xt Accelerators 


Intrinsic.h 


XtRBoolean 


Boolean 


Intrinsic, h 


XtRBool 


Bool 


Xlib.h 


XtRCallback 


XtCallbackList 


Intrinsic.h 


XtRCallproc 


... 




XtRColor 


XColor 


Xlib.h 


XtRCursor 


Cursor 


X.h 


XtRD intension 


Dimension 


Intrinsic.h 


XtRDisplay 


Display 


Xlib.h 


XtRFile 


FILE* 


Xos.h 


XtRFloat 


float 


... 


XtRFont 


Font 


X.h 


XtRFontStruct 


XFontStruct * 


Xlib.h 


XtRFunction 


<*) () 




XtRImmediate 


... 




XtRInt 


int 




XtRPixel 


Pixel 


Intrinsic.h 


XtRPixmap 


Pixmap 


X.h 


XtRPointer 


caddr t 


. . . 


XtRPosition 


Position 


Intrinsic.h 


XtRShort 


short 


. . . 


XtRString 


char * 




XtRTranslationTable 


XtTranslations 


Intrinsic.h 


XtRUnsignedChar 


unsigned char 


. . . 


XtRWidget 


Widget 


Intrinsic.h 


XtRWindow 


Window 


X.h 



xtRCallProc and XtRImmediate are special cases; they can only be used as default 
values. Both of these resource types, by their very nature, defeat resource type checking and 
conversion. 

The XtRCallProc type allows a widget to specify a procedure to actually determine the 
default value of the resource at run time. The XtRCallProc procedure is invoked as an 
XtResourceDefaultProc. 



12 



X Toolkit Intrinsics Reference Manual 



The XtRlmmediate 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 -1X11 

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 


Resource 


Value 


Sets 


-bg 


*background 


next argument 


background color 


-background 


*background 


next argument 


background color 


-bd 


*borderColor 


next argument 


border color 


-bw 


.borderWidth 


next argument 


width of border in pixels 


-borderwidth 


.borderWidth 


next argument 


width of border in pixels 


-bordercolor 


*borderColor 


next argument 


co lor of border 


-display 


.display 


next argument 


server to use 


-fg 


*f oreground 


next argument 


foreground color 


-fn 


*font 


next argument 


font name 


-font 


*font 


next argument 


font name 


-foreground 


*f oreground 


next argument 


foreground color 


-geometry 


.geometry 


next argument 


size and position 


-iconic 


. iconic 


"on" 


start as an icon 


-name 


.name 


next argument 


name of application 


-reverse 


*reverseVideo 


"on" 


reverse video 


-rv 


* re verse Video 


"on" 


reverse video 


+rv 


*reverseVideo 


"off 


No Reverse Video 


-selectionTimeout 


. selectionTimeout 


Null 


selection timeout 


-synchronous 


. synchronous 


"on" 


synchronous debug mode 


asynchronous 


. synchronous 


"off 


synchronous debug mode 


-title 


.title 


next argument 


title of application 


-xrm 


value of argument 


next argument 


depends on argument 



Introduction 



13 



New entries can be added to the Intrinsics parsing table. This is discussed in Volume Four, 
X Toolkit Intrinsics Programming Manual. More extensive examples are also given there. 



1.8 Geometry Management 

Geometry management allows a widget to control the size and layout of other widgets. The 
controlling widget is called the parent, and the controlled widgets are called children. 

A parent becomes capable of siring children by being a subclass of Composite(3). The Com 
posite class provides several methods that are invoked when children are created, managed, 
and destroyed. 

A widget is managed when it is placed on its parent s list of widgets whose layout is con 
trolled explicitly by the parent An application can manage a widget by calling xt- 
ManageWidget or by creating it with XtCreateManagedWidget. A widget cannot 
be realized (i.e., given an actual window) or mapped (positioned on the display) until it is 
managed. 

Most widgets are mapped_when_managed. That means, when they are put under parental 
management, they will subsequently be mapped without any further intervention; the core 
set_mapped_when_managed Boolean can be set explicitly with xtSetMapped- 
WhenManaged. Widgets that are not mapped when managed must call xtMapWidget 
explicitly. In any case, a widget cannot safely perform output until the X Server sends an 
Expose event, which will in turn cause the Intrinsics to invoke the child widget s Redraw 
method. 

Geometry management is asymmetrical and can be considered from either the perspective of 
the child or the perspective of the parent The following sections describe geometry manage 
ment from both perspectives, with reference to the Composite(3) class methods used in each 
case. In the following discussion, a reference to a "composite widget" (note the lower-case 
c) means "a widget that is a subclass of Composite, whereas a reference to the class 
"Composite" means the actual Composite class. 

1.8.1 Parent s Perspective 

The Intrinsics invoke a parent s insert_child method when the application creates a 
child widget. When the application manages the child, the Intrinsics invoke the 
change_managed method. The Intrinsics invoke the geometry_manager method to 
lay out the widget s children. 

The geometry_manager can then determine the layout of its children as it sees fit. It 
sets the actual values of its core values using xtConf igurewidget, xtResize- 
Widget, or XtMoveWidget. 

The insert and delete routines are of type xtwidgetProc(2). 



14 X Toolkit Intrinsics Reference Manual 



To remove the child from the parent s children array, the XtDestroyWidget function 
eventually causes a call to the composite parent s class delete_child method. A 
delete_chi Id method is of type XtWidgetProc(2). 

Most widgets inherit the delete_child method from their superclass. Composite wid 
gets that create companion widgets define their own delete_child method to remove 
these companion widgets. 

To add a child to the parent s list of children, the xtCreateWidget function calls the par 
ent s class routine insert_child. The insert_child method for a composite widget 
is of type XtwidgetProc(2). 

Most composite widgets inherit their superclass s operation. The Composite class s 
insert_child method calls the insert_position method and inserts the child at 
the specified position. 

Some composite widgets define their own insert_child method so that they can order 
their children in some convenient way, create companion controller widgets for a new 
widget, or limit the number or type of their children widgets. 

If there is not enough room to insert a new child in the children array (that is, 
num_children = num_slots), the insert_child method must first reallocate the 
array and update num_slots. The insert_child method then places the child wher 
ever it wants and increments the num_children field. 

Instances of composite widgets may need to specify 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 alphabet 
ical order. 

Composite widgets that allow clients to order their children (usually homogeneous boxes) 
can call their widget instance s insert_position method from the class s 
insert_child method to determine where a new child should go in its children array. 
Thus, a client of a composite class can apply different sorting criteria to widget instances of 
the class, passing in a different insert_position method when it creates each compos 
ite widget instance. 

The return value of the insert_j)osition method indicates how many children should 
go before the widget. Returning zero means before all other children, and returning 
num_children means after all other children. The default insert_position func 
tion 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. 



1.8.2 Child s Perspective 

The child widget uses xtMakeGeometryRequest to petition its parent to change its 
geometry. For simplified cases, the child can use XtMakeResizeRequest. 

Some parents may be more democratic than others. More open-minded parents can find out a 
child s ambitions by using XtQueryGeometry. Calling XtQueryGeometry triggers a 



Introduction 15 



call to the Core query_geometry method. The parent is not bound by any of its child s 
suggestions. 

A child s query_geometry method is expected to examine the bits set in: 

intended->request_mode , 

evaluate the preferred geometry of the widget, and store the result in 
pref erred_return (setting the bits in: 

pref erred_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 pref erred_return is different from the corre 
sponding field in intended or if a bit was set in pref erred_return that was not set in 
intended, the query_geometry method should return XtGeometryAlmost. If the 
preferred geometry is identical to the current geometry, the query_geometry method 
should return xtGeometryNo. After calling the query_geometry method or if the 
query_geometry field is NULL, XtQueryGeometry examines all the unset bits in: 

pref err ed_return->request_mode 

and sets the corresponding fields in pref erred_return to the current values from the 
widget instance. If StackMode is not set, the stack_mode field is set to xtSMDont- 
Change. XtQueryGeometry returns the value returned by the query_geometry 
method or Xt Geometry Yes if the query_geometry 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 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 inter 
est 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 procedure. 

1.8.3 Constraint Widgets 

A constraint widget (a subclass of Constraint(3)) is a widget class that allows the parent to 
provide per-child data in the child widget structure. The parent can use this as an aid in lay 
ing out the children or for some application-dependent funcion. The per-child data is main 
tained as resources and is transparent to the child itself. 



16 X Toolkit Intrinsics Reference Manual 



The constraint structure itself adds several new fields. The constraint class itself adds a 
resource set which gets propagated to its children. There are also const raint_init, 
constraint_destroy, and constraint_set_values methods which are 
invoked. They are passed the child widget 

The values passed to the parent constraint initialization procedure are the same as those 
passed to the child s class widget initialization procedure. 

The constraint initialization procedure should compute any constraint fields derived from 
constraint resources. It can make further changes to the widget to make the widget conform 
to the specified constraints, for example, changing the widget s size or position. 

If a constraint class does not need a constraint initialization procedure, it can specify NULL 
for the initialize field of the Const raintClassPart in the class record. 

The constraint destroy procedure is retrieved from the destroy field of the structure, is called 
for a widget whose parent is a subclass of constraintwidgetClass, and is of type 
xtwidgetProc. The constraint destroy procedures are called in subclass-to-superclass 
order, starting at the widget s parent and ending at constraintwidgetClass. There 
fore, a parent s constraint destroy procedure only should deallocate storage that is specific to 
the constraint subclass and not the storage allocated by any of its superclasses. 

If a parent does not need to deallocate any constraint storage, the constraint destroy proce 
dure entry in its class record can be NULL. 

1.8.4 Related Discussion 

Detailed examples of widgets that do geometry management, and use constraints, are 
presented in Chapter 11, Geometry Management, in Volume Four, X Toolkit fntrinsics Pro 
gramming Manual. See also Composite(3) and Constraint(3). 



1.9 Xlib Interface 

The X Toolkit relies on underlying Xlib structures of Windows, Displays, and Screens to per 
form input and output 

A widget performs output by using Xlib calls to draw graphics and text A widget maintains 
Xlib structures in Core instance variables. To simplify access whenever an Xlib structure is 
used, <X11 /Intrinsic. h> provides macros (for widget implementors) and functions (for widget 
users). 

In particular, see XtDisplay, Xtwindow, and xtScreen. The dimensions of the 
widget s window can be obtained from Core instance variables. Other data structures that a 
widget might need to perform its particular function more efficiently can be put in the widget 
data structures. 



Introduction 17 



The Intrinsics also provide a scheme to improve the efficiency of Graphics Contexts. See 
also xtGetGC and xtDestroyGC. Examples using these functions are presented in Vol 
ume Four. 



Mark Langley 



X Toolkit 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 right 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 right for the name of the 
relevant command page. 



The Permuted Index 



internal/ /compile an accelerator table into its XtParseAcceleratorTable(l ) 

its descendants/ /install all accelerators from a widget and XtlnstallAllAccelerators(l) 

/install a widget s accelerators on another widget XtlnstallAccelerators(l) 

/prototype procedure to accept or reject keyboard focus ... . XtAcceptFocusProc(2) 

/call a widget s accept_focus procedure XtCallAcceptFocus(l) 

XtResize Window: resize a widget according to the values of its/ XtResizeWindow(l) 

MenuPopdown: built-in action for popping down a widget ........... MenuPopdown(l) 

MenuPopup: built-in action for popping up a widget MenuPopup(l ) 

XtApp Add Actions: declare an action table and register it/ XtAppAddActions(l ) 

XtAdd Actions: register an action table with the/ XtAddActions(l) 

procedure for registering action tables /prototype XtActionProc(2) 

/command button activated by pointer click Command(4) 

widget s/ XtAddCallback: add a callback procedure to a XtAddCallback(l ) 

context /open, initialize, and add a display to an application XtOpenDisplay(l) 

procedures to a/ XtAddCallbacks: add a list of callback XlAddCallbacks(l) 

list of managed/ XtManageChild: add a widget to its parent s XtManageChild(l ) 

/initialize a display and add it to an application context XtDisplaylnitialize(l) 

list of/ XtManageChildren: add widgets to their parent s XtManageChildren(l) 

XtAppCreateShell: create additional top-level widget XtAppCreateShell(l ) 

/create an additional top-level widget XtCreateApplicationShell(l) 

elements to zero XtCalioc: allocate an array and initialize XtCalloc(l) 



Permuted Index 19 



instance of a data type XtNew: 

XtMalloc: 

XtFree: free an 

XtRealloc: change the size of an 

XtRemovelnput: cancel source of 

/called by the Intrinsics when 

scrolling of viewing area in 

a widget s accelerators on 

its displays /destroy an 

widget /get the 

a display and remove it from an 
/create an 

a display and add it to an 

and add a display to an 

window/ Shell Widget Class: 

file as an input source for an 

register a work procedure for an 

a new resource converter for an 

as an input source for a given 

a work procedure for a given 

process input from a given 

base-offset resource list (by 

/return next event from an 

/examine the head of an 

/if there are any events in an 

/examine the head of an 

/if there are any events in an 

to control scrolling of viewing 

XtMergeArgLists: merge two 

list XtSetSubvalues: copy from 

XtSetValues: copy resources from 

XtSetArg: construct or modify an 

base-offset resource list to the 

resources from a widget to the 

zero XtCalloc: allocate an 

of elements in a fixed-size 

when requested selection data 

descendants /destroy the windows 

other widgets gripWidgetClass: 

/user input from modal widget 

XtWorkProc: perform 

application) /update 

name/ XtGetSubresources: update 

XtGetSubvalues: copy from 

/copy from ArgList to 

XtFree: free an allocated 

change the size of an allocated 

XtStringConversion Warning: emit 

geometry -managing 

dialog WidgetClass: dialog 

geometry-managing box widget 

a widget MenuPopdown: 

widget MenuPopup: 

commandWidgetClass: command 

XtOffset: determine the 

perform resource conversion and 

procedure XtCallAcceptFocus: 

handler XtAppErrorMsg: 



allocate storage for one XtNew(l) 

allocate storage XtMalloc(l) 

allocated block of storage XtFree(l) 

allocated block of storage XtRealloc(l) 

alternate input events XtRemovelnput(l) 

another client claims the/ XtLoseSelectionProc(2) 

another widget Ao control Scrollbar(4) 

another widget /install XtlnstallAccelerators(l) 

application context and close XtDestroyApplicationContext(l) 

application context for a given XtWidgetToApplicationContext(l) 

application context /close XtCloseDisplay(l) 

application context XtCreateApplicationContext(l) 

application context /initialize XtDisplaylnitialize(l) 

application context /initialize, XtOpenDisplay(l) 

application resources linking Shell(3) 

application /register a new XtAddlnput(l) 

application XtAddWorkProc: XtAddWorkProc(l) 

application /register XtAppAddConverter(l) 

application /register a new file XtAppAddlnput(l) 

application /register XtAppAddWorkProc(l) 

application XtAppMainLoop: XtAppMainLoop(l) 

application) /update XtGetApplicationResources(l) 

application s input queue XtAppNextEvent(l) 

application s input queue XtAppPeekEvent(l) 

application s input queue XtAppPending(l) 

application s input queue XtPeekEvent(l) 

application s input queue XtPending(l) 

area in another widget /widget Scrollbar(4) 

ArgList structures XtMergeArgLists(l) 

ArgList to base-offset resource XtSetSubvalues(l) 

ArgList to widget XtSetValues(l) 

argument list dynamically XtSetArg(l) 

argument list /copy from XtGetSubvalues(l) 

argument list XtGetValues: copy XtGetValues(l) 

array and initialize elements to XtCalloc(l) 

array /determine the number XtNumber(l) 

arrives /procedure called XtSelectionCallbackProc(2) 

associated with a widget and its XtUnrealizeWidget(l) 

attachment point for dragging Grip(4) 

back to normal destination XtRemoveGrab(l) 

background processing XtWorkProc(2) 

base-offset resource list (by XtGetApplicationResources(l) 

base-offset resource list (by XtGetSubresources(l) 

base-offset resource list to the/ XtGetSubvalues(l) 

base-offset resource list XtSetSubvalues(l) 

block of storage XtFree(l) 

block of storage XtRealloc: XtRealloc(l) 

boilerplate string conversion/ XtStringConversion Warning(l) 

box widget boxWidgetClass: Box(4) 

Box widget Dialog(4) 

boxWidgetClass: Box(4) 

built-in action for popping down MenuPopdown(l) 

built-in action for popping up a MenuPopup(l) 

button activated by pointer/ Command(4) 

byte offset of a field within a/ XtOffset(l) 

cache result XtDirectConvert: XtDirectConvert(l) 

call a widget s accept_focus XtCallAcceptFocus(l) 

call the high-level fatal error XtAppErrorMsg(l) 



20 



X Toolkit Intrinsics Reference Manual 



handler XtErrorMsg: call the high-level fatal error XtErrorMsg(l) 

procedure XtAppError: call the installed fatal error XtAppError(l) 

warning/ XtAppWarningMsg: call the installed high-level XtAppWamingMsg(l) 

warning handler XtWarningMsg: call the installed high-level XtWamingMsg(l) 

warning handler XtWarning: call the installed low-level XtWaming(l) 

error procedure XtApp Warning: call the installed nonfatal XtAppWarning(l) 

handler XtError: call the low-level fatal error XtError(l) 

widget XtCallbackExclusive: callback function to pop up a XtCallbackExclusive(l) 

widget. XtCallbackNone: callback function to pop up a XtCallbackNone(l) 

widget. XtCallbackNonexclusive: callback function to pop up a XtCallbackNonexclusive(l) 

procedures to a given widget s callback list /list of callback XtAddCaUbacks(l ) 

the procedures in a widget s callback list /execute XtCallCallbacks(l) 

the status of a widget s callback list /determine XtHasCallbacks(l ) 

/delete all procedures from a callback list XtRemoveAllCallbacks(l) 

delete a procedure from a callback list XtRemoveCallback: XtRemoveCallback(l) 

a list of procedures from a callback list /delete XtRemoveCallbacks(l) 

XtTimerCallbackProc: prototype callback procedure invoked when/ XtTimerCallbackProc(2) 

callback/ XtAddCallback: add a callback procedure to a widget s XtAddCallback(l) 

XtCallbackProc: prototype callback procedure XtCallbackProc(2) 

XtAddCallbacks: add a list of callback procedures to a given/ XtAddCallbacks(l) 

callback procedure to a widget s callback resource /add a XtAddCallback(l) 

/pop down a widget from a callback routine XtCallbackPopdown(l) 

completes /prototype procedure called after a data transfer XtSelectionDoneProc(2) 

another/ /prototype procedure called by the Intrinsics when XtLoseSelectionProc(2) 

/register a procedure to be called on fatal error conditions XtAppSetErrorHandler(l ) 

/register a procedure to be called on fatal error conditions XtAppSetErrorMsgHandler(l) 

/register a procedure to be called on fatal error conditions XtSetErrorHandler(l) 

/register a procedure to be called on nonfatal error/ XtAppSetWamingHandler(l) 

/register a procedure to be called on nonfatal error/ Xt AppSetWamingMsgHandler( 1 ) 

/register a procedure to be called on nonfatal error/ XtSetErrorMsgHandler(l) 

/register a procedure to be called on nonfatal error/ XtSetWamingHandler(l) 

/a high-level procedure to be called on nonfatal error/ XtSetWamingMsgHandler(l) 

XtCaseProc: prototype procedure called to convert the case of/ XtCaseProc(2) 

/prototype procedure called to handle file events XtInputCallbackProc(2) 

data/ /prototype procedure called when requested selection XtSelectionCallbackProc(2) 

/prototype procedure called when widget is realized XtRealizeProc(2) 

events XtRemovelnput: cancel source of alternate input XtRemovelnput(l) 

/register a case converter XtRegisterCaseConverter(l) 

procedure called to convert the case of keysyms /prototype XtCaseProc(2) 

/request parent to change child s geometry XtMakeGeometryRequest(l) 

/request parent to change child s size XtMakeResizeRequest(l) 

block of storage XtRealloc: change the size of an allocated XtRealloc(l ) 

XtSetMappedWhenManaged: change the value of a widget s/ XtSetMappedWhenManaged(l) 

state of a/ XtlsSensitive: check the current sensitivity XtlsSensitive(l) 

XtResize Widget: resize a child or sibling widget XtResizeWidget(l) 

/create and manage a child widget XtCreateManagedWidget(l) 

/redirect keyboard input to a child widget XtSetKeyboardFocus(l ) 

XtQueryGeometry: query a child widget s preferred/ XtQueryGeometry(l) 

implementing constraints on children /widget Form(4) 

managed list /remove a list of children from a parent widget s XtUnmanageChildren(l) 

/procedure for ordering the children of composite widget/ XtOrderProc(2) 

to its parent s list of managed children /add a widget XtManageChild(l) 

their parent s list of managed children /add widgets to XtManageChildren(l) 

/request parent to change child s geometry XlMakeGeometryRequest(l ) 

/request parent to change child s size XtMakeResizeRequest(l) 

Intrinsics when another client claims the selection /by the XtLoseSelectionProc(2) 

linking window/ Shell Widget Class: application resources Shell(3) 

geometry/ Composite Widget Class: defines methods for Composite(3) 



Permuted Index 2 1 



widget Core Widget Class: fundamental, top-level Core(3) 

for a/ Constraint Widget Class: provides data structures Constraint(3) 

in DEBUG mode, verify a widget s class XtCheckSubclass: XtCheckSubclass(l) 

XtClass: obtain a widget s class XtClass(l) 

method used in Core widget class /prototype expose XtExposeProc(2) 

resource list (by name or class) /update base-offset XtGetSubresources(l) 

procedure for a widget class /prototype initialize XtInitProc(2) 

subclass of the Composite widget class /whether a widget is a XtlsComposite(l) 

of the Constraint widget class /a widget is a subclass XtlsConstraint(l) 

a subclass of the Shell widget class /test whether a widget is XtlsShell(l) 

a widget is a subclass of a class /determine whether XtlsSubclass(l) 

to initialize data for a widget class /prototype procedure XtProc(2) 

XtRemoveTimeOut: clear a timeout value XtRemoveTimeOut(l ) 

button activated by pointer click /command Command(4) 

/by the Intrinsics when another client claims the selection XtLoseSelectionProc(2) 

from an/ XtCloseDisplay: close a display and remove it XtCloseDisplay(l) 

an application context and close its displays /destroy XtDestroyApplicationContext(l) 

pointer/ commandWidgetClass: command button activated by Command(4) 

button activated by pointer/ commandWidgetClass: command Command(4) 

widget methods XtWidgetProc: common prototype procedure for XtWidgetProc(2) 

XtDestroyGC: Release 2 compatible function to free up/ XtDestroyGC(l) 

its/ XtParseTranslationTable: compile a translation table into XtParseTranslationTable(l) 

into/ XtParseAcceleratorTable: compile an accelerator table XtParseAcceleratorTable(l) 

XtGetSelection Value: obtain the complete selection data XtGetSelectionValue(l) 

called after a data transfer completes /prototype procedure XtSelectionDoneProc(2) 

methods for geometry management Composite Widget Class: defines Composite(3) 

a widget is a subclass of the Composite widget class /whether XtlsComposite(l) 

/for ordering the children of composite widget instances XtOrderProc(2) 

to be called on fatal error conditions /register a procedure XtAppSetErrorHandler(l) 

to be called on fatal error conditions /register a procedure XtAppSetErrorMsgHandler(l) 

to be called on nonfatal error conditions /register a procedure XtAppSetWarningHandler(l) 

to be called on nonfatal error conditions, /a procedure XtAppSetWamingMsgHandler(l) 

to be called on fatal error conditions /register a procedure XtSetErrorHandler(l) 

to be called on nonfatal error conditions /register a procedure XtSetErrorMsgHandler(l) 

to be called on nonfatal error conditions /register a procedure XtSetWamingHandler(l) 

to be called on nonfatal error conditions /high-level procedure XtSetWarningMsgHandler(l) 

provides data structures for a/ Constraint Widget Class: Constraint(S) 

a widget is a subclass of the Constraint widget class /whether XtlsConstraint(l) 

/widget implementing constraints on children Form(4) 

list dynamically XtSetArg: construct or modify an argument XtSetArg(l) 

/destroy an application context and close its displays XtDestroyApplicationContext(l) 

/get the application context for a given widget XtWidgetToApplicationContext(l) 

remove it from an application context /close a display and XtCloseDisplay(l) 

/create an application context XtCreateApplicationContext(l) 

and add it to an application context /initialize a display XtDisplaylnitialize(l) 

add a display to an application context /open, initialize, and XtOpenDisplay(l) 

XtMainLoop: continuously process events XtMainLoop(l) 

scrollbarWidgetClass: widget to control scrolling of viewing/ Scrollbar(4) 

/perform resource conversion and cache result XtDirectConvert(l) 

/emit boilerplate string conversion error message XtStringConversionWaming(l) 

XtConvert: convert resource type XtConvert(l) 

/prototype procedure called to convert the case of keysyms XtCaseProc(2) 

/register a new resource converter for an application XtAppAddConverter(l ) 

/procedure passed as a resource converter of type XtRCallProc XtResourceDefaullProc(2) 

/prototype of a resource converter procedure XtConverter(2) 

register a new resource converter XtAddConverter: XtAddConverter(l) 

/register a case converter XtRegisterCaseConverter(l ) 

coordinates to/ /translate an x-y coordinate pair from widget XtTranslateCoords(l) 



22 



X Toolkit Intrinsics Reference Manual 



/x-y coordinate pair from widget coordinates to root coordinates . XtTranslateCoords(l ) 

from widget coordinates to root coordinates /x-y coordinate pair XtTranslateCoords(l) 

XtNewString: copy an instance of a string XtNewString(l) 

resource list XtSetSubvalues: copy from ArgList to base-offset XtSetSubvalues(l) 

list to the/ XtGetSubvalues: copy from base-offset resource XtGetSubvalues(l) 

the argument list XtGet Values: copy resources from a widget to XtGetValues(l) 

widget XtSet Values: copy resources from ArgList to XtSetValues(l) 

according to the values of its core dimensions /resize a widget XtResizeWindow(l) 

top-level widget Core Widget Class: fundamental, Core(3) 

prototype expose method used in Core widget class XtExposeProc: XlExposeProc(2) 

template WidgetClass: widget to create a custom widget Template(4) 

XtCreatePopupShell: create a pop-up shell XtCreatePopupShell(l) 

XtAddTimeOut: create a timeout value XtAddTimeOut(l) 

widget XtAppCreateShell: create additional top-level XtAppCreateShell(l) 

XtCreateApplicationShell: create an additional top-level/ XtCreateApplicationShell(l) 

XtCreateApplicationContext: create an application context XtCreateApplicationContext(l) 

XtCreate Widget: create an instance of a widget XtCreateWidget(l) 

XtCreateManagedWidget: create and manage a child widget XtCreateManagedWidget(l) 

XtCreate Window: create widget s working window XtCreateWindow(l) 

/get the current selection timeout value XtAppGetSelectionTimeout(l) 

XtGetSelectionTimeout: get the current selection timeout value XtGetSelectionTimeout(l) 

widget XtlsSensitive: check the current sensitivity state of a XtlsSensitive(l) 

XtTranslateKey: invoke the currently registered/ XtTranslateKey(l) 

XtTranslateKeycode: invoke the currently registered/ XtTranslateKeycode(l) 

/widget to create a custom widget Template(4) 

called when requested selection data arrives /procedure XtSelectionCallbackProc(2) 

/procedure to initialize data for a widget class XtProc(2) 

/obtain selection data in multiple formats XtGetSelectionValues(l) 

/indicate that selection data is available XtOwnSelection(l) 

/indicate that selection data is no longer available XtDisownSelection(l) 

parent /Widget Class: provides data structures for a widget s Constraint(3) 

/procedure called after a data transfer completes XtSelectionDoneProc(2) 

storage for one instance of a data type XtNew: allocate XtNew(l) 

procedure to return selection data /prototype XtConvertSelectionProc(2) 

obtain the complete selection data XtGetSelection Value: XtGetSelectionValue(l) 

XtDataha.se: obtain the resource database for a particular/ XtDatabase(l) 

warning /obtain the error database text for an error or a XtAppGetErrorDatabaseText(l) 

warning /obtain the error database text for an error or a XtGetErrorDatabaseText(l) 

obtain the error database XtAppGetErrorDatabase: XtAppGetErrorDatabase(l) 

obtain the error database XtGetErrorDatabase: XtGet HrrorDatabase(l) 

is no longer/ XtReleaseGC: deallocate a shared GC when it XtReleaseGC(l) 

class XtCheckSubclass: in DEBUG mode, verify a widget s XtCheckSubclass(l) 

register it/ XtApp Add Actions: declare an action table and XtAppAddActions(l) 

XtGetResourceList: retrieve default values for a resource/ XtGetResourceList(l) 

Composite Widget Class: defines methods for geometry/ Composite(S) 

a callback/ XtRemoveCallbacks: delete a list of procedures from XtRemoveCallbacks(l) 

callback list XtRemoveCallback: delete a procedure from a XtRemoveCallback(l) 

callback/ XtRemoveAUCallbacks: delete all procedures from a XtRemoveAllCallbacks(l) 

/from a widget and its descendants onto a destination XtlnstallAllAccelerators(l) 

associated with a widget and its descendants /destroy the windows XtUn realize Widget(l) 

and its descendants onto a destination /from a widget XtlnstallAllAccelerators(l) 

from modal widget back to normal destination /redirect user input XtRemoveGrab(l) 

XtDestroy Widget: destroy a widget instance XtDestroyWidget(l) 

XtDestroyApplicationContext: destroy an application context/ XtDestroy ApplicationContext(l) 

with a/ XtUnrealize Widget: destroy the windows associated XtUnrealizeWidget(l) 

events in an/ XtAppPending: determine if there are any XtAppPending(l) 

events in an/ XtPending: determine if there are any XtPending(l) 

field within a/ XtOffset: determine the byte offset of a XtOffset(l) 



Permuted Index 



23 



in a fixed-size array XtNumber: determine the number of elements XtNumber(l) 

widget s/ XtHasCallbacks: determine the status of a XtHasCallbacks(l) 

lower-case/ XtConvertCase: determine upper-case and XtConvertCase(l) 

been realized XtlsRealized: determine whether a widget has XtlsRealized(l) 

subclass of a/ XtlsSubclass: determine whether a widget is a XtlsSubclass(l) 

managed by its/ XtlsManaged: determine whether a widget is XtlsManaged(l) 

dialog WidgetClass: dialog Box widget Dialog(4) 

widget dialog WidgetClass: dialog Box Dialog (4) 

to the values of its core dimensions /a widget according XtResizeWindow(l) 

an event XtDispatchEvent: dispatch registered handlers for XtDispatchEvent(l) 

labelWidgetClass: widget to display a non-editable string Label(4) 

application/ /initialize a display and add it to an XtDisplaylnitialize(l) 

XtCloseDisplay : close a display and remove it from an/ XtCloseDisplay(l ) 

specified/ XtDisplay: return the display pointer for the XtDisplay(l) 

instance /translate a window and display pointer into a widget XtWindowToWidget(l) 

/open, initialize, and add a display to an application/ XtOpenDisplay(l) 

database for a particular display /obtain the resource XtDatabase(l) 

initialize toolkit and display Xtlnitialize: Xtlnitialize(l) 

XtMap Widget: map a widget to its display XtMapWidget(l) 

move a widget on the display XtMoveWidget: XtMoveWidget(l) 

/prototype procedure for display_accelerator method XtStringProc(2) 

context and close its displays /destroy an application XtDestroyApplicationContext(l) 

routine XtCallbackPopdown: pop down a widget from a callback XtCallbackPopdown(l) 

built-in action for popping down a widget MenuPopdown: MenuPopdown(l) 

/attachment point for dragging other widgets Grip(4) 

or modify an argument list dynamically XtSetArg: construct XtSetArg(l) 

/determine the number of elements in a fixed-size array XtNumber(l) 

allocate an array and initialize elements to zero XtCalloc: XtCalloc(l) 

XtStringConversion Warning: emit boilerplate string/ XtStringConversionWarning(l) 

/prototype for low-level error and warning handlers XtErrorHandler(2) 

/prototype for high-level error and warning handlers XtErrorMsgHandler(2) 

procedure to be called on fatal error conditions /register a XtAppSetErrorHandler(l) 

procedure to be called on fatal error conditions /register a XtAppSetErrorMsgHandler(l) 

to be called on nonfatal error conditions /a procedure XtAppSetWarningHandler(l) 

to be called on nonfatal error conditions, /a procedure XtAppSetWamingMsgHandler(l) 

procedure to be called on fatal error conditions /register a XtSetErrorHandler(l) 

to be called on nonfatal error conditions /a procedure XtSetErrorMsgHandler(l) 

to be called on nonfatal error conditions /a procedure XtSetWarningHandler(l) 

to be called on nonfatal error conditions /procedure XtSetWarningMsgHandler(l) 

or a warning /obtain the error database text for an error XtAppGetErrorDatabaseText(l) 

or a warning /obtain the error database text for an error XtGetErrorDatabaseText(l) 

/obtain the error database XtAppGetErrorDatabase(l) 

XlGetErrorDatabase: obtain the error database XtGetErrorDatabase(l) 

call the high-level fatal error handler XtAppErrorMsg: XtAppErrorMsg(l ) 

call the low-level fatal error handler XtError: XtError(l) 

call the high-level fatal error handler XtErrorMsg: XtErrorMsg(l) 

boilerplate string conversion error message /emit XtStringConversion Warning(l) 

the error database text for an error or a warning /obtain XtAppGetErrorDatabaseText(l) 

the error database text for an error or a warning /obtain XtGetErrorDatabaseText(l) 

call the installed fatal error procedure XtAppError: XtAppError(l) 

call the installed nonfatal error procedure XtApp Warning: XtAppWaming(l) 

XtAppNextEvent: return next event from an application s/ XtAppNextEvent(l) 

XtNextEvent: return next event from input queue XtNextEvent(l) 

for the event /register an event handler without selecting XtAddRawEventHandler(l ) 

/remove a previously registered event handler XtRemoveEventHandler(l) 

/remove a raw event handler XtRemoveRawEventHandler(l) 

retrieve a widget s event mask XtBuildEventMask: XtBuildEventMask(l) 

without selecting for the event /register an event handler XtAddRawEventHandler(l) 



24 



X Toolkit Intrinsics Reference Manual 



process one input event XtAppProcessEvent: ...................... XtAppProcessEvent(l) 

registered handlers for an event XtDispatchEvent: dispatch XtDispatchEvent(l) 

process one input event XtProcessEvent: XtProcessEvent(l) 

/determine if there are any events in an application s input/ XtAppPending(l) 

/determine if there are any events in an application s input/ XtPending(l) 

/merge Expose and Graphics Hxpose events into a region XtAddExposureToRegion(l) 

register a procedure to handle events XtAddEventHandlen XtAddEventHandler(l) 

procedure to handle input events /prototype XtEventHandler(2) 

procedure called to handle file events /prototype XtInputCallbackProc(2) 

XtMainLoop: continuously process events XtMainLoop(l) 

cancel source of alternate input events XtRemovelnput: XtRemovelnput(l) 

XtAppPeekEvent: nondestructively examine the head of an/ XtAppPeekEvent(l) 

XtPeekEvent: nondestructively examine the head of an/ XtPeekEvent(l) 

widget s/ XtCallCallbacks: execute the procedures in a XtCallCallbacks(l) 

new translations with widget s existing ones /merge XtAugmentTranslations(l) 

overwriting widget s existing ones /new translations, XtOverrideTranslations(l) 

XtUninstallTranslations: remove existing translations XtUninstallTranslations(l) 

procedure invoked when timeouts expire /prototype callback XtTimerCallbackProc(2) 

XtUnmap Widget: unmap a widget explicitly XtUnmapWidget(l) 

XtAddExposureToRegion: merge Expose and GraphicsExpose events/ XtAddExposureToRegion(l) 

widget/ XtExposeProc: prototype expose method used in Core XtExposeProc(2) 

a procedure to be called on fatal error conditions /register XtAppSetErrorHandler(l ) 

a procedure to be called on fatal error conditions /register XtAppSetErrorMsgHandler(l) 

a procedure to be called on fatal error conditions /register XtSetErrorHandler(l) 

/call the high-level fatal error handler Xt AppErrorMsg(l ) 

XtError: call the low-level fatal error handler XtError(l) 

XtErrorMsg: call the high-level fatal error handler XtErrorMsg(l) 

XtAppError: call the installed fatal error procedure XtAppError(l ) 

/determine the byte offset of a field within a structure XtOffset(l) 

of a widget s map_when_managed field /change the value XtSetMappedWhenManaged(l) 

XtAppAddlnput: register a new file as an input source for a/ XtAppAddlnput(l) 

XtAddlnput: register a new file as an input source for an/ XtAddlnput(l) 

procedure called to handle file events /prototype XtInputCallbackProc(2) 

the number of elements in a fixed-size array /determine XtNumber(l) 

to accept or reject keyboard focus /prototype procedure XtAcceptFocusProc(2) 

selection data in multiple formats /obtain XtGetSelectionValues(l) 

geometry-managing widget/ formWidgetClass: Form(4) 

storage XtFree: free an allocated block of XtFree(l) 

/Release 2 compatible function to free up read-only GCs XtDestroyGC(l) 

GCs /Release 2 compatible function to free up read-only XtDestroyGC(l) 

XtCallbackExclusive: callback function to pop up a widget XtCallbackExclusive(l) 

XtCallbackNone: callback function to pop up a widget XtCallbackNone(l) 

XtCallbackNonexclusive: callback function to pop up a widget XtCallbackNonexclusive(l) 

Core Widget Class: fundamental, top-level widget Core(3) 

XtReleaseGC: deallocate a shared GC when it is no longer needed XtReleaseGC(l) 

obtain a read-only, sharable GC XtGetGC: XtGetGC(l) 

function to free up read-only GCs /Release 2 compatible XtDestroyGC(l) 

widget for managing row-column geometry listWidgetClass: List(4) 

Class: defines methods for geometry management /Widget Composite(3) 

/scrollable widget for geometry management Viewport(4) 

/prototype procedure to handle geometry requests XtGeometryHandler(2) 

request parent to change child s geometry XtMakeGeometryRequest: XtMakeGeometryRequest(l) 

query a child widget s preferred geometry XtQueryGeometry: XtQueryGeometry(l) 

boxWidgetClass: geometry -managing box widget Box(4) 

vertical/ vPanedWidgetClass: geometry-managing widget for VPaned(4) 

implementing/ formWidgetClass: geometry-managing widget Form(4) 

a/ XtWidgetToApplicationContext: get the application context for XtWidgelToApplicationContext(l) 

XtAppGetSelectionTimeout: get the current selection/ XtAppGetSelectionTimeout(l ) 



Permuted Index 



25 



timeout/ XtGetSelectionTimeout: get the current selection ............................ XtGetSelectionTimeout(l) 

/prototype procedure for get_values_hook method .......................... XtArgsProc(2) 

region /merge Expose and Graphics Expose events into a XlAddExposureToRegion(l) 

point for dragging other/ gripWidgetClass: attachment Grip(4) 

/register a procedure to handle events XtAddEventHandler(l) 

/prototype procedure called to handle file events XtLiputCallbackProc(2) 

/prototype procedure to handle geometry requests XtGeometryHandler(2) 

/prototype procedure to handle input events XtHventI Iandlcr(2) 

the event /register an event handler without selecting for XtAddRawEventHandler(l) 

call the high-level fatal error handler XtAppErrorMsg: XtAppErrorMsg(l) 

the installed high-level warning handler XtAppWamingMsg: call XtAppWarningMsg(l) 

call the low-level fatal error handler XtError: XtError(l) 

call the high-level fatal error handler XtErrorMsg: XtErrorMsg(l) 

a previously registered event handler /remove XtRemoveEventHandler(l) 

/remove a raw event handler XtRemoveRawEventHandler(l) 

the installed low-level warning handler XtWaming: call XtWaming(l) 

the installed high-level warning handler XtWarningMsg: call XtWamingMsg(l) 

/dispatch registered handlers for an event XtDispatchEvent(l) 

for low-level error and warning handlers /prototype XtErrorHandler(2) 

for high-level error and warning handlers /prototype XtErrorMsgHandler(2) 

/nondestructively examine the head of an application s input/ XtAppPeekEvent(l) 

Aiondestructively examine the head of an application s input/ XtPeekEvent(l) 

XtErrorMsgHandler: prototype for high-level error and warning/ XtErrorMsgHandler(2) 

XtAppErrorMsg: call the high-level fatal error handler XtAppErrorMsg(l) 

XtErrorMsg: call the high-level fatal error handler XtErrorMsg(l) 

called on nonfatal/ /register a high-level procedure to be XtSetWamingMsgHandler(l) 

/call the installed high-level warning handler XtAppWamingMsg(l) 

XtWamingMsg: call the installed high-level warning handler XtWamingMsg(l) 

/geometry-managing widget implementing constraints on/ Form(4) 

available XtOwnSelection: indicate that selection data is XtOwnSelection(l) 

no longer/ XtDisownSelection: indicate that selection data is XtDisownSelection(l) 

to an/ XtDisplaylnitialize: initialize a display and add it XtDisplaylnitialize(l) 

an/ XtOpenDisplay: open, initialize, and add a display to XtOpenDisplay(l) 

XtProc: prototype procedure to initialize data for a widget/ XtProc(2) 

XtCalloc: allocate an array and initialize elements to zero XtCalloc(l) 

widget/ XtlnitProc: prototype initialize procedure for a XtInitProc(2) 

internals XtToolkitlnitialize: initialize the X Toolkit XtToolkitlnitialize(l) 

X initialize: initialize toolkit and display Xtlnitialize(l) 

XtAppProcessEvent: process one input event XtAppProcessEvent(l) 

XtProcessEvent: process one input event XtProcessEvent(l) 

prototype procedure to handle input events XtEventHandler: XtEventHandler(2) 

cancel source of alternate input events XtRemovelnput: XtRemovelnput(l) 

XtAppMainLoop: process input from a given application XtAppMainLoop(l) 

XtRemoveGrab: redirect user input from modal widget back to/ XtRemoveGrab(l) 

next event from an application s input queue /return XtAppNextEvent(l) 

the head of an application s input queue /examine XtAppPeekEvent(l) 

any events in an application s input queue /if there are XtAppPending(l) 

return next event from input queue XtNextEvent: XtNextEvent(l) 

the head of an application s input queue /examine XtPeekEvent(l) 

any events in an application s input queue /if there are XtPending(l) 

/register a new file as an input source for a given/ XtAppAddlnput(l) 

/register a new file as an input source for an application XtAddlnput(l) 

/redirect keyboard input to a child widget XtSetKeyboardFocus(l) 

XtAddGrab: redirect user input to a modal widget XtAddGrab(l) 

on/ XtlnstallAccelerators: install a widget s accelerators XtlnstallAccelerators(l) 

XtlnstallAllAccelerators: install all accelerators from a/ XtInstallAllAccelerators(l ) 

XtAppError: call the installed fatal error procedure XtAppError(l ) 

XtAppWamingMsg: call the installed high-level warning/ XtAppWamingMsg(l) 



26 



X Toolkit Intrinsics Reference Manual 



handler XtWamingMsg: call the 

handler XtWaming: call the 

XtApp Warning: call the 

XtNew: allocate storage for one 

XtNewString: copy an 

XtCreate Widget: create an 

destroy a widget 

a widget name to a widget 

realize a widget 

display pointer into a widget 

the children of composite widget 

an accelerator table into its 

a translation table into its 

initialize the X Toolkit 

/set the 

claims/ /procedure called by the 

specified/ XtAppAddTimeOut: 

XtTranslateKey: 

XtTranslateKeycode: 

/prototype callback procedure 

XtSetKey Translator: register a 

procedure to translate a 

procedure to accept or reject 

XtSetKeyboardFocus: redirect 

/invoke the currently registered 

/invoke the currently registered 

and lower-case versions of a 

called to convert the case of 

display a non-editable string 

Class: application resources 

/update base-offset resource 

/update base-offset resource 

construct or modify an argument 

given/ XtAddCallbacks: add a 

XtUnmanageChildren: remove a 

/add a widget to its parent s 

/add widgets to their parent s 

XtRemoveCallbacks: delete a 

/copy from base-offset resource 

to a given widget s callback 

in a widget s callback 

default values for a resource 

resource list to the argument 

from a widget to the argument 

status of a widget s callback 

all procedures from a callback 

a procedure from a callback 

of procedures from a callback 

ArgList to base-offset resource 

widget from its parent s managed 

from a parent widget s managed 

managing row-column geometry 

that selection data is no 

a shared GC when it is no 

/determine upper-case and 

XtErrorHandler: prototype for 

XtError: call the 

XtWaming: call the installed 



installed high-level warning XtWarningMsg(l) 

installed low -level warning XtWaming(l) 

installed nonfatal error/ XtApp Warning(l) 

instance of a data type XtNew(l) 

instance of a string XtNewString(l) 

instance of a widget XtCreate Widget(l) 

instance XtDestroy Widget: XtDestroyWidget(l) 

instance /translate XtNameToWidget(l) 

instance XtRealize Widget: XtRealizeWidget(l) 

instance Aranslate a window and XtWindowToWidget(l) 

instances /for ordering XtOrderProc(2) 

internal representation /compile XtParseAcceleratorTable(l) 

internal representation /compile XtParseTranslationTable(l) 

internals XtToolkitlnitialize: XtToolkitlnitialize(l) 

Intrinsics selection timeout XtAppSetSelectionTimeout(l) 

Intrinsics when another client XtLoseSelectionProc(2) 

invoke a procedure after a XtApp AddTimeOut(l) 

invoke the currently registered/ XtTranslateKey (1) 

invoke the currently registered/ XtTranslateKeycode(l) 

invoked when timeouts expire XtTimerCallbackProc(2) 

key translator XtSetKey Translator(l) 

key XtKeyProc: prototype XtKeyProc(2) 

keyboard focus /prototype XtAcceptFocusProc(2) 

keyboard input to a child widget XtSetKeyboardFocus(l) 

keycode-to-keysym translator XtTranslateKey(l) 

keycode-to-keysym translator XtTranslateKeycode(l) 

keysym /determine upper-case XtConvertCase(l) 

keysyms /prototype procedure XtCaseProc(2) 

labelWidgetClass: widget to Label(4) 

linking window managers /Widget Shell(3) 

list (by application) XtGetApplicationResources(l) 

list (by name or class) XtGetSubresources(l) 

list dynamically XtSetArg: XtSetArg(l) 

list of callback procedures to a XlAddCallbacks(l) 

list of children from a parent/ XtUnmanageChildren(l) 

list of managed children XtManageChild(l) 

list of managed children XtManageChildren(l) 

list of procedures from a/ XtRemoveCallbacks(l) 

list to the argument list XtGetSubvalues(l) 

list /of callback procedures XtAddCallbacks(l) 

list /execute the procedures XtCallCallbacks(l) 

list /retrieve XtGetResourceList(l) 

list /copy from base-offset XtGetSubvalues(l) 

list /copy resources XtGetValues(l) 

list /determine the XtHasCallbacks(l) 

list /delete XtRemoveAllCallbacks(l) 

list XtRemoveCallback: delete XtRemoveCallback(l) 

list /delete a list XtRemoveCallbacks(l) 

list XtSetSubvalues: copy from XtSetSubvalues(l) 

list XtUnmanageChild: remove a XtUnmanageChild(l) 

list /remove a list of children XtUnmanageChildren(l) 

listWidgetClass: widget for List(4) 

longer available /indicate XtDisownSelection(l) 

longer needed /deallocate XtReleaseGC(l) 

lower-case versions of a keysym XtConvertCase(l) 

low-level error and warning/ XtErrorHandler(2) 

low-level fatal error handler XtError(l) 

low-level warning handler XlWaming(l) 



Permuted Index 



27 



/create and 

/determine whether a widget is 

a widget to its parent s list of 

to their parent s list of 

a widget from its parent s 

children from a parent widget s 

defines methods for geometry 

scrollable widget for geometry 

table with the Translation 

register it with the Resource 

resources linking window 

listWidgetClass: widget for 

XtPopup: 

XtMapWidget: 

/change the value of a widget s 

retrieve a widget s event 

events/ XtAddExposureToRegion: 

XtOverrideTranslations: 

widget s/ /nondestructively 

XtMerge ArgLists : 

string conversion error 

XtExposeProc: prototype expose 

prototype set_values_alrnost 

prototype set_values_hook 

procedure for get_values_hook 

for display_accelerator 

Composite Widget Class: defines 

procedure for various set_values 

prototype procedure for widget 

/redirect user input from 

redirect user input to a 

XtCheckSubclass: in DEBUG 

XtSetArg: construct or 

XtMoveWidget: 

XtConfigure Widget: 

/obtain selection data in 

base-offset resource list (by 

/translate a widget 

a shared GC when it is no longer 

a/ XtAppAddlnput: register a 

an/ XtAddlnput: register a 

XtAppAddConverter: register a 

XtAddConverter: register a 

XtOverrideTranslalions: merge 

existing/ /nondestructively merge 

input/ XtAppNextEvent: return 

XtNextEvent: return 

head of an/ XtAppPeekEvent: 

head of an/ XtPeekEvent: 

XtAugmentTranslations: 

/widget to display a 

/a procedure to be called on 

/a procedure to be called on 

/a procedure to be called on 

/a procedure to be called on 

/procedure to be called on 

XtApp Warning: call the installed 

input from modal widget back to 



manage a child widget XtCreateManagedWidget(l) 

managed by its parent XtlsManaged(l) 

managed children /add XtManageChild(l) 

managed children /add widgets XtManageChildren(l) 

managed list /remove XtUnmanageChild(l) 

managed list /remove a list of XtUnmanageChildren(l) 

management /Widget Class: Composite(3) 

management viewportWidgetClass: Viewport(4) 

Manager /register an action XtAddActions(l) 

Manager /an action table and XtAppAddActions(l) 

managers /Class: application Shell(3) 

managing row-column geometry List(4) 

map a pop-up shell XtPopup(l) 

map a widget to its display XtMapWidget(l) 

map_when_managed field XtSetMappedWhenManaged(l) 

mask XtBuildEventMask: XtBuildEventMask(l) 

merge Expose and GraphicsExpose XtAddExposureToRegion(l) 

merge new translations,/ XtOverrideTranslations(l) 

merge new translations with XtAugmentTranslations(l) 

merge two ArgList structures XtMergeArgLists(l) 

message /emit boilerplate XtStringConversionWarning(l) 

method used in Core widget class XtExposeProc(2) 

method XtAlmostProc: XtAlmostProc(2) 

method XtArgsFunc: XtArgsFunc(2) 

method XtArgsProc: prototype XtArgsProc(2) 

method /prototype procedure XtStringProc(2) 

methods for geometry management Composite(3) 

methods /prototype XtSetValuesFunc(2) 

methods XtWidgetProc: common XtWidgetProc(2) 

modal widget back to normal/ XtRemoveGrab(l) 

modal widget XtAddGrab: XtAddGrab(l) 

mode, verify a widget s class XtCheckSubclass(l) 

modify an argument list/ XtSetArg(l) 

move a widget on the display XtMoveWidget(l) 

move and/or resize widget XtConfigure Widget(l) 

multiple formats XtGetSelectionValues(l) 

name or class) /update XtGetSubresources(l) 

name to a widget instance XtNameToWidget(l) 

needed XtReleaseGC: deallocate XtReleaseGC(l) 

new file as an input source for XtApp Addlnput(l) 

new file as an input source for XtAddlnput(l) 

new resource converter for an/ XtApp AddConverter(l) 

new resource converter XtAddConverter(l) 

new translations, overwriting/ XtOverrideTranslations(l) 

new translations with widget s XtAugmentTranslations(l) 

next event from an application s XtAppNextEvent(l) 

next event from input queue XtNextEvent(l) 

nondestructively examine the XtAppPeekEvent(l) 

nondestructively examine the XtPeekEvent(l) 

nondestructively merge new/ XtAugmentTranslations(l) 

non-editable string Label(4) 

nonfatal error conditions XtAppSetWamingHandler(l) 

nonfatal error conditions XtAppSetWamingMsgHandler(l) 

nonfatal error conditions XtSetErrorMsgHandler(l) 

nonfatal error conditions XtSetWarningHandler(l) 

nonfatal error conditions XtSetWamingMsgHandler(l) 

nonfatal error procedure XtApp Warning(l) 

normal destination /user XtRemoveGrab(l) 



28 



X Toolkit Intrinsics Reference Manual 



XtNumber: determine the number of elements in a/ XtNumber(l) 

XtGetGC: obtain a read-only, sharable GC XtGetGC(l) 

XtQass: obtain a widget s class XtClass(l) 

XtSuperclass: obtain a widget s superclass XtSuperclass(l) 

multiple/ XtGetSelection Values: obtain selection data in XtGetSelectionValues(l) 

data XtGetSelection Value: obtain the complete selection XtGetSelection Value(l) 

for/ XtAppGetErrorDatabaseText: obtain the error database text XtAppGetErrorDatabaseText(l) 

for an/ XtGetErrorDatabaseText: obtain the error database text XtGetErrorDatabaseText(l) 

XtAppGetErrorDatabase: obtain the error database XtAppGetErrorDatabase(l) 

XtGetErrorDatabase: obtain the error database XtGetErrorDatabase(l) 

a particular/ XtDatabase: obtain the resource database for XtDatabase(l) 

XtOffset: determine the byte offset of a field within a/ XtOffset(l) 

display to an/ XtOpenDisplay: open, initialize, and add a XtOpenDisplay(l) 

/prototype procedure for ordering the children of/ XtOrderProc(2) 

ones /merge new translations, overwriting widget s existing XtOverrideTranslations(l) 

/translate an x-y coordinate pair from widget coordinates to/ XtTranslateCoords(l) 

data structures for a widget s parent /Widget Qass: provides Constraint(3) 

XtMakeGeometryRequest: request parent to change child s/ XtMakeGeometryRequest(l ) 

XtMakeResizeRequest: request parent to change child s size XlMakeResizeRequest(l) 

widget XtParent: return the parent widget for the specified XtParent(l) 

/remove a list of children from a parent widget s managed list XtUnmanageChildren(l) 

a widget is managed by its parent /determine whether XtlsManaged(l) 

children /add a widget to its parent s list of managed XtManageChild(l ) 

children /add widgets to their parent s list of managed XtManageChildren(l) 

/remove a widget from its parent s managed list XtUnmanageChild(l) 

of type/ /prototype procedure passed as a resource converter XtResourceDefaultProc(2) 

XtWorkProc: perform background processing XtWorkProc(2) 

cache result XtDirectConvert: perform resource conversion and XtDirectConvert(l) 

gripWidgetClass: attachment point for dragging other widgets Grip(4) 

/command button activated by pointer click Command(4) 

XtDisplay: return the display pointer for the specified widget XlDisplay(l) 

XtScreen: return the screen pointer for the specified widget XtScreen(l) 

/translate a window and display pointer into a widget instance XtWindowToWidget(l) 

callback/ XtCallbackPopdown: pop down a widget from a XtCallbackPopdown(l) 

/callback function to pop up a widget XtCallbackExclusive(l) 

/callback function to pop up a widget XtCallbackNone(l) 

/callback function to pop up a widget XtCallbackNonexclusive(l) 

MenuPopdown: built-in action for popping down a widget MenuPopdown(l) 

MenuPopup: built-in action for popping up a widget MenuPopup(l) 

XtCreatePopupShell: create a pop-up shell XtCreatePopupShell(l) 

XtPopdown: unmap a pop-up shell XtPopdown(l) 

XtPopup: map a pop-up shell XtPopup(l) 

/query a child widget s preferred geometry XtQueryGeometry(l) 

XtRemoveEventHandler: remove a previously registered event/ XtRemoveEventHandler(l) 

XtAppAddTimeOut: invoke a procedure after a specified/ XtAppAddTimeOut(l) 

XtSelectionDoneProc: prototype procedure called after a data/ XlSelectionDoneProc(2) 

XtLoseSelectionProc: prototype procedure called by the/ XtLoseSelectionProc(2) 

case of/ XtCaseProc: prototype procedure called to convert the XtCaseProc(2) 

XtlnputCallbackProc: prototype procedure called to handle file/ XtInputCallbackProc(2) 

selection data/ /prototype procedure called when requested XtSelectionCallbackProc(2) 

XtRealizeProc: prototype procedure called when widget is/ XtRealizeProc(2) 

application /register a work procedure for a given XtAppAddWorkProc(l) 

XtlnitProc: prototype initialize procedure for a widget class XtInitProc(2) 

XtAddWorkProc: register a work procedure for an application XtAddWorkProc(l) 

XtStringProc: prototype procedure for/ XtStringProc(2) 

method XtArgsProc: prototype procedure for get_values_hook XtArgsProc(2) 

children/ XtOrderProc: prototype procedure for ordering the XtOrderProc(2) 

tables XtActionProc: prototype procedure for registering action XtActionProc(2) 



Permuted Index 



29 



XtSetValuesFunc: prototype 

XtWidgetProc: common prototype 

XtRemoveCallback: delete a 

expire /prototype callback 

XtResourceDefaultProc: prototype 

XtAddCaUback: add a callback 

XtAcceptFocusProc: prototype 

XtAppSetErrorHandler: register a 

error conditions /register a 

XtSetErrorHandler: register a 

nonfatal error/ /register a 

nonfatal error/ /register a 

XtSetErrorMsgHandler: register a 

XtSetWamingHandler: register a 

nonfatal/ /register a high-level 

XtAddEventHandler: register a 

XtGeometryHandler: prototype 

XtEventHandler: prototype 

a widget/ XtProc: prototype 

data /prototype 

XtKeyProc: prototype 

call the installed fatal error 

the installed nonfatal error 

call a widget s accept_focus 

prototype callback 

of a resource converter 

XtRemoveWorkProc: remove a work 

XtRemoveAllCallbacks: delete all 

/delete a list of 

XtCallCallbacks: execute the 

callback/ /add a list of callback 

XtMainLoop: continuously 

application XtAppMainLoop: 

XtAppProcessEvent: 

XtProcessEvent: 

XtWorkProc: perform background 

invoked/ XtTimerCallbackProc: 

XtCallbackProc: 

Core widget class XtExposeProc: 

and warning/ XtErrorMsgHandler: 

and warning/ XtErrorHandler: 

for a widget class XtlnitProc: 

converter/ XtConverter: 

a data/ XtSelectionDoneProc: 

the/ XtLoseSelectionProc: 

convert the case of/ XtCaseProc: 

handle/ XtlnputCallbackProc: 

XtSelectionCallbackProc: 

widget is/ XtRealizeProc: 

XtStringProc: 

get_values_hook/ XtArgsProc: 

the children of/ XtOrderProc: 

registering/ XtActionProc: 

set_values/ XtSetValuesFunc: 

methods XtWidgetProc: common 

resource/ XtResourceDefaultProc: 

reject/ XtAcceptFocusProc: 

geometry/ XtGeometryHandler: 



procedure for various set_values/ XtSetValuesFunc(2) 

procedure for widget methods XtWidgetProc(2) 

procedure from a callback list XtRemoveCallback(l) 

procedure invoked when timeouts XtTimerCallbackProc(2) 

procedure passed as a resource/ XtResourceDefaultProc(2) 

procedure to a widget s callback/ XtAddCallback(l) 

procedure to accept or reject/ XtAcceptFocusProc(2) 

procedure to be called on fatal/ XtAppSetErrorHandler(l) 

procedure to be called on fatal XtAppSetErrorMsgHandler(l) 

procedure to be called on fatal/ XtSetErrorHandler(l) 

procedure to be called on XtAppSetWarningHandler(l) 

procedure to be called on XtAppSetWamingMsgHandler(l) 

procedure to be called on/ XtSetErrorMsgHandler(l) 

procedure to be called on/ XtSetWarningHandler(l) 

procedure to be called on XtSetWarningMsgHandler(l) 

procedure to handle events XtAddEventHandler(l) 

procedure to handle geometry/ XtGeometryHandler(2) 

procedure to handle input events XtEventHandler(2) 

procedure to initialize data for XtProc(2) 

procedure to return selection XtConvertSelectionProc(2) 

procedure to translate a key XtKeyProc(2) 

procedure XtAppError: XtAppError(l) 

procedure XtApp Warning: call XtAppWarning(l) 

procedure XtCallAcceptFocus: XtCallAcceptFocus(l) 

procedure XtCallbackProc: XtCallbackProc(2) 

procedure /prototype XtConverter(2) 

procedure XtRemoveWorkProc(l ) 

procedures from a callback list XtRemoveAllCallbacks(l) 

procedures from a callback list XtRemoveCallbacks(l) 

procedures in a widget s/ XtCallCallbacks(l) 

procedures to a given widget s XtAddCallbacks(l) 

process events XtMainLoop(l) 

process input from a given XtAppMainLoop(l) 

process one input event XtAppProcessEvent(l) 

process one input event XtProcessEvent(l) 

processing XtWorkProc(2) 

prototype callback procedure XtTimerCallbackProc(2) 

prototype callback procedure XtCallbackProc(2) 

prototype expose method used in XtExposeProc(2) 

prototype for high-level error XtErrorMsgHandler(2) 

prototype for low -level error XtErrorHandler(2) 

prototype initialize procedure XtInitProc(2) 

prototype of a resource XtConverter(2) 

prototype procedure called after XtSelectionDoneProc(2) 

prototype procedure called by XtLoseSelectionProc(2) 

prototype procedure called to XtCaseProc(2) 

prototype procedure called to XtInputCallbackProc(2) 

prototype procedure called when/ XtSelectionCallbackProc(2) 

prototype procedure called when XtRealizeProc(2) 

prototype procedure for/ XtStringProc(2) 

prototype procedure for XtArgsProc(2) 

prototype procedure for ordering XtOrderProc(2) 

prototype procedure for XtActionProc(2) 

prototype procedure for various XtSetValuesFunc(2) 

prototype procedure for widget XlWidgetProc(2) 

prototype procedure passed as a XtResourceDefaultProc(2) 

prototype procedure to accept or XtAcceptFocusProc(2) 

prototype procedure to handle XtGeometryHandler(2) 



30 



X Toolkit Intrinsics Reference Manual 



input events XlEventHandler prototype procedure to handle .......... XtEventHandler(2) 

initialize data for a/ XtProc: prototype procedure to .................... XtProc(2) 

XtConvertSelectionProc: prototype procedure to return/ XtConvertSelectionProc(2) 

a key XtKeyProc: prototype procedure to translate XtKeyProc(2) 

method XtAlmostProc: prototype set_values_almost XtAlmostProc(2) 

XtArgsFunc: prototype set_values_hook method XtArgsFunc(2) 

geometry XtQueryGeometry: query a child widget s preferred XtQueryGeometry(l) 

from an application s input queue /return next event XtAppNextEvent(l) 

head of an application s input queue /examine the XtAppPeekEvent(l) 

events in an application s input queue /if there are any XtAppPending(l) 

return next event from input queue XtNextEvent: XtNextEvent(l) 

head of an application s input queue /examine the XtPeekEvent(l) 

events in an application s input queue /if there are any XtPending(l ) 

/remove a raw event handler XtRemoveRawEventHandler(l) 

2 compatible function to free up read-only GCs /Release XtDestroyGC(l) 

XtGetGC: obtain a read-only, sharable GC XtGetGC(l) 

XtRealize Widget: realize a widget instance XtRealizeWidget(l) 

whether a widget has been realized /determine ... XtlsRealized(l) 

procedure called when widget is realized /prototype XtRealizeProc(2) 

child/ XtSetKeyboardFocus: redirect keyboard input to a ...................... XtSetKeyboardFocus(l ) 

widget back to/ XtRemoveGrab: redirect user input from modal XtRemoveGrab(l) 

widget XtAddGrab: redirect user input to a modal XtAddGrab(l) 

and GraphicsExpose events into a region /merge Expose XtAddExposureToRegion(l) 

XtRegisterCaseConverter: register a case converter XtRegisterCaseConverter(l) 

to be/ XtSetWamingMsgHandler: register a high-level procedure XtSetWamingMsgHandler(l) 

XtSetKeyTranslator: register a key translator XtSetKeyTranslator(l) 

source for a/ XtAppAddlnput: register a new file as an input XtAppAddlnput(l) 

source for an/ XtAddlnput: register a new file as an input XtAddlnput(l) 

converter/ XlAppAddConverter: register a new resource XtAppAddConverter(l) 

converter XtAddConverter. register a new resource XtAddConverter(l) 

called on/ XtAppSetErrorHandler: register a procedure to be XtAppSetErrorHandler(l) 

called/ XtAppSetErrorMsgHandler: register a procedure to be XtAppSetErrorMsgHandler(l) 

called on/ XtSetErrorHandler: register a procedure to be XtSetErrorHandler(l) 

called/ XtAppSetWamingHandler: register a procedure to be XtAppSetWarningHandler(l) 

XtAppSetWarningMsgHandler: register a procedure to be/ XtAppSetWamingMsgHandler(l) 

called on/ XtSetErrorMsgHandler: register a procedure to be XtSetErrorMsgHandler(l) 

called on/ XtSetWamingHandlen register a procedure to be XtSetWamingHandler(l) 

events XtAddEventHandler: register a procedure to handle XtAddEventHandler(l) 

given/ XtAppAddWorkProc: register a work procedure for a XtAppAddWorkProc(l ) 

application XtAddWorkProc: register a work procedure for an XtAddWorkProc(l) 

the Translation/ XtAdd Actions: register an action table with XtAddActions(l) 

without/ XtAddRawEventHandler: register an event handler XtAddRawEventHandler(l ) 

/declare an action table and register it with the Resource/ XtAppAddActions(l) 

/remove a previously registered event handler XtRemoveEventHandler(l) 

XtDispatch Event: dispatch registered handlers for an event XtDispatchEvent(l) 

translator /invoke the currently registered keycode-to-keysym . XtTranslateKey(l) 

translator /invoke the currently registered keycode-to-keysym XtTranslateKeycode(l) 

/prototype procedure for registering action tables XtActionProc(2) 

/prototype procedure to accept or reject keyboard focus XtAcceptFocusProc(2) 

free up read-only/ XtDestroyGC: Release 2 compatible function to XtDestroyGC(l) 

parent/ XtUnmanageChildren: remove a list of children from a XtUnmanageChildren(l) 

event/ XtRemoveEventHandlen remove a previously registered XtRemoveEventHandler(l) 

XtRemoveRawEventHandler: remove a raw event handler XtRemoveRawEventHandler(l) 

parent s/ XtUnmanageChild: remove a widget from its XtUnmanageChild(l) 

XtRemoveWorkProc: remove a work procedure XtRemoveWorkProc(l) 

XtL ninstallTranslations: remove existing translations XtUninstallTranslations(l) 

context /close a display and remove it from an application XtCloseDisplay(l) 

table into its internal representation /an accelerator XtParseAcceleratorTable(l) 



Permuted Index 



31 



table into its internal 

geometry XtMakeGeometryRequest: 

size XtMakeResizeRequest: 

/prototype procedure called when 

procedure to handle geometry 

XtResizeWidget: 

values of its/ XtResize Window: 

XtConfigure Widget: 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 XtGet Values: copy 

XtSet Values: 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 

XtGetSelection Values: obtain 

XtOwnSelection: indicate that 

XtDisownSelection: indicate that 

/prototype procedure to return 

/obtain the complete 

/get the current 

/get the current 

/set the Intrinsics 

/set value of 

when another client claims the 

XtlsSensitive: check the current 

XtSetSensitive: set the 

XtAppSetSelectionTimeout: 

widget XtSetSensitive: 

XtSetSelectionTimeout: 



representation /a translation ..................... XtParseTranslationTable(l) 

request parent to change child s XtMakeGeometryRequest(l) 

request parent to change child s XtMakeResizeRequest(l) 

requested selection data arrives XtSelectionCallbackProc(2) 

requests /prototype XtGeometryHandler(2) 

resize a child or sibling widget XtResize Widget(l) 

resize a widget according to the XtResize Window(l) 

resize widget XtConfigure Widget(l) 

resource conversion and cache XtDirectConvert(l) 

resource converter for an XtAppAddConverter(l) 

resource converter of type/ XtResourceDef aultProc(2) 

resource converter procedure XtConverter(2) 

resource converter XtAddConverter(l) 

resource database for a/ XtDatabase(l) 

resource list (by application) XtGetApplicationResources(l) 

resource list (by name or class) XtGetSubresources(l) 

resource list to the argument XtGetSubvalues(l) 

resource list XtGetResourceList(l) 

resource list XtSetSubvalues: XtSetSubvalues(l) 

Resource Manager /an action XtAppAddActions(l) 

resource type XtConvert(l) 

resource /add a callback XtAddCallback(l) 

resources from a widget to the XtGet Values(l) 

resources from ArgList to widget XtSetValues(l) 

resources linking window/ Shell(3) 

retrieve a widget s event mask XtBuildEventMask(l) 

retrieve default values for a XtGetResourceList(l) 

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(l) 

return the parent widget for the XtParent(l) 

return the screen pointer for XtScreen(l) 

return the window of the XtWindow(l) 

root coordinates /x-y coordinate XtTranslateCoords(l) 

routine XtCallbackPopdown: pop XtCallbackPopdown(l) 

row-column geometry List(4) 

screen pointer for the specified XtScreen(l) 

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/ XtGetSelection Values(l) 

selection data is available XtOwnSelection(l) 

selection data is no longer/ XtDisownSelection(l) 

selection data XtConvertSelectionProc(2) 

selection data XtGetSelection Value(l) 

selection timeout value XtAppGetSelectionTimeout(l) 

selection timeout value XtGetSelectionTimeout(l) 

selection timeout XtAppSetSelectionTimeout(l) 

selection timeout XtSetSelectionTimeout(l) 

selection /by the Intrinsics XtLoseSelectionProc(2) 

sensitivity state of a widget XtlsSensitive(l) 

sensitivity state of a widget XtSetSensitive(l) 

set the Intrinsics selection/ XtAppSetSelectionTimeout(l) 

set the sensitivity state of a XtSetSensitive(l) 

set value of selection timeout XtSetSelectionTimeout(l) 



32 



X Toolkit Intrinsics Reference Manual 



/prototype procedure for various set_values methods ............... XtSetValuesFunc(2) 

XtAlmostProc: prototype set_values_almost method XtAlmostProc(2) 

XtArgsFunc: prototype set_values_hook method XtArgsFunc(2) 

XtGetGC: obtain a read-only, sharable GC XtGetGC(l) 

XtReleaseGC: deallocate a shared GC when it is no longer/ XtReleaseGC(l) 

resources Unking window/ Shell Widget Class: application Shell(3) 

a widget is a subclass of the Shell widget class /test whether XtIsShell(l ) 

create a pop-up shell XtCreatePopupShell: XtCreatePopupShell(l) 

XtPopdown: unmap a pop-up shell XtPopdown(l) 

XtPopup: map a pop-up shell XtPopup(l) 

resize a child or sibling widget XtResize Widget: XtResizeWidget(l) 

storage XtRealloc: change the size of an allocated block of XtRealloc(l) 

request parent to change child s size XtMakeResizeRequest: XtMakeResizeRequest(l) 

/register a new file as an input source for a given application XtAppAddlnput(l) 

/register a new file as an input source for an application XtAddlnput(l) 

XtRemovelnput: cancel source of alternate input events XtRemovelnput(l) 

/invoke a procedure after a specified timeout XtAppAddTimeOut(l) 

the display pointer for the specified widget /return XtDisplay(l) 

return the parent widget for the specified widget XtParent: XtParent(l) 

the screen pointer for the specified widget /return XtScreen(l) 

return the window of the specified widget XtWindow: XtWindow(l) 

/check the current sensitivity state of a widget XtlsSensitive(l) 

/set the sensitivity state of a widget XtSelSensitive(l) 

XtHasCallbacks: determine the status of a widget s callback/ XtHasCallbacks(l) 

data type XtNew: allocate storage for one instance of a XtNew(l) 

free an allocated block of storage XtFree: XtFree(l) 

XtMalloc: allocate storage XtMalloc(l) 

size of an allocated block of storage XtRealloc: change the XtRealloc(l) 

/emit boilerplate string conversion error message XtStringConversionWaming(l) 

widget to display a non -editable string labelWidgetClass: Label(4) 

copy an instance of a string XtNewString: XtNewString(l) 

byte offset of a field within a structure /determine the XtOffset(l) 

/Widget Class: provides data structures for a widget s parent Constraint(3) 

merge two ArgList structures XtMergeArgLists: XtMergeArgLists(l) 

/determine whether a widget is a subclass of a class XtlsSubclass(l) 

/test whether a widget is a subclass of the Composite widget/ XtlsComposite(l) 

/lest whether a widget is a subclass of the Constraint/ XtlsConstraint(l) 

Aest whether a widget is a subclass of the Shell widget/ XtIsShell(l ) 

XtSuperclass: obtain a widget s superclass XtSuperclass(l) 

Resource/ /declare an action table and register it with the XtAppAddActions(l) 

/compile an accelerator table into its internal/ XtParseAcceleratorTable(l) 

/compile a translation table into its internal/ XtParseTranslationTable(l) 

XtAddActions: register an action table with the Translation/ XlAddActions(l) 

procedure for registering action tables XtActionProc: prototype XtActionProc(2) 

create a custom widget template WidgetClass: widget to Template(4) 

subclass of the/ XllsComposile: test whether a widget is a XtlsComposite(l) 

subclass of the/ XtlsConstraint: test whether a widget is a XtIsConstraint(l ) 

subclass of the/ XtlsShell: test whether a widget is a XtlsShell(l) 

/obtain the error database text for an error or a warning XtAppGetErrorDatabaseText(l ) 

/obtain the error database text for an error or a warning XtGetErrorDatabaseText(l) 

textWidgetClass: text-editing widget Text(4) 

widget textWidgetClass: text-editing Text(4) 

widget for vertical tiles /geometry-managing VPaned(4) 

XtAddTimeOut: create a timeout value XtAddTimeOut(l) 

/get the current selection timeout value XtAppGetSelectionTimeout(l) 

/get the current selection timeout value XtGetSelectionTimeout(l ) 

XtRemoveTimeOut: clear a timeout value XtRemoveTimeOut(l) 

a procedure after a specified timeout XtAppAddTimeOut: invoke XtAppAddTimeOut(l) 



Permuted Index 



33 



/set the Intrinsics selection timeout XtAppSetSelectionTimeout(l) 

set value of selection timeout XtSetSelectionTimeout: XtSetSelectionTimeout(l) 

callback procedure invoked when timeouts expire /prototype XtTimerCallbackProc(2) 

Xtlnitialize: initialize toolkit and display Xtlnitialize(l) 

/initialize the X Toolkit internals XtToolkitlnitialize(l) 

Core Widget Class: fundamental, top-level widget Core(3) 

/create additional top-level widget XtAppCreateShell(l) 

/create an additional top-level widget XtCreateApplicationShell(l) 

procedure called after a data transfer completes /prototype XtSelectionDoneProc(2) 

prototype procedure to translate a key XtKeyProc: XtKeyProc(2) 

widget instance XtNameTo Widget: translate a widget name to a XtNameToWidget(l) 

pointer into/ XtWindowTo Widget: translate a window and display XtWindowToWidget(l) 

from widget/ XtTranslateCoords: translate an x-y coordinate pair XtTranslateCoords(l) 

an action table with the Translation Manager /register XtAddActions(l) 

internal/ /compile a translation table into its XtParseTranslationTable(l) 

widget s existing/ /merge new translations, overwriting XtOverrideTranslations(l) 

/hondestructively merge new translations with widget s/ XtAugmentTranslations(l) 

/remove existing translations XtUninstallTranslations(l) 

register a key translator XtSetKey Translator: XtSetKeyTranslator(l) 

registered keycode-to-keysym translator /invoke the currently XtTranslateKey(l) 

registered keycode-to-keysym translator /invoke the currently XtTranslateKeycode(l) 

XtMergeArgLists: merge two ArgList structures XtMergeArgLists(l) 

XtConvert: convert resource type XtConvert(l) 

for one instance of a data type XtNew: allocate storage XtNew(l) 

as a resource converter of type XtRCallProc /passed XtResourceDefaultProc(2) 

XtPopdown: unmap a pop-up shell XtPopdown(l) 

XtUnmapWidget: unmap a widget explicitly XtUnmapWidget(l) 

(by/ XtGetApplicationResources: update base-offset resource list XtGetApplicationResources(l) 

(by name or/ XtGetSubresources: update base-offset resource list XtGetSubresources(l) 

XtConvertCase: determine upper-case and lower-case/ XtConvertCase(l) 

back to/ XtRemoveGrab: redirect user input from modal widget XtRemoveGrab(l ) 

XtAddGrab: redirect user input to a modal widget XtAddGrab(l) 

map_when_managed/ /change the value of a widget s XtSetMappedWhenManaged(l) 

XtSetSelectionTimeout: set value of selection timeout XtSetSelectionTimeout(l) 

XtAddTimeOut: create a timeout value XtAddTimeOut(l) 

the current selection timeout value /get XtAppGetSelectionTimeout(l) 

the current selection timeout value /get XtGetSelectionTimeout(l) 

XtRemoveTimeOut: clear a timeout value XtRemoveTimeOut(l) 

/retrieve default values for a resource list XtGetResourceList(l) 

/resize a widget according to the values of its core dimensions XtResizeWindow(l) 

XtCheckSubclass: in DEBUG mode, verify a widget s class XtCheckSubclass(l) 

upper-case and lower-case versions of a keysym /determine XtConvertCase(l) 

/geometry-managing widget for vertical tiles VPaned(4) 

/widget to control scrolling of viewing area in another widget Scrollbar(4) 

widget for geometry management viewportWidgetClass: scrollable Viewport(4) 

geometry-managing widget for/ vPanedWidgetClass: VPaned(4) 

/call the installed high-level warning handler XtAppWamingMsg(l ) 

call the installed low-level warning handler XtWarning: XtWaming(l) 

call the installed high-level warning handler XtWamingMsg: XtWamingMsg(l) 

for low-level error and warning handlers /prototype XtErrorHandler(2) 

for high-level error and warning handlers /prototype XtErrorMsgHandler(2) 

database text for an error or a warning /obtain the error XtAppGetErrorDatabaseText(l) 

database text for an error or a warning /obtain the error XtGetErrorDatabaseText(l ) 

of its/ XtResize Window: resize a widget according to the values XtResizeWindow(l) 

/install all accelerators from a widget and its descendants onto/ XtlnstallAllAccelerators(l) 

/the windows associated with a widget and its descendants XtUnrealizeWidget(l) 

/redirect user input from modal widget back to normal/ XtRemoveGrab(l) 

geometry -managing box 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 

dialog WidgetClass: dialog Box 

XtUnmap Widget: 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 

XtDestroy Widget: destroy a 

translate a widget name to a 

XtRealize Widget: realize a 

and display pointer into a 

the children of composite 

/determine whether a 

XtlsComposite: test whether a 

XtlsConstraint: test whether a 

Shell/ XtlsShell: test whether a 

XtlsManaged: determine whether a 

/prototype procedure called when 

action for popping down a 

built-in action for popping up a 

common prototype procedure for 

XtNameTo Widget: translate a 

XtMove Widget: move a 

of viewing area in another 

widget to create a custom 

textWidgetClass: text-editing 

viewing/ scrollbarWidgetClass: 

template WidgetClass : 

string labelWidgetClass: 

XlMap Widget: 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(S) 

widget class /prototype XtExposeProc(2) 

widget class /prototype XtInitProc(2) 

widget class /whether a widget XtlsComposite(l) 

widget class /whether a widget XtlsConstraint(l) 

widget class /whether a widget XtlsShell(l) 

widget class /procedure XtProc(2) 

widget coordinates to root/ XtTranslateCoords(l) 

widget Core Widget Core(3) 

widget Dialog(4) 

widget explicitly XtUnmapWidget(l) 

widget for geometry management Viewport(4) 

widget for managing row-column List(4) 

widget for the specified widget XtParent(l) 

widget for vertical tiles VPaned(4) 

widget from a callback routine XtCallbackPopdown(l) 

widget from its parent s managed XtUnmanageChild(l) 

widget has been realized XtlsRealized(l) 

widget implementing constraints Form(4) 

widget instance XtDestroy Widget(l) 

widget instance XtNameTo Widget: XtNameTo Widget(l) 

widget instance XtRealize Widget(l) 

widget instance /a window XtWindowToWidget(l) 

widget instances /for ordering XtOrderProc(2) 

widget is a subclass of a class XtlsSubclass(l) 

widget is a subclass of the/ XtlsComposite(l) 

widget is a subclass of the/ XtlsConstraint(l) 

widget is a subclass of the XtlsShell(l) 

widget is managed by its parent XtlsManaged(l) 

widget is realized XtRealizeProc(2) 

widget MenuPopdown: built-in MenuPopdown(l) 

widget MenuPopup: MenuPopup(l) 

widget methods XtWidgetProc: XtWidgetProc(2) 

widget name to a widget instance XtNameTo Widget(l) 

widget on the display XtMove Widget(l) 

widget Ao control scrolling Scrollbar(4) 

widget template WidgetClass: 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(l) 

widget to its parent s list of XtManageChild(l) 

widget to the argument list XtGetValues(l) 

widget XtAddGrab: XtAddGrab(l) 

widget XtAppCreateShell: XtAppCreateShell(l) 

widget XlCallbackExclusive: XtCallbackExclusive(l) 

widget. XtCaUbackNone: XtCaUbackNone(l) 

widget. XtCallbackNonexclusive: XtCallbackNonexclusive(l) 

widget XtConfigure Widget: XtConfigureWidget(l) 

widget XtCreate ApplicationShell( 1 ) 

widget XtCreateManagedWidget: XtCreateManagedWidget(l) 

widget XtCreateWidget: XtCreateWidget(l) 

widget /return the display XtDisplay(l) 

widget /install a XtlnstallAccelerators(l) 



Permuted Index 



35 



current sensitivity state of a 

parent widget for the specified 

resize a child or sibling 

screen pointer for the specified 

keyboard input to a child 

set the sensitivity state of a 

copy resources from ArgList to 

application context for a given 

the window of the specified 

XtlnstallAccelerators: install a 

XtCallAcceptFocus: call a 

callback procedures to a given 

/execute the procedures in a 

/determine the status of a 

/add a callback procedure to a 

in DEBUG mode, verify a 

XtClass: obtain a 

XtBuildEventMask: retrieve a 

/merge new translations with 

new translations, overwriting 

point for dragging other 

a list of children from a parent 

/change the value of a 

provides data structures for a 

XtQuery Geometry: query a child 

XtSuperclass: obtain a 

of/ XtManageChildren: add 

XtCreate Window: create 

a/ XtWindowTo Widget: translate a 

application resources linking 

XtWindow: return the 

create widget s working 

XtUnrealize Widget: destroy the 

XtAppAddWorkProc: register a 

XtAddWorkProc: register a 

XtRemoveWorkProc: remove a 

XtCreate Window: create widget s 

/initialize the 

as a resource converter of type 
XtTranslateCoords: translate an 
array and initialize elements to 



widget XtlsSensitive: check the XtlsSensitive(l) 

widget XtParent: return the XtParent(l) 

widget XtResizeWidget: XtResizeWidget(l) 

widget XtScreen: return the XtScreen(l) 

widget /redirect XtSetKeyboardFocus(l) 

widget XtSetSensitive: XtSetSensitive(l) 

widget XtSet Values: XtSetValues(l) 

widget /get the XtWidgetToApplicationContext(l) 

widget XtWindow: return XtWindow(l) 

widget s accelerators on another/ XtlnstallAccelerators(l) 

widget s accept_focus procedure XtCallAcceptFocus(l) 

widget s callback list /list of XtAddCallbacks(l) 

widget s callback list XtCallCallbacks(l) 

widget s callback list XtHasCaUbacks(l) 

widget s callback resource XtAddCaUback(l) 

widget s class XtCheckSubclass: XtCheckSubclass(l) 

widget s class XtClass(l) 

widget s event mask XtBuildEventMask(l) 

widget s existing ones XtAugmentTranslations(l) 

widget s existing ones /merge XtOverrideTranslations(l) 

widgets /attachment Grip(4) 

widget s managed list /remove XtUnmanageChildren(l) 

widget s map_when_managed field XtSetMappedWhenManaged(l) 

widget s parent /Widget Class: Constraint(3) 

widget s preferred geometry XtQueryGeometry(l) 

widget s superclass XtSuperclass(l) 

widgets to their parent s list XtManageChildren(l) 

widget s working window XtCreateWindow(l) 

window and display pointer into XtWindowTo Widget(l) 

window managers /Widget Class: Shell(3) 

window of the specified widget XtWindow(l) 

window XtCreate Window: XtCreate Window(l) 

windows associated with a widget/ XtUnrealize Widget(l) 

work procedure for a given/ XtAppAddWorkProc(l) 

work procedure for an/ XtAddWorkProc(l) 

work procedure XtRemoveWorkProc(l) 

working window XtCreate Window(l) 

X Toolkit internals XtToolkitlnitialize(l) 

XtRCallProc /procedure passed XtResourceDefaultProc(2) 

x-y coordinate pair from widget/ XtTranslateCoords(l) 

zero XtCalloc: allocate an XtCalloc(l) 



36 



X Toolkit Intrinsics Reference Manual 



X Toolkit Intrinsics 
Functions and Macros 



This section contains alphabetically-organized reference pages for each Intrinsics 
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. 



J MenuPopdown 

Xt - Pop Ups 

Name 

MenuPopdown built-in action for popping down a widget 

Synopsis 

void MenuPopdown (shell_name) 
String shell_name; 

Arguments 

shell_name Specifies the name of the widget shell to pop down. 

Description 

Pop-ups can be popped down through several mechanisms: 

A call to XtPopdown 

The supplied callback procedure XtCallbackPopdown 

The standard translation action MenuPopdown 

To pop down a spring-loaded menu when a pointer button is released or when the pointer is 
moved into some window, use MenuPopdown. 

MenuPopdown is known to the Translation Manager, which must perform special actions for 
spring-loaded pop ups. All that is necessary is to map it to some event or event sequence using 
a translation specification in a resource file. Calls to MenuPopdown in a translation specifica 
tion are mapped into calls to a nonexported action procedure. 

If a shell name is not given as an argument, MenuPopdown calls XtPopdown with the widget 
for which the translation is specified. If a shell_name is specified in the translation table, 
MenuPopdown tries to find the shell by looking up the widget tree starting at the parent of the 
widget in which it is invoked. If it finds a shell with the specified name in the pop-up children 
of that parent, it pops down the shell; otherwise, it moves up the parent chain as needed. If 
MenuPopdown gets to the application top-level shell widget and cannot find a matching shell, 
it generates an error. 

See Also 

MenuPopup, XtCallbackPopdown, XtPopDown, XtPopup. 



X Toolkit Intrinsics Reference Manual 39 



MenuPopup V 

N Xt - Pop Ups 

Name 

MenuPopup built-in action for popping up a widget. 

Synopsis 

void MenuPopup(sheII_/ia/ne) 
String shell_name; 

Arguments 

shell_name Specifies the name of the widget shell to pop up. 

Description 

MenuPopup is a built-in action that pops up a widget It must be specified in a translation for 
ButtonPress or an EnterNotify event 

MenuPopup is known to the Translation Manager, which must perform special actions for 
spring-loaded pop ups. All that is necessary is to map it to some event or event sequence using 
a translation specification in a resource file. Calls to MenuPopup in a translation specification 
are mapped into calls to a nonexported action procedure, and the translation manager fills in 
parameters based on the event specified on the left-hand side of a translation. 

If MenuPopup is invoked on ButtonPress (possibly with modifiers), the translation man 
ager pops up the shell with grab_kind set to XtGrabExclusive and spring_loaded 
set to TRUE. If MenuPopup is invoked on EnterWindow (possibly with modifiers), the trans 
lation manager pops up the shell with grab_kind set to XtGrabNonexclusive and 
spring_loaded set to FALSE. Otherwise, the translation manager generates an error. 

When the widget is popped up, the following actions occur: 

Calls XtCheckSubclass to ensure popup_shell is a subclass of Shell. 

Generates an error if the shell s popped_up field is already TRUE. 

Calls the callback procedures on the shell s popup_callback list. 

Sets the shell popped_up field to TRUE and the shell grab_kind and 
spring_loaded fields appropriately. 

If the shell s create_jpopup_child field is non-NULL, it is called with 
popup_shell as the parameter. 

Calls: 

XtAddGrab(popup_shell, (grab_kind == XtGrabExclusive), 
spring_loaded) 



Calls XtRealizeWidget withpopup_sheJI specified. 
Calls XMapWindow with popup_shell specified. 



(Note that these actions are the same as those for xt Popup.) MenuPopup tries to find the 
shell by searching the widget tree starting at the parent of the widget in which it is invoked. If 
it finds a shell with the specified name in the pop-up children of that parent, it pops up the shell 
with the appropriate parameters. Otherwise, it moves up the parent chain as needed. If 



40 X Toolkit Intrinsics Reference Manual 



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 



XtAddActions 

Xt - Translations and Actions 

Name 

XtAddActions register an action table with the Translation Manager. 

Synopsis 

void XtAddActions ( actions, num_actions) 
XtActionList actions; 
Cardinal num_actions; 

Arguments 

a c t i on s Specifies the action table to register. 

num_actions Specifies the number of entries in this action table. 

Description 

All widget class records contain an action table. In addition, using XtAddActions, an appli 
cation can register its own action tables with the Translation Manager. An action table consists 
of a list of string names (which can be used in translation tables to associate an action with one 
or more events) and corresponding function pointers. The function pointer is of type xt- 

ActionProc. 

By convention, 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 files, which are made up entirely of strings. 

For example, the Command widget has procedures to take the following actions: 

Set the appearance of the Command widget to indicate it is activated when a pointer but 
ton has been pressed in it 

Unset the button back to its normal mode. 

Highlight the button borders when the pointer enters the Command widget 

Unhighlight the button borders when the pointer leaves. 
Notify any callbacks that the button has been activated. 

The action table for the Command widget class makes these functions available to translation 
tables written for Command or any subclass: 

XtActionsRec actionTable [ ] = { 
{"Set", Set}, 
{"Unset", Unset}, 
{"Highlight", Highlight}, 



42 X Toolkit Intrinsics Reference Manual 



Xt - Translations and Actions (continued) XtAddActions 

{"Unhighlight", Unhighlight } 

{"Notify", Notify}, 

}; 

The actions specified in a translation can be registered before or after the translation table is 
parsed. 

The items in an action list registered with XtAddActions are registered globally for the 
entire application. By contrast, the action list specified in a widget class structure is 
local only translations specified by the widget itself can access local actions. However, a 
widget s local translation can access global actions, if there is no local action of the same name. 

If an application registers more than one global action with the same name, the most recently 
registered action is used. The Intrinsics register an action table for MenuPopup and Menu- 
Popdown as part of X Toolkit initialization. 

The Core class structure holds a list of translations and actions. Compare XtP arse- 
Trans lationTable. Chapter 7, Events, Translations, and Accelerators, in Volume Four, X 
Toolkit Intrinsics Programming Manual, contains general discussion and examples. 

Structures 

The xtActionList is a pointer to an xtActionsRec, defined as follows in <Xll/Xt- 

Intrinsic.h>: 

typedef _XtActionsRec *XtActionList; 

typedef struct _XtActionsRec { 

char *string; 

XtActionProc proc; 
} XtActionsRec; 

The string field is the name that you use in translation tables to access the procedure. The 
proc field is a pointer to a procedure that implements the functionality. 

The form of an XtActionProc is described in XtActionProc(2). 

The string field is the name that you use in translation tables to access the procedure. The 
proc field is a pointer to a procedure that implements the functionality. 

See Also 

Section 1.5, "Translations and Actions," 

XtAppAddActions,XtParseTranslationTable,MenuPopdown, MenuPopup, 

XtActionProc(2), 
Core(3). 



X Toolkit Intrinsics Reference Manual 



XtAddCallback \ 



Xt- Callbacks 



Name 

XtAddCallback add a callback procedure to a widget s callback resource. 

Synopsis 

void XtAddCallback (w, callback_name f callback, client_data) 
Widget w; 

String callback_name; 
XtCallbackProc callback; 
caddr_t client_data; 

Arguments 

w Specifies the widget 

callback_name 

Specifies the resource name of the callback list to which the procedure is to 
be appended. SeextCallbackProc(2). 

callback Specifies the callback procedure to be added. 

client_data Specifies the argument to be passed to the specified callback procedure when 
it is invoked by XtCallCallbacks, or specifies NULL. 

Description 

Generally speaking, a widget expecting to interact with an application will declare one or more 
callback lists as resources; the application adds functions to these callback lists, which will be 
invoked whenever the predefined callback conditions are met. Callback lists are resources, so 
that the application can set or change the function that will be invoked. 

Callbacks are not necessarily invoked in response to any event; a widget can call the specified 
routines at any arbitrary point in its code, whenever it wants to provide a "hook" for application 
interaction. For example, all widgets provide an xtNdestroyCallback resource to allow 
applications to interpose a routine to be executed when the widget is destroyed. 

Widgets can define additional callback lists as they see fit. For example, the Athena Command 
widget defines the xtNcallback callback list to notify clients when the widget has been 
activated (by the user clicking on it with the pointer). (This is actually a poor choice of names. 
It should have been given a more specific name, such as xtNnotif yCallback.) 

Callback functions are registered with a widget using a call to XtAddCallback or xtAdd- 
Callbacks. Even though callback lists are resources, callback functions cannot be added 
from resource files, since callback lists are maintained in a private internal form by the Intrin- 
sics. They cannot be modified directly except through one of the calls (such as XtAdd 
Callback) provided to access them. 

XtAddCallback adds a new callback to the end of the callback list. A callback will be 
invoked as many times as it occurs in the callback list. See xtCallbackProc(2) for a 
description of the format of a callback function. 

Use xtAddCallbacks to add a list of callbacks to a widget s callback list. 



44 X Toolkit Intrinsics Reference Manual 



Xt- Callbacks (continued) Xt Add Call back 

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

See Also 

Section 1.3, "Application Interface," 

XtAddCallbacks, XtCallCallbacks, XtRemoveAllCallbacks, XtRemove- 

Callback, XtRemoveCallbacks, 

XtCallbackProc(2). 




X Toolkit Intrinsics Reference Manual 45 



XtAddCallbacks 

Xt- Callbacks 



XtAddCallbacks add a list of callback procedures to a given widget s callback list. 
Synopsis 

void XtAddCallbacks (w f callback_name, callbacks) 
Widget w; 

String callback_name; 
XtCallbackList callbacks; 

Arguments 

w Specifies the widget. 

c a 1 1 ba ck_n ame 

Specifies the resource name of the callback list to which the procedure is to 
be appended. 

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

Description 

Generally speaking, a widget expecting to interact with an application will declare one or more 
callback lists as resources; the application adds functions to these callback lists, which will be 
invoked whenever the predefined callback conditions are met. Callback lists are resources, so 
that the application can set or change the function that will be invoked. 

Callbacks are not necessarily invoked in response to any event; a widget can call the specified 
routines at any arbitrary point in its code, whenever it wants to provide a "hook" for application 
interaction. For example, all widgets provide an XtNdestroyCallback resource to allow 
applications to interpose a routine to be executed when the widget is destroyed. 

Widgets can define additional callback lists as they see fit. For example, the Athena Command 
widget defines the xtNcallback callback list to notify clients when the widget has been 
activated (by the user clicking on it with the pointer). (This is actually a poor choice of names. 
It should have been given a more specific name, such as xtNnotif yCallback.) 

Callback functions are registered with a widget using a call to XtAddCallbacks or xtAdd- 
Callback. Even though callback lists are resources, callback functions cannot be added from 
resource files, since callback lists are maintained in a private internal form by the Intrinsics. 
They cannot be modified directly except through one of the calls (such as xtAddCallback) 
provided to access them. 

XtAddCallbacks adds new callbacks to the end of the callback list. A callback will be 
invoked as many times as it occurs in the callback list. See XtCallbackProc(2) for a 
description of the format of a callback function. 

Use XtAddCallback to add a single callback to a widget s callback list. 

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 



46 X Toolkit Intrinsics Reference Manual 



Xt- Callbacks (continued) Xt Add Call backs 

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 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* XtCallbackList; 

typedef struct _XtCallbackRec { 

XtCallbackProc callback; 

caddr_t client_data; 
} XtCallbackRec, *XtCallbackList; 

See Also 

Section 1.3, "Application Interface," 

XtAddCallback, XtCallCallbacks, XtRemoveAllCallbacks, XtRemove- 

Callback, XtRemoveCallbacks, 

XtCallbackProc(2). 



X Toolkit Intrinsics Reference Manual 47 



XtAddConverter \ xt _ Resource Management- 

Name 

XtAddConverter register a new resource converter. 

Synopsis 

void XtAddConverter (from_type, to_type, converter, convert_args f 

num_args) 
String from_type; 
String to_type; 
XtConverter converter; 
XtConvertArgList convert _args; 
Cardinal num_args; 

Arguments 

from_type Specifies the source type of the resource to be converted. 

t o_ type Specifies the destination type to which the resource is to be converted. 

converter 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 con vert_args. 

num_args Specifies the number of additional arguments to the converter 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 
verter. 

Structures 

typedef struct { 

XtAddressMode address_mode; 

caddr_t address_id; 

Cardinal size; 

} XtConvertArgRec, * XtConvertArgList ; 

See Also 

XtAppAddConverter, 
XtConverter(2). 



X Toolkit Intrinsics Reference Manual 



-X, - Even, HandHng / XtAddEventHandler 

Name 

XtAddEventHandler register a procedure to handle events. 

Synopsis 

void XtAddEventHandler (w, event_mask f nonmaskable, proc, 

client_data) 
Widget w, 

EventMask event_mask; 
Boolean n onma skable ; 
XtEventHandler proc; 
caddr__t client_data; 

Arguments 

w Specifies the widget for which this event handler is being registered. 

event_mask Specifies the event mask for which to call this procedure. 

nonmaskable Specifies a Boolean value that indicates whether this procedure should be 
called on the nonmaskable events. (This argument should almost always be 

FALSE.) 

proc Specifies the procedure that is to be called. See xtEventHandler(2). 

client_data Specifies additional data to be passed to the client s event handler. 

Description 

XtAddEventHandler registers a procedure to be called when an event matching the 
event_mask occurs in the specified widget XtAddEventHandler can be called at any 
time during the widget s lifetime; it ensures that Xlib will deliver the requested event by cal 
ling XSelect Input directly if the widget is realized, and it ORs the mask bits into the 
widget s event mask otherwise. (Compare XtAddRawEventHandler.) 

See xtEventHandler(2) for a description of an event handler procedure. 

A procedure may be registered with the same client_data to handle multiple events. Fur 
ther, more than one event handler can be registered for a given event. If multiple handlers are 
registered, the handlers will be called, but in an indeterminate order. Translations and event 
handlers can also be registered for the same event 

If a widget should wish to be informed when a nonmaskable event occurs, nonmaskable 
should be set to TRUE. The nonmaskable events are GraphicsExpose, NoExpose, 
SelectionClear, SelectionRequest, SelectionNotify, ClientMessage, and 
MappingNotify. Ordinarily, nonmaskable events are of interest only to the Intrinsics. 

Chapter 8, More Input Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual, 
provides example code for tracking pointer motion, pointer motion hints, and keyboard events. 




X Toolkit Intrinsics Reference Manual 49 



XtAddEventHandler 



(continued) 



Xt- Event Hand ling 



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 (|). Each mask symbol sets a bit in the 
event_mask. 

The table also briefly describes the circumstances under which you would want to specify each 
symbol. 



Event Mask Symbol 



NoEventMask 

KeyPressMask 

KeyReleaseMask 

Button? res sMask 

ButtonReleaseMask 

EnterWindowMask 

LeaveWindowMask 

Point erMotionMask 

Point erMotionHintMask 

ButtonlMotionMask 

Button2MotionMask 

ButtonSMotionMask 

Button4MotionMask 

ButtonSMotionMask 

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 EnterNotif y, 

LeaveNotif y, Focusln 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," Section 1.5, Translations and Actions," 

XtAddRawE vent Handler, Xt Remove Event Handler, 
Xt Event Handler (2). 



50 



X Toolkit Intrinsics Reference Manual 



Xt- Event Handling- 



J XtAddExposureToRegion 



Name 

XtAddExposureToRegion merge Expose and GraphicsExpose events into a region. 

Synopsis 

void XtAddExposureToRegion (event, region) 
XEvent * event; 
Region region; 

Arguments 

event Specifies a pointer to the Expose or GraphicsExpose event. 

region Specifies the region object (as defined in <XlllXutil.h>). 

Description 

The XtAddExposureToRegion utility function merges Expose and GraphicsExpose 
events into a region that clients can process at once rather than processing individual rectan 
gles. 

XtAddExposureToRegion computes the union of the rectangle defined by the exposure 
event and the specified region. Then it stores the results back in region. The Intrinsics 
pass an XRegion to a widget in the XtExposure method. 

If the event argument is not an Expose or GraphicsExpose event, XtAddExposure 
ToRegion returns without an error and without modifying region. 

This function is used by the Intrinsics exposure compression mechanism. It is not ordinarily 
used explicitly by widgets. 

Structures 

A region is defined as an XRegion in <Xll/region.h> among the private files for Xlib. A 
region is made up of these definitions: 

typedef struct { 

short xl, x2, yl, y2; 
} Box; 

typedef struct _XRegion { 
short size; 
short numRects; 
Box *rects; 
Box extents; 



See Also 

Core(3) 



X Toolkit Intrinsics Reference Manual 51 



XtAddGrab \ , 

v Xt - Pop Ups 

Name 

XtAddGrab redirect user input to a modal widget 

Synopsis 

void XtAddGrab ( w, exclusive, spring_l oaded) 
Widget w; 

Boolean exclusive/ 
Boolean spring_loaded; 

Arguments 

w Specifies the widget to add to the modal cascade. 

exclusive 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, Key-Release, ButtonPress,and ButtonRelease. The user events that are 
ignored when they occur outside the cascade are MotionNotify, EnterNotify, and 
LeaveNotif y. 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_l oaded is TRUE. If these are not both 
TRUE, XtAddGrab generates a warning and asserts an exclusive 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 exclusive 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 exclusive set to FALSE, 
so that the submenu can receive input event after it pops up. Modal dialog boxes that restrict 
user input to the most deeply nested dialog box add a subdialog widget to the cascade with 
exclusive 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 

Xtlnputld XtAddlnput (source, condition, proc, client_data) 
int source; 
caddr_t condition; 
XtlnputCallbackProc proc; 
caddr_t client_data; 

Arguments 

source Specifies the source file descriptor (on a UNIX-based system) or other 

operating-system-dependent device specification. 

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

proc Specifies the procedure that is to be called when input is available. See xt- 

InputCallbackProc(2). 

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

Description 

XtAddlnput obtains the default application context and invokes XtAppAddlnput. Xt 
Addlnput is a simplified interface to XtAppAddlnput, 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, XtAddlnput does not require the application to pass 
app_context explicitly. 

While most applications are driven only by X events, some applications need to incorporate 
other sources of input. XtAppAddlnput allows an application to integrate notification of 
pending file data into the event mechanism. The application uses XtAppAddlnput 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.) 

XtAppAddlnput also specifies the condition under which source can generate events. 
The legal values for condition are operating-system-dependent. On a UNIX-based system, 
the possible values are XtlnputReadMask, XtlnputWriteMask, or Xt Input Except - 
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 XtlnputCallback 
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 XtMainLoop. 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 

XtAppAddlnput, XtRemove Input, 
XtInputCallbackProc(2). 




X Toolkit Intrinsics Reference Manual 55 



XtAddRawEventHandler \ Xl _ Event Handllng _ 

Name 

XtAddRawEventHandler register an event handler without selecting for the event. 

Synopsis 

void XtAddRawEventHandler (w f event_mask, nonmaskable, proc, 

client_data) 
Widget v; 

EventMask event_mask; 
Boolean nonmaskable; 
XtEventHandler proc; 
caddr_t client_data; 

Arguments 

w Specifies the widget for which this event handler is being registered. 

event_mask Specifies the event mask for which to call this procedure. See XtAdd- 
Event Handler. 

nonmaskable Specifies a Boolean value that indicates whether this procedure should be 
called on the nonmaskable events (GraphicsExpose, NoExpose, 
SelectionClear, SelectionRequest, SelectionNotify, 
ClientMessage, and MappingNotif y ) . 

proc Specifies the procedure that is to be registered. See xtEventHandler(2). 

client_data Specifies additional data to be passed to the client s event handler. 

Description 

XtAddRawEventHandler is similar to XtAddEventHandler except that it does not 
affect the widget s mask and never causes an xSelect input call to be made for its events. 
The event mask in XtAddRawEventHandler indicates which events the handler will be 
called in response to, but only when these events are selected elsewhere. 

A raw event handler might be used to "shadow" another event handler (both added with the 
same event mask), such that until a primary event handler is added, the shadow handler will 
never be called. The primary handler will be added with XtAddEventHandler and will 
alter the event mask, and then both handlers will be called when the appropriate events occur. 

However, the "shadowing" technique is not necessary to assure that multiple calls to XtAdd 
EventHandler would not result in wasted XSelect Input calls in which the event mask 
has not changed. Xt keeps a cache of the event masks of each widget and calls XSelect - 
Input only when it is necessary to change the window s event mask attribute. 

Raw event handlers are removed with a call to xtRemoveRawEventHandler. 

A widget needs to register a raw handler only in extraordinary circumstances; most widgets use 

XtAddEventHandler. 



X Toolkit Intrinsics Reference Manual 



Xt - Event Handling 



(continued) 



XtAddRawEventHandler 



See Also 

Section 1.4, "Events," 

XtAddE vent Handler, XtRemoveRawE vent Handler, 
XtEventHandler(2). 



X Toolkit Intrinsics Reference Manual 



57 



XtAddTimeOut 

Xt - Event Handling 

Name 

XtAddTimeOut create a timeout value. 

Synopsis 

Xtlntervalld XtAddTimeOut (interval, proc, client_data) 
unsigned long interval; 
XtTimerCallbackProc proc; 
caddr_t client_data; 

Arguments 

interval Specifies the time interval in milliseconds. 

proc Specifies the procedure to be called when the time expires. See xt Timer - 

CallbackProc(2). 

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

Description 

XtAddTimeOut obtains the default application context and invokes XtAppAddTimeOut. It 
is retained as a simplified interface to xtAppAddTimeout. Since most applications have 
only one app_context, XtAddTimeOut does not require the application to pass an 
app_ context explicitly. 

The Intrinsics invoke the specified proc when interval elapses and the timeout is removed 
from the event queue. 

The return value xtlntervallD uniquely identifies the pending timer pseudo-event. The 
pending event can be deleted from the queue before the interval expires by calling xt- 

RemoveTimeOut. 

The callback procedure pointer that is invoked when timeouts expire is of type XtTimer 
CallbackProc. 

Xt AppNextEvent and Xt AppPeekEvent dispatch timer queue entries. 

See Also 

Section 1.4, "Events," 

XtAppAddTimeOut, XtAppNextEvent, XtAppPeekEvent, XtAppPending, Xt- 

DispatchEvent, XtRemoveTimeOut, 

XtTimerCallbackProc(2). 



58 X Toolkit Intrinsics Reference Manual 



c u f XtAddWorkProc 

Xt - Event Handling 

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_ con text explicitly. 

xtWorkProc(2) discusses the responsibilities of the application s background processing rou 
tine. 

See Also 

XtAppAddWorkProc, XtRemoveWorkProc, 
XtWorkProc(2). 



X Toolkit Intrinsics Reference Manual 59 



XtAppAddActions 



Xt - Translations and Actions 



Name 

XtAppAddActions declare an action table and register it with the Resource Manager. 

Synopsis 

void XtAppAddActions (app_context, actions, num_actions) 
XtAppContext app_context; 
XtActionList actions; 
Cardinal num_actions; 

Arguments 

app_ context Specifies the application context. 

a c t i on s Specifies the action table to register. 

num_args Specifies the number of entries in this action table. 

Description 

All widget class records contain an action table. In addition, using xtAddActions, an appli 
cation can register its own action tables with the Resource Manager. An action table consists 
of a list of string names (which can be used in translation tables to associate an action with one 
or more events) and corresponding function pointers. The function pointer is of type xt- 

ActionProc. 

By convention, 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 files, which are made up entirely of strings. 

For example, the Command widget has procedures to take the following actions: 

Set the appearance of the Command widget to indicate it is activated when a pointer but 
ton has been pressed in it 

Unset the button back to its normal mode. 

Highlight the button borders when the pointer enters the Command widget 

Unhighlight the button borders when the pointer leaves. 

Notify any callbacks that the button has been activated. 

The action table for the Command widget class makes these functions available to translation 
tables written for Command or any subclass: 

XtActionsRec actionTable [ ] = { 
{"Set", Set}, 
{"Unset", Unset}, 
{"Highlight", Highlight}, 



60 X Toolkit Intrinsics Reference Manual 



Xt - Translations and Actions (continued) XtAppAddActions 

{"Unhighlight", Unhighlight} 

{"Notify", Notify}, 

}; 

The actions specified in a translation can be registered before or after the translation table is 
parsed. 

The items in an action list registered with xtAddActions are registered globally for the 
entire application. By contrast, the action list specified in a widget class structure is 
local only translations specified by the widget itself can access local actions. However, a 
widget s local translation can access global actions, if there is no local action of the same name. 

If an application registers more than one global action with the same name, the most recently 
registered action is used. The Intrinsics register an action table for MenuPopup and Menu- 
Popdown as part of X Toolkit initialization. 

The Core class structure holds a list of translations and actions. Compare xtParse- 
TranslationTable. Chapter 7, Events, Translations, and Accelerators, in Volume Four,X 
Toolkit Intrinsics Programming Manual, contains general discussion and examples. 

If more than one action is registered with the same name, the most recently registered action is 
used. If duplicate actions exist in an action table, the first is used. The Intrinsics register an 
action table for actions called MenuPopup and MenuPopdown as part of X Toolkit initializa 
tion. 

See Also 

XtAddActions 



X Toolkit Intrinsics Reference Manual 



XtAppAddConverter 

v Xt - Resource Management 

Name 

XtAppAddConverter register a new resource converter for an application. 

Synopsis 

void XtAppAddConverter (app_ con text, from_type, to_type r 

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 Specifies the application context. 

from_type Specifies the source type of the resource to be converted. 

to_type Specifies the destination type to which the resource is to be converted. 

converter 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 sec 
tion below for a detailed description of the format of con vert_args. 

num_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 derived. These are defined in 
<X11 /Convert. h>, as follows: 

typedef enurn { 

/* address mode parameter representation */ 

XtAddress, /* address */ 

XtBaseOffset, /* offset */ 

Xtlmmediate /* constant */ 

XtResourceString /* resource name string */ 

XtResourceQuark /* resource name quark */ 
} XtAddressMode; 



62 X Toolkit Intrinsics Reference Manual 



Xt - Resource Management (continued) XtAppAddConverter 

typedef struct { 

XtAddressMode address_mode; 

caddr__t address_id; 

Cardinal size; 
} XtConvertArgRec, *XtConvertArgList ; 

The address_mode member specifies how to interpret the address_id member: 
xt Addre s s causes addr e s s_id to be interpreted as the address of the data. 

xtBaseOf f set causes address_id to be interpreted as the offset from the widget 

base. 

xt Immediate causes addre s s_id to be interpreted as a constant. 

xtResourceString causes address_id to be interpreted as the name of a resource to be 
converted into an offset from the widget base. 

XtResourceQuark means address_id is an internal compiled form of an Xt 
ResourceString. The size field specifies the length of the data in 
bytes. 

Assuming a routine called CvtStringToPixel (see xtConverter for an example of this 
converter), the following code registers the routine as an official resource converter: 

static XtConvertArgRec colorConvertArgs [ ] = { 

{XtBaseOf f set, (caddr_t) XtOff set (Widget, core . screen) , 

sizeof (Screen *)}, 
{XtBaseOffset, (caddr_t) XtOff set (Widget, core .colormap) , 

sizeof (Colormap) } 
}; 

XtAddConverter (XtRString, XtRPixel, CvtStringToPixel, 
colorConvertArgs, XtNumber (colorConvertArgs) ) ; 

The conversion argument descriptors colorConvertArgs and screenConvertArg are 
predefined. The screenConvertArg descriptor puts the widget s screen field into 
args[0]. The colorConvertArgs descriptor puts the widget s screen field into 
args [ ] and the widget s colormap field into args [ 1 ] . 

Conversion routines should not just put a descriptor for the address of the base of the widget 
into args [ ] and then use that in the routine. They should pass in the actual values that the 
conversion depends on. By keeping the dependencies of the conversion procedure-specific, it 
is more likely that subsequent conversions will find what they need in the conversion cache. 
This way the cache is smaller and has fewer and more widely applicable entries. 

XtAddConverter provides a simplified interface for programs using the default application 
context. 

XtConverter(2) explains the responsibilities and conventions of the converter function 
itself; it also shows an example converter, CvtStringToPixel. 




X Toolkit Intrinsics Reference Manual 63 



XtAppAddConverter (continued) Xt - Resource Management 

See Also 

XtAddConverter, XtDirectConvert, 
XtConverter(2). 



64 X Toolkit Intrinsics Reference Manual 



Xt- Event Hand I Ing 



f XtAppAddlnput 



Name 

XtAppAddlnput register a new file as an input source for a given application. 

Synopsis 

Xtlnputld XtAppAddlnput (app_con text, source, condition, proc, 

client_data) 

XtAppContext app_context; 
int source; 
caddr_t condition; 
XtlnputCallbackProc proc; 
caddr_t client_data; 

Arguments 

app_context Specifies the application context that identifies the application. 

source Specifies the source file descriptor (on a UNIX-based system) or other 

operating-system-dependent device specification. 

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

proc Specifies the procedure that is to be called when condition is true. See 

XtInputCallbackProc(2). 

cli en t_da ta Specifies for argument source to be passed to proc when I/O is available. 

Description 

While most applications are driven only by X events, some applications need to incorporate 
other sources of input. XtAppAddlnput allows an application to integrate notification of 
pending file data into the event mechanism. The application uses XtAppAddlnput 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.) 

XtAppAddlnput also specifies the condition 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 Input ReadMask, XtlnputWriteMask, or XtlnputExcept- 
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 XtlnputCallback 
Proc. 

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



X Toolkit Intrinsics Reference Manual 65 



XtAppAddlnpUt (continued) Xt- Event Handling 

See Also 

XtAddlnput, Xt Remove Input, 
XtInputCallbackProc(2). 



55 X Toolkit Intrinsics Reference Manual 



c u Mt f XtAppAddTimeOut 

Xt - Event Handling 

Name 

XtAppAddTimeOut invoke a procedure after a specified timeout. 

Synopsis 

Xtlntervalld XtAppAddTimeOut (app_con text, interval, proc, 

client_data) 

XtAppContext app_context; 
unsigned long interval; 
XtTimerCallbackProc proc; 
caddr_t client_data; 

Arguments 

app_context Specifies the application context for which the timer is to be set. 

interval Specifies the time interval in milliseconds. 

proc Specifies the procedure that is to be called when the time expires. See xt- 

TimerCallbackProc(2). 

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

Description 

While most applications are driven only by X events, some applications need to incorporate 
other types of events, such as timeouts or file data pending. XtAppAddTimeOut allows a 
program to have an event occur after a specified timeout. XtAppAddTimeOut creates the 
timeout and returns an identifier for it The length of the timeout value is interval mil 
liseconds. 

The Intrinsics invoke the specified callback when interval elapses, and the timeout is 
removed from the event queue. 

The return value Xt Interval ID uniquely identifies the pending timer pseudo-event The 
pending event can be deleted from the queue before the interval expires by calling xt- 

RemoveTimeOut. 

The callback procedure pointer that is invoked when timeouts expire is of type XtTimer 
CallbackProc. 

XtAppNextEvent and Xt AppPeekEvent dispatch timer queue entries. 

See Also 

Section 1.4, "Events," 

XtAddTimeOut, XtAppNextEvent, XtAppPeekEvent, XtDispatchEvent, 

Xt Remo veT imeOu t , 

XtTimerCallbackProc(2). 




X Toolkit Intrinsics Reference Manual 67 



XtAppAddWorkProc \ 

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

client_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 xtAppNext Event or xt- 
AppProcessEvent. 

XtAppAddWorkProc adds the specified proc for the application identified by 
app_context. XtWorkProcId 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 

XtAddWorkProc, XtAppNext Event, XtAppProcessEvent, XtRemoveWorkProc, 
XtWorkProc(2). 



68 X Toolkit Intrinsics Reference Manual 



Xt- Initialization 



J XtAppCreateShell 



Name 

XtAppCreateShell create additional top-level widget 

Synopsis 

Widget XtAppCreateShell (application_name, application_class r 

widget_class, display, args, num_args) 
String application_name; 
String application_class; 
WidgetClass widget_class; 
Display *display; 
ArgList args; 
Cardinal num_args; 

Arguments 

appl ication_name 

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

applicatio/j_class 

Specifies the class name of this application. 

wi dge t_ cl a s s 

Specifies the widget class that the application top-level widget should be 
(normally applicationShellWidgetClass). 

di spl ay Specifies the display from which to get the resources. 

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

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

applicatio/3_na/ne and appl ication_cl ass 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 



XtAppCreateShell (continued) Xt - Initialization 

There are two alternatives for creating multiple top-level shells within a single (logical) appli 
cation: 

Designate one shell as the real top-level shell and create the others as pop-up children of 
it by using XtCreatePopupShell. 

Have all shells as pop-up children of an unrealized top-level shell. 

The first method, which is best when there is a clear choice for what is the main window, leads 
to resource specifications like the following: 

xmail. geometry: . . . (the main window) 

xmail. read, geometry: . . . (the read window) 

mail . compose . geometry : . . . (the compose window) 

The second method, which is best if there is no main window, leads to resource specifications 
like the following: 

xmail. headers .geometry: . . . (the headers window) 
xmail. read, geometry: . . . (the read window) 

xmail .compose. geometry : . . . (the compose window) 

Xtlnitialize is a simplified interface to XtCreateApplicationContext, Xt- 
Displaylnitialize, and XtAppCreateShell. 

See Also 

Section 1.1, "Widget Lifecycle," 

XtCreateApplicationContext, XtCreatePopupShell, XtDisplay- 
Initialize, Xtlnitialize. 



70 X Toolkit Intrinsics Reference Manual 



E u , XtAppError 

Xt - Error Handling 

Name 

XtAppError call the installed fatal error procedure. 

Synopsis 

void XtAppError (app_con text, message) 
XtAppContext app_context; 
String message; 

Arguments 

app_context Specifies the application context. 

message Specifies the message to be reported. 

Description 

Xt provides two levels of error handling: 

A high-level interface that takes an error name and class and looks the error up in an 
error resource database. 

A low-level interface that takes a simple string, which is printed out as the error message. 

Application-context-specific error handling is not implemented on many systems. Most imple 
mentations will have just one set of error handlers. If different handlers are set for different 
application contexts, the one set last will be used. 

In theory, most programs should use xtAppErrorMsg (or xtErrorMsg if application 
contexts are not being used), not XtAppError or xtError, so that the programs can be eas 
ily customized to provide international or other custom error messages. However, the low-level 
handlers are much easier to use. 

XtAppError calls the low-level fatal error handler. Fatal errors are assumed to be catastro 
phic and irrecoverable. A warning error handler also exists for errors that require attention but 
do not preempt a program running correctly to a normal successful completion. (xtApp- 
Warning calls the corresponding nonfatal error handler. XtAppErrorMsg and xtApp- 
WarningMsg call the corresponding high-level handlers.) 

See Also 

XtAppErrorMsg, XtAppSetErrorHandler, XtAppSetErrorMsgHandler, XtApp- 
SetWarningHandler, XtAppSetWarningMsgHandler, XtAppWarning, XtApp- 
WarningMsg, XtError, XtErrorHandler, XtErrorMsg, XtErrorMsgHandler, 
XtSetErrorHandler, XtSetErrorMsgHandler, XtSetWarningHandler, XtSet- 
WarningMsgHandler, XtWarning, XtWarningMsg. 



X Toolkit Intrinsics Reference Manual 



XtAppErrorMsg \ vi 

v Xt - Error Handling 

Name 

XtAppErrorMsg call the high-level fatal error handler. 

Synopsis 

void XtAppErrorMsg(app_context, name, type, class, default, 

pa rams, num_params) 
XtAppContext app_context; 
String name; 
String type; 
String class; 
String default; 
String * pa rams; 
Cardinal *num_params; 

Arguments 

app_ c on t ex t Specifies the application context. 

name Specifies the general kind of error; for example, invalidParameter. 

type Specifies the detailed name of the error. This is specified using print f -like 

syntax, with the parameters and number of parameters specified by pa rams 
and num_params. 

class Specifies the resource class. 

defaul t Specifies the default message to use if no message is found in the database. 

pa rams Specifies a pointer to a list of values to be stored in the type argument when 

the message is generated. 

num_params Specifies the number of values in the parameter list. 

Description 

Xt provides two levels of error handling: 

A high-level interface that takes an error name and class and looks the error up in an 
error resource database. 

A low-level interface that takes a simple string, which is printed out as the error message. 

The high-level functions construct a string to pass to the lower-level interface. The name and 
type arguments are concatenated to form the "name" that is used to look up a message in the 
error database. On UNIX-based systems, the error database is usually lusrlliblXlllXtErrorDB. 

In theory, most programs should use XtAppErrorMsg (or xtErrorMsg if application 
contexts are not being used), not xtAppError or xtError, so that the programs can be eas 
ily customized to provide international or other custom error messages. However, the low-level 
handlers are much easier to use. 

XtAppError calls the low-level fatal error handler. Fatal errors are assumed to be catastro 
phic and irrecoverable. A warning error handler also exists for errors that require attention but 
do not preempt a program running correctly to a normal successful completion. 



72 X Toolkit Intrinsics Reference Manual 



Xt - Error Handling (continued) XtAppErrorMsg 

(XtAppWarning calls the corresponding non-fatal error handler. XtAppErrorMsg and 
XtAppWarningMsg call the corresponding high-level handlers.) 

The Intrinsics internal errors all have class xtToolkitError. 
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 



XtAppGetErrorDatabase \ xt _ Error Hand|lng _ 

Name 

XtAppGetErrorDatabase obtain the error database. 

Synopsis 

XrmDatabase *XtAppGetErrorDatabase ( app_context ) 
XtAppContext app_context; 

Arguments 

app_context Specifies the application context. 

Description 

Xt s high-level error and warning message handlers use a resource-like database for storing 
error messages. On UNIX-based systems, the error database is usually stored in the file 
lusrlliblXlllXtErrorDB. However, it is possible to have separate application-context-specific 
databases. 

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

The XtAppGetErrorDatabase function returns the address of the error database. The 
Intrinsics do a lazy binding of the error database and do not merge in the database file until the 
first call to XtAppGetErrorDatabaseText. 

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 
contexts, the one performed last will prevail. 

The high-level error and warning handler procedure pointers are of type xtErrorMsg- 
Handler(2). For a complete listing of all errors and warnings that can be generated by the 
Intrinsics, see Appendix D, Standard Errors and Warnings. 

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, and XrmQGetResource. 

See Also 

XtAppGetErrorDatabaseText,XtGetErrorDat abase, XtGetErrorDat abase- 

Text, 

XtErrorMsgHandler(2). 



74 X Toolkit Intrinsics Reference Manual 



-x- Error Handling / XtAppGetErrorDatabaseText 

Name 

XtAppGetErrorDatabaseText obtain the error database text for an error or a warning. 

Synopsis 

void XtAppGetErrorDatabaseText (app_context, name, type, class, 

default, buffer_return, nbytes, database) 
XtAppContext app_context; 
char *name, *type, * class; 
char * default; 
char *buffer_return; 
int nbytes; 
XrmDatabase database; 

Arguments 

app_context Specifies the application context. 

name, type Specifies the name and type that are concatenated to form the resource name 
of the error message. 

class Specifies the resource class of the error message. 

defaul t Specifies the default message to use if an error database entry is not found. 

b u ffe r_ r e t u r n 

Specifies the buffer into which the error message is to be returned. 

nbytes Specifies the size of the buffer in bytes. 

database Specifies the name of the alternative database to be used, or specifies NULL if 
the application s database is to be used. 

Description 

Xt s high-level error and warning message handlers use a resource-like database for storing 
messages. Messages are looked up by name and class, and the appropriate message retrieved 
from the database. A custom error message handler can obtain the error database text for an 
error or a warning by calling XtAppGetErrorDatabaseText. 

XtAppGetErrorDatabaseText returns the appropriate message from the error database 
or returns the specified default message if one is not found in the error database. 

On UNIX-based systems, the error database is usually stored in lusrlliblXlllXtErrorDB. Cus 
tom error or warning messages should be appended to this file. 

The address of the loaded database can be returned by a call to xtAppGetErrorDatabase 
(or XtGetErrorDatabase). 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. 

Typical usage of XtAppGetErrorDatabaseText () is deep in the X Toolkit error hand 
ling code. See the code below (slightly modified for clarity) for use of this function from the Xt 



X Toolkit Intrinsics Reference Manual 75 



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 



char 



size; 



*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, 1000); 

/* 
* Need better solution here, perhaps use lower-level 

* printf primitives? 
*/ 

if (num_params == NULL) 
XtError (buffer) ; 
else { 

(void) sprintf (message, buffer, params [0], params [1], 
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) Xt AppGetErrorDatabaseText 

(void) fprintf (stderr, "X Toolkit Error: %s\n", message); 
exit (1) ; 

} 

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 

XtAppGetErrorDat abase, XtGetErrorDat abase, XtGetErrorDatabaseText, 
XtErrorMsgHandler(2). 




X Toolkit Intrinsics Reference Manual 



XtAppGetSelectionTimeout \ 

v Xt - Selections- 
Name 

XtAppGetSelectionTimeout get the current selection timeout value. 

Synopsis 

unsigned int XtAppGetSelectionTimeout (app_context) 
XtAppContext app_context; 

Arguments 

app_ context Specifies the application context. 

Description 

XtAppGetSelectionTimeout returns the current selection timeout value for the specified 
application context, in milliseconds. (Xt Get Select ionTimeout 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 

XtAppSet Select ionTimeout, Xt Get Select ionTimeout, XtSetSelection 
Timeout. 



78 X Toolkit Intrinsics Reference Manual 



Xt- Event Handling- 



J XtAppMainLoop 



Name 

XtAppMainLoop process input from a given application. 

Synopsis 

void XtAppMainLoop (app_con text) 
XtAppContext app_context; 

Arguments 

app_c on text Specifies the application context that identifies the application. 

Description 

XtAppMainLoop first reads the next incoming X event by calling xtAppNext Event and 
dispatches it to the appropriate registered procedure by calling xt D i spa tchE vent. This 
constitutes the main loop of X Toolkit applications, and as such, it does not return. Applica 
tions are expected to exit in response to some user action. 

There is nothing special about XtAppMainLoop; it is simply an infinite loop that calls Xt- 
AppNextEvent and then xtDispatchEvent. An application can provide its own version 
of this loop. For example, it might test an application-dependent global flag or other termina 
tion condition before looping back and calling XtAppNext Event. For example, if the num 
ber of top-level widgets drops to zero, the application may be able to exit safely. 

See XtAppAddWorkProc for information on how to spend idle time. 

See Also 

Section 1.1, "Widget Lifecycle," 

XtAppAddWorkProc, XtAppNext Event, XtDispatchEvent, XtMainLoop. 




X Toolkit Intrinsics Reference Manual 79 



XtAppNextEvent \ 

v Xt - Event Handling 

Name 

XtAppNextEvent return next event from an application s input queue. 

Synopsis 

void XtAppNextEvent (app_context f event_return) 
XtAppContext app_context; 
XEvent *event_return; 

Arguments 

app_context Specifies the application context that identifies the application. 

event_return 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 directly 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 Xt AppPending. 

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 Handling- 



J XtAppPeekEvent 



Name 

XtAppPeekEvent nondestructively examine the head of an application s input queue. 

Synopsis 

Boolean XtAppPeekEvent (app_con text, event_return) 
XtAppContext app_context ; 
XEvent *event_return; 

Arguments 

app_context Specifies the application context that identifies the application. 

e ven t_ r e t u rn 

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 xt Pending. 

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 event xtProcessEvent combines some 
(but not all) of the functions from xtNextEvent and xtDispatchEvent. That is, while 
xtNext Event 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 XtlMXEvent, Xt- 
iMTimer, and xt iMAlternatelnput. This lets you select only some of these event types 



X Toolkit Intrinsics Reference Manual 8 1 




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 



Xt- Event Hand ling 



J XtAppPending 



Name 

XtAppPending determine if there are any events in an application s input queue. 

Synopsis 

XtlnputMask XtAppPending (app_con text) 
XtAppContext app_context; 

Arguments 

app_context Specifies the application context for the application to check. 

Description 

XtAppPending returns a nonzero value if there are pending events from the X server, timer, 
or other input sources. The return value is a bit mask that is the OR of xt iMXEvent (an X 
event), xtlMTimer (a timer event introduced onto the queue by a call to xtAppAddTime- 
Out), and xtlMAlternatelnput (an alternate input event introduced onto the queue by a 
call to xtAppAddlnput). As a convenience, the symbolic name xtlMAll is defined as the 
bitwise inclusive OR of all event types. If there are no events pending, XtAppPending 
flushes the output buffer and returns zero. This call is the Intrinsics equivalent to the Xlib call 
XPending. 

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 xt Pee JcE vent. 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 event. 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 xtlMXEvent, xt- 
IMTimer, and XtlMAlternatelnput. This lets you select only some of these event types 
for processing. In addition, XtProcessEvent actually calls XtDispatchEvent to dis 
patch X events, so only this one call is necessary. 

See Also 

XtAppAddlnput, XtAppAddTimeOut, XtAppMainLoop, XtAppNext Event, XtApp- 
PeekEvent, XtAppProcessEvent, XtDispatchEvent, XtPending. 



X Toolkit Intrinsics Reference Manual 83 




XtAppProcessEvent V 



Xt- Event Handling 



Name 

XtAppProcessEvent process one input event 

Synopsis 

void XtAppProcessEvent (app_context, mask) 
XtAppContext app_context; 
Xt Input Mask 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 xtlMXEvent (X event), xtlMTimer (timer events), or xt- 
iMAlternatelnput (alternate input events). The symbolic name Xt- 
IMA11 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 



Xt- Error Handling- 



J XtAppSetErrorHandler 



Name 

XtAppSetErrorHandler register a procedure to be called on fatal error conditions. 

Synopsis 

void XtAppSetErrorHandler (app_con text, handler) 
XtAppContext app_context; 
XtErrorHandler handler; 

Arguments 

app_ con text Specifies the application context. 

handler Specifies the new fatal error procedure, which should not return. 

Description 

The default error handler provided by the Intrinsics is _xtError. On UNIX-based systems, it 
prints the message to standard error and terminates the application. 

Using XtAppSetErrorHandler or XtSetErrorHandler, you can replace this default 
handler with one of your own. 

Fatal error handlers should not return. If one does, subsequent X Toolkit behavior is undefined. 

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, XtAppSetErrorMsgHandler, XtAppSetWarning- 
Handler, XtAppSetWarningMsgHandler, XtAppWarning, XtAppWarningMsg, 
XtError, XtErrorHandler, XtErrorMsg, XtErrorMsgHandler, XtSetError 
Handler, XtSetErrorMsgHandler, XtSetWarningHandler, XtSetWarningMsg- 
Handler, XtWarning, XtWarningMsg, 
XtErrorHandler(2). 




X Toolkit Intrinsics Reference Manual 85 



XtAppSetErrorMsgHandler A 

v Xt - Error Handling 

Name 

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

Synopsis 

void XtAppSetErrorMsgHandler (app_con text, msg_handler) 
XtAppContext app_context; 
XtErrorMsgHandler msg_handler; 

Arguments 

app_c on text Specifies the application context. 

msg_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 calls 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 



Xt- Selections- 



J XtAppSetSelectionTimeout 



Name 

XtAppSetSelectionTimeout set the Intrinsics selection timeout 

Synopsis 

void XtAppSetSelectionTimeout (app_context, timeout) 
XtAppContext app_context; 
unsigned long timeout; 

Arguments 

app_context Specifies the application context. 

timeout Specifies the selection timeout in milliseconds. 

Description 

XtAppSetSelectionTimeout sets the Intrinsics selection timeout value for the specified 
application context. (xtSetSelectionTimeout performs the same function 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 select ion- 
Timeout application resource, or if select ionTimeout is not specified, it defaults to 
5000 milliseconds (5 seconds). 

The current timeout value can be retrieved by a call to xtAppGetSelectionTimeout or 
Xt Get Select ionTimeout. 

See Also 

XtAppGet Select ionTimeout, Xt Get Select ionTimeout, XtSetSelection 
Timeout. 



X Toolkit Intrinsics Reference Manual 87 



XtAppSetWarningHandler \ Xt _ Error Handl|ng _ 

Name 

XtAppSetWarningHandler register a procedure to be called on nonfatal error conditions. 

Synopsis 

void XtAppSetWarningHandler (app_context, handler) 
XtAppContext app_context; 
XtErrorHandler handler; 

Arguments 

app_ con text Specifies the application context. 

handler Specifies the new nonfatal error procedure, which usually returns. 

Description 

The default warning handler provided by the Intrinsics is _Xt Warning. On UNIX-based sys 
tems, it prints the message to standard error and returns to the caller. Using XtAppSet 
WarningHandler, you can replace this default handler with one of your own. 

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, XtAppSetErrorMsg- 
Handler, XtAppSetWarningHandler, XtAppSetWarningMsgHandler, XtApp- 
Warning, XtAppWarningMsg, XtError, XtErrorHandler, XtErrorMsg, Xt- 
ErrorMsgHandler, XtSetErrorHandler, XtSetErrorMsgHandler, XtSet- 
WarningMsgHandler, XtWarning, XtWarningMsg. 



88 X Toolkit Intrinsics Reference Manual 



-x, - Error Hand,,n g / XtAppSetWarningMsgHandler 

Name 

XtAppSetWarningMsgHandler register a procedure to be called on nonfatal error condi 
tions. 

Synopsis 

void XtAppSetWarningMsgHandler (app_con text, msg_handler) 
XtAppContext app_context; 
XtErrorMsgHandler msg_handler; 

Arguments 

app_context Specifies the application context. 

msg_handler Specifies the new nonfatal error procedure, which usually returns. 

Description 

The default warning handler provided by the Intrinsics constructs a string from the error 
resource database and calls xtwarning. Using XtAppSetWarningMsgHandler, you can 
replace this 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 warning handler (using xtAppSetWarningHandler) 
instead. 

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, XtAppSetErrorMsg- 
Handler, XtAppSetWarningHandler, XtAppSetWarningMsgHandler, XtApp- 
Warning, XtAppWarningMsg, XtError, XtErrorHandler, XtErrorMsg, Xt 
ErrorMsgHandler, XtSetErrorHandler, XtSetErrorMsgHandler, XtSet- 
WarningHandler, XtWarning, XtWarningMsg. 



X Toolkit Intrinsics Reference Manual 89 



XtApp Warn ing X 



Xt- Error Handling 



Name 

XtAppWarning call the installed nonfatal error procedure. 

Synopsis 

void XtAppWarning (app_context, message) 
XtAppContext app_context; 
String message; 

Arguments 

app_context Specifies the application context. 

message Specifies the nonfatal error message that is to be reported. 

Description 

Xt provides two levels of error handling: 

A high-level interface that takes an error name and class and looks the error up in an 
error resource database. 

A low-level interface that takes a simple string, which is printed out as the error message. 

Application-context-specific error handling is not implemented on many systems. Most imple 
mentations will have just one set of error handlers. If different handlers are set for different 
application contexts, the one set last will be used. 

In theory, most programs should use XtAppWarningMsg (or XtWarningMsg if application 
contexts are not being used), not XtAppWarning or XtWarning, so that programs can be 
easily customized to provide international or other custom error messages. However, the low- 
level handlers are much easier to use. 

xtAppError calls the low-level fatal error handler. Fatal errors are assumed to be catastro 
phic and irrecoverable. A warning error handler also exists for errors that require attention but 
do not preempt a program running correctly to a normal successful completion. (XtApp 
Warning calls the corresponding non-fatal error handler. xtAppErrorMsg and xtApp- 
WarningMsg call the corresponding high-level handlers.) 

See Also 

XtAppError, XtAppErrorMsg, XtAppSetErrorHandler, XtAppSetErrorMsg- 
Handler, XtAppSetWarningHandler, XtAppSetWarningMsgHandler, XtApp 
WarningMsg, XtError, XtErrorHandler, XtErrorMsg, XtErrorMsgHandler, 
XtSetErrorHandler, XtSetErrorMsgHandler, XtSetWarningHandler, XtSet- 
WarningMsgHandler, XtWarning, XtWarningMsg. 



QQ X Toolkit Intrinsics Reference Manual 



K u . J XtAppWarningMsg 

Xt - Error Handling 

Name 

XtAppWarningMsg call the installed high-level warning handler. 

Synopsis 

void XtAppWarningMsg (app_con text, name, type, class , default, 

pa rams, num_params) 
XtAppContext app_context ; 
String name; 
String type; 
String class; 
String default; 
String * pa rams; 
Cardinal *num_params; 

Arguments 

app_context Specifies the application context. 

name Specifies the general kind of error; for example, InvalidParameter. 

type Specifies the detailed name of the error. This is specified using printf-like 

syntax, with the parameters and number of parameters specified by pa rams 
and num_params. 

class Specifies the resource class. 

defaul t Specifies the default message to use if no message is found in the database. 

pa rams Specifies a pointer to a list of values to be stored in the type argument when 

the message if generated. 

numjparams Specifies the number of values in the parameter list. 

Description 

Xt provides two levels of error handling: 

A high-level interface that takes an error name and class and looks the error up in an 
error resource database. 

A low-level interface that takes a simple string, which is printed out as the error message. 

The high-level functions construct a string to pass to the lower-level interface. The name and 
type arguments are concatenated to form the "name" that is used to look up a message in the 
error database. On UNIX-based systems, the error database is usually lusrlliblXlllXtErrorDB. 
In theory, most programs should use xtAppErrorMsg (or xtErrorMsg if application 
contexts are not being used), not xtAppError or xtError, so that the programs can be eas 
ily customized to provide international or other custom error messages. However, the low-level 
handlers are much easier to use. 

XtAppError calls the low level fatal error handler. Fatal errors are assumed to be catastro 
phic and irrecoverable. A warning error handler also exists for errors that require attention but 
do not preempt a program running correctly to a normal successful completion. 



X Toolkit Intrinsics Reference Manual 9 1 



XtAppWarningMsg (continued) Xt - Error Handling 

(xtAppWarning calls the corresponding non-fatal error handler. xtAppErrorMsg and 
XtAppWarningMsg call the corresponding high-level handlers.) 

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 



Xt - Translations and Actions- 



XtAugmentTranslations 



Name 

XtAugmentTranslations nondestructively merge new translations with widget s existing 

ones. 

Synopsis 

void XtAugmentTranslations (w, translations) 
Widget w; 
XtTranslations translations; 

Arguments 

w Specifies the widget into which the new translations are to be merged. 

translations Specifies the compiled translation table to merge in (must not be NULL). 
Description 

XtAugmentTranslations nondestructively merges translations into a widget s 
existing translations. If translations contains an event or event sequence that already 
exists in the widget s translations, then the new translation is ignored. 

The translation table must be in compiled form, as produced by xtParseiranslation- 
Table. 

Translation tables can also be constructed by converting resources. To make it easy to modify 
translation tables in resource files, the string-to-translation-table resource type converter allows 
you to specify whether the table should replace, augment, or override any existing translation 
table in the widget. As an option, a pound sign (#) as the first character of the table followed by 
replace (default), augment, or override indicates how to treat existing translations 
(Release 3 and later only.) 

To merge new translations but keep existing translations in case of conflict, use XtAugment 
Translations. To completely remove existing translations, use xtUninstall- 
Translations. 

XtParseTranslationTable produces the binary form of the translation table from text 
XtConvert can also do the conversion, specifying xtRTranslationTable as the desti 
nation resource type. A text translation table is automatically parsed in the Core widget struc 
ture when a widget class is initialized. 

Release Information 

In Release 2, a bug made it impossible to successfully call xtAugmentrranslations on a 
widget that had already been realized. This bug was fixed in Release 3. 

The # syntax described above was new in Release 3. In addition, new syntax was added to sup 
port all keysym names in modifiers or detail fields, as well as case sensitivity, plus hooks for 
providing nonstandard case converters and nonstandard keycode-to-keysym converters. 



X Toolkit Intrinsics Reference Manual 93 



XtAugmentTranslatlonS (continued) Xt - Translations and Actions 

See Also 

Section 1.5, Translations and Actions," 

XtConvert, XtOverrideTranslations, XtParseTranslationTable, Xt- 
UninstallTranslations. 



94 X Toolkit Intrinsics Reference Manual 






Xt - Event Handling- 



XtBuildEventMask 



Name 

XtBuildEventMask retrieve a widget s event mask. 

Synopsis 

EventMask XtBuildEventMask (w) 
Widget w; 



Arguments 



Specifies the widget 



Description 

XtBuildEventMask returns a widget s event mask. The mask reflects the events the widget 
is currently selecting. (If the widget is unrealized, then the mask reflects the events the widget 
will select when it is realized.) This event mask is the logical OR of all event masks selected 
by adding event handlers and event translations (including accelerators). 

This event mask is stored in the XSetwindowAttributes structure by XtRealize- 
widget and is sent to the server when event handlers and translations are installed or removed 
for the realized widget. 

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 (|). Each mask symbol sets a bit in the 

event_mask. 

The table also briefly describes the circumstances under which you would want to specify each 
symbol. 



Event Mask Symbol 



NoEventMask 

KeyPressMask 

KeyReleaseMask 

ButtonPressMask 

ButtonReleaseMask 

EnterWindowMask 

LeaveWindowMask 

Point erMotionMask 

PointerMotionHintMask 

Button IMotionMask 

Button2MotionMask 

Button3MotionMask 

Button4MotionMask 

ButtonSMotionMask 

ButtonMotionMask 

KeymapStateMask 



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 EnterNotif y, 

LeaveNotif y, Focusln or FocusOut 



X Toolkit Intrinsics Reference Manual 



95 



XtBuildEventMask 



Event Mask Symbol 



ExposureMask 

VisibilityChangeMask 

StructureNotifyMask 

ResizeRedirectMask 

SubstructureNotifyMask 

SubstructureRedirectMask 

FocusChangeMask 

PropertyChangeMask 

ColormapChangeMask 

OwnerGrabButtonMask 



(continued) 



Circumstances 



Xt- Event Hand ling 



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," 

XtAddE vent Handler, XtAddRawEventHandler, XtRealizeWidget. 



96 



X Toolkit Intrinsics Reference Manual 



-X, - Keyboard HandHng / XtCallACCeptFOCUS 

Name 

XtCallAcceptFocus call a widget s accept_f ocus procedure. 

Synopsis 

Boolean XtCallAcceptFocus (w, time) 
Widget w; 
Time *ti/ne; 

Arguments 

w Specifies the widget 

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

Description 

XtCallAcceptFocus calls the specified widget s accept_f ocus method, passing it the 
specified widget and time, and returns whatever the accept_f ocus method returns. If the 

accept_f ocus 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 
XSetlnputFocus actually pass the focus to a child. 

The accept_f ocus method is part of the Core class structure. 
See Also 

XtSetKeyboardFocus, 
XtAcceptFocusProc(2). 



X Toolkit Intrinsics Reference Manual 97 



XtCallbackExclusive A 

v Xt - Pop Ups 

Name 

XtCallbackExclusive callback function to pop up a widget 

Synopsis 

void XtCallbackExclusive (w, client_data, call_data) 
Widget w; 

caddr_t client_data; 
caddr_t call_data; 

Arguments 

w Specifies the widget 

client_data Specifies the pop-up shell. 

call_data Specifies the callback data, which is not used by this procedure. 

Description 

The XtCallback* routines are built in callback functions that pop up a pop-up shell widget. 
The suffixes Exclusive, Nonexclusive, and None refer to the grab types xtGrabExclusive, 
XtGrabNonexclusive, and XtGrabNone, respectively, to be applied to the pop-up shell. 
Callback XtExclusive and callback xtNonexclusive call xtAddGrab with the 
exclusive argument set to TRUE and FALSE respectively. xtCallbackNone does not call 
XtAddGrab. 

To pop up a shell from a callback list, it is sufficient to pass one of the above routines in a call 
back list and to the client_data field to be the pop-up shell. When the XtCallback rou 
tine is called, it invokes xt Popup with the designated grab type. Before xt Popup is called, 
the XtCallback routine uses xtSetSensitive to set the calling widget to be insensitive. 

These routines provide one strategy for popping up widgets but you do not have to use them. 
It may be better to write a custom routine to call xt Popup yourself. In particular, an applica 
tion may provide customized code to create pop-up shells dynamically or to perform additional 
processing. For example, XtCallbackExclusive does nothing to place the pop-up widget, 
so it pops up in the upper-left corner of the display. A custom pop-up routine might move the 
pop-up shell to the location of the pointer, or the middle of the current window, before calling 
xt Popup. This can also be done in a separate callback function, added to the callback list 
before XtCallback*. 

An example follows: 

f () 
{ 

Widget pshell, button; 



pshell = XtCreatePopupShell (...); 

button = XtCreateWidget (...); 

XtAddcallback (button, XtCallbackNone, pshell) ; 



98 X Toolkit Intrinsics Reference Manual 



Xt-PopUps (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 pop-up shell pshell will be popped up. 

A companion example to the one above is presented on xtCallbackPopdown. 

See Also 

Section 1.6,"PopUps," 

XtCallbackNone, XtCallbackPopdown, XtCallCallbacks, XtMoveWidget, Xt- 
Popdown, XtPopup, XtSetSensitive. 



X Toolkit Intrinsics Reference Manual " 



XtCallbackNone \ xt . Pop Ups _ 

Name 

XtCallbackNone callback function to pop up a widget 

Synopsis 

void XtCallbackNone (w, client_data, call_data) 
Widget w; 

caddr_t client_data; 
caddr_t call_data; 

Arguments 

w Specifies the widget 

client_data Specifies the pop-up shell. 

call_data Specifies the callback data, which is not used by this procedure. 

Description 

See xtCallbackExclusive. 



700 X Toolkit Intrinsics Reference Manual 



/ XtCallbackNonexclusive 

Xt - Pop Ups 

Name 

XtCallbackNonexclusive callback function to pop up a widget 

Synopsis 

void XtCallbackNonexclusive (w r client_data, call_data) 
Widget v/; 

caddr_t client_data; 
caddr_t call_data; 

Arguments 

w Specifies the widget 

cl ient_data Specifies the pop-up shell. 

call_data Specifies the callback data, which is not used by this procedure. 

Description 

See XtCallbackExclusive. 




X Toolkit Intrinsics Reference Manual 101 



XtCallbackPopdown \ xt _ pop Ups _ 

Name 

XtCallbackPopdown pop down a widget from a callback routine. 

Synopsis 

void XtCallbackPopdown (vr r client_data r call_data) 
Widget w; 

caddr_t client_data; 
caddr_t call_data; 

Arguments 

w Specifies the widget. 

client_data Specifies a pointer to the xtPopdownlD structure. 
call_data Specifies the callback data, which is not used by this procedure. 

Description 

XtCallbackPopdown pops down a pop-up shell widget This function is suitable for pop 
ping down shells that were previously popped up with xtCallbackNone, xtCallback- 
Nonexclusive, or XtCallbackExclusive. An XtPopdownlD in the client_ data 
field indicates which widget is to be popped down. 

Structures 

XtCallbackPopdown casts the client data parameter to an XtPopdownlD pointer: 

typedef struct { 

Widget shell_widget; 

Widget enable_widget ; 
} XtPopdownlDRec, *XtPopdownID; 

shell_widget is the pop-up shell to pop down, and enable_widget is the widget that 
was used to pop it up. 

XtCallbackPopdown calls XtPopdown with the specified shell_widget and then calls 
XtSetSensitive to resensitize the enable_widget. 

Here is an example: 

Widget pshell, confirm; 
XtPopdownlDRec pop_rec; 

main() { 

confirm = XtCreateWidget (...); 

pshell = XtCreatePopupShell (...); 

pop_rec.shell_widget = pshell; 

pop_rec.enable_widget = confirm; 

XtAddCallback (confirm, XtCallbackPopdown, pop_rec) ; 



102 X Toolkit Intrinsics Reference Manual 



xt-PopUps (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- 

Exclusive. 

See Also 

Section 1.6,"PopUps," 

XtCallbackExclusive, XtCallCallbacks, XtPopdown, XtSetSensitive. 



X Toolkit Intrinsics Reference Manual 1 3 



XtCallCallbacks "\ 



Xt - Callbacks- 



Name 

XtCallCallbacks execute the procedures in a widget s callback list. 

Synopsis 

void XtCallCallbacks (w f callback_name f call_data) 
Widget w; 

String callback_name; 
caddr_t call_data; 

Arguments 

w Specifies the widget 

callback_name 

Specifies the resource name of the callback list to be executed. 

cali_data Specifies the value to pass to each callback procedure as its third argument 

Description 

XtCallCallbacks is used to execute the callbacks in a given callback list. 

The caJLI_da ta argument is a (32-bit) longword. The actual form of the data in the argument 
must be agreed on in advance by the callback function and the widget or application invoking it 
through XtCallCallbacks. The longword can be used to represent an address if more data 
is to be passed to the callback procedure. 

If no data is needed, the call_data argument should be NULL. (For example, the xt- 
Ncallback callback list in the Athena Command widget needs only to notify its clients that 
the button has been activated. No data is passed in.) 

XtCallCallbacks ensures that if a callback procedure itself adds callbacks (with xtAdd- 
Callbacks), no unwanted recursion ensues. 

Callback lists are maintained in an internal compiled form. Callback lists can be accessed out 
side the widget as resources but cannot be added, deleted, or invoked except through one of the 
Intrinsics functions (such as xtAddCallback) provided to access them. The Intrinsics them 
selves make sure that resources of type Callback get compiled into this internal form. 

For more information on how to explicitly compile callbacks as resources of type xt- 
RCallback, see XtConvert. 

See Also 

XtAddCallback, XtAddCallbacks, XtCallbackProc, XtConvert, XtRemove- 
AllCallbacks, XtRemoveCallbacks. 



104 X Toolkit Intrinsics Reference Manual 



AM , f XtCalloc 

Xt - Memory Allocation 

Name 

XtCalloc allocate an array and initialize elements to zero. 

Synopsis 

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

Arguments 

num Specifies the number of array elements to allocate. 

size 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 xtErrorMsg. 

XtCalloc differs from xtMalloc 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 calloc will still work. 

xtNew and xtNewString provide slightly higher-level approaches to memory allocation. 
See Also 

XtErrorMsg, XtFree, XtMalloc, XtNew, XtNewString, XtRealloc. 



X Toolkit Intrinsics Reference Manual 105 



XtCheckSubclass A 



Name 

XtCheckSubclass in DEBUG mode, verify a widget s class. 

Synopsis 

void XtCheckSubclass (w f widget_class, message) 
Widget w; 

WidgetClass widget_class; 
String message; 

Arguments 

w Specifies the widget 

wi dget_class Specifies the widget class to test against. 
message 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, XtlsSubclass, XtSuperclass, 
Core(3). 



106 X Toolkit Intrinsics Reference Manual 



I YtPlflQQ 

-Xt- Widget Information 

Name 

XtClass obtain a widget s class. 

Synopsis 

WidgetClass XtClass (w) 
Widget w; 

Arguments 

w Specifies the widget 

Description 

XtClass returns a pointer to the widget s class structure. 

The class is obtained by accessing the widget core field core . widget_class. 

XtClass is a macro for programs that include <XlllCoreP.h>. It is a function for application 
programs that do not have access to the Core widget field names. 

See Also 

XtCheckSubclass, XtlsSubclass, XtSuperclass, 
Core(3). 



X Toolkit Intrinsics Reference Manual 107 



XtCloseDisplay A 



Xt -Initialization 



Name 

XtCloseDisplay close a display and remove it from an application context. 

Synopsis 

void XtCloseDisplay (display) 
Display *display; 

Arguments 

display Specifies the display. 

Description 

XtCloseDisplay closes the specified display as soon as it is safe to do so. If called from 
within an event dispatch (for example, a callback procedure), XtCloseDisplay does not 
close the display until the dispatch is complete. Note that applications need only call Xt 
CloseDisplay if they are to continue executing after closing the display; otherwise, they 
should call XtDestroyApplicationContext or just exit 

See Also 

XtAppCreateShell, XtDestroyApplicationContext, Xtlnitialize. 



108 X Toolkit Intrinsics Reference Manual 



Xt - Geometry Management- 



J XtConfigureWidget 



Name 

XtConfigureWidget move and/or resize widget. 

Synopsis 

void XtConf igureWidget (w r x, y, width, height, border_width) 
Widget w; 
Position x; 
Position y; 
Dimension width; 
Dimension height; 
Dimension horde r_ width; 

Arguments 

w Specifies the widget 

x, y Specify the widget s new x and y coordinates. 

width, height, border_width 

Specify the widget s new dimensions. 

Description 

XtConfigureWidget moves and/or resizes a widget according to the specified width, 
height, and position values. It returns immediately if the specified geometry fields are the same 
as the old values. Otherwise, XtConfigureWidget writes the new x, y, width, height, 
and border_width values into the widget and, if the widget is realized, makes an Xlib 
XConf igureWindow call on the widget s window. 

If either the new width or the new height is different from its old value, XtConfigure 
Widget calls the widget s resize procedure to notify it of the size change. 

A parent widget can use XtConfigureWidget to set the geometry of its children. It may 
also be used to reconfigure a sibling widget A child widget can use xtMakeGeometry- 
Request and xtMakeResizeRequest to request more space from a parent 

If only the size of a widget is to be changed, xtResizeWidget is simpler to use; similarly, if 
only the location of a widget is to be changed, use xtMoveWidget . 

The x and y coordinates are specified with respect to the origin in the upper-left corner of the 
screen. Widget coordinates can be converted to screen coordinates with xtTranslate- 
Coords. 

Note that once a widget is resized or otherwise reconfigured by its parent it may need to do 
additional processing in its own resize method. Widgets usually need to know when they have 
changed size so that they can lay out their displayed data again to match the new size. When a 
parent resizes a child, it calls XtResizeWidget, which updates the geometry fields in the 
widget, configures the window if the widget is realized, and calls the child s resize method to 
notify the child. The resize procedure pointer is of type XtwidgetProc(2). 




X Toolkit Intrinsics Reference Manual 109 



XtConf igureWidget (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 

Section 1.8, "Geometry Management," 

XtMakeGeometryRequest, XtMakeResizeRequest, XtMoveWidget, XtResize- 
Widget, XtTranslateCoords. 



110 X Toolkit Intrinsics Reference Manual 



Xt - Resource Management- 



XtConvert 



Name 

XtConvert convert resource type. 

Synopsis 

void XtConvert (w, from_type, from, to_type, to_return) 
Widget w; 
String from_type; 
XrmValuePtr from; 
String to_type; 
XrmValuePtr to return; 




Arguments 

w 

from_type 
from 
to_type 



Specifies the widget to use for additional arguments (if any are needed). 
Specifies the source type. 
Specifies the value to be converted. 
Specifies the destination type. 



t o_re turn Returns the converted value. 

Description 

XtConvert looks up the appropriate resource converter registered to convert from_type to 
to_type and then calls XtDirectConvert to convert from to to_return. If the con 
version is successful, to_return . addr will be non-NULL. 

Xt recognizes and converts between the from_ types and the to_ types shown in the table 
below. In addition, it is possible to register custom converters using XtAddConverter. 



from_type 



XtRString 



to_type 



XtRAcceleratorTable 
XtRBoolean 

XtRBool 
XtRCursor 
XtRDimension 
XtRDisplay 

XtRFile 
XtRFloat 



Description 



Compiles a string accelerator table into internal accel 
erator table format (no need to call Xt Parse- 
Accelerator Table). 

Converts strings "true," "false," "yes," "no," "on," 
"off 1 to corresponding Boolean value (case insensi 
tive). 

Same as for XtRBoolean. 

Given a standard X cursor name, returns a cursor ID. 
Converts a width or height value to a Dimension. 
Given a display name, opens the display and returns a 
Display structure. 

Given a filename, opens the file and returns the file 
descriptor. 
Converts a numeric string to floating point 



X Toolkit Intrinsics Reference Manual 



111 



XtConvert 



(continued) 



Xt - Resource Management 



from type 



t o type 



Description 



XtRColor 
XtRPixel 
XtRInt 



XtRFont 



XtRFontStruct 



XtRInt 
XtRPixel 



XtRPosition 
XtRShort 

XtRTranslationTable 



XtRUnsignedChar 

XtRPixel 

XtRColor 

XtRBoolean 

XtRBool 

XtRColor 

XtRDimension 

XtRFloat 

XtRFont 

XtRPixel 

XtRPixmap 

XtRPosition 

XtRShort 

XtRUnsignedChar 



Given a font name, loads the font (if it is not already 
loaded) and returns the font ID. See Appendix C, 
Specifying Fonts and Colors, for more information on 
legal values. The value XtDef aultFont will return 
the default font for the screen. 

Given a font name, loads the font (if it is not already 
loaded) and returns a pointer to the Font Struct 
containing font metrics. The value XtDef aultFont 
will return the default font for the screen. 
Converts a numeric string to an integer. 
Converts a color name string (e.g., "red" or 
"#FFOOOO") into the pixel value that will produce the 
closest color possible on the hardware. See Appendix 
C, Specifying Fonts and Colors, for more information 
on legal values. The two values XtDefault- 
Background and XtDef aultForeground are 
always guaranteed to exist, and to contrast, on any 
server. 

Converts an x or y value to a Posit ion. 
Converts a numeric string to a short integer. 
Compiles string translation table into internal transla 
tion table format (no need to call XtParse- 
TranslationTable). 
Converts a string to an unsigned char. 
Converts an XColor structure to a pixel value. 
Converts a pixel value to an XColor structure. 
Converts an int to a Boolean. 
Converts an int to a Bool. 
Converts an int to an XColor. 
Converts an int to a Dimension. 
Converts an int to a float. 
Converts an int to a Font. 
Converts an int to a pixel value. 
Converts an int to a Pixmap. 
Converts an int to a Position. 
Converts an int to a short. 
Converts an int to an unsigned char. 



In addition, the Xmu library (miscellaneous utilities) contains converters between xtRString 
and XtRBackingStore, XtRCursor, XtRJustify, XtROrientation, XtRPixmap, 
and XtRWidget and between XtRFunction and XtRCallback. See Chapter 9, Resource 
Management and Type Conversion, in Volume Four, X Toolkit Intrinsics Programming Manual, 
for details. 



112 



X Toolkit Intrinsics Reference Manual 



Xt - Resource Management (continued) XtConvert 

All resource-fetching routines (e.g., XtGetSubresources, XtGetApplication- 
Resources as well as the internal code that reads the resource database when a widget is 
created) call resource converters if the user-specified resource is represented in a different form 
from the desired representation. A widget seldom has to access resource converters explicitly 
with XtConvert or XtDirectConvert. 

XtConvert accesses the widget w to obtain values for any additional arguments the resource 
converter needs. The computation of additional arguments is discussed with xtAppAdd- 
Converter. XtConvert invokes XtDirectConvert to perform the actual conversion. 
It is usually easier to access resource conversion indirectly through the resource mechanism. 

Converters not only are a good labor-saving device, but also make it possible to hide the details 
of data structures in the resource converter. For example, a program can access fonts, files, and 
application-dependent data structures using resource conversions. 

Structures 

typedef struct { 

unsigned int size; 

caddr_t addr; 
} XrmValue, *XrmValuePtr; 

See Also 

Section 1.7, "Resources," 

XtAppAddConverter, XtDirectConvert, XtGetApplicationResources, Xt 
GetSubresources. 



X Toolkit Intrinsics Reference Manual 1 13 



XtConvertCase \ xt . Keyboard 

Name 

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

Synopsis 

void XtConvertCase (display, keysym, lower_return r upper_return) 
Display *display; 
KeySym keysym; 
KeySym *lovfer_return; 
KeySym *upper_return; 

Arguments 

di spl ay Specifies the display that the keysym came from. 

keysym Specifies the keysym to convert. 

lower_return Returns the lower-case equivalent of the keysym. 
upper_ret urn 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 Intrinsics 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). 



1 14 X Toolkit Intrinsics Reference Manual 



Xt - Application Contexts- 



J XtCreateApplicationContext 



Name 

XtCreateApplicationContext 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. Xt Initialize creates a 
default application context. 

Xt Initialize is a simplified interface to XtToolkit Initialize, XtCreate 
ApplicationContext, XtDisplaylnitialize, 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 xtlnitialize. You cannot use these routines if you initialize a 
specific application context. 

Structures 

/* 

* Data structure for setting window attributes. 
*/ 

typedef struct { 

Pixmap background_pixmap; /* pixmap, None, or ParentRelative */ 

unsigned long background_pixel; /* background pixel */ 

Pixmap border_pixmap; /* pixmap, None, or CopyFromParent */ 

unsigned long border_pixel; /* border pixel value */ 

int bit_gravity; /* one of bit gravity values */ 

int win_gravity; /* one of the window gravity values */ 

int backing_store; /* NotUseful, WhenMapped, Always */ 

unsigned long backing_planes; /* planes to be preseved if possible */ 

unsigned long backing_pixel; /* value to use in restoring planes */ 

Bool save_under; /* should bits under be saved (pop ups) */ 

long event_mask; /* set of events that should be saved */ 

long do_not_propagate_mask; /* set of events that should not propagate */ 

Bool override_redirect; /* override redirected config request */ 

Colormap colormap; /* colormap to be associated with window */ 

Cursor cursor; /* cursor to be displayed (or None) */ 

} XSetWindowAttributes; 

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

#define CWBackPixmap (1L0) 

#define CWBackPixel (1L1) 

#define CWBorderPixmap (1L2) 

#define CWBorderPixel (1L3) 

#define CWBitGravity (1L4) 

#define CWWinGravity (1L5) 

#define CWBackingStore (1L6) 

#define CWBackingPlanes (1L7) 

tdefine CWBackingPixel (1L8) 



X Toolkit Intrinsics Reference Manual 1 15 



XtCreateApplicatlonContext (continued) Xt - Application Contexts 

#define CWOverrideRedirect (1L9) 

#define CWSaveUnder (1L10) 

#define CWEventMask (1L11) 

#define CWDontPropagate (1L12) 

#define CWColormap (1L13) 

#define CWCursor (1L14) 

See Also 

Section 1.1," Widget Lifecycle" 



X Toolkit Intrinsics Reference Manual 



Xt -Initialization 



j XtCreateApplicationShel! 



Name 

XtCreateApplicationShell create an additional top-level widget 

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 

appl icati on_n ame 

Specifies the name of the application instance. 

widget_class 

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. 

num_args 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, XtCreateApplicationShell 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 XtAppCreateShell. 

See Also 

Section 1.1, "Widget Lifecycle," 

XtAppCreateShell. 



X Toolkit Intrinsics Reference Manual 1 1 7 



XtCreateManagedWidget \ 



Name 

XtCreateManagedWidget create and manage a child widget 

Synopsis 

Widget XtCreateManagedWidget (name, widget_class, parent, args, 

num_args) 
String name; 

WidgetClass widget_class; 
Widget parent; 
ArgList args; 
Cardinal num_args; 

Arguments 

name Specifies the text name for the created shell widget 

wi dget_class Specifies the widget class pointer for the created widget 

pa ren t Specifies the parent widget 

args Specifies the argument list to override the resource defaults. 

num_args Specifies the number of arguments in the argument list. 

Description 

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. 



X Toolkit Intrinsics Reference Manual 



Xt-PopUps- 



J XtCreatePopupShell 



Name 

XtCreatePopupShell create a pop-up shell. 

Synopsis 

Widget XtCreatePopupShell (name, widget_class, parent, args, 

num_args) 
String name; 

WidgetClass widget_class; 
Widget parent; 
ArgList args; 
Cardinal num_args; 

Arguments 

name Specifies the text name for the created shell widget 

widget_class Specifies the widget class pointer for the created shell widget 

parent Specifies the parent widget 

args Specifies the argument list to override the resource defaults. 

num_args Specifies the number of arguments in the argument list. 

Description 

XtCreatePopupShell creates a pop-up shell widget suitable for containing one composite 
or simple widget that is to be popped up. Pop-up widgets are used to create windows that are 
descendants of the root window (rather than the application s main window) so that the pop-up 
window can appear anywhere on the screen, not just with the application. Therefore, pop ups 
have their own shell widget parent 

For a widget to pop up, it must be the child of a pop-up widget shell. A pop-up shell is never 
allowed more than one child, referred to as the pop-up child. Both the shell and child taken 
together are referred to as the pop up. 

xtCreateManagedWidget is used to create the pop up s child (which is the widget which 
will be visible to the user). After the pop-up shell and its child are created, the shell can be 
popped up with xtPopup and popped down with xtPopdown. It can also be popped up from 
a callback list with XtCallbackExclusive, et al. 

There are currently two classes of pop-up shells. They are listed in the table below and defined 
in <X1 II Shell. h>. Either can be passed to XtCreatePopupShell as the widget_ class 
argument 



X Toolkit Intrinsics Reference Manual 119 



XtCreatePopupShell 



Shell Types 



(continued) 



Xt-PopUps 



o ver r i de She llWidget Class 
trans lent ShellWidget Class 



Purpose 



Bypasses window management. 
Does not bypass window management. 



The overrideShellwidgetClass window is created with the override-redirect window 
attribute set, thereby forcibly bypassing window management, t rans lent ShellWidget - 
Class hints to the window manager that it should not decorate the window as it would a gen 
eral application and asks it to allow it to bypass its geometry management. The latter approach 
is preferred, but the former may be used for dropdown menus and other short-term windows. 

XtCreatePopupShell ensures that the specified class is a subclass of Shell and attaches 
the shell to the parent s pop-up list. The pop-up shell is not a normal child of its parent a 
pop-up child is kept on its parent s list of pop-up children. 

The pop-up shell accepts a resource callback list named xtNpopupCallback that will get 
called back when the widget is popped up. There is an analogous resource, xtNpopdown- 
Callback, that is invoked when the widget is popped down. These callbacks provide the 
opportunity either to make last-minute changes to a pop-up child before it is popped up or to 
change it after it is popped down. Note that excessive use of pop-up callbacks can make pop 
ping up occur more slowly. 

Once a pop-up shell is created, the single child of the pop-up shell can be created in one of 
three ways: 

At startup, an application can create the child of the pop-up shell. This is appropriate for 
pop-ups that the user will need on every invocation of the application. Creating the 
pop-up child at this time means that pop-up time is minimized, especially if the applica 
tion calls xtRealizeWidget on the pop-up shell at startup. When the menu is 
needed, all the widgets that make up the menu already exist and need only be mapped. 
The menu should pop up as quickly as the X server can respond. 

An application can postpone the creation of the child until it is needed, which minimizes 
application startup time, but slows pop-up time. 

An application can use work procedures (xtAddWorkProc) to create the child during 
application idle time. This solves both the above problems, but may introduce random 
user response delays. 

The pop-up shell accepts a resource function pointer (of type xtRFunction) that gets 
invoked when a widget is popped up. The resource is named xtNcreatePopupChild- 
Proc. It can be used to create the pop-up child, if one does not exist at the time the pop-up is 
invoked. 



120 



X Toolkit Intrinsics Reference Manual 



Xt-PopUps (continued) XtCreatePopupShell 

Pop-up child creation does not map the pop up, even if you create the child and call Xt- 
Realizewidget on the pop-up shell. Pop ups can be popped up through several mecha 
nisms: 

A call to xt Popup. 

One of the supplied callback procedures (for example, xtCallbackNone, xt- 
CallbackNonexclusive, or XtCallbackExclusive). 

The standard translation action MenuPopup. 

Some of these routines take an argument of type XtGrabKind, which is defined as: 

typedef enum {XtGrabNone, XtGrabNonexclusive, XtGrabExclusive } XtGrabKind; 

For a general discussion of pop ups, see Section 1.6, "Pop Ups." Popping up a shell with the 
Resource Manager is discussed in Section 1.5, Translations and Actions." For a discussion of 
the underlying concepts of override-redirection, see Chapter 4 of Volume One, Xlib Program 
ming Manual. 

See Also 

XtCallbackExclusive, XtCreateManagedWidget, XtNameToWidget, Xt- 
Popdown, XtPopup. 



X Toolkit Intrinsics Reference Manual 121 



XtCreateWidget \ Yi 

v Xt - Widget Lifecycle 

Name 

XtCreateWidget create an instance of a widget 

Synopsis 

Widget XtCreateWidget (name, widget_class, parent, args, 

num_args) 
String name; 

WidgetClass widget_ class; 
Widget parent; 
ArgList args; 
Cardinal num_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 

widget_class 

Specifies the widget class pointer for the created widget 

parent Specifies the parent widget 

args Specifies the argument list to override the resource defaults. 

num_args 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- 
Number macro.) 

Description 

XtCreateWidget creates a new widget instance of class vridget_ 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) XtCreateWldget 

Initializes the core nonresource data fields (for example, parent and visible). 

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 raintwidgetClass, 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 constraintwidgetClass, 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), Constrain t(3), and Compos- 
ite(3). 

See Also 

Section 1.1, "Widget Lifecycle," 

XtCreateManagedWidget. 



X Toolkit Intrinsics Reference Manual 123 



XtCreateWindow \ Y< 

Xt- Window Manipulation 

Name 

XtCreateWindow create widget s working window 

Synopsis 

void XtCreateWindow (w, window_class, visual, value_mask, 

attributes) 
Widget w; 

unsigned int window_class; 
Visual * visual; 
XtValueMask fyalue_mask; 
XSetWindowAt tributes * attributes; 

Arguments 

w Specifies the widget that is used to set the x,y coordinates and so on. 

window_class Specifies the Xlib window class (Input Output, Input Only, or 
CopyFromParent). 

visual Specifies the Xlib visual type (usually CopyFromParent). 

val ue_mask Specifies which attribute fields to use. 

attributes Specifies the window attributes to use in the XCreateWindow call. 

Description 

A widget is responsible for creating its own window when its Core realize method is called. 
Rather than call the Xlib XCreateWindow function explicitly, a realize method should 
call the Intrinsics analog XtCreateWindow, which simplifies the creation of windows for 
widgets. XtCreateWindow calls the Xlib XCreateWindow function, merging values from 
the Core widget instance structure (see below) and attributes. Then it assigns the created 
window to the widget s core window field. 

XtCreateWindow evaluates the following fields of the Core widget structure: 

depth 

screen 

parent -> core. window 

x and y 

width and height 

border_width 

Window attributes are documented more fully in Volume One, Xlib Programming Manual, and 
Volume Two, Xlib Reference Manual; see XSetWindowAtt ributes for a summary. 



124 X Toolkit Intrinsics Reference Manual 



Xt - Window Manipulation 



(continued) 



XtCreateWindow 



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; 

See Also 

Section 1.1, "Widget Lifecycle," 

XtRealizeProc(2). 



/* 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) */ 



X Toolkit Intrinsics Reference Manual 



125 



XtDatabaSG V xt _ Res0 urce Management- 

Name 

XtDatabase obtain the resource database for a particular display. 

Synopsis 

XrmDatabase XtDatabase (display) 
Display * display ; 

Arguments 

display Specifies the display for which the resource database should be returned. 

Description 

XtDatabase returns the complete resource database built by xtDisplaylnitialize that 
is associated with display. The contents of the database are fully merged from resource val 
ues on the server and command line arguments. 

If display has not been initialized by XtDisplaylnitialize, the results are not 
defined. 

In general, the type XrmDatabase should be treated as opaque and should not be manipulated 
directly. XrmDatabases can be manipulated safely with Xlib functions (XrmPut- 
Resource, XrmQPutResource, XrmGetResource, XrmQGetResource, etc.). 

Xt Initialize, XtGetResourceList, and XtGetSubresources provide a more 
manageable approach to obtaining resources. 

Structures 

Set the typedef of XrmDatabase to _XrmHashBucketRec. _XrmHashBucketRec is 
defined within Xlib source with this structure: 

typedef struct _XrmHashBucketRec { 

XrmHashBucket next; /* Next entry in this hash chain */ 

XrmQuark quark; /* Quark for string */ 

XrmRepresentation type; /* Representation of value (if any) */ 

XrmValue value; /* Value of this node (if any) */ 

XrmHashTable tables [2]; /* Hash table pointers for tight, loose */ 

} XrmHashBucketRec; 

These data structures should not be traversed by the uninitiated. If you have Xt source avail 
able, examine the code in XllR3lcore.srclliblXIXrm.c, 

Command line arguments and a complete example using alternate command line parsing are 
presented in Chapter 9, Resource Management and Type Conversion, in Volume Four, X Toolkit 
Intrinsics Programming Manual. 

See Also 

XtDisplaylnitialize, XtGetResourceList, XtGetSubresources, Xt- 
Initialize. 



126 x Toolkit Intrinsics Reference Manual 



. ., - . . J XtDestroyApplicationContext 

Xt - Application Contexts * 

Name 

XtDestroyApplicationContext destroy an application context and close its displays. 

Synopsis 

void XtDestroyApplicationContext (app_ context) 
XtAppContext app_context; 

Arguments 

app_ context Specifies the application context. 

Description 

XtDestroyApplicationContext destroys the specified application context as soon as it 
is safe to do so. If called from within an event handler or a callback procedure, XtDestroy 
ApplicationContext does not destroy the application context until the dispatch is com 
plete. 

All X Toolkit applications should terminate by calling XtDestroyApplicationContext 
and then exiting using the standard method for their operating system (typically, by calling 
exit for UNIX-based systems). The quickest way to make the windows disappear while exit 
ing is to call xtUnmapWidget on each top-level shell widget. The X Toolkit has no resources 
beyond those in the program image, and the X server will free its resources when its connection 
to the application is broken. 

See Also 

Section 1.1, "Widget Lifecycle," 

XtCreateApplicationContext. 



X Toolkit Intrinsics Reference Manual 127 



XtDestroyGC \ Vl 

^ Xt - Memory Allocation 

Name 

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

Synopsis 

void XtDestroyGC (gc) 
GC gc; 

Arguments 

w Specifies the widget 

gc 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 gc 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 



nj , u XtDestroyWidget 

Xt - Widget Lit ecycle 7 

Name 

XtDestroyWidget destroy a widget instance. 

Synopsis 

void XtDestroyWidget (w) 
Widget w; 

Arguments 

w Specifies the widget to be destroyed. 

Description 

Most applications simply exit, causing widgets to be destroyed automatically. XtDestroy 
Widget destroys widgets explicitly. It can also be used by widgets that need to destroy them 
selves. It can be called at any time, including from an application callback routine of the 
widget being destroyed. 

Widget destruction occurs in two phases to prevent dangling references to destroyed widgets. 
In phase one, XtDestroyWidget performs the following: 

If the being_dest royed field of the widget is TRUE, it returns immediately; 

Otherwise, it recursively descends the widget tree and sets the be ing_dest royed 
field to TRUE for the widget and all children; and 

It adds the widget to a list of widgets (the destroy list) that should be destroyed when it is 
safe to do so. 

For entries on the destroy list, if w2 occurs after wl on the destroy list, then w2 is not a descen 
dant of wl . (A descendant can be either a normal or a pop-up child.) 

Phase two occurs when all procedures that should execute as a result of the current event have 
been called (including all procedures registered with the Event and Resource Managers). That 
is, when the current invocation of Xt Di spa tchE vent is about to return (or immediately if 
not in XtDispatchEvent). 
In phase two, XtDestroyWidget performs the following on each entry in the destroy list: 

Calls the destroy callback procedures registered on the widget (and all descendants). The 
calls happen in reverse order (children callbacks before parent callbacks). 

If the widget s parent is a subclass of compos it eWidgetClass and if the parent is 
not being destroyed, XtDestroyWidget calls xtUnmanageChild on the widget 
and then calls the widget s parent s delete_child procedure. 

If the widget s parent is a subclass of constraintwidgetClass, it calls the con 
straint destroy procedure for the parent, then the parent s superclass, until finally it calls 
the constraint destroy procedure for constraintwidgetClass. 



X Toolkit Intrinsics Reference Manual 



XtDestroy Widget (continued) Xt - Widget Lit ecycle 

Calls the destroy methods for the widget (and all descendants) in post-order. For each 
such widget, it calls the destroy procedure declared in the widget class, then the destroy 
procedure declared in its superclass, until finally it calls the destroy procedure declared 
in the Core class record. 

Calls the Xlib function XDestroyWindow if the widget is realized (that is, has an X 
window). The server recursively destroys all descendant windows. 

Recursively descends the tree and deallocates all pop-up widgets, constraint records, 
callback lists and, if the widget is a subclass of compos iteWidgetClass, children. 

When an application needs to perform additional processing during the destruction of a widget, 
it should register a destroy callback procedure for the widget The destroy callback list is iden 
tified by the resource name XtNdestroyCallback. 

The following example adds an application-supplied destroy callback procedure Client- 
Destroy with client data to a widget 

XtAddCallback (w, XtNdestroyCallback, ClientDestroy, client_data) 

Similarly, the following example removes the application-supplied destroy callback procedure 

ClientDestroy: 

XtRemoveCallback (w, XtNdestroyCallback, ClientDestroy, client_data) 
The ClientDestroy procedure is of type XtCallbackProc: 
typedef void (*XtCallbackProc) (Widget, caddr_t, caddr_t) ; 
For further information, see xtCallbackProc(2). 

A widget s windows can be removed from the display while leaving the widget data structures 
intact by calling XtUnrealizeWidget. 

See Also 

Section 1.1, "Widget Lifecycle," 

XtRemoveAllCallbacks, XtRemoveCallback, XtUnrealizeWidget, 
Core(3). 



130 X Toolkit Intrinsics Reference Manual 



. / XtDirectConvert 

Xt - Resource Management 

Name 

XtDirectConvert perform resource conversion and cache result. 

Synopsis 

void XtDirectConvert (converter, args, num_args, from, to_return) 
XtConverter converter; 
XrmValuePtr args; 
Cardinal num_args; 
XrmValuePtr from; 
XrmValuePtr to_return; 

Arguments 

converter Specifies the conversion procedure to be called. 

args Specifies the argument list that contains the additional arguments needed to 

perform the conversion (often NULL). 

num_args Specifies the number of additional arguments (often zero), 
from Specifies the value to be converted. 

to_return Returns the converted value. 

Description 

XtDirectConvert looks in the converter cache to see if the named conversion procedure 
has been called with the specified arguments. If so, it returns a descriptor for information 
stored in the cache; otherwise, it calls converter and enters the result in the cache. 

Before calling the specified converter, XtDirectConvert sets the return value size to zero 
and the return value address to NULL. If the conversion succeeds, to_return . address will 
be non-NULL. 

It is usually easier to access resource conversion indirectly through xtGetSubresources 
and xtGetApplicationResources. XtConvert provides a higher-level interface to 
XtDirectConvert; XtAddConverter and XtAppAddConverter allow additional 
conversion arguments. 

Structures 

typedef struct { 

unsigned int size; 

caddr_t addr; 
} XrmValue, *XrmValuePtr; 

See Also 

Section 1.7, "Resources," 

XtAppAddConverter, XtConvert, XtGetApplicationResources, 

XtGetSubresources, 

XtConverter(2). 



X Toolkit Intrinsics Reference Manual 1 3 1 



XtDisownSelection \ V4 

x Xt - Selections 

Name 

XtDisownSelection indicate that selection data is no longer available. 

Synopsis 

void XtDisownSelection (w, selection, time) 
Widget w; 
Atom selection; 
Time time; 

Arguments 

vf Specifies the widget relinquishing selection ownership. 

selection Specifies which selection the widget is giving up (XA_PRIMARY or XA_SEC- 
ONDARY). 

time Specifies the timestamp that indicates when the selection is relinquished. 

Description 

Usually the Intrinsics selection mechanism informs an application when one of its widgets has 
lost ownership of the selection. However, in response to some user actions (for example, when 
a user deletes the information selected), the application should explicitly inform the Intrinsics 
that its widget no longer is to be the selection owner by using XtDisownSelection. 

XtDisownSelection renounces ownership of a selection. It informs the Intrinsics that new 
requests for selection data should be directed elsewhere. No subsequent requests will be sent to 
the xtConvertProc registered when the widget called xtOwnSelection. 

If the widget does not currently own selection, either because it lost the selection or 
because it never had the selection to begin with, XtDisownSelection does nothing. 

After a widget has called XtDisownSelection, its XtConvertProc is not called even if 
a request arrives with a timestamp indicating the period that it owned the selection. However, 
its xtDoneProc will be called if a conversion that started before the call to XtDisown 
Selection finishes after the call to XtDisownSelection. 

If the selection has changed hands because another client has claimed it (rather than as a result 
of a call to XtDisownSelection), the Intrinsics inform the application of the loss by calling 
its XtLoseSelectionProc. 

An example widget that sends and receives data using selection is presented in Chapter 10, 
Inter-Client Communications, in Volume Four, X Toolkit Intrinsics Programming Manual. 

See Also 

Xt Get Select ionValue, XtOwnSelection, 
XtConvertProc(2), XtDoneProc(2), XtLoseSelectionProc(2). 



132 X Toolkit Intrinsics Reference Manual 



u . / XtDispatch Event 

Xt - Event Handling * 

Name 

XtDispatchEvent dispatch registered handlers for an event 

Synopsis 

void XtDispatchEvent (event) 
XEvent * event; 

Arguments 

event Specifies a pointer to the event structure to be dispatched to the appropriate 

event handler. 

Description 

XtDispatchEvent sends events to handler functions previously registered with xtAdd- 
E vent Handler. XtDispatchEvent calls the appropriate handler functions and passes 
them the widget, the event, and client-specific data. 

If no handlers for the event are registered, the event is ignored. If there are multiple handlers 
registered for an event, the order in which handlers are called is undefined. 

XtDispatchEvent returns TRUE if it dispatched the event to some handler and FALSE if it 
found no handler to dispatch the event to. In most applications, xtMainLoop is used- to dis 
patch events transparently. XtAddEventHandler and XtAddRawE vent Handler are 
used to register event handlers. 

The most common use of XtDispatchEvent is to dispatch an event acquired with xt App- 
NextEvent. However, it also can be used to dispatch user-constructed events. Xt 
DispatchEvent does not handle the pseudo-events (timer interrupts and auxiliary input). 
Those are dispatched directly by XtAppNextEvent. 

XtDispatchEvent is used to implement the grab semantics for XtAddGrab. 

See Also 

Section 1.4, "Events," 

XtAddEventHandler, XtAddGrab, XtAddRawEvent Handler, XtAppNextEvent, 
XtEventHandler, XtMainLoop. 



X Toolkit Intrinsics Reference Manual 133 



1 P y > Xt- Widget Information 

Name 

XtDisplay return the display pointer for the specified widget 

Synopsis 

Display *XtDisplay (w) 
Widget vt; 

Arguments 

w Specifies the widget for which the Display is to be returned. 

Description 

XtDisplay returns the display pointer for the specified widget 

See Also 

XtScreen 



134 X Toolkit Intrinsics Reference Manual 



Xt - Application Contexts- 



J XtDisplaylnitialize 



Name 

XtDisplaylnitialize initialize a display and add it to an application context. 

Synopsis 

void XtDisplaylnitialize (app_context f display, application_name, 

application_class, options, num_options, argrc, argv) 
XtAppContext app_context; 
Display *display; 
String application_name; 
String application_class; 
XrmOptionDescRec * options; 
Cardinal num_ options; 
Cardinal *argc; 
String *argrv; 

Arguments 

app_ con text Specifies the application context. 

display Specifies the display. Note that a display can be in at most one application 

context. 

appl icati on_n ame 

Specifies the name of the application instance. 

application_class 

Specifies the class name of this application. This name is usually the generic 
name for all instances of this application. 

options Specifies how to parse the command line for any application-specific 

resources. The options argument is passed as a parameter to XrmParse- 
Command. 

num_options Specifies the number of entries in the options list. 

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

argv Specifies the command line parameters. 

Description 

XtDisplaylnitialize builds the resource database, parses the command line using the 
Xlib XrmParseCommand function, and performs other per-display initialization. This func 
tion is not often used unless you are creating multiple application contexts, since xt- 
Initialize provides a simplified interface to it (and the other two Toolkit initialize func 
tions, XtCreateApplicationContext and XtAppCreateShell). 

See xt initialize for a complete description of how the arguments are used. 



X Toolkit Intrinsics Reference Manual 135 



XtDisplaylnitialize 



(continued) 



Xt - Application Contexts 



Structures 

typedef enum { 

XrmoptionNoArg, 
XrmoptionlsArg, 
XrmoptionStickyArg, 
XrmoptionSepArg, 

Xrmopt i on S k ipAr g , 
XrmoptionSkipLine 
} XrmOptionKind; 



/* 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 */ 



typedef struct { 

char *option; /* Option name in argv */ 

char *specifier; /* 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 



-X, - Error HandUng XtElTOr 

Name 

XtError call the low-level fatal error handler. 

Synopsis 

void XtError (message) 
String message; 

Arguments 

message Specifies the message to be reported. 

Description 

Xt provides two levels of error handling: 

A high-level interface that takes an error name and class and looks the error up in an 
error resource database. 

A low-level interface that takes a simple string, which is printed out as the error message. 

Application-context-specific error handling is not implemented on many systems. Most imple 
mentations will have just one set of error handlers. If different handlers are set for different 
application contexts, the one set last will be used. 

In theory, most programs should use XtAppErrorMsg (or XtErrorMsg if application con 
texts are not being used), not XtError or xtAppError, so that the programs can be easily 
customized to provide international or other custom error messages. However, the low-level 
handlers are much easier to use. 

XtAppError calls the low-level fatal error handler. Fatal errors are assumed to be catastro 
phic and irrecoverable. A warning error handler also exists for errors that require attention but 
do not preempt a program running correctly to a normal successful completion. (xtApp- 
Warning calls the corresponding nonfatal error handler. XtAppErrorMsg and xtApp- 
WarningMsg call the corresponding high-level handlers.) 

See Also 

XtErrorMsg, XtSetErrorHandler, XtSetWarningMsg, XtWarning, XtWarning- 
Msg. 



X Toolkit Intrinsics Reference Manual 



XtErrorMsg 



X 



Xt- Error Handling- 



Name 

XtErrorMsg call the high-level fatal error handler. 

Synopsis 

void XtErrorMsg (name, type, class, default, params, num_params) 
String name; 
String type; 
String class; 
String default; 
String * params; 
Cardinal *num_params; 

Arguments 

name Specifies the general kind of error; for example, InvalidParameter. 

type Specifies the detailed name of the error. This is specified using printf-like 

syntax, with the parameters and number of parameters specified by params 
and num_params. 

class Specifies the resource class. 

defa ul t Specifies the default message to use if no message is found in the database. 

params Specifies a pointer to a list of values to be stored in the type argument when 

the message is generated. 

num_params Specifies the number of values in the parameter list. 

Description 

Xt provides two levels of error handling: 

A high-level interface that takes an error name and class and looks the error up in an 
error resource database. 
A low-level interface that takes a simple string, which is printed out as the error message. 

The high-level functions construct a string to pass to the lower-level interface. The name and 
type arguments are concatenated to form the "name" that is used to look up a message in the 
error database. On UNIX-based systems, the error database is usually called 
lusrlliblXl 1 IXtErrorDB . 

In theory, most programs should use AppXtErrorMsg (or XtErrorMsg if application con 
texts are not being used), not AppXtError or xtError, so that the programs can be easily 
customized to provide international or other custom error messages. However, the low-level 
handlers are much easier to use. 

xtAppError calls the low-level fatal error handler. Fatal errors are assumed to be catastro 
phic and irrecoverable. A warning error handler also exists for errors that require attention but 
do not preempt a program running correctly to a normal successful completion. (xtApp- 



138 



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 Intrinsics internal errors all 
have class XtToolkitError. 

See Also 

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



X Toolkit Intrinsics Reference Manual 139 



XtFree \ 

v Xt - Memory Allocation 

Name 

XtFree free an allocated block of storage. 

Synopsis 

void XtFree (ptr) ; 
char *ptr; 

Arguments 

ptr Specifies a pointer to the block of storage to be freed. 

Description 

XtFree returns storage previously allocated by xtCalloc and xtMalloc and allows it to 
be reused. If ptr is NULL, XtFree returns immediately. 

Calling the Toolkit s XtMalloc and XtFree is more portable than calling system-specific 
malloc and free. Deallocating blocks of memory not allocated by XtMalloc would be 
disastrous. 

xtNew and xtNewString provide slightly higher-level approaches to memory allocation. 
See Also 

XtCalloc, XtErrorMsg, XtMalloc, XtNew, XtNewString, XtRealloc. 



140 X Toolkit Intrinsics Reference Manual 



Xt - Resource Management- 



J XtGetApplicationResources 



Name 

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

Synopsis 

void XtGetApplicationResources (w, base, resources, 

num_re sources, args, num_args) 
Widget w; 
caddr_t base; 
XtResourceList resources; 
Cardinal /3um_resources; 
ArgList args; 
Cardinal num_args; 

Arguments 

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

nu/n_resources Specifies the number of resources in the resource list. 

args Specifies the argument list to override resources obtained from the 

resource database. 

num_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 xtOf f set can be 
used to specify resource_of f set. (XtOf f set 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 




XtGet Application Resources 



(continued) 



Xt - Resource Management 



/* res.c - access application resources */ 
#include <stdio.h> 



#include 

#include <Xll/StringDef s.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_yariables { 

String label; 

XFont Struct *font_struct; 

long foreground; 

} instance_variable_rec, *instance_variables; 
instance_variables Instance Variables; 

static XtResource resources [] = { 
{ 

XtN foreground, 
XtCForeground, 
XtRPixel, sizeof (Pixel) , 

XtOffset (instance_variables, foreground) , 
XtRString, "XtDefaultForeground" 



XtNfont, 

XtCFont, 

XtRFont Struct, sizeof (XFontStruct *), 

XtOffset (instance_variables, font_struct) , 

XtRString, "XtDefaultFont" 



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 



Xt - Resource Management (continued) XtGetApplicationResources 

instance_variable_rec iv; 

toplevel = Xtlnitialize(av[0] , "my-widget", NULL, 0, &ac, av) ; 

XtGetApplicationResources (toplevel, /* widget */ 

&iv, /* base address */ 

resources, /* resource */ 
XtNumber (resources) ,/* how many */ 
NULL, 0); /* ArgList to merge */ 

printf ("label=%s\n", iv. label) ; 
} 

All resource-fetching routines (for example, XtGetSubresources and XtGet 
ApplicationResources) call resource converters if the user specifies a resource that is a 
different representation from the desired representation or if the widget s default resource value 
representation is different from the desired representation. 

Structures 

A Resource is defined as follows in <X1 II Intrinsic. h>: 

typedef struct _XtResource { 

String resource_name; /* Resource name */ 

String resource_class; /* Resource class */ 

String resource_type; /* Representation type desired */ 

Cardinal resource_size; /* Size in bytes of representation */ 

Cardinal resource_of f set; /* Offset from base to put resource value */ 

String default_type; /* Representation type of specified default */ 

caddr_t default_addr; /* Address of resource default value */ 

} XtResource, *XtResourceList; 

An Arg is defined as follows: 

typedef struct { 

String name; 

XtArgVal value; 
} Arg, *ArgList; 

See Also 

XtGetSubresources, XtOf f set. 



X Toolkit Intrinsics Reference Manual 



XtGetErrorDatabase A v 

v Xt - Error Handling 

Name 

XtGetErrorDatabase 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 
lusrlliblXHIXtErrorDb. The XtGetErrorDatabase 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 



-x - Error Hand.ing / XtGetErrorDatabaseText 

Name 

XtGetErrorDatabaseText obtain the error database text for an error or a warning. 

Synopsis 

void XtGetErrorDatabaseText (name, type, class, default, buf- 
fer_return, nbytes) 

char *name, *type, * class; 

char * default; 

char *buffer_return; 

int nbytes; 

Arguments 

name, type Specify the name and type that are concatenated to form the resource name of 
the error message. 

cl ass Specifies the resource class of the error message. 

defa ul t Specifies the default message to use if an error database entry is not found. 

buffer_re t urn 

Specifies the buffer into which the error message is to be returned. 

nbytes Specifies the size of the buffer in bytes. 

Description 

XtGetErrorDatabaseText returns the appropriate message from the error database for 
name and type. If no such entry exists, it returns the specified default message. On 
UNIX-based systems, the error database is usually stored in lusrlliblXHIXtErrorDb. Custom 
error or warning messages should be appended to this file. The address of the loaded database 
can be returned by a call to XtGetErrorDatabase. 

See Also 

XtAppGetErrorDatabase, XtAppGetErrorDatabaseText, XtGetError 
Database, 
XtErrorMsgHandler(2). 



X Toolkit Intrinsics Reference Manual 



* V xt - Graphics Context- 

Name 

XtGetGC obtain a read-only, sharable GC. 

Synopsis 

GC XtGetGC (w, value_mask, values) 
Widget w; 

XtGCMask value_mask; 
XGCValues * values ; 

Arguments 

w Specifies the widget with which the GC is to be associated. 

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

Description 

The Intrinsics 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 sharable, 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. value_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; /* LjneSolid, LineOnOf fDash, 

LineDoubleDash */ 
int cap_style; /* CapNotLast, CapButt, 

CapRound, CapPro jecting */ 

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, Includelnferiors */ 

/* 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 



147 



XtGetResourceList 

-Xt - Resource Management 

Name 

XtGetResourceList retrieve default values for a resource list. 

Synopsis 

void XtGetResourceList (widget_class f resources_return f 

num_resources_return) ; 
WidgetClass vfidget_class; 
XtResourceList *resources_return; 
Cardinal *num_resources_return; 

Arguments 

widget_class 

Specifies the widget class for which you want the list. 

resources_return 

Specifies a pointer to where to store the returned resource list. The caller must free 
this storage using xtFree when done with it 

num_resources_return 

Specifies a pointer to the number of entries in the resource list. 

Description 

XtGetResourceList allocates and returns a list of resources used by widget_class (as 
opposed to xtGetApplicationResources, which obtains the resources from the actual 
widget instance). If the widget class has not been initialized (i.e., no instances of the widget 
have been created), the resource list is a copy of the resource list in the widget class record. If 
the resource class has been initialized, the resource list is merged with the resources from all 
the widget s superclasses. 

Here is an abbreviated version of the resource list in the Label widget 

/* Resources specific to Label */ 
static XtResource resources [] = { 
{XtNforeground, XtCForeground, XtRPixel, sizeof (Pixel) , 

XtOffset (LabelWidget, label . foreground) , XtRString, 
XtDefaultForeground} , 
{XtNfont, XtCFont, XtRFont Struct, sizeof (XFontStruct *) , 

XtOffset (LabelWidget, label . font) , XtRString, XtDefaultFont } , 
{XtNlabel, XtCLabel, XtRString, sizeof (String) , 

XtOffset (LabelWidget, label . label) , XtRString, NULL}, 



The complete resource name for a field of a widget instance is the concatenation of the applica 
tion name (from argv[0]) or the -name command-line option (see xtDisplay- 
initialize), the instance names of all the widget s parents, the instance name of the widget 
itself, and the resource name of the specified field of the widget Likewise, the full resource 



148 X Toolkit Intrinsics Reference Manual 



Xt - Resource Management 



(continued) 



XtGetResourceList 



class of a field of a widget instance is the concatenation of the application class (from xt App- 
CreateShell), the widget class names of all the widget s parents (not the superclasses), the 
widget class name of the widget itself, and the resource name of the specified field of the 
widget 

Structures 

A Resource is defined as follows in <Xll/Intrinsic.h>: 



typedef struct _XtResource { 
String resource_name; /* 
String resource_class; /* 
String resource_type; /* 
Cardinal resource_size; /* 
Cardinal resource_of f set; /* 
String default_type; /* 
caddr_t default_addr; /* 

} XtResource, XtResourceList; 



Resource name */ 
Resource class */ 
Representation type desired */ 
Size in bytes of representation */ 
Offset from base to put resource value */ 
Representation type of specified default */ 
Address of resource default value */ 



See Also 

Section 1.7, "Resources," 

XtAppCreateShell, XtDisplaylnitialize, XtFree, XtGetApplication- 
Resources. 



X Toolkit Intrinsics Reference Manual 



149 



XtGetSelectionTimeout \ 



Xt- Selections- 



Name 

XtGetSelectionTimeout 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 



750 X Toolkit Intrinsics Reference Manual 



Xt -Selections- 



j XtGetSelectionValue 



Name 

XtGetSelectionValue obtain the complete selection data. 

Synopsis 

void XtGetSelectionValue (w, selection, target, callback, cli- 

ent_data, time) 
Widget w; 
Atom selection; 
Atom target; 

Xt Select ionCallbackP roc callback; 
opaque client_data; 
Time time; 

Arguments 

w Specifies the widget that is making the request 

selection Specifies the particular selection desired (either XA_PRIMARY or XA_SECON- 

DARY). 

target Specifies the type to which the sender should convert the selection. 

callback Specifies the callback procedure to be called when the selection value has 
been obtained. Note that this is how the selection value is communicated 
back to the client. 

client_data Specifies an argument to be passed to the specified procedure when it is 
called. 

time Specifies the timestamp that indicates when the selection is desired. This 

should be the timestamp of the event that triggered this request; the value 
CurrentTime is not acceptable. 

Description 

XtGetSelectionValue requests the selection owner to send the value of the selection, 
converted to the target type, callback will be called some time after XtGetSelection 
Value is called; in fact, it may be called before or after XtGetSelectionValue returns. 

If multiple calls to the server are required to get all the data, this will be transparent to the 
widget; the Intrinsics perform all the necessary fragmentation and reassembly of the selection. 

To determine the actual target types that the selection owner will be willing to return, intern the 
string TARGETS using XInternAtom, and send the corresponding Atom as target. 

See Also 

XtGetSelectionValues.XtOwnSelection, 
XtSelectionCallbackProc(2). 



X Toolkit Intrinsics Reference Manual 



XtGetSelectionValues A 



Xt- Selections 



Name 

XtGetSelectionValues obtain selection data in multiple formats. 

Synopsis 

void XtGetSelectionValues (w, selection, targets, count, 

callback, client_data, time) 
Widget w; 
Atom selection; 
Atom * targets; 
int count; 

Xt Select ionCallbackP roc callback; 
opaque client_data; 
Time time; 

Arguments 

w Specifies the widget that is making the request 

selection Specifies the particular selection desired (either XA_PRIMARY or XA_SECON- 
DARY). 

targets Specifies the types to which the sender should convert the selection. 

coun t Specifies the length of the targets and cl i en t_da t a lists. 

callback Specifies the callback procedure to be called with each selection value 
obtained. Note that this is how the selection values are communicated back 
to the client. 

client_data Specifies the client data (one for each target type) that is passed to the 
callback procedure when it is called for that target. 

time Specifies the timestamp that indicates when the selection value is desired. 

This should be the timestamp of the event which triggered this request; the 
value Cur rent Time is not acceptable. 

Description 

XtGetSelectionValues is similar to xtGetSelectionValue except that it takes a list 
of target types and a list of client data and obtains the current value of the selection converted 
to each of the targets. The effect is as if each target were specified in a separate call to Xt 
GetSelectionValue. The callback is called once with the corresponding client data for 
each target. XtGetSelectionValues guarantees that all the conversions will use the same 
selection value because the ownership of the selection cannot change in the middle of the list, 
as would happen when calling XtGetSelectionValue repeatedly. 

To determine the actual target types that the selection owner will be willing to return, intern the 
string TARGETS, and send the corresponding Atom as target. 



752 X Toolkit Intrinsics Reference Manual 



Xt - Selections 



(continued) 



XtGetSelect ion Va lues 



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 Get Select ionValue.XtOwnSelect ion, 
Xt Select ionCallbackProc(2). 



X Toolkit Intrinsics Reference Manual 



153 



XtGetSubresources V 

v Xt - Resource Management 

Name 

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

Synopsis 

void XtGetSubresources (w, base, name, class, resources, 

num_resources, args, num_args) 
Widget w; 
caddr_t base; 
String name; 
String class; 
XtResourceList resources; 
Cardinal num_resources ; 
ArgList args; 
Cardinal num_args; 

Arguments 

w Specifies the widget that wants resources for a subpart. 

base Specifies the base address of the subpart data structure where the resources 

should be written. 

name Specifies the name of the subpart. 

class Specifies the class of the subpart. 

resources Specifies the resource list for the subpart. 

/ju/n_resources 

Specifies the number of resources in the resource list. 

args 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 argrs 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) XtGetSubresources 

With the exception of name and class, the arguments to XtGetSubresources are the same 
as those for XtGetApplicationResources. See XtGetApplicationResources 
for additional details. 

All resource-fetching routines (for example, XtGetSubresources and XtGet 
ApplicationResources) call resource converters if the desired representation differs 
from the resource the user specifies or from the widget s default resource value. 

Structures 

A Resource is defined as follows in <Xll/Intrinsic.h>: 

typedef struct _XtResource { 

String resource_name; /* Resource name */ 

String resource_class; /* Resource class */ 

String resource_type; /* Representation type desired */ 

Cardinal resource_size; /* Size in bytes of representation */ 

Cardinal resource_of fset; /* Offset from base to put resource value */ 

String def ault_type; /* Representation type of specified default */ 

caddr_t def ault_addr; /* Address of resource default value */ 

} XtResource, XtResourceList; 

An Arg is defined as follows: 

typedef struct { 

String name; 

XtArgVal value; 
} Arg, *ArgList; 

See Also 

Section 1.7, "Resources," 

XtGetApplicationResources, 

Volume Four, X Toolkit Intrinsics Programming Manual, Chapter 9, Resource Management and 

Type Conversion. 



X Toolkit Intrinsics Reference Manual 15S 



XtGetSub values 

Xt - Resource Management- 
Name 

XtGetSubvalues copy from base-offset resource list to the argument list. 

Synopsis 

void XtGetSubvalues (base, resources, num_resources, args r 

num_args) 
caddr_t base; 
XtResourceList resources; 
Cardinal /ju/n_resources; 
ArgList args; 
Cardinal num_args; 

Arguments 

jbase Specifies the base address from which resources should be read. 

resources Specifies the nonwidget resources list. 

/iu/n_resources 

Specifies the number of resources in the resource list and the address into 
which the resource value is to be stored. 

args Specifies the argument list of name/address pairs that contain the resource 

name. The arguments and values passed in are dependent on the subpart. 
The storage for argument values that are pointed to by the argument list must 
be deallocated by the application when no longer needed. 

num_args Specifies the number of arguments in the argument list. 

Description 

XtGetSubvalues obtains resource values from the structure identified by .base, and writes 
them in the provided argument list. XtGetSubvalues expects the contents of args to be 
pointers to locations where the actual values can be put 

The conjugate function xt Set Subva lues sets a widget s values. 

XtGetSubvalues is used for obtaining resource data from entities that are not widgets. For 
further discussion of nonwidget subclass resources, see xtGetSubresources. 

Structures 

A Resource is defined as follows in <X 11 /Intrinsic. h>: 

typedef struct _XtResource { 

String resource_name; /* Resource name */ 

String resource_class; /* Resource class */ 

String resource_type; /* Representation type desired */ 

Cardinal resource_size; /* Size in bytes of representation */ 

Cardinal resource_off set;/* Offset from base to put resource value */ 

String default_type; /* Representation type of specified default */ 

caddr_t default_addr; /* Address of resource default value */ 

} XtResource, XtResourceList; 



156 X Toolkit Intrinsics Reference Manual 



Xt - Resource Management (continued) XtGetSubvalUGS 

An Arg is defined as follows: 

typedef struct { 

String name; 

XtArgVal value; 
} Arg, *ArgList; 

See Also 

Section 1.7, "Resources," 

Xt Set Arg, 
XtArgsProc(2). 



X Toolkit Intrinsics Reference Manual 157 



XtGetValues 

Xt - Resource Management 

Name 

XtGetValues copy resources from a widget to the argument list. 

Synopsis 

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

Arguments 

w Specifies the widget whose values are to be read and the address into which 

the resource value is to be stored. 

args Specifies the argument list of name/address pairs that contain the resource 

name. The resource names are widget-dependent. 

num_args Specifies the number of arguments in the argument list. 

Description 

XtGetValues retrieves the current value of a resource associated with a widget instance. 
The conjugate function xtSetValues sets a widget s values. 

The name fields in args contain the names of resources. The value fields in args contain 
addresses into which XtGetValues stores the corresponding resource values. XtGet 
Values expects the args .value fields to be pointers to locations where the actual values 
can be put It is the caller s responsibility to allocate and deallocate this storage according to 
the size of the resource representation type used within the widget 

XtGetValues starts with the resources specified for the Core widget fields and descends the 
subclass chain to the widget If the widget s parent is a subclass of constraintwidget- 
Class, XtGetValues then fetches the values for any Constraint resources requested. It 
starts with the Constraint resources specified for const raintwidgetClass and proceeds 
down the subclass chain to the parent s Constraint resources. If the argument list contains a 
resource name that is not found in any of the resource lists searched, the value at the corre 
sponding address is not modified. 

Finally, if the widget s get_values_hook methods are non-NULL, they are called in super- 
class-to-subclass order after all the resource values have been fetched by XtGetValues. 
get_values_hook methods are used by widgets that have nonwidget subparts to provide 
nonwidget resource data to XtGetValues. 

Structures 

An Arg is defined as follows in <XlllIntrinsic.h>: 

typedef struct { 

String name; 

XtArgVal value; 
} Arg, *ArgList; 



158 X Toolkit Intrinsics Reference Manual 



Xt - Resource Management 



(continued) 



XtGet Values 



See Also 

Section 1.7, "Resources," 

XtSetArg, XtSetValues, 
XtArgsProc(2). 



X Toolkit Intrinsics Reference Manual 



159 



XtHasCallbacks \ v 

v Xt - Callbacks- 
Name 

XtHasCallbacks determine the status of a widget s callback list. 

Synopsis 

XtCallbackStatus XtHasCallbacks (w f callback_name) 
Widget w; 
String callback_name; 

Arguments 

w Specifies the widget 

callback_name Specifies the callback list to be checked. 

Description 

XtHasCallbacks checks the widget for a resource named callback_name. If the 
resource does not exist or is not of type xtRCallback, XtHasCallbacks returns Xt- 
CallbackNoList. If the callback list exists but is empty, it returns xtCallbackHas- 
None. If the callback list contains at least one callback procedure, it returns xtCallback- 
HasSome. 

Structures 

typedef enum { 

XtCallbackNoList, 

XtCallbackHasNone, 

XtCallbackHasSome 
} XtCallbackStatus; 

See Also 

Section 1.3, "Application Interface," 

XtAddCallbacks, XtCallCallbacks. 



160 X Toolkit Intrinsics Reference Manual 



Xt- Initialization 



f Xtlnitialize 



Name 

Xtlnitialize initialize toolkit and display. 

Synopsis 

Widget Xtlnitialize (shell_name, application_class, options, 

num_options, argc, argv) 
char *shell_name; /*unused in R3*/ 
char *application_class; 
XrmOptionDescRec options[]; 
Cardinal n um_ option s; 
Cardinal *argc; 
char *argrv[] ; 

Arguments 

shell_name Specifies the name of the application shell widget instance. 

application_class 

Specifies the class name of this application. 

options Specifies how to parse the command line for any application-specific 

resources. The options argument is passed as a parameter to XrmParse- 
Command. 

num_opti ons Specifies the number of entries in options list. 

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

argv Specifies the command line parameters. 

Description 

Xtlnitialize returns an application shell suitable for parenting the rest of the application, 
and consolidates other requisite Toolkit initialization. This is the initialization routine of 
choice for simple applications that use widgets. 

Xtlnitialize calls XtToolJcitlnitialize to initialize the Toolkit internals, creates a 
default application context with xtCreateApplicationContext, xtOpenDisplay, 
and xtAppCreateShell, and returns the created shell. Xtlnitialize is generally more 
convenient than calling each of the routines individually. 

The semantics of calling Xtlnitialize more than once are undefined. 

Command Line Parsing 

Xtlnitialize calls XtDisplaylnitialize, which in turn calls the Xlib XrmParse- 
Command function to parse the command line. 

The command line parser modifies argc and argv to contain only those parameters that were 
not in the standard option table or in the table specified by the options argument If the 
resulting argc is not zero, then there were unexpected parameters declared on the user s com 
mand line. Most applications handle this by simply printing out the remaining contents of 



X Toolkit Intrinsics Reference Manual 161 



Xtlnitlalize (continued) Xt - Initialization 

argv along with a message listing the allowable options, with the application name. (On 
UNIX-based systems, the application name is usually the final component of argv [ ] .) 

Note that the argc and argv arguments of xtlnitialize are in the same order as in the 
call to main. This is the opposite order of arrays and array lengths throughout other Xt and 
Xlib routine calls. Also note that the address of argc, not argc itself, is passed to Xt 
lnitialize. This is so that xtlnitialize can decrement the count to reflect recognized 
options. Watch out for these snags. 

Loading the Resource Database 

The xtDisplaylnitialize function loads the application s resource database for this dis 
play/host/application combination from the following sources (in order): 

Application-specific class resource file on the local host 

Application-specific user resource file on the local host 

Resource property on the server or user preference resource file on the local host 

Per-host user environment resource file on the local host 

Application command line (argv). 

Each resource database is kept on a per-display basis. 

The application-specific class resource file name is constructed from the class name of the 
application. It points to a site-specific resource file that usually is installed by the site manager 
when the application is installed. On UNIX-based systems, this file usually is lusrlliblXlllapp- 
defaults/ class, where class is the application class name. This file is expected to be provided by 
the developer of the application and may be required for the application to function properly. 

The application-specific user resource file name is constructed from the class name of the appli 
cation and points to a user-specific resource file. This file is owned by the application and typi 
cally stores user customizations. On UNIX-based systems, this file name is constructed from the 
user s XAPPLRESDIR variable by appending class to it, where class is the application class 
name. (That is, XAPPLRESDIR specifies the name of a directory, and class the name of a file 
contained in it) If XAPPLRESDIR is not defined, it defaults to the user s home directory. If the 
resulting resource file exists, it is merged into the resource database. This file may be provided 
with the application or constructed by the user. 

The server resource file is the contents of the X server s RESOURCE_MANAGER property that 
was returned by XQpenDisplay. If no such property exists for the display, the contents of 
the resource file in the user s home directory is used instead. On UNIX-based systems, the usual 
name for the user preference resource file is X defaults. If the resulting resource file exists, it is 
merged into the resource database. The server resource file is constructed entirely by the user 
and contains both display-independent and display-specific user preferences. 

If one exists, a user s environment resource file is then loaded and merged into the resource 
database. This file name is user and host specific. On UNIX-based systems, the user s environ 
ment resource file name is constructed from the value of the user s XENVIRONMENT variable 
for the full path of the file. If this environment variable does not exist, xtDisplay 
lnitialize searches the user s home directory for the Xdefaults-host file, where host is the 

162 X Toolkit Intrinsics Reference Manual 



Xt - Initialization 



(continued) 



Xtlnitialize 



name of the machine on which the application is running. If the resulting resource file exists, it 
is merged into the resource database. The environment resource file is expected to contain 
system-specific resource specifications that are to supplement those user-preference specifica 
tions in the server resource file. 

Parsing the Command Line 

xtDisplaylnitialize has a table of standard command line options for adding resources 
to the resource database, and it can accept application-specific resource abbreviations. 

The format of this table is shown below in the Structures section of this man page. The stan 
dard table contains the following entries: 



Option 


Resource 


Value 


Sets 


-bg 


*background 


next argument 


background color 


-background 


^background 


next argument 


background color 


-bd 


*borderColor 


next argument 


border color 


-bw 


.borderWidth 


next argument 


width of border in pixels 


-borderwidth 


.borderWidth 


next argument 


width of border in pixels 


-bordercolor 


*borderColor 


next argument 


color of border 


-display 


.display 


next argument 


server to use 


-fg 


*f oreground 


next argument 


foreground color 


-fn 


*font 


next argument 


font name 


-font 


*font 


next argument 


font name 


-foreground 


*foreground 


next argument 


foreground color 


-geometry 


.geometry 


next argument 


size and position 


-iconic 


.iconic 


"on" 


start as an icon 


-name 


.name 


next argument 


name of application 


-reverse 


*reverseVideo 


"on" 


reverse video 


-rv 


*reverseVideo 


"on" 


reverse video 


+rv 


*reverseVideo 


"off 


No Reverse Video 


-selectionTimeout 


. selectionTimeout 


Null 


selection timeout 


-synchronous 


. synchronous 


"on" 


synchronous debug mode 


+synchronous 


. synchronous 


"off" 


synchronous debug mode 


-title 


.title 


next argument 


tide of application 


-xrm 


value of argument 


next argument 


depends on argument 



Note that any unique abbreviation for an option name in the standard table or in the application 
table is accepted. 

The table above lists the complete set of standard options. Options for which the resource 
name is shown starting with a dot rather than an asterisk set that resource only in the applica 
tion s top-level Shell. 

If the user specifies synchronize TRUE on the command line, XtDisplaylnitialize 
calls the Xlib XSynchronize function to put the Xlib display connection into synchronous 



X Toolkit Intrinsics Reference Manual 



163 



Xtlnltlallze (continued) Xt - Initialization 

mode. If reverseVideo is TRUE, the Intrinsics exchange XtDef aultForeground and 
XtDef aultBackground for widgets created on this display. (See Section 1.7, "Resources," 
for more information on default resources.) 

The -xrm option provides a method of setting any resource in an application. The next argu 
ment should be a quoted string identical in format to a line in the user resources file. For 
example, to give a red background to all command buttons in an application named xmh, you 
can start it up as: 

xmh -xrm xmh*Command. background: red 

When it fully parses the command line, XtDisplaylnitialize merges the application 
option table with the standard option table and then calls the Xlib XrmParseCommand func 
tion. An entry in the application table with the same name as an entry in the standard table 
overrides the standard table entry. If an option name is a prefix of another option name, both 
names are kept in the merged table. 

Structures 

You make Xt Initialize understand additional command-line options by initializing a 
XrmOptionDescRec structure (called the options table) and passing it as an argument to 

Xt Initialize. 

typedef struct { 

char *option;/* Option name in argv */ 

char *specifier;/* Resource name (without application name) */ 
XrmOptionKind argKind;/* Which style of option it is */ 
caddr_t value;/* Value to provide if XrmoptionNoArg */ 

} XrmOptionDescRec, *XrmOptionDescList; 

Each options table entry consists of four fields: 

The option to be searched for on the command line. As with standard command-line 
options, Xt will automatically accept any unique abbreviation of the option specified 
here. For example, the option -pixmapWidthlnPixels will be recognized if typed 
on the command line as -pixmapW. However, if you wanted the option -pw to set the 
same resource, then you would need another entry, since pw is not the leading string of 
pixmapWidthlnPixels. 

The resource specification. This must identify a widget resource or an application 
resource, but not provide a value. Since it has the same form as allowed in the resource 
databases, it may apply to a single widget or to many widgets. If it applies to no widgets, 
no error message will be issued. 

The argument style. This field is one of seven enumerated constants describing how the 
option is to be interpreted. These constants are described below. 

The value. This field is the value to be used for the resource if the argument style is 
XrmOptionNoArg. This field is not used otherwise. Note that this value must already 
be converted to the value expected for the resource (often not a string). You may be able 
to use Xt s type converter routines explicitly to convert this data to the right type. 



164 X Toolkit Intrinsics Reference Manual 



Xt - Initialization 



(continued) 



Xtlnitialize 



The XrmOptionKind enum constants that specify the various command-line argument 
styles are as shown in the table below: 



Constant 



Meaning 



XrmoptionNoArg 



Xrmopt ion I s Ar g 



XrmoptionStickyArg 



Xrmopt ionSepArg 



Xrmopt ionResArg 



Xrmopt ionSkipArg 
Xrmopt ionSkipLine 



Take the value in the value field of the options table. For 

example, this is used for Boolean fields, where the option might 

be -debug and the default value FALSE. 

The flag itself is the value without any additional information. 

For example, if the option were -on, the value would be "on." 

This constant is infrequently used, because the desired value such 

as "on" is usually not descriptive enough when used as an option 

(-on). 

The value is the characters immediately following the option with 

no white space intervening. This is the style of arguments for 

some UNIX utilities such as uucico where -sventure means to call 

system venture. 

The next item after the white space after this flag is the value. 

For example, -f g blue would indicate that "blue" is the value 

for the resource specified by -f g. 

The resource name and its value are the next argument in argv 

after the white space after this flag. For example, the flag might 

be 

-res basecalc*background: white; 

then the resource name/value pair would be used as is. This form 
is rarely used because it is equivalent to -xrm, and because the C 
shell requires that special characters such as * be quoted. 
Ignore this option and the next argument in argv. 
Ignore this option and the rest of argv. 



The options table is passed to Xtlnitialize as its third argument, and the number of 
options table entries as the fourth. The Xt Number macro is a convenient way to count the 
number of entries (this is only one of many contexts in which you ll see this macro used). 

Note that you cannot override the standard options by providing options with the same names 
in your own parsing table. If you try this, your options with the same names will simply not be 
set to the values specified on the command line. Instead, the standard options will be set to 
these values. This was a design decision in Xt, one of the few cases where a user-interface pol 
icy is enforced. Uniformity in this basic area was deemed more valuable than flexibility. 

See Also 

Section 1.1, "Widget Lifecycle," 

XtOpenDisplay, XtToolkit Initialize. 



X Toolkit Intrinsics Reference Manual 



165 



Xtl nstal I Accelerators 

Xt - Translations and Actions- 
Name 

Xtlnstall Accelerators install a widget s accelerators on another widget 

Synopsis 

void XtlnstallAccelerators (destination, source) 
Widget destination; 
Widget source; 

Arguments 

destina ti on 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 Intrinsics 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 XtlnstallAccelerators (or XtlnstallAllAccelerators). This call 
specifies two arguments. The destination 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: 

Xtlnitialize (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, XtlnstallAccelerators 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 



Xt - Translations and Actions (continued) Xtlnsta 1 1 Accelerators 

invoked to inform the source widget that its accelerators have been installed on the destination 
widget so it can display them appropriately. 

Core(3) describes the display_accelerator method. Volume Four, X Toolkit Intrinsics 
Programming Manual, has a complete accelerator programming example. 

See Also 

Section 1.5, Translations and Actions," 

XtlnstallAllAccelerators. 



X Toolkit Intrinsics Reference Manual 167 



XtlnstallAIIAccelerators 

Xt - Translations and Actions 

Name 

XtlnstallAllAccelerators install all accelerators from a widget and its descendants onto a 

destination. 

Synopsis 

void XtlnstallAllAccelerators (destination, source) 
Widget destination; 
Widget source; 

Arguments 

destinati on Specifies the widget whose translations are to be augmented. 

source Specifies the widget from which the accelerators are to come. 

Description 

XtlnstallAllAccelerators 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 XtlnstallAllAccelerators 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 xtlnstallAccelerators, the difference between: 

XtlnstallAccelerators (topLevel, quit) ; 

and 

XtlnstallAllAccelerators (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, "Translations and Actions," 

XtlnstallAccelerators. 



168 X Toolkit Intrinsics Reference Manual 



_. .. . .. J XtlsComposite 

Xt - Widget Information 

Name 

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

Synopsis 

Boolean XtlsComposite (w) 
Widget w; 

Arguments 

w Specifies the widget whose class is to be tested. 

Description 

XtlsComposite tests whether a widget is a subclass of the Composite widget class. This is 
really just a convenience function equivalent to calling xtlsSubclass with composite- 
WidgetClass as the class argument. XtlsComposite is defined as a macro in 
<X1 II Intrinsic. h>: 

#define XtlsComposite (widget) XtlsSubclass (widget, (WidgetClass) \ 
compositeWidget Class) 

See Also 

Composite(3), Core(3). 




X Toolkit Intrinsic* Reference Manual 169 



XtlsConstraint \ Vl 

v Xt - Widget Information 

Name 

XtlsConstraint test whether a widget is a subclass of the Constraint widget class. 

Synopsis 

Boolean XtlsConstraint (w) 
Widget w; 

Arguments 

w Specifies the widget whose class is to be tested. 

Description 

XtlsConstraint tests whether a widget is a subclass of the Constraint widget class. This is 
really just a convenience function equivalent to calling Xt isSubclass with const raint- 
WidgetClass as the class argument. XtlsConstraint is defined as a macro in 
<X1 II Intrinsic. h>: 

tdefine XtlsConstraint (widget) XtlsSubclass (widget, (WidgetClass) \ 
const raintWidget Class) 

See Also 

Constraint(3), Core(3). 



1 70 X Toolkit Intrinsics Reference Manual 



_. J XtlsManaged 

Xt - Widget Information 

Name 

XtlsManaged determine whether a widget is managed by its parent 

Synopsis 

Boolean XtlsManaged ( w) 
Widget w; 

Arguments 

w 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 <XlllInstrinsicP.h>. It is a function for 
application programs that do not have access to the Core widget field names. 

XtlsManaged simply accesses the Core widget s managed field. 
See Also 

XtManageChildren, XtUnmanageChildren, 
Core(3). 



X Toolkit Intrinsics Reference Manual 



XtlsRealized \ xt _ W|dget lnformatlon _ 

Name 

XtlsRealized determine whether a widget has been realized. 

Synopsis 

Boolean XtlsRealized (w) 
Widget w; 

Arguments 

w Specifies the widget whose state is to be tested. 

Description 

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

XtlsRealized is a macro for programs that include <X1 II Intrinsic?. h>. It is a function for 
application programs that do not have access to the Core widget field names. XtlsRealized 
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" 



1 72 X Toolkit Intrinsics Reference Manual 



- Xt - Widget .nformatlon / XtlsSeiSJtive 

Name 

XtlsSensitive check the current sensitivity state of a widget 

Synopsis 

Boolean XtlsSensitive (w) 
Widget w, 

Arguments 

w Specifies the widget whose state is to be tested. 

Description 

XtlsSensitive returns TRUE or FALSE to indicate whether or not the widget is sensitive, 
(i.e., whether or not user input events are being dispatched). If both core . sensitive and 
core.ancestor_sensitive are TRUE, XtlsSensitive returns TRUE; otherwise, it 
returns FALSE. 

A widget s sensitivity is often checked by its parent For example the parent may wish to 
determine whether it should should pass the keyboard focus to the child, or it may choose to 
follow the lead of its children, and make itself insensitive. 

See Also 

XtCallAcceptFocus.Xt Set Sensitive, 
Core(3). 



X Toolkit Intrinsics Reference Manual 1 73 



XtlsShell V Xt- Widget Information- 

Name 

XtlsShell test whether a widget is a subclass of the Shell widget class. 

Synopsis 

Boolean XtlsShell (w) 
Widget w; 

Arguments 

w Specifies the widget whose class is to be tested. 

Description 

XtlsShell tests whether a widget is a subclass of the Shell widget class. This is really just a 
convenience function equivalent to calling XtlsSubclass with shellWidgetClass as 
the class argument XtlsShell is defined as a macro in <X1 II Intrinsic. h>: 

#define XtlsShell (widget) XtlsSubclass (widget, (WidgetClass) \ 
shellWidgetClass) 

See Also 

Shell(3), Core(3). 



7 74 X Toolkit Intrinsics Reference Manual 



Xt- Widget Information XtlsSubdaSS 

Name 

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

Synopsis 

Boolean XtlsSubclass (w, wldget_class) 
Widget w; 
WidgetClass widget_class; 

Arguments 

w 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. XtlsSubclass 
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. XtlsSubclass 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 Xtls 
Subclass 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 1 75 



XtMainLoop 



Xtoolkit Xt - Event Handling 



Name 

XtMainLoop continuously process events. 

Synopsis 

void XtMainLoop () 

Description 

XtMainLoop obtains the default application context and reads the next incoming X event by 
calling xtAppNext Event. It then dispatches the appropriate registered procedure with xt- 
DispatchEvent. This constitutes the main loop of Toolkit applications, and, as such, it does 
not return. Applications are expected to exit in response to some user action. (xtAppAdd- 
WorkProc provides a way of using an application s idle time.) There is nothing special about 
XtMainLoop; it is simply an infinite loop that calls xtAppNextEvent and then Xt- 
DispatchEvent. 

An application can provide its own version of this loop. For example, it might test an applica 
tion-dependent global flag or other termination condition before looping back and calling Xt 
AppNextEvent. Instead of exiting on a particular event (say a button press), it might exit if 
the number of top-level widgets drops to zero. 

See Also 

Section 1.1, "Widget Lifecycle," 

XtAppAddWorkProc, XtAppMainLoop, XtAppNextEvent, XtDispatchEvent. 



1 76 X Toolkit Intrinsics Reference Manual 



Xt - Geometry Management- 



J XtMakeGeometry Request 



Name 

XtMakeGeometry Request request parent to change child s geometry. 

Synopsis 

XtGeometryResult XtMakeGeometryRequest (w, request, reply_return) 
Widget w; 

Xt Widget Geometry * request ; 
Xt Widget Geometry *reply_return; 

Arguments 

w Specifies the child widget that is making the request 

request Specifies the desired widget geometry (size, position, border width, and stacking 
order). 

reply _ return 

Returns the allowed widget size or may be NULL if the requesting widget is not 
interested in handling XtGeometryAlmost. 

Description 

Child widgets are not allowed to change their own size or position. Instead, a child uses Xt 
MakeGeometryRequest to ask its parent to change its geometry. XtMakeGeometry- 
Request returns XtGeometryYes or XtGeometryNo. (See below.) 

XtMakeGeometryRequest performs the following tasks: 

If the widget is unmanaged or the widget s parent is not realized, it makes the changes to 
the widget s preferred geometry and returns XtGeometryYes. 

If the parent is not a subclass of compositeWidgetClass or the parent s 
geometry_manager method (the function pointed to by the geometry_ manager 
field in the widget class record) is NULL, it issues an error. 

If the widget s being_destroyed field is TRUE, it returns XtGeometryNo. 

If the widget x, y, width, height and border_width fields are already equal to the 
requested values, it returns XtGeometryYes; otherwise, it calls the parent s 
geometry_manager method with the given parameters. 

If the parent s geometry manager returns XtGeometryYes, XtCWQueryOnly 
is not set in request_mode (see Structures below for details) and if the widget is 
realized, XtMakeGeometryRequest calls the Xlib XConf igureWindow 
function to adjust the widget s window (setting its size, location, and stacking 
order as appropriate). 

If the geometry manager returns XtGeometryDone, the change has been 
approved and actually has been done. In this case, XtMakeGeometryRequest 
does no configuring and returns XtGeometryYes. XtMakeGeometry 
Request never returns XtGeometryDone. 



X Toolkit Intrinsics Reference Manual 1 77 




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 Xt Geometry Yes 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 <Xll/X.h>: 

#define CWX 

#define CWY 

#define CWWidth 

#define CWHeight 

#define CWBorderWidth 

#define CWSibling 

#define CWStackMode 

The Xt Intrinsics also support the following value: 

tdefine XtCWQueryOnly (17) 

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 XConf igureWindow function, uses 
request_mode to determine which fields in the XtwidgetGeometry structure you want 
to specify. 



1 78 X Toolkit Intrinsics Reference Manual 



Xt - Geometry Management 



(continued) 



XtMakeGeometry Request 



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



#define Above 

#define Below 

#define Toplf 

#define Bottomlf 

#define Opposite 



The Intrinsics also support the following value: 

#define XtSMDontChange 5 

For precise definitions of Above, Below, Toplf, Bottomlf, and Opposite, see the refer 
ence page for XtConf igureWindow 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," 

XtMakeResizeRequest. 



X Toolkit Intrinsics Reference Manual 



179 



XtMakeResizeRequest . v< 

v Xt - Geometry Management 

Name 

XtMakeResizeRequest request parent to change child s size. 

Synopsis 

XtGeometryResult XtMakeResizeRequest (w, width, height, 

width_return r 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 

width_return, height_return 

Return the allowed widget width and height 

Description 

XtMakeResizeRequest is a simplified version of XtMakeGeometryRequest. A child 
uses XtMakeResizeRequest to ask its parent to change its size. 

XtMakeResizeRequest creates an XtWidget Geometry 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 XtGeometryAlmost, 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 XtGeometryAlmost replies, it can pass NULL for 
width_return and heigh t_return. 

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; 

See Also 

Section 1.8, "Geometry Management," 

XtMakeGeometryRequest, 

Volume Four, X Toolkit Intrinsics Programming Manual, Chapter 11, Geometry Management. 



180 X Toolkit Intrinsics Reference Manual 



-Xt- Memory Allocation / XtMallOC 

Name 

XtMalloc allocate storage. 

Synopsis 

char *XtMalloc (size) ; 
unsigned int size; 

Arguments 

si ze 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 XtMalloc and copy the data there. 

XtMalloc 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 xtNewString provide slightly higher-level approaches to memory allocation. 
See Also 

XtCalloc, XtErrorMsg, XtFree, XtNew, XtNewString, XtRealloc. 



X Toolkit Intrinsics Reference Manual 18 1 



XtManageChild ~\ Y , 

^ Xt - Widget Lifecycle 

Name 

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

Synopsis 

void XtManageChild (w) 
Widget w; 

Arguments 

w 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. 
Calling XtManageChild or XtManageChildren can be bypassed if widgets are created 
with XtCreateManagedWidget. 

Note that 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. 

See Also 

Section 1.1, "Widget Lifecycle," 

XtCreateManagedWidget, XtlsManaged, XtManageChildren, XtSetMapped- 
WhenManaged, XtUnmanageChild, XtUnmanageChildren. 



182 X Toolkit Intrinsics Reference Manual 



Xt- Widget Lifecycle- 



J XtManageChildren 



Name 

XtManageChildren add widgets to their parent s list of managed children. 

Synopsis 

void XtManageChildren (children, num_ children) 
WidgetList children; 
Cardinal n um_ children ; 

Arguments 

children Specifies an array of child widgets. 

n um_chil dren Specifies the number of children in the array. 

Description 

XtManageChildren brings a list of widgets created with xtCreateWidget under the 
geometry management of their parent A widget cannot be made visible until it is managed. (A 
widget can be created and managed at the same time by calling the convenience function xt- 

CreateManagedWidget.) 

XtManageChildren performs the following: 

Issues an error if the children do not all have the same parent or if the parent is not a sub 
class of compositeWidgetClass. It returns immediately if the common parent is 
being destroyed. 

Marks each child viewable that is not already under management and not being des 
troyed. 

For each viewable child, if the parent is realized, XtManageChildren: 

- Calls the parent s change_managed routine. 
Calls XtRealizeWidget if the child is unrealized. 

- Maps child if map_when_managed is TRUE. 

Managing children is independent of their ordering and their creation and deletion. The parent 
should lay out only children whose managed field is TRUE and ignore all others. Note that some 
composite widgets, especially fixed boxes, call xtManageChild from their insert_child 
method. 

If the parent widget is realized, its change_managed method is called to notify it that its set 
of managed children has changed. The parent can reposition and resize any of its children. It 
moves each child as needed by calling xtMoveWidget, which first updates the x and y fields 
and then calls the Xlib XMoveWindow function if the widget is realized. 

If the composite widget wishes to change the size or border width of any of its children, it calls 
XtResizeWidget, which first updates the Core fields and then calls the Xlib 
XConf igurewindow function if the widget is realized. 

Calling XtManageChild or XtManageChildren explicitly can be bypassed if widgets are 
created with the convenience function xtCreateManagedWidget. Note that 



X Toolkit Inthnsics Reference Manual 183 



XtManageChildren (continued) xt - Widget LHecycle 

XtManageChild, XtManageChildren, XtUnmanageChild, and XtUnmanage- 
Children 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. 

Structures 

typedef Widget *WidgetList; 

See Also 

Section 1.1, "Widget Lifecycle," Section 1.8, "Geometry Management," 

XtCreateManagedWidget, XtlsManaged, XtManageChild, XtMoveWidget, Xt- 
RealizeWidget, XtResizeWidget, XtSetMappedWhenManaged, XtUnmanage 
Child, XtUnmanageChildren. 



184 X Toolkit Intrinsics Reference Manual 



Xt -Widget Lifecycle- 



J XtMapWidget 



Name 

XtMapWidget map a widget to its display. 

Synopsis 

XtMapWidget { w) 
Widget w; 

Arguments 

w 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_managed 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 also be set 
through a call to XtSetMapWhenManaged. 

See Also 

Section 1.1, "Widget Lifecycle," 

XtSetMappedWhenManaged, XtUnmapWidget. 



X Toolkit Intrinsics Reference Manual 



XtMergeArg Lists \ 

> Xt - Memory Allocation 

Name 

XtMergeArgLists merge two ArgList structures. 

Synopsis 

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

Arguments 

argsl Specifies the first ArgList. 

num_argsl Specifies the number of arguments in the first argument list. 

args2 Specifies the second ArgList. 

num_args2 Specifies the number of arguments in the second argument list. 

Description 

XtMergeArgLists allocates a new ArgList large enough to hold argsl and args2 and 
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 <X1 II Intrinsic. h>: 

typedef struct { 

String name; 

XtArgVal value; 
} Arg, * ArgList; 

See Also 

XtFree, XtMalloc, XtSetArg. 




186 X Toolkit Intrinsics Reference Manual 



Xt - Geometry Management- 



j XtMoveWidget 



Name 

XtMoveWidget move a widget on the display. 

Synopsis 

void XtMoveWidget ( w, x, y) 
Widget w; 
Position x; 
Position y; 

Arguments 

vf Specifies the widget to be moved. 

x, y Specify the new widget x and y coordinates. 

Description 

XtMoveWidget returns immediately if the specified geometry fields for the widget are the 
same as the old values. Otherwise, XtMoveWidget writes the new x and y values into the 
widget and, if the widget is realized, issues an Xlib XMove window call on the widget s win 
dow. 

The XtConf igure widget resizes and moves a widget A parent widget must use XtMove 
Widget to rearrange its children on the display. It may also be used to relocate a sibling 
widget A child widget must use XtMakeGeometryRequest and XtMakeResize- 
Request to ask its parent to move or resize it; it cannot move or resize itself. 

The x and y coordinates are specified with respect to the origin in the upper left of the screen. 
Widget coordinates can be converted to screen coordinates with xtTranslateCoords. 

See Also 

Section 1.8, "Geometry Management," 

XtMakeGeometryRequest, XtMakeResizeRequest, XtTranslateCoords. 



X Toolkit Intrinsics Reference Manual 187 



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 Specifies the widget from which the search is to start. 

name 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 



XtNew 

Xt - Memory Allocation 

Name 

XtNew allocate storage for one instance of a data type. 

Synopsis 

type *XtNew ( type) 
type; 

Arguments 

type Specifies a previously declared data type. 

Description 

XtNew is used to allocate storage for one instance of a data type. It returns a pointer to the 
allocated storage. For example, XtNew (xtCallbackList) allocates storage for one call 
back list structure. 

If there is insufficient memory to allocate the new block, xtErrorMsg terminates execution. 
XtNew is a convenience macro that calls xtMalloc with the following arguments specified: 

((type *) XtMalloc ( (unsigned) sizeof (type) ) 
To copy an instance of a string, use xtNewString. 

See Also 

XtMalloc, XtNewString. 



X Toolkit Intrinsics Reference Manual 189 



XtNewString 

Xt - Memory Allocation 

Name 

XtNewString copy an instance of a string. 

Synopsis 

String XtNewString (string) 
String string; 

Arguments 

string Specifies a NULL-terminated string. 

Description 

XtNewString is used to copy an instance of a string. It returns a pointer to the allocated stor 
age. If there is insufficient memory to allocate the new block, XtNewString calls Xt- 
ErrorMsg. For example, xtNew(xtCallbackList) allocates storage for one callback 
list structure. XtNewString is a macro that allocates storage for a string, copies the string 
into the new storage, and returns the pointer. For example, a string can be copied into new stor 
age using the following: 

static String buf [] = "How do you do?"; 
String p; 

p = XtNewString (buf ); 

After this sequence, p points to a separate string that contains "How do you do?" Then buf 
can be changed without affecting p. 

XtNewString is a convenience macro that calls xtMalloc with the following arguments 
specified: 

(strcpy (XtMalloc ( (unsigned) strlen(str) + 1), str) ) 

See Also 

XtMalloc, XtNew, XtFree. 



190 X Toolkit Intrinsics Reference Manual 



-x, - Ev.m H.nd,,ng XtNextEvent 



Name 

XtNextEvent return next event from input queue. 

Synopsis 

void XtNextEvent (even t_re turn) 
XEvent *event_return; 

Arguments 

event_return Returns the event information from the dequeued event structure. 

Description 

XtNextEvent obtains the default application context, and invokes xtAppNextEvent. It is 
retained as a simplified interface to XtAppNextEvent. Since most applications have only 
one application context, this routine does not require the application to pass an application con 
text explicitly. 

Release Information 

In Release 2, a bug prevented widgets from calling XtNextEvent recursively from input or 
timer callbacks. This bug was fixed in Release 3. 

See Also 

XtAppNextEvent 



X Toolkit Intrinsics Reference Manual 19 1 



XtNumber 

Xt - Argument Lists- 
Name 

XtNumber determine the number of elements in a fixed-size array. 

Synopsis 

Cardinal XtNumber (array) 
array; 

Arguments 

array Specifies a fixed-size array. 

Description 

XtNumber returns the number of elements in the specified argument list, resource list, or other 
fixed-size array. It only works for objects whose total size is known at compile time. 

It is a macro defined in <XlllXt Intrinsic.h> as: 

tdefine XtNumber (arr) ((Cardinal) (sizeof(arr) / sizeof (arr [0] ) ) ) 

Related Commands 

XtOf f set, XtSetArg. 



192 X Toolkit Intrinsics Reference Manual 



Xt - Argument Lists XtOff S6t 

Name 

XtOffset determine the byte offset of a field within a structure. 

Synopsis 

Cardinal XtOffset (point er_type, field_name) 
Type pointer_type; 
Field field_name; 

Arguments 

pointer_type Specifies a type that is declared as a pointer to the structure. 

field_name Specifies the name of the field for which to calculate the byte offset. 

Description 

XtOffset computes the relative address of a field in bytes, given a pointer to a structure. 
Using XtOffset, a program can use field names, instead of numeric byte offsets, to specify 
addresses in a structure relative to a base pointer. XtOffset can be used at compile time in 
static initializations. 

XtOffset is often used to determine the location of an instance variable in a widget record. 
Resource fields are defined in terms of offsets from a base address from the beginning of a 
widget Thus, a resource value can be kept up to date by the Resource Manager without any 
knowledge of the instance structure of the widget; it uses just a relative byte offset. 

The following code uses XtOffset to define the foreground resource in the Athena Label 
widget 

static XtResource resources!] = { 
{ 

XtNforeground, /* Resource name is foreground */ 
XtCForeground, /* Resource class is Foreground */ 
XtRPixel, /* Resource type is Pixel */ 

sizeof (Pixel) , /* allocate enough space to hold a Pixel value */ 
XtOffset (LabelWidget, label . foreground) , /*where in instnce strct*/ 
XtRString, /*Default val is a String (will need conversion) */ 

XtDefaultForeground /* Default address */ 



XtNlabel, 
XtCLabel, 
XtRString, 
NULL 



X Toolkit Intrinsics Reference Manual 



XtOffset (continued) Xt - Argument Lists 

xtOf f set is a macro defined in <XlllXt Intrinsic. h> as follows: 

#define XtOffset (type, field) ((unsigned int) (((char *) \ 
(&(( (type) NULL) ->field) )) ( (char *) NULL))) 

See Also 

Section 1.7, "Resources," 

XtGetResources. 



194 X Toolkit Intrinsics Reference Manual 



Xt - Application Contexts- 



J XtOpenDisplay 



Name 

XtOpenDisplay open, initialize, and add a display to an application context. 

Synopsis 

Display *XtOpenDisplay (app_context r display_name, 

application_name, application_class, options, 
num_options, argc, argv) 
XtAppContext app_context; 
String display_name; 
String application_name; 
String application_class; 
XrmOptionDescRec *options; 
Cardinal num_options; 
Cardinal *argc; 
String *argv; 

Arguments 

app_context Specifies the application context. 

di spl ay_n ame 

Specifies the display. A display can be in at most one application context. 

application_name 

Specifies the name of the application instance. 

application_class 

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

options Specifies how to parse the command line for any application-specific 

resources. The options argument is passed as a parameter to XrmParse- 
Command. For further information, see XtlnitializeDisplay. 

num_options Specifies the number of entries in the options list. 

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

argv Specifies the command line parameters. 

Description 

XtOpenDisplay can be used to open a display (possibly an additional display) and add it to 

an application context. 

XtOpenDisplay first parses the command line for the following options: 

-display The display name to be passed to XOpenDi splay; overrides dis- 

play_name. 

-name The resource name prefix; overrides appl icati on_name. 



X Toolkit Intrinsics Reference Manual 1 95 



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 succeeds, XtOpenDisplay then calls XtDisplay Initialize 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 [ ] . 

XtOpenDisplay 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 XtDisplaylnitialize. There is example code in Chapter 9, 
Resource Management and Type Conversion, in Volume Four, X Toolkit Intrinsics Program 
ming Manual. 

See Also 

XtDisplaylnitialize, Xtinitialize. 



196 X Toolkit Intrinsics Reference Manual 



.x-Tv.n,,a,,on..nd Action. XtOverrideTranslations 

Name 

XtOverrideTranslations merge new translations, overwriting widget s existing ones. 

Synopsis 

void XtOverrideTranslations (w r translations) 
Widget w; 
XtTranslations translations; 

Arguments 

w Specifies the widget into which the new translations are to be merged. 

trans la ti ons Specifies the compiled translation table to merge in (must not be NULL). 

Description 

XtOverrideTranslations merges new translations into the existing widget translations, 
overriding the translations for any event or event sequence that already exists in the widget s 
translations, and possibly adding new ones. 

The translation table must be in compiled form, as produced by xtParseTranslation- 
Table. xtParseTranslationTable produces the binary form of the translation table 
from text XtConvert can also do this, specifying XtRTranslationTable -as the 
destination resource type. (A text translation table is automatically parsed in the Core widget 
structure when a widget class is initialized.) 

Translation tables can also be constructed by converting resources with XtConvert. To make 
it easy to modify translation tables in resource files, the string-to-translation-table resource type 
converter allows you to specify whether the table should replace, augment, or override any 
existing translation table in the widget As an option, a pound sign (#) as the first character of 
the table followed by replace (default), augment, or override indicates how to treat 
existing translations (Release 3 only). 

To merge new translations, but keep existing translations in case of conflict, use xt Augment - 
Translations. 

To replace a widget s translations completely and not just selectively overwrite some of them, 
use XtSetValues on the XtNtranslations resource and specify a compiled translation 
table as the value. 
To completely remove existing translations, use XtUninstallTranslations. 

See Also 

Section 1.5, Translations and Actions," 

XtAugmentTranslations, XtConvert, XtParseTranslationTable, 

Core(3), 

Text(4). 



X Toolkit Intrinsics Reference Manual 1 9 7 



XtOwnSelection . 

v Xt - Selections 

Name 

XtOwnSelection indicate that selection data is available. 

Synopsis 

Boolean XtOwnSelection (w, selection, time, convert_proc, 

lose_proc, done_proc) 
Widget w; 
Atom selection; 
Time time; 

XtConvert Selection? roc convert^proc; 
XtLoseSelectionProc lose_proc; 
XtSelectionDoneProc done_proc; 

Arguments 

w 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 
<XlllXatom.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 Cur rent - 
Time is not acceptable. 

convert_proc 

Specifies the procedure to call whenever someone requests the current value 
of the selection. 

lose_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 XtDisownSelection. 

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

XtConvertSelectionProc(2) describes the responsibilities of the widget or application 
sending data and its conversion duties. 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 

XtDisownSelection, XtGetSelectionValue, XtSelectionDone, 
XtConvert Select ionProc(2), XtLoseSelectionProc(2). 



X Toolkit Intrinsics Reference Manual 1 " 



XtParent 

Xt - Widget Information 

Name 

XtParent return the parent widget for the specified widget 

Synopsis 

Widget XtParent (w) 
Widget w; 

Arguments 

w Specifies the widget whose parent is to be returned. 

Description 

XtParent returns the parent widget of the specified widget 



200 X Toolkit Intrinsics Reference Manual 



v T . XtParseAcceleratorTable 

Xt - Translations and Actions 

Name 

XtParseAcceleratorTable compile an accelerator table into its internal representation. 

Synopsis 

XtAccelerators XtParseAcceleratorTable (table) 
String table; 

Arguments 

table Specifies the accelerator table to compile. 

Description 

XtParseAcceleratorTable compiles the accelerator table into its opaque internal rep 
resentation. 

An accelerator is a translation table that is bound with its actions in the context of a particular 
widget The accelerator table can then be installed on some destination widget. When an 
action in the destination widget would cause an accelerator action to be taken, rather than caus 
ing an action in the context of the destination, the actions are executed as though triggered by 
an action in the accelerator widget 

Each widget instance contains that widget s exported accelerator table. Each class of "widget 
exports a method that takes a displayable string representation of the accelerators so that widg 
ets can display their current accelerators. The representation is the accelerator table in canoni 
cal translation table form (see Appendix B, X Toolkit Data Types). The display_acceler- 
ator procedure pointer is of type XtStringProc. 

The facility to parse accelerator tables can also be accessed by converting a string resource into 
a resource of type xtRAcceleratorTable. 

Accelerators can be specified in defaults files, and the string representation is the same as for a 
translation table. However, the interpretation of the taugment and toverride directives 
apply to what will happen when the accelerator is installed; that is, whether or not the accelera 
tor translations will override the translations in the destination widget. The default is 
# augment, which means that the accelerator translations have lower priority than the 
destination translations. The # rep lace directive is ignored for accelerator tables. 

An accelerator table must be stored in the Core widget structure in this compiled format, not as 
a string. Core(3) describes the display_accelerator method. 

See Also 

Section 1.5, Translations and Actions," 

XtlnstallAccelerators, 

Volume Four, X Toolkit Intrinsics Programming Manual, Chapter 7, Events, Translations, and 

Accelerators. 




X Toolkit Intrinsics Reference Manual 20 1 



XtParseTranslationTable 

Xt - Translations and Actions 

Name 

XtParseTranslationTable compile a translation table into its internal representation. 

Synopsis 

XtTranslations XtParseTranslationTable (table) 
String table; 

Arguments 

table Specifies the translation table to compile. 

Description 

XtParseTranslationTable compiles table into its opaque internal representation of 
type XtTranslations. 

A translation table is a string containing a list of translations from an event sequence into one 
or more action procedure calls. The translations are separated from one another by newline 
characters (ASCII LF). The complete syntax of translation tables is specified in Appendix F, 
Translation Table Syntax. All widget instance records contain a translation table, which is a 
resource with no default value. A translation table specifies what action procedures are 
invoked for an event or a sequence of events. 

As an example, the default behavior of the Athena Command widget is: 
Highlight on enter window. 

Unhighlight on exit window. 

Invert on left button down. 

Call callbacks and rein vert on left button up. 

The following illustrates the Command widget s default translation table: 

static String defaultTranslations = 

"<EnterWindow> : Highlight ( ) \n\ 
<LeaveWindow>: Unhighlight () \n\ 
<BtnlDown> : Set ( ) \n\ 
<BtnlUp>: Notify () Unset ()"; 

The tm_table field of the CoreClass record should be filled in at static initialization time 
with the string containing the class* default translations. If a class wants to inherit its super 
class* translations, it can store the special value xtlnheritTranslations into 
tm_table. After the class initialization procedures have been called, the Intrinsics compile 
this translation table into an efficient internal form. Then, at widget creation time, this default 
translation table is used for any widgets that have not had their core translations field set by the 
Resource Manager or the initialize procedures. 

The resource conversion mechanism automatically compiles string translation tables that are 
resources. If a client uses translation tables that are not resources, it must compile them itself 
using XtParseTranslationTable. 



202 X Toolkit Intrinsics Reference Manual 



Xt - Translations and Actions (continued) XtParseTranslationTable 

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

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 Toolkit Intrinsics Reference Manual 203 



XtPeekEvent Yi 

Xt - Event Handling 

Name 

XtPeekEvent nondestructively examine the head of an application s input queue. 

Synopsis 

Boolean XtPeekEvent (event_return) 
XEvent *event_return; 

Arguments 

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

Description 

XtPeekEvent obtains the default application context, and invokes xtAppPeekEvent. It is 
retained as a simplified interface to XtAppPeekEvent. Since most applications have only 
one application context, this function does not require the application to pass an application 
context explicitly. 

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

See Also 

XtAppPeekEvent 



204 X Toolkit Intrinsics Reference Manual 



Xt - Event Handling 



J XtPending 



Name 

XtPending determine if there are any events in an application s input queue. 

Synopsis 

Xt InputMask XtPending ( ) 

Description 

XtPending obtains the default application context, and invokes xtAppPending. It is 
retained as a simplified interface to XtAppPending. Since most applications have only one 
application context, XtPending does not require the application to pass an application con 
text explicitly. 

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

See Also 

XtAppPending 



X Toolkit Intrinsics Reference Manual 205 



XtPopdown \ 

v Xt - Pop Dps 

Name 

XtPopdown unmap a pop-up shell. 

Synopsis 

void XtPopdown (pop up_sh ell) 
Widget popup_shell; 

Arguments 

popup_shell Specifies the widget shell to pop down. 

Description 

XtPopdown pops down a pop-up shell that was popped up by xt Popup or by one of the 
built-in callback functions, xtCallbackExclusive, XtCallbackNonexclusive, or 
XtCallbackNone. 

To perform a pop down from a callback list, use xtCallbackPopdown. To do so from a 
translation table, useMenuPopdown. 

XtPopdown performs the following: 

Calls XtCheckSubclass to ensure popup_shell is a subclass of Shell. 

Checks that popup_shell is currently popped_up; otherwise, it generates an error. 

Unmaps popup_shell s window. 

If popup_shell s grab_kind is either XtGrabNonexclusive or XtGrab- 
Exclusive, it calls xtRemoveGrab. The grab kind is specified as an argument to 
Xt Popup. 

Sets popup_shell s popped_up field to FALSE. 

Calls the callback procedures on the shell s popdown_callback list, designated by 
the resource XtNpopdownCallback. (See XtCreatePopupShell.) 

Pop-up widgets can be created and popped up with XtCreatePopupShell and xtPopup. 

See Also 

Section 1.6,"PopUps," 

XtCallbackExclusive, XtCallbackNone, XtCallbackNonexclusive, Xt 
CheckSubclass, XtCreatePopupShell, XtPopup, XtRemoveGrab. 
Volume Four, X Toolkit Intrinsics Programming Manual, Chapter 12, Menus, Gadgets, and 
Cascaded Pop Ups. 



206 X Toolkit Intrinsics Reference Manual 



J XtPopup 



Xt - Pop Ups 

Name 

XtPopup map a pop-up shell. 

Synopsis 

void XtPopup (popup_shell, grab_kind) 
Widget popup_shell; 
XtGrabKind grab_kind; 

Arguments 

popup_shel 1 Specifies a widget shell returned by XtCreotePopupShell. 

grab_kind Specifies how user events should be constrained. (Can be one of Xt Grab- 
None, XtGrabNonexclusive, XtGrabExclusive.) 

Description 

After creating a pop-up shell with xtCreatePopupShell and its managed child with xt- 
CreateManagedWidget, the pop up is ready to be mapped to the display. The easiest way 
to map the pop up is with XtPopup. 

XtPopup maps its window, by default, to the upper-left corner of the display. This can be cir 
cumvented by relocating the pop-up shell with xtMoveWidget before calling XtPopup. 

XtPopup performs the following duties: 

Calls xtCheckSubclass to ensure popup_shell is a subclass of Shell. 

Generates a nonfatal error if the shell is already popped up. 

Calls the callback procedures on the shell s pop-up callback list, designated by the 
resource xtNpopupCallback. (See XtCreatePopupShell.) 

Sets the shell popped_up field to TRUE, the shell spring_loaded field to FALSE, 
and the shell grab_kind field to grab_kind. grab_kind specifies the grab type 
inserted in the modal cascade. (See xtAddGrab.) 

If the shell s create_popup_child field is non-NULL, XtPopup calls it with 
popup_shell as the parameter. This field is designated by the resource xtNcreate- 
PopupChildProc. (See XtCreatePopupShell). 

If grab_kind is either XtGrabNonexclusive or XtGrabExclusive, it calls: 

XtAddGrab (popup_shell, (grab_kind == XtGrabExclusive), FALSE) 

Calls XtRealizeWidget with popup_shell. 

Calls XMapWindow with the Core window field from popup_shell. 

Widgets can be popped down with xtPopdown. For more specifics on how to relocate the 
pop-up shell before popping it up, see XtMoveWidget and xtTranslateCoords. To per 
form a pop up from a callback list, see xtCallbackNone, xtCallbackNonexclusive, 
and XtCallbackExclusive. To do so from a translation table, use MenuPopup. For 
details on how events are constrained to the pop up, see XtAddGrab. 



X Toolkit Intrinsics Reference Manual 207 



XtPOpUp (continued) Xt - Pop Ups 

See Also 

Section 1.6, "Pop Ups," 

XtCheckSubclass, XtCreateManagedWidget, XtRealizeWidget. 

Volume Four.X Toolkit Intrinsics Programming Manual, Chapter 12, Menus, Gadgets, and 

Cascaded Pop Ups. 



208 X Toolkit Intrinsics Reference Manual 



-X, - Even, HandUng / XtPrOCeSSEvent 

Name 

XtProcessEvent process one input event 

Synopsis 

void XtProcessEvent (mask) 
XtlnputMask mask; 

Arguments 

mask Specifies what types of events to process. The mask is the bitwise inclusive 

OR of XtlMXEvent (an X event), XtlMTimer (a timer event), or Xt- 
iMAlternatelnput (an alternate input event). The symbolic name xt- 
IMA11 is the bitwise inclusive OR of all event types. 

Description 

XtProcessEvent obtains the default application context, and invokes XtAppProcess- 
Event. It is retained as a simplified interface to xtAppProcessEvent. Since most 
applications have only one application context, XtProcessEvent does not require the 
application to pass app_c on text explicitly. 

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

See Also 

XtAppProcessEvent 



X Toolkit Intrinsics Reference Manual 209 



XtQueryGeometry v 

v Xt - Geometry Management- 
Name 

XtQueryGeometry query a child widget s preferred geometry. 

Synopsis 

XtGeometryResult XtQueryGeometry (w r intended, preferred_return) 
Widget w; 

Xt Widget Geometry *intended; 
Xt Widget Geometry *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 XtQueryGeometry. 

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 XtWidget Geometry structure 
with request_mode=0 before calling query_geometry. 

The query_geometry procedure pointer is of type XtGeometryHandler(2): 

The query_geometry 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 about). If the proposed geometry change is 
acceptable without modification, the query_geometry procedure should return xt- 
Geomet ryYes. If at least one field in geomet ry_return is different from the correspond 
ing field in request or if a bit was set in geomet ry_ret urn that was not set in request, the 
query_geometry procedure should return Xt Geomet ryAlmost. If the preferred 
geometry is identical to the current geometry, the query_geometry procedure should return 
Xt Geomet ryNo. 

After calling the query_geometry procedure or if the query_geometry field is NULL, 
XtQueryGeometry examines all the unset bits in geomet ry_return->request_mode 



210 X Toolkit Intrinsics 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 XtSMDont Change. XtQueryGeometry returns the value returned by the 
query_geometry procedure or XtGeometryYes if the query_geometry 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 
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 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 (10) 

#define CWY (11) 

tdefine CWWidth (12) 

#define CWHeight (13) 



X Toolkit Intrinsics Reference Manual 2 1 1 



XtQueryGeometry (continued) Xt - Geometry Management 

tdefine CWBorderWidth (14) 
tdefine CWSibling (15) 
tdefine CWStackMode (16) 

The Xt Intrinsics also support the following value: 

tdefine XtCWQueryOnly (17) 

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 XConf igureWindow function, uses 
request_mode to determine which fields in the Xtwidget Geometry structure you want 
to specify. 

The stack_mode definitions are from <Xll/X.h>: 

#define Above 

tdefine Below 1 

#define Toplf 2 

tdefine Bottomlf 3 

tdefine Opposite 4 

The Intrinsics also support the following value: 

tdefine XtSMDontChange 5 

For precise definitions of Above, Below, Toplf, Bottomlf, 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," 

XtMakeGeometryRequest, 
Core(3), Composite(3). 



212 X Toolkit Intrinsics Reference Manual 



Xt - Widget Llfecycle 



J- XtRealizeWidget 



Name 

XtRealizeWidget realize a widget instance. 

Synopsis 

void XtRealizeWidget (w) 
Widget w; 

Arguments 

w Specifies the widget to be realized. 

Description 

XtRealizeWidget causes widgets to create their windows on the display, and perform their 
final initializations. XtRealizeWidget is called just prior to calling XtMainLoop to pro 
cess events. The argument to XtRealizeWidget is usually the top-level widget returned 
from Xtlnitialize. 

If the widget is already realized, XtRealizeWidget simply returns. Otherwise, it performs 
the following: 

Binds all action names in the widget s translation table to procedures. (See Section 1.5, 
Translations and Actions.") 

Makes a post-order traversal of the widget tree rooted at the specified widget and calls 
the change_managed procedure of each composite widget that has one or more man 
aged children. 

Constructs an XSetwindowAttributes structure filled in with information derived 
from the Core widget fields and calls the realize procedure for the widget, which adds 
any widget-specific attributes and creates the X window. 

If the widget is not a subclass of compositeWidgetClass, XtRealizeWidget 
returns; otherwise, it performs the following: 

- Descends recursively to each of the widget s managed children and calls the real 
ize procedures. Primitive widgets that instantiate children are responsible for real 
izing those children themselves. 

Maps all of the managed child windows that have mapped_when_managed 
TRUE. (If a widget is managed but mapped_when_managed is FALSE, the 
widget is allocated visual space but is not displayed.) 

If the widget is a top-level shell widget (that is, it has no parent), and 
mapped_when_managed is TRUE, XtRealizeWidget maps the widget window. 



X Toolkit Intrinsics Reference Manual 213 



XtRealize Widget (continued) Xt - Widget Llfecycle 

XtCreateWidget, XtRealizeWidget, XtManageChildren, XtUnmanage- 
Children, and XtDestroyWidget maintain the following invariants: 

If a widget is realized, then all its managed children are realized. 

If a widget is realized, then all its managed children that are also 
mapped_when_managed are mapped. 

Functions should take special care to work correctly with both realized and unrealized widgets. 

See Also 

Section 1.1, "Widget Lifecycle," 

Xtlnitialize, XtlsRealized, XtRealizeProc, XtUnrealizeWidget, 
Core(3). 



214 X Toolkit Intrinsics Reference Manual 



Xt - Memory Allocation XtReal IOC 

Name 

XtRealloc change the size of an allocated block of storage. 

Synopsis 

char *XtRealloc (ptr, num) ; 
char *ptr; 
unsigned int num; 

Arguments 

ptr Specifies a pointer to the old storage. 

num Specifies the number of bytes desired in new storage. 

Description 

XtRealloc changes the size of a block of storage, possibly moving it Then, it copies the old 
contents (or as much as will fit) into the new block and frees the old block. If there is insuffi 
cient memory to allocate the new block, XtRealloc terminates by calling xtErrorMsg. 

If ptr is NULL, XtRealloc allocates the new storage without copying the old contents. That 
is, it simply calls xtMalloc. 

The function XtRealloc is implemented by the Toolkit independently of the particular envi 
ronment, so programs ported to a system not supporting realloc will still work. 

See Also 

XtAlloc, XtErrorMsg, XtFree, XtMalloc, XtNew, XtNewString. 



X Toolkit Intrinsics Reference Manual 2 1 5 



XtRegisterCaseConverter 

v Xt- Keyboard Handling- 
Name 

XtRegisterCaseConverter register a case converter. 

Synopsis 

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

Arguments 

di spl ay Specifies the display from which the key events are to come. 

proc Specifies the XtCaseP roc that is to do the conversions. 

start Specifies the first keysym for which this converter is valid, 

stop Specifies the last keysym for which this converter is valid. 

Description 

XtRegisterCaseConverter registers the specified case converter (see 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 (_Xt Convert Case) can be explicitly reinstalled. 

The default converter understands case conversion for all keysyms defined in the XI 1 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, Xt Trans lateKeycode, 
XtCaseProc(2), XtKeyProc(2). 



216 X Toolkit Intrinsics Reference Manual 



-X, - M.mory A, to e.,,on 



Name 

XtReleaseGC deallocate a shared GC when it is no longer needed. 

Synopsis 

void XtReleaseGC (w r gc) 
Widget w; 
GC gc; 

Arguments 

w Specifies the widget that no longer needs the specified GC. 

gc Specifies the GC to be deallocated. 

Description 

XtReleaseGC disassociates an application from a GC allocated with xtGetGC. It must be 
used instead of XtDest royGC if the application is using XtGetGC on multiple displays. 

The Intrinsics maintain reference counts of sharable GCs allocated by XtGetGC. The Intrin- 
sics do not actually pass a free request to the server until the last user of a GC in an application 
releases it 

The Intrinsics use a caching mechanism for sharable read-only GCs. This is explained in Chap 
ter 6, Basic Widget Methods, in Volume Four, X Toolkit Intrinsics Programming Manual. 

See Also 

XtDest royGC, XtGetGC. 



X Toolkit Intrinsics Reference Manual 2 1 7 



XtRemoveAIICallbacks A v 

v Xt - Callbacks- 
Name 

XtRemoveAIICallbacks delete all procedures from a callback list. 

Synopsis 

void XtRemoveAIICallbacks (w, callback_name) 
Widget w; 
String callback_name; 

Arguments 

vr Specifies the widget whose callbacks are to be deleted. 

callback_name Specifies the callback list to be removed. 

Description 

XtRemoveAIICallbacks removes all the widget s callback procedures identified by 
calljbacA:_/ia/ne, regardless of the value of its client_data. This is in contrast to Xt- 
RemoveCallback and XtRemoveCallbacks, which remove the specified callback only if 
a specified client_data argument also matches. 

Calling any of these routines implicitly frees all storage associated with the Intrinsics internal 
representation of the callback list. 

See Also 

Section 1.3, "Application Interface," 

XtAddCallbacks, XtCallCallbacks, XtRemoveCallback, XtRemove 
Callbacks. 



218 X Toolkit Intrinsics Reference Manual 



-xt-caiibacks XtRemoveCallback 

Name 

XtRemoveCallback delete a procedure from a callback list. 

Synopsis 

void XtRemoveCallback (w, callback_name, callback, client_data) 
Widget w; 

String callback_name; 
XtCallbackProc callback; 
caddr_t client_data; 

Arguments 

w Specifies the widget 

ca 1 1 ba c k_n ame 

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

callback Specifies the callback procedure which is to be deleted. 
client_data Specifies the client data to match on the registered callback procedure. 

Description 

XtRemoveCallback removes a callback procedure identified by 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 client_data. 

See Also 

Section 1.3, "Application Interface," 

XtAddCallbacks, XtCallCallbacks, XtRemoveAllCallbacks, XtRemove- 
Callbacks. 



X Toolkit Intrinsics Reference Manual 2 1 9 



XtRemoveCallbacks \ 

v Xt - Callbacks 

Name 

XtRemoveCallbacks 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 
resource 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 xtRemoveAHCallbacks if you want to remove a partic 
ular callback regardless of the value of its client_data. 

Structures 

typedef struct _XtCallbackRec* XtCallbackList; 

See Also 

Section 1.3, "Application Interface," 

XtAddCallbacks, XtCallCallbacks, XtRemoveAllCallbacks, XtRemove- 
Callback. 



220 X Toolkit Intrinsics Reference Manual 



-x - E v.n, XtRemoveEventHandler 



Name 

XtRemoveEventHandler remove a previously registered event handler. 

Synopsis 

void XtRemoveEventHandler (w, event_mask r nonmaskable, proc, 

client_data) 
Widget vr; 

EventMask event_mask; 
Boolean nonmaskable; 
XtEventHandler proc; 
caddr_t client_data; 

Arguments 

w Specifies the widget for which this handler is registered. 

event_mask Specifies the events for which to unregister this handler. 

nonmaskable Specifies a Boolean value that indicates whether this handler should be unre 
gistered for nonmaskable events (GraphicsExpose, NoExpose, 
SelectionClear, SelectionRequest, SelectionNotify, 
ClientMessage, and MappingNotif y) . 

proc Specifies the handler procedure to be removed. 

client_data Specifies the client data to match on the registered handler. 

Description 

XtRemoveEventHandler stops the specified procedure from receiving any more of the 
specified events. 

A handler is removed only if both the procedure proc and client_da ta 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. 

If the widget is realized, XtRemoveEventHandler calls XSelect Input, if necessary, to 
prevent the client from receiving further events of that type. 

To keep a procedure from receiving any events, and to remove it from the widget s 
event_table entirely, call XtRemoveEventHandler with an event_mask of Xt All- 
Events with nonmaskable TRUE, and the client_data registered in a previous call to Xt- 

AddEventHandler. 

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 (|). 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 22 1 



XtRemoveEventHandler 



(continued) 



Xt- Event Hand ling 



Event Mask Symbol 



NoEventMask 

KeyPressMask 

KeyReleaseMask 

ButtonPressMask 

ButtonReleaseMask 

EnterWindowMask 

LeaveWindowMask 

PointerMotionMask 

Point erMotionHintMask 

ButtonlMotionMask 

Button2MotionMask 

Button3MotionMask 

Button4MotionMask 

ButtonSMotionMask 

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 EnterNotif y, 

LeaveNotif y, Focusln 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," 

XtAddEventHandler, XtRemoveRawEventHandler, 
XtEventHandler(2). 



222 



X Toolkit Intrinsics Reference Manual 



v _ / XtRemoveGrab 

Xt - Pop Ups 

Name 

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

Synopsis 

void XtRemoveGrab (w) 
Widget w; 

Arguments 

w 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 Xt Di spa tchE vent 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, XtDi spa tchE vent 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 \ 

v Xt - Event Handling 

Name 

XtRemovelnput cancel source of alternate input events. 

Synopsis 

void XtRemovelnput (id) 
Xt Input Id id; 

Arguments 

id Specifies the ID returned from the corresponding xtAddinput call. 

Description 

XtRemovelnput 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, XtAppAddlnput. 



224 X Toolkit Intrinsics Reference Manual 



-x - EV.H, / XtRemoveRawEventHandler 



Name 

XtRemoveRawEventHandler remove a raw event handler. 

Synopsis 

void XtRemoveRawEventHandler (w, event_mask r nonmaskable, proc, 

client_data) 
Widget w; 

EventMask event_mask; 
Boolean nonmaskable; 
XtEventHandler proc; 
caddr_t client_data; 

Arguments 

w Specifies the widget for which this handler is registered. 

event_mask Specifies the events for which to unregister this handler. 

nonmaskable Specifies a Boolean value that indicates whether this procedure should be 
unregistered for the nonmaskable events (GraphicsExpose, NoExpose, 
SelectionClear, SelectionRequest, SelectionNotify, 
ClientMessage, and MappingNotif y) . 

proc Specifies the procedure to be registered. 

client_data Specifies the client data to match on the registered event handler. 

Description 

XtRemoveRawEventHandler stops the specified procedure 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 Input 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 (|). 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 



Circumstances 



NoEventMask 

KeyPressMask 

KeyReleaseMask 

ButtonPressMask 

ButtonReleaseMask 

EnterWindowMask 

LeaveWindowMask 

PointerMotionMask 

PointerMotionHintMask 

ButtonlMotionMask 

Button2MotionMask 

Button3MotionMask 

ButtonlMotionMask 

ButtonSMotionMask 

ButtonMotionMask 

KeymapStateMask 

ExposureMask 

VisibilityChangeMask 

StructureNotifyMask 

ResizeRedirectMask 

SubstructureNotifyMask 

SubstructureRedirectMask 

FocusChangeMask 

PropertyChangeMask 

ColormapChangeMask 

OwnerGrabButtonMask 



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 EnterNotif y, 

LeaveNot if y, Focusln 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," 

XtRemoveEventHandler. 
XtEventHandler(2). 



226 



X Toolkit Intrinsics Reference Manual 



v . c 4U ... XtRemoveTimeOut 

Xt - Event Handling 

Name 

XtRemoveTimeOut clear a timeout value. 

Synopsis 

void XtRemoveTimeOut (id) 
Xtlntervalld id; 

Arguments 

i d Specifies the ID for the timeout request to be destroyed. 

Description 

XtRemoveTimeOut removes the timeout specified by id. id is the value returned by either 
XtAppAddTimeOut or XtAddTimeOut. 

Note that timeouts are automatically removed once they expire and the callback has been 
delivered. 

See Also 

Section 1.4, "Events," 

XtAddTimeOut, XtAppAddTimeOut. 



X Toolkit Intrinsics Reference Manual 227 



XtRemoveWorkProc \ 

v Xt - Event Handling 

Name 

XtRemoveWorkProc remove a work procedure. 

Synopsis 

void XtRemoveWorkProc (id) 
XtWorkProcId id; 

Arguments 

i d Specifies which work procedure to remove. 

Description 

XtRemoveWorkProc explicitly removes the specified background work procedure. The xt- 
WorkProcId is returned from a corresponding XtAddWorkProc call. 

An XtWorkProc is removed automatically once it returns TRUE. 
See Also 

XtAddWorkProc, XtAppAddWorkProc, 
XtWorkProc(2). 



228 X Toolkit Intrinsics Reference Manual 



Xt - Geometry Management- 



J XtResizeWidget 



Name 

XtResizeWidget resize a child or sibling widget 

Synopsis 

void XtResizeWidget (w, width, height, border_width) 
Widget w; 
Dimension width; 
Dimension height; 
Dimension border_width; 

Arguments 

w Specifies the widget to be resized. 

width, height, border_width 

Specify the new widget size and border width. 

Description 

XtResizeWidget is customarily used by a parent to resize widgets that are its children. It 
can also be used on siblings. 

XtResizeWidget returns immediately if the specified geometry fields are the same as the 
old values. Otherwise, XtResizeWidget writes the new width, height, and 
border_width values into the widget and, if the widget is realized, issues an Xlib 
XConf igureWindow call on the widget s window. 

XtResizeWidget calls the widget s resize procedure to notify it of the size change. 

Note that once a widget is resized or otherwise reconfigured by its parent, it may need to do 
additional processing in its own resize procedure. Widgets usually need to know when they 
have changed size so that they can lay out their displayed data again to match the new size. 
When a parent resizes a child, it calls XtResizeWidget, which updates the geometry fields 
in the widget, configures the window if the widget is realized, and calls the child s resize proce 
dure to notify the child. The resize procedure pointer is of type XtwidgetProc. 

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 procedure takes a widget as its only argument 

See Also 

Section 1.8, "Geometry Management," 

XtConf igureWidget, XtMakeGeometryRequest, XtResizeWindow. 



X Toolkit Intrinsics Reference Manual 229 



XtResizeWindow \ 

v Xt- Window Manipulation 

Name 

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

Synopsis 

void XtResizeWindow (w) 
Widget vr; 

Arguments 

w Specifies the widget 

Description 

XtResizeWindow calls the XConf igurewindow Xlib function to make the window of the 
specified widget match its Core width, height, and border_width. 

The call to XConf igurewindow is done unconditionally because there is no way to tell if 
these values match the current values. 

XtResizeWindow does not cause the widget s resize method to be called. 

There are very few occasions when you need to use XtResizeWindow; it is more diplomatic 
to use XtResizeWidget. 

See Also 

Section 1.8, "Geometry Management," 

XtResizeWidget. 



230 x Toolkit Intrinsics Reference Manual 



-Xt - Widget Information / 

Name 

XtScreen return the screen pointer for the specified widget. 

Synopsis 

Screen *XtScreen (w) 
Widget w; 

Arguments 

w Specifies the widget 

Description 

XtScreen returns a pointer to the screen the specified widget is on. 

See Also 

XtDisplay 




X Toolkit Intrinsics Reference Manual 23 1 



XtSetArg Yi 

Xt - Argument Lists 

Name 

XtSetArg 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 set 

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 xt ArgVal, the resource value 
is stored directly in val ue; otherwise, a pointer to it is stored in val ue.) 

Description 

Many Intrinsics 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, 100); 
XtSetArg (args [n] , XtNwidth, 200); 
XtSetValues (widget, args, n) ; 

Volume Four, X Toolkit Intrinsics Programming Manual, presents several examples using 
Args, setting them both with values initialized at compile time and using XtSetArg. 

Structures 

Arg is defined as follows in <X1 L Intrinsic. h>: 

typedef struct { 

String name; 

XtArgVal value; 
} Arg, * ArgList; 



232 X Toolkit Intrinsics Reference Manual 



Xt - Argument Lists (continued) X tSet A rg 

The definition of xtArgVal differs depending on architecture its purpose is precisely to 
make code portable between architectures with different byte sizes. 

The macro itself, from the same file, is listed below: 

#define XtSetArg (arg, n, d) ( (arg) .name= (n) , (arg) .value= (XtArgVal) (d) ) 

See Also 

Section 1.7, "Resources," 

XtMergeArgLists, XtNumber. 



X Toolkit Intrinsics Reference Manual 233 



XtSetErrorHandler Yi 

Xt - Error Handling 

Name 

XtSetErrorHandler 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 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 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 _xt Error. 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 xtSetErrorHandler(2) for more details. 

See Also 

XtSetErrorMsgHandler, XtSetWarningHandler, 
XtErrorHandler(2). 



234 X Toolkit Intrinsics Reference Manual 



Xt - Error Handling- 



J XtSetErrorMsgHandler 



Name 

XtSetErrorMsgHandler register a procedure to be called on nonfatal error conditions. 

Synopsis 

void XtSetErrorMsgHandler (msg_handler) 
XtErrorMsgHandler msg_handler; 

Arguments 

msg_handler Specifies the new high-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 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 xt Warning 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 lusrlliblXHIXtErrorDB. 

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 error handler provided by the Intrinsics constructs a string from the error resource 
database and calls XtError. Using XtSetErrorMsgHandler, you can replace this with 
your own handler. 

See Also 

XtSetErrorHandler, XtSetWarningMsgHandler, 
XtErrorMsgHandler(2). 



X Toolkit Intrinsics Reference Manual 235 



XtSetKeyboardFocus Y| 

v Xt - Keyboard Handling 

Name 

XtSetKeyboardFocus redirect keyboard input to a child widget 

Synopsis 

void XtSetKeyboardFocus (subtree, descendant) 
Widget subtree, descendant; 

Arguments 

subtree Specifies the widget to be considered the root of the subtree for which the 

keyboard focus is to be set (For example, a composite widget that is turning 
over all keyboard input to one of its children.) 

descendant Specifies either the widget in the subtree structure which is to receive the 
keyboard event, or NULL. Note that it is not an error to specify NULL when no 
input focus was previously set. 

Description 

XtSetKeyboardFocus directs subsequent keyboard events that occur within subtree or 
one of its descendants to one specified descendant widget (This routine can be used 
instead of calling the Xlib xSetlnputFocus routine.) subtree presumably specifies a 
composite widget that is turning over all the keyboard input to one of its children. 

If a future KeyPress or KeyRelease event occurs within the specified subtree (i.e., in the 
subtree widget or one of its descendants), XtSetKeyboardFocus causes xt- 
DispatchEvent to remap and send the event to the specified descendant widget 

When there is no modal cascade, keyboard events can occur within a widget W in one of three 
ways: 

W has the X keyboard focus. 

W has the keyboard focus of one of its ancestors, and the event occurs within the ancestor 
or one of the ancestor s descendants. 

No ancestor of W has a descendant within the keyboard focus, and the pointer is within 
W. 

When there is a modal cascade (see xt AddGrab), a widget W receives keyboard events if an 
ancestor of W is in the active subset of the modal cascade and one or more of the previous con 
ditions is TRUE. 

When subtree or one of its descendants acquires the X keyboard focus, or the pointer 
moves into the subtree such that keyboard events would now be delivered to subtree, a 
Focus In event is generated for descendant if FocusNotif y events have been selected 
by descendant. Similarly, when W loses the X keyboard focus or the keyboard focus for one 
of its ancestors, a FocusOut event is generated for descendant if FocusNotif y events 
have been selected by descendant. 

Note that every widget exports an accept_f ocus procedure to allow outside agents to cause 
a widget to get the keyboard focus. To call a widget s accept_f ocus procedure, use xt- 
CallAcceptFocus. The widget returns whether it actually took the focus or not, so that the 



236 X Toolkit Intrinsics Reference Manual 



Xt - Keyboard Handling (continued) XtSetKey board FOCUS 

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 xsetlnputFocus explicitly. Widgets that never want the keyboard focus should set 
their accept_f ocus procedure pointer to NULL. 

See Also 

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



X Toolkit Intrinskx Reference Manual 237 



XtSetKeyTranslator 

v Xt- Keyboard Handling- 
Name 

XtSetKeyTranslator register a key translator. 

Synopsis 

void XtSetKeyTranslator (display, proc) 
Display *display; 
XtKeyProc proc; 

Arguments 

display Specifies the display from which to translate the events. 

proc Specifies the procedure that is to perform key translations. 

Description 

XtSetKeyTranslator registers the specified procedure as the current key translator. The 
default translator is xtTranslateKey, an XtKeyProc that uses Shift and Lock modifiers 
with the interpretations defined by the XI 1 protocol. XtSetKeyTranslator is provided so 
that new translators can call it to get default keycode-to-keysym translations and so that the 
default translator can be reinstalled. 

The only way to remove a converter is to register a new one. For example, the default key 
translator (XtTranslateKey) can be explicitly reinstalled. Another approach to deleting a 
converter would be for an application to register an identity converter that simply copied the 
input keysym to both output keysyms. 

For a more detailed discussion of processing keyboard input, see Volume Four, X Toolkit Intrix- 
sics Programming Manual. 

See Also 

XtRegisterCaseConverter, Xt Trans lateKeycode, 
XtTranslateKey, XtKeyProc(2). 



238 X Toolkit Intrinsics Reference Manual 



Xt - Resource Management- 



J XtSetMappedWhenManaged 



Name 

XtSetMappedWhenManaged change the value of a widget s map_when_managed field. 

Synopsis 

void XtSetMappedWhenManaged (w r map_when_managed) 
Widget w; 
Boolean map_when__managed; 

Arguments 

w Specifies the widget 

map_ wh en_man a ged 

Specifies a Boolean value that indicates the new value of the map_ 
when_managed field. 

Description 

After a widget is realized, it must be mapped before it can become visible. XtSetMapped 
WhenManaged controls whether this mapping occurs automatically or not 

If the widget is realized and managed and if the new value of map_when_managed is TRUE, 
XtSetMappedWhenManaged maps the window. If the widget is realized and managed and 
if the new value of map_when_managed is FALSE, it unmaps the window. 

XtSetMappedWhenManaged is a convenience function that is equivalent to (but slightly 
faster than) calling XtSetValues and setting the new value for the MappedwhenManaged 
resource. As an alternative to using XtSetMappedWhenManaged to control mapping, a cli 
ent may set mapped_when_managed to FALSE and use XtMapWidget and XtUnmap- 
Widget explicitly. 

A widget is normally mapped if it is managed. However, this behavior can be overridden by 
setting the Core xtNmappedWhenManaged resource for the widget when it is created or by 
setting the map_when_managed field to FALSE. 

The mapped_when_managed field can be altered in several ways. A widget can control 
whether it is mapped when managed by setting its core map_when_managed field. This 
field, normally TRUE, can be set to FALSE explicitly. At the application level, the 
mapped_when_managed attribute can be disabled by setting the XtNmappedWhen 
Managed resource to false in the argument list specified at widget creation time. 

See Also 

Section 1.1, "Widget Lifecycle," 

XtCreateManagedWidget, XtManageChildren, XtMapWidget, XtSetValues, 
XtUnmapWidget. 



X Toolkit Intrinsics Reference Manual 239 



XtSetSelectionTimeout \ 

v 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 timeout 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 

Xt Get Select ionTimeout 



240 X Toolkit Intrinsics Reference Manual 



-Xt - Resource Management / XtSetSenSffl V6 

Name 

XtSetSensitive set the sensitivity state of a widget 

Synopsis 

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

Arguments 

*r Specifies the widget 

sensitive 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 insensitive. 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, Focusln, 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 Xt Set Values 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_yalues 
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 <Xll/CoreP.h>. 

See Also 

XtGetValues, XtlsSensitive, XtSetValues. 



X Toolkit Intrinsics Reference Manual 24 1 



XtSetSubvalues . , xt _ Resource Hanagem . nt _ 

Name 

XtSetSubvalues copy from ArgList to base-offset resource list. 

Synopsis 

void XtSetSubvalues (base, resources, num_resources, args, 

num_args) 
caddr_t base; 
XtResourceList resources; 
Cardinal nu/n_resources; 
ArgList args; 
Cardinal num_args; 

Arguments 

base Specifies the base address to which the resources should be written. 

resources Specifies the current nonwidget resources values. 

/jum_resources 

Specifies the number of resources in the resource list. 

args Specifies the argument list of name/value pairs that contain the resources to 

be modified. The resources and values passed are dependent on the subpart 
of the widget being modified. 

num_args Specifies the number of arguments in the argument list. 

Description 

XtSetSubvalues stores resources into the structure identified by base. In particular, Xt 
SetSubvalues writes the values of args into resources. The location of the resources 
to write are determined from the resources array and the base address. 

This is used for explicitly writing resource data in entities that are not widgets. 
The conjugate function xtGetSubvalues gets a widget s values. 

Structures 

A Resource is defined as follows in <XlllInstrinsic.h>: 

typedef struct _XtResource { 

String resource_name; /* Resource name */ 

String resource_class; /* Resource class */ 

String resource_type; /* Representation type desired */ 

Cardinal resource_size; /* Size in bytes of representation */ 

Cardinal resource_of f set; /* Offset from base to put resource value */ 

String default_type; /* Representation type of specified default */ 

caddr_t def ault_addr; /* Address of resource default value */ 

} XtResource, XtResourceList; 



242 X Toolkit Intrinsics Reference Manual 



Xt - Resource Management (continued) XtSetSub values 

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 243 



XtSetValues 

Xt - Resource Management 

Name 

XtSetValues copy resources from ArgList to widget 

Synopsis 

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

Arguments 

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

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

num_a rgs 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 constraintwidgetdass, XtSetValues also 
updates the widget s constraints. It starts with the constraint resources specified for 
constraintwidgetdass 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 constraintwidgetdass 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 Xt Geometry Yes, 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 returned, XtSetValues calls the set_values_almost 



244 X Toolkit Intrinsics Reference Manual 



Xt - Resource Management (continued) Xt Set Values 

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_yalues methods returned TRUE, XtSetValues causes the 
widget s expose procedure to be invoked by calling the Xlib xciearArea 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 \ v 

v Xt - Error Handling 

Name 

XtSetWarningHandler 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 Xt Warn ing 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 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- Error Handling 



f XtSetWarningMsgHandler 



Name 

XtSetWarningMsgHandler register a high-level procedure to be called on nonfatal error con 
ditions. 

Synopsis 

void XtSetWarningMsgHandler (msg_handler) 
XtErrorMsgHandler msg_handler; 

Arguments 

msg_handler Specifies the new high-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 Xt Warning 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 warning handler provided by the Intrinsics constructs a string from the error 
resource database and calls xtwarning. Using XtSetWarningMsgHandler, you can 
replace this default handler with one of your own. 

See Also 

XtSetErrorHandler, XtSetErrorMsgHandler, XtSetWarningHandler, Xt 
WarningMsg, 
XtWarningMsgHandler(2). 



X Toolkit Intrinsics Reference Manual 247 



XtStringConversionWarning \ xt _ Error Handl|ng _ 

Name 

XtStringConversionWarning emit boilerplate string conversion error message. 

Synopsis 

void XtStringConversionWarning (src, dst_type) 
String src, dst_type; 

Arguments 

src Specifies the string that could not be converted. 

dst_type Specifies the name of the type to which the string could not be converted. 

Description 

XtStringConversionWarning is a convenience routine for use in new resource conver 
ters that convert from strings. It issues a warning message with the name conversion- 
Error, type string, class xtToolkitError, and default message string: 

"Cannot convert src to type dst_type" 

It can be used by a conversion routine to announce a nonfatal conversion error. 

See Also 

XtWarning, XtWarningMsgHandler. 



248 X Toolkit Intrinsics Reference Manual 



Xt - Widget Information- 



J XtSuperclass 



Name 

XtSuperclass obtain a widget s superclass. 

Synopsis 

WidgetClass XtSuperclass (w) 
Widget w; 

Arguments 

w Specifies the widget whose superclass is to be checked. 

Description 

XtSuperclass returns a pointer to the class structure of the widget s superclass. 

See Also 

XtCheckSubclass, XtClass, XtlsSubclass, 
Core(3). 



X Toolkit Intrinsics Reference Manual 249 



XtToolkitlnitialize \ xt _ Appllcatk)n 

Name 

XtToolkitlnitialize initialize the X Toolkit internals. 

Synopsis 

void XtToolkitlnitialize () 

Description 

XtToolkitlnitialize initializes internal Toolkit data structures. It does not set up an 
application context or open a display. 

Xtlnitialize calls XtToolkitlnitialize in the course of its initialization. Programs 
too sophisticated to use Xtlnitialize (such as those that create multiple application con 
texts) need to call XtToolkitlnitialize explicitly. 
The semantics of calling XtToolkitlnitialize more than once are undefined. 

See Also 

Section 1.1, "Widget Lifecycle," 

Xtlnitialize. 



25Q X Toolkit Intrinsics Reference Manual 



-xt - window Manipulation / XtTranslateCoords 

Name 

XtTranslateCoords translate an x-y coordinate pair from widget coordinates to root coordi 
nates. 

Synopsis 

void XtTranslateCoords (w, x, y, rootx_return, rooty_return) 
Widget im 
position x, y; 
Position *rootx_return f *rooty_return; 

Arguments 

w Specifies the widget 

x, y Specify the widget-relative x and y coordinates. 

root x_ret urn, rooty_return 

Return the root-relative x and y coordinates. 

Description 

XtTranslateCoords converts widget-relative coordinates to display-relative coordinates. 
This is useful in moving and resizing widgets, since those routines work with display-relative 
coordinates. 

The display height and width can be obtained in pixels with the Xlib macros XDisplay- 
Height and XDisplayWidth, and in millimeters with the Xlib macros XDisplay- 
HeightMM and XDisplayWidthMM. 

These macros require a display and screen, which can be returned by Intrinsics functions. An 
example might be: 

height = XDisplayHeight (XtDisplay (w) , XtScreen (w) ) ; 

XtTranslateCoords is similar to the Xlib XTranslateCoordinates function, which 
also translates window-relative coordinates to display-relative coordinates. But Xt 
TranslateCoords does not generate a server request because the required information is 
already in the widget s data structures. 

Availability 

As of Release 3, the Intrinsics define Position as short rather than as int. This saves 
space in widget instance records, but may break Release 2 programs that pass pointers to ints. 

See Also 

Core(3) 



X Toolkit Intrinsics Reference Manual 2S1 



XtTranslateKey 

Xt - Keyboard Handling 

Name 

XtTranslateKey invoke the currently registered keycode-to-keysym translator. 

Synopsis 

void XtTranslateKey (display, keycode, modifiers, 

modifiers_return f keysym_return) 
Display *display; 
KeyCode keycode; 
Modifiers modifiers; 
Modifiers *modifiers_return; 
KeySym *keysym_return; 

Arguments 

di spl ay Specifies the display that the keycode is from. 

keycode Specifies the keycode to translate. 

modi fi ers Specifies the modifiers to be applied to the keycode. 

modi fi ers_return 

Returns a mask that indicates the modifiers actually used to generate the 
keysym (an AND of modifiers and any default modifiers applied by the 
currently registered translator). 

keysym_re t urn 

Returns the resulting keysym. 

Description 

XtTranslateKey is the default XtKeyProc. It takes a keycode and returns the corre 
sponding KeySym, recognizing Shift and Lock modifiers. It is provided so that new tranlsators 
with more expanded functionality can call it to get default KeyCode-to-KeySym translations in 
addition to whatever they add, and so that the default translation can be reinstalled. 

The default key translator can be invoked directly by calling XtTranslateKeyCode. A 
new translator can be registered by calling xtSetKeyTranslator. There is no way to 
remove a translator; to reinstall the default behavior, call XtSetKeyTranslator with Xt 
TranslateKey as the proc argument 

Structures 

typedef unsigned int Modifiers; 

Modifiers will be made up of the bitwise OR of the following masks: 
Shif tMask Shift key was depressed. 

LOG kMa s k Caps Lock key was depressed. 

ControlMask Control key was depressed. 



X Toolkit Intrinsics Reference Manual 



Xt - Keyboard Handling (continued) XtTransiateKey 

ModlMask Key defined as Modi was depressed. 



ModSMask Key defined as Mod5 was depressed. 

StandardMask (ShiftMask | LockMask). 

See Also 

XtRegisterCaseConverter, XtSetKeyTranslator, 
XtKeyProc(2). 



X Toolkit Intrinsics Reference Manual 253 



XtTranslateKeycode \ V1 

v Xt- Keyboard Handling- 
Name 

XtTranslateKeycode invoke the currently registered keycode-to-keysym translator. 

Synopsis 

void XtTranslateKeycode (display, keycode, modifiers, modifi- 

ers_return, keysym_return) 
Display *display; 
KeyCode keycode; 
Modifiers modifiers; 
Modifiers *modifiers_return; 
KeySym *keysym_return; 

Arguments 

display Specifies the display that the keycode is from. 

keycode Specifies the keycode to translate. 

modi fi ers Specifies the modifiers to be applied to the keycode. 

modi fi ers_return 

Returns a mask that indicates the modifiers actually used to generate the 
keysym (an AND of modifiers and any default modifiers applied by the 
currently registered translator). 

keysym_re t urn 

Returns the resulting keysym. 

Description 

XtTranslateKeycode is used to invoke the currently registered keycode-to-keysym trans 
lator (xtTranslateKey by default). It passes its arguments directly to that converter. The 
translator is registered by a call to Xt SetKeyTranslator. 

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

Structures 

typedef unsigned int Modifiers; 

Modifiers will be made up of the bitwise OR of the following masks: 
Shi f tMa s k Shift key was depressed. 

LockMask Caps Lock key was depressed. 

Cont r o IMa s k Control key was depressed. 
ModlMa s k Key defined as Modi was depressed. 



254 X Toolkit Intrinsics Reference Manual 



Xt - Keyboard Handling 



(continued) 



XtTranslateKeycode 



ModSMask Key defined as Mod5 was depressed. 

StandardMask (ShiftMask | LockMask). 

See Also 

XtRegisterCaseConverter, XtSetKeyTranslator, XtTranslateKey, 
XtKeyProc(2). 



X Toolkit Intrinsics Reference Manual 



255 



XtUnlnstallTranslations 

Xt - Translations and Actions 

Name 

XtUninstallTranslations remove existing translations. 

Synopsis 

void XtUninstallTranslations (w) 
Widget w; 

Arguments 

w Specifies the widget from which the translations are to be removed. 

Description 

XtUninstallTranslations removes a widget s translation table. This might be useful to 
eliminate all of a widget s translations, perhaps for debugging or testing. 

To replace a widget s translations completely and not just selectively overwrite some of them, 
use xtSetValues on the xtNtranslations resource and specify a compiled translation 
table as the value. 

To merge new translations, but keep existing translations in case of conflict, use xt Augment - 
Translations. 

To completely remove existing translations, use XtUninstallTranslations. 

See Also 

Section 1.5, Translations and Actions," 

Xt Augment Translations, Xt Over rideTranslat ions, Xt Par seTranslat ion- 
Table, XtSetValues. 



256 X Toolkit Intrinsics Reference Manual 



v t u XtUnmanageChild 

Xt - Geometry Management r 

Name 

XtUnmanageChild remove a widget from its parent s managed list. 

Synopsis 

void XtUnmanageChild(fcr) 
Widget w; 

Arguments 

w Specifies the child widget to be unmanaged. 

Description 

XtUnmanageChild constructs a widget list containing one element and calls Xt- 

UnmanageChildren. 

Note that 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. 

See Also 

Section 1.1, "Widget Lifecycle," 

XtDestroyWidget, XtlsManaged, XtManageChild, XtManageChildren, Xt- 
UnmanageChildren. 



X Toolkit Intrinsics Reference Manual 257 



XtUnmanageChildren 

v Xt - Geometry Management 

Name 

XtUnmanageChildren remove a list of children from a parent widget s managed list. 

Synopsis 

void XtUnmanageChildren (children, num_ children) 
WidgetList children; 
Cardinal n um_ children ; 

Arguments 

chil dren Specifies a list of child widgets . 

n um_chi 1 dren 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 compositeWidgetClass. 

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- 
pingiL 

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 banishment some time later, they may be managed again. To 
destroy widgets entirely, see xtDestroyWidget. 

Note that 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 

Section 1.1, "Widget Lifecycle," 

XtDestroyWidget, XtlsManaged, XtManageChild, XtManageChildren, Xt 
UnmanageChild. 



258 X Toolkit Intrinsics Reference Manual 



Xt -Widget Lltecycle- 



J XtUnmapWidget 



Name 

XtUnmapWidget unmap a widget explicitly. 

Synopsis 

XtUnmapWidget (w) 
Widget w; 

Arguments 

w Specifies the widget to be unmapped. 

Description 

XtUnmapWidget unmaps a widget s window from its display, causing it to become invisible. 

Most widgets are mapped when they are managed. Widgets that are not must be mapped expli 
citly by calling xtMapWidget. XtUnmapWidget takes a widget off the display without 
deleting it 

See Also 

Section 1.1, "Widget Lifecycle," 

XtManageChild, XtMapWidget, XtSetMappedWhenManaged. 



X Toolkit Intrinsics Reference Manual 259 



XtUnrealizeWidget "\ 

v Xt - Widget LHecycle 

Name 

XtUnrealizeWidget destroy the windows associated with a widget and its descendants. 

Synopsis 

void XtUnrealizeWidget (w) 
Widget w; 

Arguments 

w Specifies the widget 

Description 

XtUnrealizeWidget destroys the windows of a widget and its children. It traverses the 
widget tree inpre-order traversal, unrealizing children before it unrealizes the parent. 

Note that this call simply destroys the windows associated with the widget(s). The widget 
instances themselves remain intact. To recreate the windows at a later time, call xt Realize - 
widget again. Compare xtDestroyWidget, which destroys the widget(s) themselves. 

If the widget was managed, it will be unmanaged automatically before its window is freed. 

See Also 

Section 1.1, "Widget Lifecycle," 

XtDestroyWidget, XtRealizeWidget. 



260 X Toolkit Intrinsics Reference Manual 



Xt- Error Handling 



J XtWarning 



Name 

XtWaming call the installed low-level warning handler. 

Synopsis 

void XtWarning (message) 
String message; 

Arguments 

message Specifies the nonfatal error message to be reported. 

Description 

XtWarning calls the existing low-level warning error procedure. Warning errors are nonfatal. 
The default low-level warning handler provided by the Intrinsics is _Xt Warn ing. On UNIX- 
based systems, it prints the message to standard error and returns to the caller. 

Most programs should use the more elaborate xtWarningMsg, to print customized error mes 
sages from an error database. XtWarningMsg allows an application to be more easily cus 
tomized by site, and allows for international considerations in reporting errors. 

A custom warning handler can be installed by calling xtSetWarningHandler. 

See Also 

XtSetErrorHandler, XtSetErrorMsgHandler, XtSetWarningHandler, XtSet- 
WarningMsgHandler, XtWarningMsg. 



X Toolkit Intrinsics Reference Manual 26 1 



XtWarningMsg A 

v Xt - Error Handling 



Name 

XtWarningMsg call the installed high-level warning handler. 

Synopsis 

void XtWarningMsg (name, type, class, default, params, 

num_params) 
String name; 
String type; 
String class; 
String default; 
String * params; 
Cardinal *num_params; 

Arguments 

name Specifies the general kind of error. 

type Specifies the detailed name of the error. 

class Specifies the resource class. 

def a ul t Specifies the default message to use. 

params Specifies a pointer to a list of values to be stored in the message. 

num_params Specifies the number of values in the parameter list. 

Description 

XtWarningMsg calls the currently installed high-level warning handler. This is the preferred 
method of delivering warning messages. The error handler that gets invoked can be customized 
on a per site basis, and can manage details like international considerations and system-wide 
error logging. 

Warning errors are assumed to be informative and recoverable. Fatal error handlers should be 
used for errors that require attention; fatal error handlers prevent a program from completing 
successfully. 

The Intrinsic internal errors all have class xtToolkitError. 
See Also 

XtWarning 



262 X Toolkit Intrinsics Reference Manual 



Xt - Widget Information 



J XtWidgetToApplicationContext 



Name 

XtWidgetToApplicationContext get the application context for a given widget 

Synopsis 

XtAppContext XtWidgetToApplicationContext (w) 
Widget w; 

Arguments 

w 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 windowOb jClass. Then 
it accesses the application context associated with the display for that widget 

See Also 

XtCreateApplicationContext 



X Toolkit Intrinsics Reference Manual 263 



XtWindow \ v 

v Xt - Widget Information 

Name 

XtWindow return the window of the specified widget 

Synopsis 

Window XtWindow (nr) 
Widget w; 

Arguments 

w Specifies the widget 

Description 

XtWindow returns the window of the specified widget 



264 X Toolkit Intrinsics Reference Manual 



Xt - Widget Information- 



J XtWindowToWldget 



Name 

XtWindowTo Widget translate a window and display pointer into a widget instance. 

Synopsis 

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

Arguments 

display Specifies the display on which the window is defined. 

window Specify the window for which you want the widget 

Description 

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

On failure, 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. 



Xt - Keyboard Handling 



J XtAcceptFocusProc 



Name 

XtAcceptFocusProc prototype procedure to accept or reject keyboard focus. 

Synopsis 

typedef Boolean (*XtAcceptFocusProc) (Widget, Time); 
Widget w; 
Time *time; 

Arguments 

w Specifies the widget. 

time 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_f ocus 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_f ocus procedure is part of the Core class structure. A widget that never wants 
the keyboard focus should set its accept_f ocus procedure to NULL when it initializes its 
class record. 

A widget can usurp the keyboard focus by calling the Xlib function XSetlnputFocus 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 

XtCallAcceptFocus, XtSetKeyboardFocus. 



X Toolkit Intrinsics Reference Manual 269 



XtActionProc , Vl 

v Xt - Translations and Actions 

Name 

XtActionProc prototype procedure for registering action tables. 

Synopsis 

typedef void (*Xt Action? roc) (Widget, XEvent *, String *, 

Cardinal *) ; 
Widget w; 
XEvent * event; 
String *params; 
Cardinal * numjparams ; 

Arguments 

w Specifies the widget that caused the action to be called. 

event Specifies the event that caused the action to be called. If the action is called 

after a sequence of events, then the last event in the sequence is used. 

pa rams Specifies a pointer to the list of strings that were specified in the translation 

table as arguments to the action. 

num_params Specifies the number of arguments specified in the translation table. 

Description 

All widget class records contain an action table. In addition, using xtAddActions, an appli 
cation can register its own action tables with the Resource Manager. An action table consists 
of a list of string names (which can be used in translation tables to associate an action with one 
or more events) and corresponding function pointers (often spelled the same as the string). The 
function pointer is of type XtActionProc. 

An XtActionProc is just a function with four arguments: a widget, an event, a string con 
taining any arguments specified for the action, and the number of arguments contained in the 
string. In most cases, the last two arguments are unused. When you don t pass any arguments, 
you can call your action function with only the first two arguments, or, if the additional argu 
ments are declared but not used, you should be sure to include the lint comment 

/*ARGUSED*/. 

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. 

Many action routines are intentionally written not to depend on the detailed information inside 
any particular type of event, so that the user uses the translation table to call the action in 
response to different types of events. For example, it is useful for an action routine normally 
triggered by a pointer click to work when called in response to a key instead. Such an action 
should not depend on the event structure fields unique to button events. 



270 X Toolkit Intrinsics Reference Manual 



Xt - Translations and Actions (continued) Xt ActionProc 

However, many other action routines, and most event handlers, do use the detailed information 
inside event structures. The first member of the event structure, type, identifies the type of 
event this structure represents, and hence implies what other fields are present in the structure. 

To access event structure fields other than type, you need to cast XEvent into the appropriate 
event structure type. If you are expecting only one type of event to trigger this action, then you 
can simply declare the argument as the appropriate type, as show below. 

static void 
Turn (w, event) 
TetrisWidget w; 
XButtonEvent *event; 
{ 

/* we must now use only the fields in XButtonEvent */ 
if (event->type != ButtonPress) 

XtWarning ("TetrisWidget: Turn action invoked\ 
by wrong event type."); 



If the data in the event structure is important to an action, it is usually better to write the action 
so that it is called in response to only one type of event If you want the same code called for 
two event types, then you would do better to create two separate translations and two separate 
actions that each call a common routine. However, it is sometimes more convenient to have an 
action called by two different events. The example below shows the ToggleCell action 
from the BitmapEdit widget, developed in Volume Four, X Toolkit Intrinsics Programming 
Manual, which is called in response to either MotionNotify or ButtonPress events. 
This action inverts a pixel in the bitmap either if the pointer is clicked on a cell in the widget, 
or if it is dragged across the cell with the pointer buttons held down. 

static void 
ToggleCell (w, event) 
BitmapEditWidget w; 
XEvent *event; 
{ 

static int oldx = -1, oldy = -1; 

GC gc; 

int mode ; 

int newx, newy; 

if (event->type == ButtonPress) { 

newx = (w->bitmapEdit .cur_x + ((XButtonEvent *) event )->x) / 
w->bitmapEdit .cell_size_in_pixels; 

newy = (w->bitmapEdit .cur_y + ((XButtonEvent *)event)->y) / 
w->bitmapEdit.cell_size_in_pixels; 

} 

else if (event->type == MotionNotify) { 

newx = (w->bitmapEdit.cur_x + ( (XMotionEvent *)event)->x) / 
w->bitmapEdit .cell_size_in_pixels; 



X Toolkit Intrinsics Reference Manual 271 



Xt ActionProc (continued) Xt - Translations and Actions 

newy = (w->bitmapEdit .cur_y + ( (XMotionEvent *)event)->y) / 
w->bitmapEdit .cell_size_in_pixels; 
} 
else 

XtWarningC 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 structures are the same, 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 



-Xt- Geometry Management XtAlmOStPrOC 

Name 

XtAlmostProc prototype set_yalues_almost method. 
Synopsis 

typedef void (*XtAlmostProc) (Widget, Widget, Xt Widget Geometry *, 

XtWidget Geometry *) ; 
Widget w; 

Widget new_widget_return; 
XtWidget Geometry * request; 
XtWidgetGeometry * reply; 

Arguments 

w Specifies the widget for which the geometry change is requested. 

new_widget_return 

Specifies the new widget into which the geometry changes are to be stored. 

request Specifies the original geometry request that was sent to the geometry man 

ager that returned XtGeometryAlmost. 

reply Specifies the compromise geometry that was returned by the geometry man 

ager that returned XtGeometryAlmost. 

Description 

The purpose of an XtAlmostProc is to negotiate geometry requests. The 
set_values_almost procedure pointer in a widget class is of type XtAlmostProc. 

A widget s set_values_almost method is called when a client tries to set a widget s 
geometry by means of a call to xtSetValues and the geometry manager cannot satisfy the 
request but instead returns XtGeometryAlmost and a compromise geometry. The 
set_values_almost method takes the original geometry and the compromise geometry 
and determines whether the compromise is acceptable or a different compromise might work. 
It returns its results in the new_widget_return parameter, which is then sent back to the 
geometry manager for another try. 

Most classes inherit this operation from their superclass by specifying Xt Inherit Set - 
ValuesAlmost in the class initialization. The Core set_values_almost method always 
accepts the compromise suggested. 

See Chapter 11, Geometry Management, in Volume Four, X Toolkit Intrinsics Programming 
Manual. 

Structures 

The XtWidgetGeometry structure is similar to but not identical to the corresponding Xlib 
structure: 

typedef unsigned long XtGeometryMask; 

typedef struct { 

XtGeometryMask request_mode; 



X Toolkit Intrinsics Reference Manual 273 



XtAlmostProc (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 <Xll/X.h>: 

#define CWX 

tdefine CWY 

#define CWWidth 

fdefine CWHeight 

#define CWBorderWidth 

#define CWSibling 

#define CWStackMode 

The Xt Intrinsics also support the following value: 

tdefine XtCWQueryOnly (17) 

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 XConf igureWindow 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 

tdefine Below 1 

#define Toplf 2 

#define Bottomlf 3 

#define Opposite 4 

The Intrinsics also support the following value: 

#define XtSMDont Change 5 

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

See Also 

Core(3) 



274 X Toolkit Intrinsics Reference Manual 



Xt - Resource Management- 



J XtArgsFunc 



Name 

XtArgsFunc prototype set_values_hook method. 

Synopsis 

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

Arguments 

*r Specifies the widget whose nonwidget resource values are to be changed. 

args Specifies the argument list that was passed to xtCreateWidget. 

num_args Specifies the number of arguments in the argument list. 

Description 

An XtArgsFunc procedure returns a Boolean indicating whether, based on the values passed 
in args, 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 still 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 



Xt ArgsFunc (continued) Xt - Resource Management 

See Also 

Section 1.7, "Resources," 

XtCreateWidget, XtSetSubvalues, XtSetValues, 
Core(3). 



276 X Toolkit Intrinsics Reference Manual 



Xt - Resource Management- 



J 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 

v Specifies the widget whose nonwidget resource values are to be retrieved. 

args Specifies the argument list that was passed to xtCreateWidget. 

num_args 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 type 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 still 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 




XtArgsPrOG (continued) Xt - Resource Management 



XtGetSubvalues ( (caddr_t) src, 

sourceRe sources, 

XtNumber (sourceResources) , 

args, 

*num_args) ; 



See Also 

Section 1.7, "Resources," 

XtCreateWidget, XtGetSubvalues, XtGetValues, 
Core(3). 



278 X Toolkit Intrinsic* Reference Manual 



Xt- Callbacks 



J XtCallbackProc 



Name 

XtCallbackProc prototype callback procedure. 

Synopsis 

typedef void (*XtCallbackProc) (Widget, caddr_t, caddr_t) ; 
Widget w; 

caddr_t client_data; 
caddr_t call_data; 

Arguments 

w Specifies the widget for which the callback is registered. 

client_data Specifies the data that the widget should pass to the client s procedure when 
the widget performs the callback. 

call_data Specifies callback-specific data that the widget passes to the client. 

Description 

Generally speaking, a widget expecting to interact with an application will declare one or more 
callback lists as resources; the application adds functions to these callback lists, which will be 
invoked whenever the predefined callback conditions are met Callback lists are resources, so 
that the application can set or change the function that will be invoked. 

Callbacks are not necessarily invoked in response to any event; a widget can call the specified 
routines at any arbitrary point in its code, whenever it wants to provide a "hook" for application 
interaction. For example, all widgets provide an xtNdestroyCallback resource to allow 
applications to interpose a routine to be executed when the widget is destroyed. 

Whenever a client wants to pass a callback list as an argument in an xtCreateWidget, Xt- 
SetValues, or xtGetValues call, it should specify the address of a NULL-terminated array 
of type xtCallbackList (see the Structures section below). Callback procedure fields for 
use in callback lists are of type XtCallbackProc. 

When a callback procedure, or list of callback procedures, is passed as a resource argument, Xt 
constructs an internal data structure for the callback list. Subsequently, callback lists must be 
referred to with strings representing the name of the resource in the widget Because Xt doesn t 
support a string to Callback resource converter, callbacks cannot be specified in resource files. 
The internal form can only be accessed by the Intrinsics functions xtAddCallbacks, xt- 
DeleteCallbacks, XtCallCallbacks, etc. Furthermore, since callback lists are han 
dled specifically by the Intrinsics, widget procedures should not allocate memory for callback 
lists passed as resources. Unlike other resources, a widget s initialize method should not 
attempt to make copies of resources of type xtRCallback. 



X Toolkit Intrinsics Reference Manual 279 



XtCallbackPrOG (continued) Xt- Callbacks 

An xtCallbackProc takes three arguments: 

The first argument is the widget that triggered the callback, as specified as the first argu 
ment in xtAddCallback. You would use the value of this argument in your callback 
function if you registered the same function as a callback for two different widgets, and 
if you wanted to distinguish in the callback which widget called it 

The second argument, client_data, is the value passed as the last argument of Xt 
AddCallback. client_data provides a way for the client registering the callback 
also to register client-specific data (for example, a pointer to additional information 
about the widget, a reason for invoking the callback, and so on). client_data should 
be NULL if all necessary information is in the widget 

The third argument call_data, is a piece of data passed from the widget Some 
classes of widget set this argument but others do not The documentation for the widget 
will specify the contents of this data if it is used. The Athena Command widget doesn t 
provide any call_data, but the Athena Scroll widget, for example, passes back the 
current position of the thumb. 

call_data is a convenience to avoid having simple cases where the client could otherwise 
call Xt Get Values or a widget-specific function to retrieve data from the widget Widgets 
should generally avoid putting complex state information in call_data. The client can use 
the more general data retrieval methods, if necessary. 

Structures 

typedef struct { 

XtCallbackProc callback; 
caddr_t closure; 
} XtCallbackRec, *XtCallbackList; 

For example, the callback list for procedures A and B with client data clientDataA and 
clientDataB, respectively, is: 

static XtCallbackRec callbacks [] = { 
{A, (caddr_t) clientDataA}, 
{B, (caddr_t) clientDataB}, 
{(XtCallbackProc) NULL, (caddr_t) NULL} 



See Also 

Section 1.3, "Application Interface," 

XtAddCallback, XtAddCallbacks, XtCallCallbacks, XtCreateWidget, Xt- 
GetValues, XtHasCallbacks, XtRemoveCallback, XtRemoveCallbacks, Xt- 
SetValues. 



280 X Toolkit Intrinsics Reference Manual 



-X,-Keyboard Hand.lng / XtCaSePrOC 

Name 

XtCaseProc prototype procedure called to convert the case of keysyms. 

Synopsis 

typedef void (*XtCaseProc) (KeySym * , KeySym *, KeySym *) ; 
KeySym *keysym; 
KeySym *lower_return; 
KeySym *upper_return; 

Arguments 

keysym Specifies the keysym to convert. 

1 o wer_ret urn Specifies the lower-case equivalent for the keysym. 
upper_return 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) | | 

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

(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 28 1 



XtCasePrOG (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, Xt Trans lateKeycode. 



282 X Toolkit Intrinsics Reference Manual 



Xt- Selections- 



XtConvertSelectionProc 



Name 



XtConvertSelectionProc prototype procedure to return selection data. 
Synopsis 

typedef Boolean (*XtConvert Select ionProc) (Widget, Atom *, Atom 

*, Atom * , caddr_t *, unsigned long *, int *) ; 
Widget w; 
Atom * selection; 
Atom * target; 
Atom * type_ return ; 
caddr_t *value_return; 
unsigned long *length_return; 
int * format return; 



Arguments 

vr 



selection 



target 



type_ return 



value return 



Specifies the widget that currently owns this selection. 

Specifies the atom that describes the type of selection requested (for 
example, XA_PRIMARY or XA_SECONDARY). 

Specifies the target type of the selection that has been requested, which 
indicates the desired information about the selection (for example, File 
Name, Text, Window). 

Specifies a pointer to an atom into which the property type of the con 
verted value of the selection is to be stored. For instance, either file name 
or text might have the property type XA_STRING. 

Specifies a pointer into which a pointer to the converted value of the 
selection is to be stored. The selection owner is responsible for allocating 
this storage. If the selection owner has provided an xt Select ion- 
DoneProc for the selection, this storage is owned by the selection 
owner; otherwise, it is owned by the Intrinsics selection mechanism, 
which frees it by calling xtFree when it is done with it 

length_return Specifies a pointer into which the number of elements in value (each of 
size indicated by format) is to be stored. 

f ormat_return Specifies a pointer into which the size in bits of the data elements of the 
selection value is to be stored. 

Description 

Arbitrary widgets (possibly not all in the same application) can communicate with each other 
by means of the Toolkit global selection mechanism, which is defined in the Inter-Client Com 
munications Manual (see Volume Two, Xlib Reference Manual). The Intrinsics provide func 
tions for providing and receiving selection data in one logical piece (atomic transfers). The 
actual transfer between the selection owner and the Intrinsics is not required to be atomic; the 
Intrinsics will break a too-large selection into smaller pieces for transport if necessary. 



X Toolkit Intrinsics Reference Manual 



283 



XtConvertSelectionProc (continued) Xt - Selections 

The Intrinsics 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 target 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 <Xll/Xatom.h>. Those that are not (for example, TARGETS) 
must be interned explicitly as Atoms by calling the Xlib function XlnternAtom. 

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 Intrinsics 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 * select ion; 
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* target?; 

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 + 1) ) ; 

target? = * (Atom**) value_return; 

*length_return = std_length + 1; 

*targetP++ = w->bitmapEdit . target_atom; 



284 X Toolkit Intrinsics Reference Manual 



Xt - Selections (continued) XtConvertSeleCtlOflProC 

bcopy ( (char*) std_targets, (char*) target? , 

sizeof (Atom) *std_length) ; 
XtFree ( (char*) std_targets) ; 
*type_return = XA_ATOM; 
*format_return = sizeof (Atom) * 8; 
ret urn (TRUE) ; 
} 

/* Xt already handles MULTIPLE, no branch needed */ 

/* Handle expected selection target */ 

else if (*target == w->bitmapEdit . target_atom) { 

/* code shown and described in Volume 4, Chapter 10 */ 



else { 

/* Handle other standard targets defined by Xmu */ 

if (XmuConvertStandardSelection(w, CurrentTime, 

selection, tarrget, type_return, 
value_return, length_return, 

format_return) ) 

return TRUE; 

else { 

fprintf (stderr, 

"bitmapEdit : requestor is requesting", 
"unsupported selection target type.Xn"); 

return (FALSE) ; 



Overall, this code handles the TARGETS atom in the first branch, the expected selection target 
in the second, and any remaining standard atoms and any unknown atoms as two cases in the 
third branch. For ICCCM-compliant code, you can copy this entire function into your widget 
and then write just the second branch. Note that branches that successfully provide the 
requested data return TRUE, and ones that don t return FALSE. The ICCCM also specifies that 
functions implementing selections must be able to respond to a MULTIPLE target value, which 
is used to handle selections too large to fit into a single property. However, the necessary hand 
ling is done by the Intrinsics. Your procedures do not need to worry about responding to the 
MULTIPLE target value; a selection request with this target type will be transparently 
transformed into a series of smaller transfers. 

In the first branch you will also need to change the reference to the instance part field that 
stores the target atom used for selections, bitmapEdit . target_atom. If your widget uses 
a predefined atom or one supported by the Xmu facility, you would reference that atom here 
instead of the instance part field. If you called xinternAtom in initialize and stored 
the result in an instance part field, you specify that here. 



X Toolkit Intrinsics Reference Manual 285 



XtConverter \ xt _ Resource Management _ 

Name 

XtConverter prototype of a resource converter procedure. 

Synopsis 

typedef void (*XtConverter) (XrmValue *, Cardinal *, XrmValue *, 

XrmValue *) ; 
XrmValue *args; 
Cardinal *num_args; 
XrmValue *from; 
XrmValue *to; 

Arguments 

args Specifies a list of additional XrmValue arguments to the converter if addi 

tional context is needed to perform the conversion, or specifies NULL. For 
example, a string-to-font converter needs the widget s screen, or a 
string-to-pixel converter needs the widget s screen and colormap. 

num_args Specifies the number of additional XrmValue arguments, or specifies zero. 

from Specifies the value to convert. 

t o Specifies the descriptor to use to return the converted value. 

Description 

The Intrinsics provide a mechanism for registering converters that are automatically invoked by 
the resource-fetching routines. The Intrinsics additionally provide and register several com 
monly used converters. This resource conversion mechanism serves several purposes: 

It permits user and application resource files to contain ASCII representations of non 
textual values. 

It allows textual or other representations of default resource values that are dependent on 
the display, screen, or colormap and thus must be computed at run time. 

It caches all conversion source and result data. Conversions that require much computa 
tion or space (for example, string to translation table) or that require round trips to the 
server (for example, string to font or color) are performed only once. 

The Intrinsics define all the representations used in the Core, Composite, Constraint, and Shell 
widgets. The following resource converters are registered with the Intrinsics: 

From XtRString to: 

XtRAcceleratorTable, XtRBoolean, XtRBool, XtRCursor, XtRDimension, 
XtRDisplay, XtRFile, XtRFloat, XtRFont, XtRFontStruct, XtRInt, Xt- 
RPixel, XtRPosition, XtRShort, XtRTranslationTable, and Xt- 
RUnsignedChar. 



286 X Toolkit Intrinsics Reference Manual 



Xt- Resource Management (continued) XtConverter 

From XtRColor to: 

XtRPixel. 
From XRlnt to: 

XtRBoolean, XtRBool, XtRColor, XtRDimension, XtRFloat, XtRFont, Xt 
RPixel, XtRPixmap, XtRPosition, XtRShort, and XtRUnsignedChar. 

From XtRPixel to: 

XtRColor. 

The string-to-pixel conversion has two predefined constants that are guaranteed to work and 
contrast with each other and with xtDef aultBackground. They evaluate the black and 
white pixel values of the widget s screen, respectively. For applications that run with reverse 
video, however, they evaluate the white and black pixel values of the widget s screen, respec 
tively. Similarly, the string to font and font structure converters recognize the constant Xt 
Def aultFont and evaluate this to the font in the screen s default graphics context. 

Type converters use pointers to XrmValue structures (defined in <XlllXresource.h>) for input 
and output values. 

typedef struct { 

unsigned int size; 

caddr_t addr; 
} XrmValue, *XrmValuePtr; 

A resource converter procedure pointer is of type XtConverter. 
Type converters should perform the following actions: 

Check to see that the number of arguments passed is correct. 
Attempt the type conversion. 

If successful, return a pointer to the data in the to parameter; otherwise, call xt- 

WarningMsg and return without modifying to. 

Most type converters just take the data described by the specified from argument and return 
data by writing into the specified to argument. A few need other information, which is avail 
able in the specified argument list. 

A type converter can invoke another type converter, which allows differing sources that may 
convert into a common intermediate result to make maximum use of the type converter cache. 

Note that the address written in to->addr cannot be that of a local variable of the converter 
because this is not valid after the converter returns. It should be a pointer to a static variable, as 
in the example below in which screenColor is returned. 

All type converters should define some set of conversion values that they are guaranteed to suc 
ceed on so these can be used in the resource defaults. This might be problematic with particu 
lar conversions, such as fonts and colors, where there is no string representation that all server 
implementations will necessarily recognize. For resources like these, the converter should 



X Toolkit Intrinsics Reference Manual 



XtCon verier (continued) Xt - Resource Management 

define a symbolic constant (for example, XtDefaultForeground, xtDefault- 
Background, or XtDef aultFont ) . 

The following example shows a converter that takes a string and converts it to a pixel value: 

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 = 1; 

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 [ 1] .addr) ; 

LowerCase ( (char *) f romVal->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) f romVal->addr [0] == # ){ /* some color rgb definition */ 

status = XParseColor (DisplayOf Screen (screen) , colormap, 

(String) f romVal->addr, SscreenColor) ; 
if (status != 0) status = XAllocColor (DisplayOf Screen 

(screen) , colormap, SscreenColor) ; 

} else /* some color name */ 

status = XAllocNamedColor (DisplayOf Screen (screen) , colormap, 
(String) f romVal->addr, &screenColor, sexactColor) ; 

if (status == 0) { 

params [0]= (String) f romVal->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," 

XtAppAddConverter, XtConvert, XtDirectConvert, XtStringConversion- 
Warning. 



X Toolkit Intrinsics Reference Manual 



289 



XtErrorHandler \ _ Vl 

N -- Xt- Error Handling 

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 (1) ; 
} 

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 



_ u ... J XtErrorMsgHandler 

Xt - Error Handling 

Name 

XtErrorMsgHandler prototype for high-level error and warning handlers. 

Synopsis 

typedef void (*XtErrorMsgHandler) (String, String, String, 

String, String *, Cardinal *) ; 
String name; 
String type; 
String class; 
String defaultp; 
String * pa rams; 
Cardinal *num_params; 

Arguments 

name Specifies the name that is concatenated with the specified type to form the 

resource name of the error message. 

type Specifies the type that is concatenated with the name to form the resource 

name of the error message. 

class Specifies the resource class of the error message. 

defaul tp Specifies the default message to use if no error database entry is found. 

pa rams Specifies a pointer to a list of values to be substituted in the message. 

numjparams Specifies the number of values in the parameter list. 

Description 

Application-supplied error handling functions, for both warnings and fatal errors, are of type 
XtErrorMsgHandler. 

The specified name can be a general kind of error, like invalidParameters or invalid- 
window, and the specified type gives extra information. Standard print f 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 Xt Warning, 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 retrieve the message from the database. 

The example below shows the default error message handler from the MIT R3 Intrinsics. 

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



X Toolkit Intrinsics Reference Manual 29 1 



XtErrorMsgHandler (continued) Xt - Error Handling 

char buffer [1000] , message [1000] ; 

XtGetErrorDatabaseText (name, type, class, defaultp, buffer, 1000) ; 

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 Intrinsics Reference Manual 



f XtEventHandler 

Xt - Event Handling 

Name 

XtEventHandler prototype procedure to handle input events. 

Synopsis 

typedef void (*XtEventHandler) (Widget, caddr_t, XEvent *) ; 
Widget w; 

caddr_t client_data; 
XEvent * event; 

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. 

event 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; 



293 
X Toolkit Intrinsics Reference Manual 



XtEventHandler (continued) Xt- Event Hand ling 

caddr_t unused;/* client_data */ 
{ 

if (event->type == Focusln) 
/* process Focusln */ 



else { 
/* process FocusOut */ 



See Also 

Section 1.4, "Events," Section 1.5, Translations and Actions, 

XtAddEventHandler. 



294 X Toolkit Intrinsics Reference Manual 



Xt- Methods- 



J XtExposeProc 



Name 

XtExposeProc prototype expose method used in Core widget class. 

Synopsis 

typedef void (*XtExposeProc) (Widget, XEvent *, Region) ; 
Widget w; 
XEvent * event; 
Region region; 

Arguments 

w Specifies the widget instance requiring redisplay. 

event Specifies the exposure event giving the rectangle requiring redisplay. 

regi on Specifies the union of all rectangles in this exposure sequence. 

Description 

The expose method is responsible for initially drawing into a widget s window and for 
redrawing the window every time a part of the window becomes exposed. This redrawing is 
necessary because the X server does not maintain the contents of windows when they are 
obscured. When a window becomes visible again, it must be redrawn. 

The expose method usually needs to modify its drawing based on the geometry of the window 
and other instance variables set in other methods. For example, the Label widget will left- 
justify, center, or right-justify its text according to the xtNjustify resource, and the actual 
position to draw the text depends on the widget s current size. 

Another factor to consider when writing the expose method is that many widgets also draw 
from action routines, in response to user events. For example, BitmapEdit toggle bitmap cells 
in action routines. The expose method must be capable of redrawing the current state of the 
widget at any time. This means that action routines usually set instance variables when they 
draw so that the expose method can read these instance variables and draw the right thing. 

BitmapEdit uses a slightly unusual exposure handling strategy. Most widgets keep track of 
what they draw in some form of arrays or display lists. When they need to redraw, they simply 
replay the saved drawing commands in the original order to redraw the window. For example, 
BitmapEdit keeps track of the state of each bitmap cell in a character array. It could easily tra 
verse this array and redraw each cell that is set in the array. 

However, BitmapEdit does not use this strategy. In order to improve its scrolling performance, 
the expose method copies an off-screen pixmap into the window whenever redisplay is 
required. The actions draw into this off-screen pixmap, and then call the expose method 
directly to have the pixmap copied to the window. 

The expose method is passed an event that contains the bounding box of the area exposed. To 
achieve maximum performance it copies only this area from the pixmap to the window. The 



X Toolkit Intrinsics Reference Manual 295 



Xt ExposeProc (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 Intrinsics 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 = 0; 

y = 0; 

width = cw->bitmapEdit .pixmap_width_in_pixels; 
height = cw->bitmapEdit .pixmap_height_in_pixels; 
} 

if (Def aultDepthOf Screen (XtScreen (cw) ) == 1) 
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 .bigjpicture, 
XtWindow(cw) , 

cw->bitmapEdit .copy_gc, x + cw->bitmapEdit .cur_x, y + 
cw->bitmapEdit .cur_y, width, height, x, y, 1) ; 

} 

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 Intrinsics Reference Manual 



Xt - Methods (continued) Xt Expose Proc 

If the compress_exposures field of the class structure is initialized to TRUE, as it is in 
BitmapEdit, Xt automatically merges the multiple Expose events that may occur because of a 
single user action into one Expose event In this case, the Expose event contains the bound 
ing box of the areas exposed. BitmapEdit redraws everything in this bounding box. For widg 
ets that are very time-consuming to redraw, you might want to use the third argument of the 
expose method, which is a region. The Region type is opaquely defined by Xlib (internally 
a linked list of rectangles). The Region passed into expose describes the union of all the 
areas exposed by a user action. You can use this region to clip output to the exposed region, 
and possibly calculate which drawing primitives affect this area. Xlib provides region mathe 
matics routines (such as XRectlnRegion) to compare the regions in which your widget 
needs to draw with the region needing redrawing. If certain areas do not require redrawing, 
you can skip the code that redraws them, thereby saving valuable time. However, if this calcu 
lation is complicated, its cost/benefit ratio should be examined. 

Each of these exposure handling techniques may be the best for certain widgets. For a widget 
like BitmapEdit, any of the three methods will work, but the bounding box method is the most 
efficient and convenient. For a complete description of Expose event handling strategies, see 
Chapter 8, Events, in Volume One, Xlib Programming Manual. 

The remainder of BitmapEdit s expose method shown in the example above consists of a 
single Xlib call to copy from a pixmap into the widget s window. As described in Chapter 4, 
An Example Application, in Volume Four, X Toolkit Intrinsics Programming Manual, Bitmap- 
Edit makes a large pixmap that is one plane deep and draws the current bitmap into it When 
needed in the expose method, this pixmap just has to be copied into the window. This 
approach was chosen for its simplicity. When scrollbars are added, the widget is able to pan 
around in the large bitmap quickly and efficiently. Note that one of two Xlib routines is called 
based on the depth of the screen. This is because XCopyArea is slightly more efficient than 
XCopyPlane and should be used when running on a monochrome screen. 

Note that instance variables are used for the arguments of the Xlib routines in the example 
above. Don t worry about exactly what each Xlib routine does or the meaning of each argu 
ment See the reference page for each routine in Volume Two, Xlib Reference Manual when 
you need to call them in your code. 

See Chapters 5, 6, and 7 in Volume One, Xlib Programming Manual, for more information on 
the GC, drawing graphics, and color, respectively. 

Structures 

The definition of a region is given in <Xll/Xutil.h>: 

typedef struct _XRegion *Region; 

This is an opaque definition pointing to a file in the library source file XllRSIliblXIregion.h. 
(X11R3 is the name of the directory where the XI 1 source is rooted.) 



X Toolkit Intrinsics Reference Manual 297 



Xt ExposeProc (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 



v _ . . / XtGeometryHandler 

Xt - Geometry Management * 

Name 

XtGeometryHandler prototype procedure to handle geometry requests. 

Synopsis 

typedef XtGeometryResult (*XtGeometryHandler) (Widget, XtWidget- 

Geometry * r XtWidgetGeometry *) / 
Widget w; 

XtWidgetGeometry * request ; 
XtWidgetGeometry *geometry_return; 

Arguments 

w Specifies the widget that is making the request 

request Specifies the desired widget geometry (size, position, border width, and 

stacking order.) 

ge ome t ry_re turn 

Returns the allowed widget size or may be null if the requesting widget is not 
interested in handling xtGeometryAlmost. 

Description 

Procedures of type XtGeometryHandler are used to negotiate geometry requests. 

The Core query_geometry method and the Composite geometry_manager method are 
both of type XtGeometryHandler. See Composite(3) for additional details. 

The query_geometry procedure pointer is of type XtGeometryHandler: 

typedef XtGeometryResult (*XtGeometryHandler) (Widget, XtWidgetGeometry *,\ 

XtWidgetGeometry *) ; 
Widget w; 

XtWidgetGeometry *request; 
XtWidgetGeometry * geometry_return; 

The query_geometry 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 about). If the proposed geometry change is 
acceptable without modification, the query_geometry procedure should return Xt- 
Geomet ryYes. If at least one field in geometry_ret urn 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 geome 
try is identical to the current geometry, the query_geometry procedure should return Xt- 
GeometryNo. 

Structures 

The return codes from geometry managers are: 



X Toolkit Intrinsics Reference Manual 299 



XtGeometry Handler (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 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 

#define CWY 

tdefine CWWidth 

#define CWHeight 

#define CWBorderWidth 

#define CWSibling 

#define CWStackMode 

The Xt Intrinsics also support the following value: 

#define XtCWQueryOnly (17) 

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 XConf igureWindow 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 

#define Below 1 

#define Top If 2 

#define Bottomlf 3 

tdefine Opposite 4 

The Intrinsics also support the following value: 

#define XtSMDontChange 5 



300 X Toolkit Intrinsics Reference Manual 



Xt - Geometry Management (continued) XtGeometry Handler 

For precise definitions of Above, Below, Toplf , Bottomlf , and Opposite, see the refer 
ence page for XConf igurewindow 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 Intrinsics Programming Manual. 



X Toolkit Intrinsics Reference Manual 30 1 



XtlnitProc A 



Xt- Methods 



Name 

XtlnitProc prototype initialize procedure for a widget class. 

Synopsis 

typedef void (*XtInitProc) (request, new) ; 
Widget request , new; 

Arguments 

request Specifies the widget with resource values as requested by the argument list, 

the resource database, and the widget defaults. 

new Specifies a widget with the new values, both resource and nonresource, as 

modified by the initialize procedure. 

Description 

An initialization procedure performs the following: 

Allocates space for and copies any resources that are referenced by address. For 
example, if a widget has a field that is a String, it cannot depend on the characters at 
that address remaining constant but must dynamically allocate space for the string and 
copy it to the new space. (Note that you should not allocate space for or copy callback 
lists.) 

Computes values for unspecified resource fields. For example, if width and height are 
zero, the widget should compute an appropriate width and height based on other 
resources. This is the only time that a widget should ever directly assign its own width 
and height 

Computes values for uninitialized nonresource fields that are derived from resource 
fields. For example, graphics contexts (GCs) that the widget uses are derived from 
resources like background, foreground, and font. 

An initialization procedure also can check certain fields for internal consistency. For example, 
it makes no sense to specify a color map for a depth that does not support that color map. 

Initialization procedures are called in superclass-to-subclass order. Most of the initialization 
code for a specific widget class deals with fields defined in that class and not with fields defined 
in its superclasses. 

If a subclass does not need an initialization procedure because it does not need to perform any 
of the above operations, it can specify NULL for the initialize field in the class record. 

Sometimes a subclass may want to overwrite values filled in by its superclass. In particular, 
size calculations of a superclass are often incorrect for a subclass and in this case, the subclass 
must modify or recalculate fields declared and computed by its superclass. 

As an example, a subclass can visually surround its superclass display. In this case, the width 
and height calculated by the superclass initialize procedure are too small and need to be incre 
mented by the size of the surround The subclass needs to know if its superclass size was calcu 
lated by the superclass or was specified explicitly. All widgets must place themselves into 



302 X Toolkit Intrinsics Reference Manual 



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 Hand ling 



Name 

XtlnputCallbackProc prototype procedure called to handle file events. 

Synopsis 

typedef void (*XtInputCallbackProc) (caddr_t, int *, Xt Input Id *) ; 
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- 
Addlnput. 

source Specifies the source file descriptor generating the event. 

id Specifies the ID returned from the corresponding xtAppAddlnput call. 

Description 

An XtlnputCallbackProc is registered by calling XtAddlnput or XtAppAddlnput. 
id is the return value from the procedure that registered it. 

An XtlnputCallbackProc 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 XtlnputCallbackProc named get_f ile_input together 
with the application used to register it 

/* header files */ 



/* ARGSUSED */ 

get_file_input (client_data, fid, id) 

caddr_t client_data; /* unused */ 

int *fid; 

Xtlnputld *id; 

char buf [BUFSIZ] ; 
int nbytes; 
int i; 

if ((nbytes = read(*fid, buf, BUFSIZ)) == -I) 
perror ("get_ f ile_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 = Xtlnitialize (argv [0] , "XFilelnput", NULL, 
0, &argc, argv) ; 

if (argv[l] == NULL) { 

fprintf (stderr, "xfileinput: filename must be specified on\ 

command line.Xn"); 
exit ( 1 ) ; 
} 
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 */ 
XtAddlnput (fileno(fid) , XtlnputReadMask, get_f ile_input, NULL); 

XtRealizeWidget (topLevel) ; 
XtMainLoop ( ) ; 



See Also 

XtAddlnput, XtApp Add Input. 



Xt Intrinsics Reference Manual 305 



XtKeyProc \ 



Xt- Keyboard Handling- 



Name 

XtKeyProc prototype procedure to translate a key. 

Synopsis 

typedef void (*XtKeyProc) (Display * r KeyCode *, Modifiers *, 
Modifiers *, KeySym *) ; 

Display *display; 

KeyCode * key code; 

Modifiers * modifiers; 

Modifiers *modifiers_return; 

KeySym *keysym_return; 

Arguments 

di spl ay Specifies the display from which to translate the events. 

keycode Specifies the keycode that is to be translated. 

modifiers Specifies the mask that indicates what modifier keys (Shift, Meta, Control, 
etc.) are pressed. 

modi fi ers_return 

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

k eysym_ 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- 

KeyProc. 

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 translator 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 > 1) 

306 Xt Intrinsics Reference Manual 



Xt - Keyboard Handling (continued) XtKey Proc 

nbd = (dpy->max_keycode - dpy->min_keycode + 1) 

* 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 < M 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, 

modif iers_return, keysym_return) 
Display *dpy; 
KeyCode keycode; 
Modifiers modifiers; 
Modifiers *modif iers_return; 
KeySym * key sym_re turn; 

{ 

XtPerDisplay perDisplay; 
perDisplay = _XtGetPerDisplay (dpy) ; 
*modifiers_return = StandardMask; 
if ((modifiers & StandardMask) == 0) 

*keysym_return =_XtKeyCodeToKeySym (dpy, perDisplay, keycode, 0) ; 
else if ((modifiers & (ShiftMask I LockMask) ) != 0) 

*keysym_return =_XtKeyCodeToKeySym (dpy, perDisplay, keycode, 1) ; 
else 

*keysym_return = NoSymbol; 



Xt Intrinsics 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: 

Shif tMask Shift key was depressed. 

LockMask Caps Lock key was depressed. 

Cont rolMask Control key was depressed. 

ModlMask Key defined as Modi was depressed. 



ModSMa s k 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 Intrinsics Programming Manual. 

See Also 

XtSetKeyTranslator, XtTranslateKeycode, XtTranslateKey. 



3Q8 Xt Intrinsics Reference Manual 



Xt -Selections- 



J XtLoseSelectionProc 



Name 

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

Synopsis 

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

Arguments 

w Specifies the widget that has lost selection ownership. 

selection 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, XtGetSelectionValues, XtOwnSelection. 



X Toolkit Intrinsics Reference Manual 309 



XtOrderProc 

-Xt - Geometry Management 

Name 

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

Synopsis 

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

Arguments 

w 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 insert_jposition method in a composite widget instance is of type XtOrderProc. 

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_jposit ion 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. 



310 X Toolkit Intrinsics Reference Manual 



Xt- Methods- 



f 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 Intrinsics Reference Manual 3 1 1 



XtRealizeProc A 

v Xt - Methods- 
Name 

XtRealizeProc prototype procedure called when widget is realized. 

Synopsis 

typedef void (*XtRealizeProc) (Widget, XtValueMask, XSetWindow- 

Attributes *) ; 
Widget w; 

XtValueMask value_mask; 
XSetWindowAttributes *at tributes; 

Arguments 

w Specifies the widget 

val ue_mask Specifies which fields in the attributes structure to use. 
attributes Specifies the window attributes to use in the XCreateWindow call. 

Description 

The Intrinsics invoke the Core realize method when the application calls xtRealize- 
widget on the application s top-level widget. 

The Core realize method must create the widget s window. The value mask indicates what 
values in the XSetWindowAttributes structure are used. 

The generic xtRealizeWidget function fills in a mask and a corresponding XSet 
WindowAttributes structure. It sets the following fields based on information in the 
widget Core structure: 

The background_jpixmap (or background_jpixel if background_jpixmap is 
NULL) is filled in from the corresponding field. 

The border_jpixmap (or border_jpixel if border^pixmap is NULL) is filled in 
from the corresponding field. 

The event_mask is filled in based on the event handlers registered, the event transla 
tions specified, whether expose is non-NULL, and whether visible_interest is 

TRUE. 

The bit_gravity is set to NorthWestGravity if the expose field is NULL. 

The do_not_jpropagate_mask is set to propagate all pointer and keyboard events up 
the window tree. A composite widget can implement functionality caused by an event 
anywhere inside it (including on top of children widgets) as long as children do not spec 
ify a translation for the event 

All other fields in attributes (and the corresponding bits in value_mask) can be set by the 
realize method. 

Note that because realize is not a chained operation, the widget class realize method 
must update the XSetWindowAttributes structure with all the appropriate fields from 
non-Core superclasses. 



312 X Toolkit Intrinsics Reference Manual 



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 value and then create the window. For example, depending on its justi 
fication, Label sets bit_gravity to WestGravity, CenterGravity, or East- 
Gravity. Consequently, shrinking 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 realize 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," 

XtCreateWindow, XtRealizeWidget, 
Core(3). 



X Toolkit Intrinsics Reference Manual 



313 



XtResourceDefaultProc 

Xt - Resource Management 

Name 

XtResourceDefaultProc prototype procedure passed as a resource converter of type xt- 

RCallProc. 

Synopsis 

typedef void (*XtResourceDef aultProc) (Widget, int, XrmValue *) 
Widget w; 
int offset ; 
XrmValue * value; 

Arguments 

w Specifies the widget whose resource is to be obtained. 

offset Specifies the offset of the field in the widget record. 

val ue 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 (XtRlmmediate and xtRCallProc) are usable only as 
default resource types. XtRlmmediate indicates that the value in the def ault_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 def ault_address field of the XtResource structure is a procedure variable. This 
procedure is automatically invoked with the widget, resource_of f set, 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 def ault_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 



XtSelectionCallbackProc \ Vl 

v Xt - Selections 

Name 

XtSelectionCallbackProc prototype procedure called when requested selection data arrives. 

Synopsis 

typedef void (*Xt Select ionCallbackProc) (Widget, caddr_t, Atom *, 

Atom * , caddr_t, unsigned long *, int *) ; 
Widget w; 

caddr_t client_data; 
Atom * selection; 
Atom *type; 
caddr_t val ue; 
unsigned long *length; 
int * format; 

Arguments 

w Specifies the widget that requested the selection value. 

client_data Specifies a value passed in by the widget when it requested the selection. 
selection Specifies the type of selection that was requested. 

type Specifies the representation type of the selection value (for example, 

XA_STRING). Note that it is not the target that was requested but the type that 
is used to represent the target. The special X Toolkit atom 
XT_CONVERT_FAIL is used to indicate that the selection conversion failed 
because the selection owner did not respond within the Intrinsics selection 
timeout interval. 

value Specifies a pointer to the selection value. The requesting client owns this 

storage and is responsible for freeing it by calling xtFree when it is done 
with it 

1 ength Specifies the number of elements in value. 

forma t Specifies the size in bits of the data elements of value. 

Description 

This procedure is called by the Intrinsics selection mechanism to deliver the requested selection 
to the requestor. Data transfer proceeds as follows: data is requested from the owner of the 
selection with XtGetSelectionValue or XtGetSelectionValues; when it finally 
arrives, the SelectionCallbackProc is invoked with the actual data. 

Data delivery is done by callback, since the Intrinsics may have to perform multiple server 
requests to get data, and other events may require processing ahead of the data transfer. There 
fore, actual data delivery must occur asynchronously with respect to XtGetSelection 
Value or XtGetSelectionValues. 



316 X Toolkit Intrinsics Reference Manual 



Xt - Selections 



(continued) 



XtSelectionCallbackProc 



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 



XtSelectionDoneProc \ 

v Xt - Selections 

Name 

XtSelectionDoneProc prototype procedure called after a data transfer completes. 

Synopsis 

typedef void (*XtSelectionDoneProc) (Widget, Atom *, Atom *) ; 
Widget v/; 
Atom * select ion; 
Atom * target; 

Arguments 

w Specifies the widget that owns the converted selection. 

select! on Specifies the atom that describes the selection type that was converted, 
target Specifies the target type to which the conversion was done. 

Description 

The Intrinsics call the XtSelectionDoneProc specified in the call to xtGet- 
SelectionValue or xtGetSelectionValues when the data transfer is actually com 
plete. 

If the selection owner has registered an XtSelectionDoneProc, it will be called once for 
each conversion that it performs after the converted value has been successfully transferred to 
the requestor. 

If the selection owner has registered an XtSelectionDoneProc, it also owns the storage 
containing the converted selection value. XtSelectionDoneProc can be used by the 
selection owner to deallocate memory allocated in ConvertSelectionProc. 

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. 



318 X Toolkit Intrinsics Reference Manual 



Xt- Methods- 



J XtSetValuesFunc 



Name 

XtSetValuesFunc prototype procedure for various set_values methods. 

Synopsis 

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

Arguments 

current Specifies a copy of the widget as it was before the xtSetValues call. 

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

new 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 (Constraint) 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 v 

Xt - Methods 

Name 

XtStringProc prototype procedure for display_accelerator method. 

Synopsis 

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

Arguments 

w Specifies the widget instance requiring redisplay. 

string 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 

XtDisplayAccelerator 



320 X Toolkit Intrinsics Reference Manual 



-X- Even, HandHng / XtTimerCallbaCkPfOC 

Name 

XtTimerCallbackProc prototype callback procedure invoked when timeouts expire. 

Synopsis 

typedef void (*XtTimerCallbackProc) (caddr_t, Xtlntervalld *) ; 
caddr_t client_data; 
Xtlntervalld *id; 

Arguments 

client_data Specifies the client data that was registered for this procedure in xtApp- 
AddTimeOut. 

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 

XtAddTimeOut. 

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

See Also 

XtAddTimeOut, XtAppAddTimeOut, 

Chapter 8, More Input Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual. 



X Toolkit Intrinsics Reference Manual 321 



XtWidgetProc 



Xt- Methods- 



Name 

XtWidgetProc common prototype procedure for widget methods. 

Synopsis 

typedef void (*XtWidgetProc) (Widget) ; 
Widget v; 

Arguments 

w Specifies the widget. 

Description 

Several widget methods are of type XtWidgetProc. These include the Core and Constraint 
destroy methods, and the Composite insert_child, delete_child, and 
change_managed methods. 

Since there are no additional arguments, methods of this type must access the widget instance 
data structures. For example, the change_managed method must access the child array from 
the Composite structures in the instance record. 

See Also 

Section 1.1, "Widget Lifecycle, "Section 1.8, "Geometry Management," 
Composite(3), Constraint(3), Core(3). 



322 X Toolkit Intrinsics Reference Manual 






vt D # t D f XtWorkProc 

Xt - Prototype Procedures 

Name 

XtWorkProc perform background processing. 

Synopsis 

typedef Boolean (*XtWorkProc) (caddr_t) ; 
caddr_t client_data; 

Arguments 

client_data Represents the client data specified when the work procedure was registered. 

Description 

A work procedure is an application-supplied function that is executed while an application is 
idle waiting for an event Work procedures are registered with xtAddWorkProc. They can 
perform any calculation that is short enough that the routine will return in a small fraction of a 
second. If the work procedure is too long, the user s response time will suffer. 

If a work procedure returns TRUE, then Xt will remove it and it will not be called again. But if 
one returns FALSE, it will be called repeatedly every time there is idle time, until the applica 
tion calls xtRemoveWorkProc. A work procedure would return TRUE if it performs a one 
time setup such as creating a pop-up widget It would return FALSE if it were continuously 
updating a disk file as security against a system crash or server connection failure. 

You can register multiple work procedures, and they will be performed one at a time. The most 
recent work procedure added has the highest priority. Therefore, for example, if you want to 
create ten pop-up widgets during idle time, you should add ten work procedures. The pop up 
that you expect to need first should be added in the last work procedure registered. 

Work procedures should be judicious about how much processing they consume each time they 
are called. If they run for more than a fraction of a second, an application s interactive 
response time is likely to suffer. 

The example below shows a work procedure to create a pop-up widget 

Widget pshell; 

/* work procedure */ 
Boolean 

create_popup (parent) 
Widget parent; 
{ 

Widget dialog, dialogDone; 

pshell = XtCreatePopupShell ( 
"pshell", 

transient She HWidget Class, 
parent, 
NULL, 


); 
dialog = XtCreateManagedWidget { 



X Toolkit Intrinsics Reference Manual 323 



XtWorkPfOC (continued) Xt - Prototype Procedures 

"dialog",/* widget name */ 

dialogWidgetClass, /* widget class */ 

pshell,/* parent widget*/ 

NULL,/* argument list*/ 

O/* arglist size */ 

); 

dialogDone = XtCreateManagedWidget ( 

"dialogDone", /* widget name */ 

commandWidgetClass, /* widget class */ 

dialog,/* parent widget*/ 

NULL,/* argument list*/ 

O/* arglist size */ 

); 

XtAddCallback (dialogDone, XtNcallback, DialogDone, dialog); 

re turn ( TRUE );/* makes Xt remove this work proc automatically */ 
} 

Remember that Xt cannot interrupt a work procedure while it is running; the procedure must 
voluntarily give up control by returning, and it must do so quickly to avoid slowing user 
response. 

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. 



Xt- Widget Types- 



Core 



Name 

Core Widget Class fundamental, top-level widget 

Synopsis 

#include StringDefs.h 
^include Intrinsic. h 

Description 

The Core widget class is the most fundamental type of widget 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 <XlllCoreP.h>. Volume Four, X 
Toolkit Intrinsics Programming Manual, discusses how Intrinsics 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 <XlllCoreP.h>. 
The ClassPartis 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; /* 

XtlnitProc 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; 



caddr_t extension; 
} CoreClassPart; 



A 



The core instance record is defined as follows: 

typedef struct _CorePart { 

Widget self; /* 

WidgetClass widget_class; /* 

Widget parent; /* 

XrmName xrm_name ; / * 

Boolean being_destroyed; /* 
XtCallbackList destroy_callbacks; 

caddr_t constraints; /* 

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; 



display your accelerator */ 
pointer to extension record */ 



pointer to widget itself */ 
pointer to widget s ClassRec */ 
parent widget */ 

widget resource name quarkified */ 
marked for destroy */ 

/* who to call when widget destroyed */ 
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? */ 



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 Intrinsics 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 



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 being_destroyed value. 

NULL 
NULL 






1 

FALSE 

TRUE 

Bitwise AND of parent s sensitive and ances- 

tor_sensitive. 

Initialized by the Event Manager. 

Initialized by the Resource Manager. 

NULL 

XtDefaultForeground 

NULL 

NULL 



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 



Core (continued) Xt - Widget Types 

Core Methods 

Core methods can often be inherited from a superclass. This is done by specifying xt- 
Inheritprocna/ne in the class field. For example, XtlnheritRealize will inherit the 
realize method. 

initialize 

initialize methods are of type XtlnitProc. initialize is called once for each 
widget instance that is created. A minimum initialize method is shown below. 

static XtlnitProc Initialize (request, new) 

Widget request, new; 

{ 

new->core .height = 100; 

new->core .width = 100; 

} 

request is a copy of the widget instance with resources supplied by the caller, new is the 
widget after it has been initialized by the superclasses of the widget, new will endure beyond 
the initialization as the actual widget instance record, request is a template and will be des 
troyed when initialization is complete; it should not be modified. Using request and new, a 
class can determine whether a value was computed by the superclass or was specified by the 
widget creator explicitly. 

As an example, a subclass can visually surround its superclass display. In this case, the width 
and height calculated by the superclass initialize procedure are too small and need to be 
incremented by the size of the surrounding border. 

At a minimum, the initialize method must compute values for core width and height, if 
they have not been computed by a superclass. This is the only time that a widget should ever 
directly assign its own width and height. 

Additionally, an initialization procedure may perform the following: 

Allocate space and copy the actual value of any resource that is passed by pointer. For 
example, if a widget is passed a pointer to a String, the widget must dynamically allo 
cate space for a new string and copy it the application s copy of the String may not 
remain intact after the call. Note that you should not allocate space for, or copy, callback 
lists. Any resource of type xtRCallback should be treated as opaque. Callback lists 
can be manipulated by specific Intrinsic routines. (See xtAddCallbacks, XtCall- 
Callbacks, XtRemoveCallbacks, etc.) 

Compute values for instance variables and resources. For example, the widget must 
ensure that core width and height are nonzero. 

Compute instance variables that are derived from resources. For example, graphics con 
texts (GCs) that the widget uses are derived from resources like background, foreground, 
and font 

Supersede values in the superclass. Initialization procedures are called in 
superclass-to-subclass order. The main purpose of a subclass may be to change non- 
resource data in a superclass, since the subclass has direct access to the instance record. 



330 X Toolkit Intrinsics Reference Manual 



Xt - Widget Types (continued) Core 

In particular, size calculations of a superclass are often incorrect for a subclass, and the 
subclass must modify or recalculate fields declared and computed by its superclass. 

Check fields for internal consistency. For example, the user may specify a colormap for a 
display depth that cannot support it. 

If a subclass does not need an initialization procedure, it can specify NULL for the initialize field 
in the class record. 

class_part_initialize and classjnitialize 

class_part_initialize and class_initialize are of types XtlnitProc and 
xtProc, respectively. 

class_initialize is called by the Intrinsics only once per program lifetime. It can be 
used to supply aggregate initialization of data. 

It can perform Toolkit operations that are not dependent on a particular widget. For example, it 
can register converters and can cache strings into quarks for speedier subsequent use. 

The class_jpart_initialize procedure is called once per class. For example, suppose a 
widget is part of several other classes. The class initialize will be called for each class record 
that the Intrinsics construct which contain this class. 

Thus, if there are initialization operations dependent on the class record, it can perform those. 
For example, it may set the insert_position method in the composite instance record. 

realize_proc 

The realize method is of type xtRealizeProc. The realize method must create the 
widget s window. A minimum realize method is given below. (See also xtCreate- 
Window.) 

static XtRealizeProc Realize (w, mask, attr) 

GenericWidget w; 

Mask *mask; 

XSetWindowAttributes *attr; 

{ 

XtCreateWindow (w, 

InputOutput, 

(Visual *) CopyFromParent, 

*mask, 

attr) ; 
} 

The realize method defined for Core calls XtCreateWindow with the passed 
value_mask and attributes and with windowClass and visual set to CopyFromParent. 
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 value and then create the window. For example, depending on its justi 
fication, Label sets bit_gravity to CenterGravity, EastGravity, or West- 



X Toolkit Intrinsics Reference Manual 33 1 




Core (continued) Xt - Widget Types 

Gravity. Consequently, shrinking the widget just moves the bits appropriately, and no 
Expose event is needed for repainting. (See Volume One, Xlib Programming Manual, for 
additional details.) 

If a composite widget s children should be realized in a particular order (typically to control 
the stacking order), it should call its children s XtRealizeWidget in the appropriate order 
from within its own realize method. 

Widgets that have children and are not subclasses of compositeWidgetClass are respon 
sible for realizing their own children. These children would usually be realized from their par 
ent s realize method. 

destroy 

The destroy method is of type XtWidgetProc. 

The destroy methods are called in subclass-to-superclass order. A widget s destroy 
method should only deallocate storage originally allocated by it and should not deallocate 
memory allocated by its superclasses. If a widget does not need to deallocate any storage, the 
destroy procedure pointer in its widget class record can be NULL. 

To reclaim memory, at least the following deallocations should be performed: 

Call XtFree on dynamic storage allocated with xtCalloc, xtMalloc, etc. 

Call XFreePixmap on pixmaps created with direct Xlib calls. 
Call xtDestroyGC on GCs allocated with xtGetGC. 

Call XFreeGC on GCs allocated with direct Xlib calls. 

Call XtRemoveE vent Handler on event handlers added with xtAddEvent- 
Handler. 

Call XtRemoveTimeOut on timers created with XtAppAddTimeOut. 

Call xtDestroyWidget for each child if the widget has children and is not a subclass 

of compositeWidgetClass. 

expose 

The expose method, responsible for all display and redisplay, is of type Xt Expose? roc. If 
a widget has no display semantics, it can specify NULL for the expose field. Many composite 
widgets serve only as containers for their children and have no expose method. 

If the expose method is NULL, XtRealizeWidget fills in a default bit gravity of North- 
WestGravity before it calls the widget s realize method. 

If the widget s compress_exposure field is FALSE, the region passed to the expose 
method is always NULL. If the widget s compress_exposure field is TRUE, the event con 
tains the bounding box for region. 

A small simple widget can ignore the bounding box information in the event and redisplay the 
entire window. A more complicated widget can use the bounding box to minimize the amount 
of calculation and redisplay it does. A very complex widget might use the region as a clip list 
in a GC and ignore the event information. The expose method is responsible for exposure of 



332 X Toolkit Intrinsics Reference Manual 



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 visibilityNotif y 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 argument 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 XtConf igurewidget.) 



X Toolkit Intrinsics Reference Manual 333 



Core (continued) Xt - Widget Types 

set_values 

The set_values method is of type xtSetValuesFunc. It is called whenever the values 
within the widget structure are modified by a call to xtSetValues or a change in the 
widget s geometry (see xtConf igureWidget). The function should return a Boolean indi 
cating whether the widget s redisplay method should be invoked. 

It should recompute any field derived from changed resources; for example, many GCs depend 
on foreground and background. If no recomputation is ever necessary and if none of the 
resources specific to a subclass require the window to be redisplayed when their values are 
changed, you can specify NULL for the set_values field in the class record. 

Like the initialize method, set_values is primarily concerned with the fields defined 
in the class, but it may have to resolve conflicts with its superclass, especially over width and 
height 

Sometimes a subclass may want to overwrite values filled in by its superclass. In particular, 
size calculations of a superclass are often incorrect for a subclass, and in this case, the subclass 
must modify or recalculate fields declared and computed by its superclass. 

As an example, a subclass can visually surround its superclass display. In this case, the width 
and height calculated by the superclass set_values method are too small and need to be 
incremented by the size of the surround. The subclass needs to know if its superclass size was 
calculated by the superclass or was specified explicitly. All widgets must place themselves into 
whatever size is explicitly given, but they should compute a reasonable size if no size is 
requested. How does a subclass know the difference between a specified size and a size com 
puted by a superclass? 

The request and new parameters provide the necessary information to resolve conflicts: 

static Boolean SetValues (current, request, new) 

Widget current, request, new; 

(...) 

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 request widget is the widget as originally requested. The new widget starts with the 
values in the request after it has been updated by all the superclass set_values methods. 
Subsequent subclass set_values methods can compare these two to resolve any conflicts. 
Namely, if request fields are of the default value (height and width will be zero, for 
example), then the XtSetValues request did not affect those field; the fields in new are the 
result of the superclass update. 

new is the actual widget instance record. Therefore, the set_values method 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. A 
widget need not refer to request, unless it must resolve conflicts between the current and 
new widgets. Any changes that the widget needs to make, including geometry changes, should 
be made in the new widget 



334 X Toolkit Intrinsics Reference Manual 



Xt - Widget Types (continued) Core 

Note that a change in the geometry fields alone does not require the set_values method to 
return TRUE, thereby forcing a redisplay. The X server will eventually generate an Expose 
event, if necessary. After calling all the set_values methods, xtSetValues forces a 
redisplay by calling the Xlib XClearArea function if any of the set_values methods 
returned TRUE. Therefore, a set_values method should not try to do its own redisplay. 

set_values methods should not do any work in response to changes in geometry because 
XtSetValues eventually will perform a geometry request, and that request might be denied. 
If the widget actually changes size in response to a XtSetValues, its resize method is 
called. Widgets should do any geometry-related work in their resize method. 

Note that it is permissible to call XtSetValues before a widget is realized. Therefore, the 
set_values method must not assume that the widget is realized. 

get_values_hook 

Some widgets maintain data structures that have resource values. If so, these data structures 
can be updated after an XtSetValues or size request using the get_values_hook 
method. The get_values_hook method is of type xtArgsProc. The widget should call 
Xt Get Subva lues and pass its subresource list. If the get_values_hook methods are 
non-NULL, they are called in superclass-to-subclass order after all the resource values have been 
fetched by xtGetValues. This permits a subclass to provide nonwidget resource data to 
XtGetValues. 

XtGetValues expects the contents of arguments to be pointers to locations where the actual 
values can be put 

See Section 1.7, "Resources," and xtArgsProc(2). 

set_values_hook 

Widgets that have a subpart can set the resource values by using XtSetValues and supplying 
a set_values_hook method. The set_values_hook procedure pointer for a widget 
class is of type XtArgsFunc(2). 

It returns a Boolean indicating whether or not XtSetValues should force the widget to be 
re-exposed. 

set_va lues_a (most 

This method is of type Xt Almost? roc. Most classes inherit this operation from their 
superclass by specifying Xt Inherit SetValuesAlmost in the class initialization. The 
Core set_values_almost method accepts the compromise suggested. 

The set_values_almost method is called when a client tries to set a widget s geometry by 
means of a call to XtSetValues and the geometry manager cannot satisfy the request but 
instead returns XtGeometryAlmost and a compromise geometry. The 
set_values_almost method takes the original geometry and the compromise geometry 
and determines whether the compromise is acceptable or whether a different compromise might 
work. It returns its results in the new widget parameter, which is then sent back to the geome 
try manager for another try. 



X Toolkit Intrinsics Reference Manual 335 



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 xtStringProc. The 
display_accelerator method is used to notify the widget that the Intrinsics 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 Intrinsics 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 XtGeometryHandler: 

typedef XtGeometryResult (*XtGeometryHandler) (Widget, 
XtWidgetGeometry *, XtWidgetGeometry *); 
Widget w; 

XtWidgetGeometry ^request; 
XtWidgetGeometry *geometry_return; 

The query_geometry 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 XtGeometryAlmost. If the preferred geometry 
is identical to the current geometry, the query_geometry method should return Xt- 
GeometryNo. 

After calling the query_geometry method or if the query_geometry field is NULL, Xt- 
QueryGeometry examines all the unset bits in geometry_return->request_mode 
and sets the corresponding fields in geometry_return to the current values from the widget 
instance. If CWStackMode is not set, the stack_mode field is set to xtSMDont Change. 
Xt Query Geometry returns the value returned by the query_geometry method or Xt- 
GeometryYes if the query_geometry field is NULL. 



336 X Toolkit Intrinsics Reference Manual 



Xt - Widget Types (continued) Core 

Therefore, the caller can interpret a return of xtGeometryYes 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 initialize method. 




X Toolkit Intrinsics Reference Manual 337 



Composite X 



Xt- Widget Types 



Name 

Composite Widget Class 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 <XlllCompositeP.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; /* array of ALL widget children */ 

Cardinal num_children; /* total number of widget children */ 

Cardinal num_slots; /* number of slots in children array */ 

XtOrderProc insert_position; /* compute position of new child */ 

} CompositePart, *CompositePtr; 

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 Compos iteClassRec are: 

extern CompositeClassRec compositeClassRec; 
extern WidgetClass compositeWidgetClass; 

The opaque types Compos itewidget and CompositeWidgetClass and the opaque 
variable compositeWidgetClass are defined for generic operations on widgets that are a 
subclass of Compos itewidget. 



338 X Toolkit Intrinsics Reference Manual 



Xt - Widget Types (continued) Com posite 



Field 



children 
num_children 
num_slots 
insert_position 



Default Value 



NULL 





Internal function InsertAtEnd 



Composite Methods 

Detailed discussions and example programs performing geometry management are contained in 
Chapter 11, Geometry Management, in Volume Four, X Toolkit Intrinsic* Programming Man 
ual. 

insert_child 

To add a child to the parent s list of children, the xtCreateWidget function calls the par 
ent s insert_child method. The insert_child procedure pointer in a composite 
widget is of type Xt widget P roc: 

typedef void (*XtWidgetProc) (Widget) ; 

Most composite widgets inherit this method from their superclass by specifying Xt Inherit - 
InsertChild for the insert_child field in the class record. Composite s 
insert_child method calls the insert_position method and inserts the child at the 
specified position. 

Some composite widgets define their own insert_child method so that they can order their 
children in some convenient way, create companion controller widgets for a new widget, or 
limit the number or type of their children widgets. 

This method can also be inherited dynamically and modified if the subclass widget wants to use 
it but wants to perform additional processing when the child is inserted. The example 
InsertChild method shown below does this: 

static XtArgsProc InsertChild (w, args, num_args) 

Widget w; 

ArgList args; 

Cardinal *num_args; 

{ 

Compos iteWidget Class superclass; 

/* 

* Satisfy parental responsibilities 
*/ 

superclass = (CompositeWidgetClass) compositeWidgetClass; 
( *superclass->composite_class . insert_child) (w, args, num_args) ; 
} 

If there is not enough room to insert a new child in the children array (that is, num_children 
= num_slots), the insert_child method must first reallocate the array and update 
num_slots. The insert_child method then places the child wherever it wants and incre 
ments the n urn children field. 



X Toolkit Intrinsics Reference Manual 339 



Composite (continued) Xt - Widget Types 

delete_child 

To remove the child from the parent s children array, the xtDestroyWidget function even 
tually causes a call to the composite parent s class delete_child method. The 
de let e_chi Id procedure pointer is of type XtwidgetProc: 

typedef void (*XtWidgetProc) (Widget ); 

Most widgets inherit the delete_child method from their superclass. Composite widgets 
that create companion widgets define their own delete_child method to remove these 
companion widgets. 

Note that the insert_child and delete_child methods exploit internal common data 
structures, so it would be unwise to inherit one and not the other. 

change_managed 

The change_managed method is invoked when the application brings the child under its 
parent s management. This happens automatically when the application uses xtCreate- 
Managedwidget to create the widget. change_managed is also invoked when the appli 
cation removes a widget from the parent s managed list. Children can be managed explicitly 
with XtManageChild, XtManageChildren, XtUnmanageChild, and XtUnmanage- 
Children. The change_managed procedure pointer is of type XtwidgetProc: 

static void ChangeManaged (w) 
Widget w; 



geometry_manager 

The geometry_manager method actually lays out the children for display. Only a subclass 
of a well-developed class of geometry manager can inherit this method; there is no default 
geometry manager defined by Composite that can manage multiple children. 

static XtGeometryResult GeometryManager (w, request, reply) 
Widget w; 

XtWidgetGeometry *request; 
XtWidgetGeometry *reply; 
{ .. } 

A bit set to zero in the request s mask field means that the child widget does not care about the 
value of the corresponding field. Then the geometry manager is free to set it as it wishes. A bit 
set to 1 means that the child wants that geometry element changed to the value in the corre 
sponding field. 

If the geometry manager can satisfy all changes requested and if xtCWQueryOnly is not 
specified, it updates the widget s x, y, width, height and border_width values appropri 
ately. Then it returns XtGeomet ryYes, and the value of the geometry_return argument 
is undefined. The widget s window is moved and resized automatically by xtMake- 
GeometryRequest. 

Homogeneous composite widgets often find it convenient to treat the widget making the 
request the same as any other widget, possibly reconfiguring it as part of its layout process, 
unless XtCWQueryOnly is specified. If it does this, it should return xtGeometryDone to 



340 X Toolkit Intrinsics Reference Manual 



Xt - Widget Types (continued) Composite 

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- 

GeometryNo. 

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 XtGeometryAlmost 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 XtMakeGeometryRequest. 

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- 
Conf igurewidget. 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 34 1 



Composite (continued) Xt - Widget Types 

The insert_position method pointer in a composite widget instance is of type Xt- 
OrderProc: 

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_jposition 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 ^ Toolkit Intrinsics Reference Manual 



-x - widge, Types / Constraint 

Name 

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

Synopsis 

tinclude 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 Const raintPart if it need not compute anything. 

The constraint set_values 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_yalues method should reset the height 
field in the widget. 

The class and instance structures are defined in <XlllConstraintP.h>. 



X Toolkit Intrinsics Reference Manual 343 



Constraint (continued) Xt - Widget Types 

The class record defines the actual data in the form of resources: 

typedef struct _ConstraintClassPart { 

XtResourceList resources; /* constraint resource list */ 

Cardinal num_resources; /* number of constraints in list */ 

Cardinal constraint_size; /* size of constraint record */ 

XtlnitProc constraint_initialize; /* constraint initialization */ 

XtWidgetProc constraint_destroy; /* constraint destroy proc */ 

XtSetValuesFunc set_values; /* constraint set_values proc */ 

caddr_t extension; /* pointer to extension record */ 

} ConstraintClassPart; 

The instance record defines no new fields, other than a dummy field to satisfy the C compiler. 

typedef struct _ConstraintPart { 

caddr_t dummy; /* No new fields, keep C compiler happy */ 

} ConstraintPart ; 

Subclasses of a Constraint widget can add additional constraint fields to their superclass. To 
allow this, widget writers should define the constraint records in their private .h file by using 
the same conventions as used for widget records. For example, a widget that needs to maintain 
a maximum width and height for each child might define its constraint record as follows: 

typedef struct { 

Dimension max_width,max_height; 
} MaxConstraintPart; 

typedef struct { 

MaxConstraintPart max; 
} MaxConstraintRecord, *MaxConstraint; 

A subclass of this widget that also needs to maintain a minimum size would define its constraint 
record as follows: 

typedef struct { 

Dimension min_width,min_height; 
} MinConstraintPart; 

typedef struct { 

MaxConstraintPart max; 

MinConstraintPart min; 
} MaxMinConstraintRecord, *MaxMinConstraint ; 

Constraints are allocated, initialized, deallocated and otherwise maintained insofar as possible 
by the Intrinsics. The constraint class record part has several entries that facilitate this. All 
entries in ConstraintClassPart are information and procedures that are defined and 
implemented by the parent, but they are called whenever actions are performed on the parent s 
children. 

The xtCreateWidget function uses the constraint_size field to allocated a constraint 
record when a child is created. The constraint_size field gives the number of bytes 
occupied by a constraint record. XtCreateWidget also uses the constraint resources to fill 
in resource fields in the constraint record associated with a child. It then calls the constraint 



344 X Toolkit Intrinsics Reference Manual 



Xt - Widget Types (continued) Constraint 

initialize methods so that the parent can compute constraint fields that are derived from 
constraint resources and can possibly move or resize the child to conform to the given con 
straints. 

The xtGetValues and xtSetValues functions use the constraint resources to get the 
values or set the values of constraint associated with a child. XtSetValues then calls the 
constraint set_values methods so that a parent can recompute derived constraint fields and 
move or resize the child as appropriate. 

The xtDestroyWidget function calls the constraint destroy method to deallocate any 
dynamic storage associated with a constraint record. The constraint record itself must not be 
deallocated by the constraint destroy method; XtDestroyWidget does this automatically. 

Methods 

constraint_destroy 

The constraint_destroy method identified in the ConstraintClassPart structure 
is called for a widget whose parent is a subclass of constraintwidgetClass. This con 
straint destroy procedure pointer is of type xtwidgetProc. The constraint destroy methods 
are called in subclass-to-superclass order, starting at the widget s parent and ending at 
constraintwidgetClass. Therefore, a parent s constraint destroy method only should 
deallocate storage that is specific to the constraint subclass and not the storage allocated by any 
of its superclasses. 

If a parent does not need to deallocate any constraint storage, the constraint destroy method 
entry in its class record can be NULL. 

constraintjnitialize 

The constraint_initialize procedure pointer is of type XtlnitProc. The values 
passed to the parent constraint_initialize method are the same as those passed to the 
child s class_initialize method. 

The constraint_initialize method should compute any constraint fields derived from 
constraint resources. It can make further changes to the widget to make the widget conform to 
the specified constraints; for example, changing the widget s size or position. 

If a constraint class does not need a const raint_initialize method, it can specify NULL 
for the initialize field of the ConstraintClassPart in the class record. 

See Also 

Core(3) 



X Toolkit Intrinsics Reference Manual 345 



^ Xt - Widget 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 Xtlnitialize or XtCreateApplication- 
Context is a Shell widget, as is a pop-up widget created with xt Popup), 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 Used for shell windows that completely bypass the window manager 

(for example, pop-up menu shells). A subclass of Shell (see below). 

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

TopLevelShell Used for normal top-level windows (for example, any additional top- 

level widgets an application needs). A subclass of VendorShell (see 
below). 

ApplicationShell 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 



Xt - Widget Types (continued) Shell 

Three classes of shells are internal and should not be instantiated or subclassed: 

Shell Provides the base class for shell widgets and the fields needed for all 

types of shells. Shell is a direct subclass of Composite. 

WMShell Contains fields needed by the common window manager protocol 

and is a subclass of Shell. 

VendorShell Contains fields used by vendor-specific window managers and is a 

subclass of WMShell. 

The actual definitions are in <X1 L Shell. h>, <Xll/SnellP.h>, <X1 1 1 Vendor. h> and 
<XlllVendorP.h>, Only <Xll/Shell.h> needs to be routinely included in application code, 
since it defines the class variables applicationShellwidgetClass, override- 
ShellWidgetClass, topLevelShellWidgetClass and transientShell- 
WidgetClass. 

By using the Shell widget classes, any routine communication with the window manager that 
an application would want to perform can be done by setting resources when the Shell widget is 
created. For example, using xtNiconPixmap, the application can set a program-supplied 
pixmap to be the application s icon. (See Chapter 10, Inter-Client Communications, in Volume 
Four, X Toolkit Intrinsics Programming Manual, for a complete example that sets the applica 
tion s icon.) 

For more information on pop-up windows with XtPopup, see Chapter 12, Menus, Gadgets, 
and Cascaded Pop Ups, in Volume Four, X Toolkit Intrinsics Programming Manual. 

ShellClassPart Definitions 

None of the shell widget classes has any additional fields: 

typedef struct { caddr_t extension; } ShellClassPart, OverrideShellClassPart, 
WMShellClassPart, VendorShellClassPart, TransientShellClassPart, 
TopLevel ShellClassPart, ApplicationShellClassPart; 

Shell widget classes have the (empty) shell fields immediately following the composite fields: 

typedef struct _ShellClassRec { 

CoreClassPart core_class; 

Compos i teC la ssP art compos it e_c lass; 

ShellClassPart shell_class; 
} ShellClassRec; 

typedef struct _OverrideShellClassRec { 

CoreClassPart core_class; 

Compos iteC las sP art compos it e_class; 

ShellClassPart shell_class; 

OverrideShellClassPart override_shell_class; 
} OverrideShellClassRec; 

typedef struct _WMShellClassRec { 
CoreClassPart core_class; 
Compos! teClassPart compos ite_class; 
ShellClassPart shell class; 



X Toolkit Intrinsics Reference Manual 347 




Shell (continued) Xt - Widget Types 

WMShellClassPart wm_shell_class; 
} WMShellClassRec; 

typedef struct _VendorShellClassRec { 

CoreClassPart core_class; 

CompositeClassPart composite_class; 

ShellClassPart shell_class; 

WMShellClassPart wm_shell_class; 

Vendor ShellClassPart vendor_shell_class; 
} VendorShellClassRec; 

typedef struct _TransientShellClassRec { 

CoreClassPart core_class; 

CompositeClassPart composite_class; 

ShellClassPart shell_class; 

WMShellClassPart wm_shell_class; 

VendorShellClassPart vendor_shell_class; 

Transient ShellClassPart transient_shell_class; 
} TransientShellClassRec; 

typedef struct _ApplicationShellClassRec { 

CoreClassPart core_class; 

CompositeClassPart composite_class; 

ShellClassPart shell_class; 

WMShellClassPart wm_shell_class; 

VendorShellClassPart vendor_shell_class; 

TopLevelShellClassPart top_level_shell_class; 

ApplicationShellClassPart application_shell_class; 
} ApplicationShellClassRec; 

The predefined class records and pointers for shells are: 

extern ShellClassRec shellClassRec; 

extern OverrideShellClassRec overrideShellClassRec; 

extern WMShellClassRec wm ShellClassRec; 

extern VendorShellClassRec VendorShellClassRec; 

extern TransientShellClassRec transientShellClassRec; 

extern TopLevelShellClassRec topLevelShellClassRec; 

extern ApplicationShellClassRec applicationShellClassRec; 

extern WidgetClass shellWidgetClass; 
extern WidgetClass overrideShellWidgetClass; 
extern WidgetClass wmShellWidgetClass; 
extern WidgetClass vendorShellWidgetClass; 
extern WidgetClass transientShellWidgetClass; 
extern WidgetClass topLevelShellWidgetClass; 
extern WidgetClass applicationShellWidgetClass; 



348 X Toolkit Intrinsics Reference Manual 



Xt- Widget Types 



(continued) 



Shell 



The following opaque types and opaque variables are defined for generic operations on widgets 
that are a subclass of ShellwidgetClass: 



Types 



ShellWidget 

OverrideShellWidget 

WMShellWidget 

VendorShellWidget 

Transient ShellWidget 

TopLevelShellWidget 

ApplicationShellWidget 

ShellwidgetClass 

OverrideShellWidgetClass 

WMShellWidgetClass 

VendorShellWidget Class 

Transient ShellwidgetClass 

TopLevelShellWidgetClass 

ApplicationShellWidget Class 



Variables 



ShellwidgetClass 
OverrideShellWidgetClass 
wmShellWidget Class 
VendorShellWidget Class 
transient ShellWidget Class 
topLevelShellWidgetClass 
applicationShellWidget Class 



ShellPart Definition 

The various shells have the following additional fields defined in their widget records: 

typedef struct { 

String geometry; 

XtCreatePopupChildProc create_popup_child_proc; 

XtGrabKind grab_kind; 

Boolean spring_loaded; 

Boolean popped_up; 

Boolean allow_shell_resize; 

Boolean client_specif ied; 

Boolean save_under; 

Boolean override_redirect; 

XtCallbackList popup_callback; 

XtCallbackList popdown_callback; 
} ShellPart; 

typedef struct { int empty; } OverrideShellPart; 

typedef struct { 

String title; 

int wm_timeout; 

Boolean wait_for_wm; 

Boolean transient; 

XSizeHints size_hints; 

XWMHints wm_hints; 
} WMShellPart; 

typedef struct { 



X Toolkit Intrinsics Reference Manual 



349 



Shell (continued) Xt - Widget Types 

int vendor_specif ic; 
} 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 full definitions of the various shell widgets have shell fields following 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 



} TransientShellRec, *TransientShellWidget; 

typedef struct { 

CorePart core; 

CompositePart composite; 

ShellPart shell; 

WMShellPart wm; 

VendorShellPart vendor; 

TopLevelShellPart topLevel; 
} TopLevelShellRec, *TopLevelShellWidget; 

typedef struct { 

CorePart core; 

CompositePart composite; 

ShellPart shell; 

WMShellPart wm; 

VendorShellPart vendor; 

TopLevelShellPart topLevel; 

ApplicationShellPart application; 
} ApplicationShellRec, *ApplicationShellWidget; 

ShellPart Default Values 

The default values for fields common to all classes of public shells (filled in by the Shell 
resource lists and the Shell initialize procedures) are: 

Field Default Value 



geometry 

create_popup_child_proc 

grab_kind 

spring_loaded 

popped_up 

allow_shell_resize 

client_specif led 

save under 



override_redirect 

popup_callback 
popdown callback 



NULL 

NULL 

(internal) 

(internal) 

(internal) 

FALSE 

(internal) 

TRUE for OverrideShell 

and TransientShell, 

FALSE otherwise 

TRUE for OverrideShell, 

FALSE otherwise 

NULL 
NULL 



The geometry resource specifies the size and position and is usually done only from a com 
mand line or a defaults file. The create_popup_child_proc is called by the xtPopup 
procedure and is usually NULL. The allow_shell_resize field controls whether or not the 
widget contained by the shell is allowed to try to resize itself. If allow_shell_resize is 
FALSE, any geometry requests always return xtGeometryNo. Setting save_under 
instructs the server to attempt to save the contents of windows obscured by the shell when it is 



X Toolkit Intrinsics Reference Manual 



351 



Shell 



(continued) 



Xt - Widget Types 



mapped and to restore its contents automatically later. It is useful for pop-up menus. Setting 
override_redirect determines whether or not the shell window is visible to the window 
manager. If it is TRUE, the window is immediately mapped without the manager s intervention. 
The pop-up and pop-down callbacks are called during xt Popup and xtPopdown. 

The default values for shell fields in WMShell and its subclasses are: 



Field 


Default Value 


title 


Icon name, if specified, other 




wise the application s name 


wm timeout 


Five seconds 


wait for wm 


TRUE 


transient 


TRUE for TransientShell, 




FALSE otherwise 


min width 


None 


min height 


None 


max width 


None 


max height 


None 


width inc 


None 


height_inc 


None 


min aspect x 


None 


min aspect y 


None 


max_aspect x 


None 


min aspect y 


None 


max aspect x 


None 


max aspect y 


None 


input 


FALSE 


initial state 


Normal 


icon_jpixmap 


None 


icon window 


None 


icon_x 


None 


icon_y 


None 


icon mask 


None 


window group 


None 



The title is a string to be displayed by the window manager. The wm_timeout resource limits 
the amount of time a shell is to wait for confirmation of a geometry request to the window man 
ager. If none comes back within that time, the shell assumes the window manager is not func 
tioning properly and sets wait_f or_wm to be FALSE (later events may reset this value). The 
wait_f or_wm resource sets the initial state for this flag. When the flag is FALSE, the shell 
does not wait for a response but relies on asynchronous notification. All other resources are for 
fields in the window manager hints and the window manager size hints. 



352 



X Toolkit Intrinsics Reference Manual 



Xt- Widget Types 



(continued) 



Shell 



TopLevel shells have the the following additional resources: 



Field 



icon_name 
iconic 



Default Value 



Shell widget s name 

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 
argv 





NULL 



The argc and argv fields are used to initialize the standard property WM_COMMAND. 




X Toolkit Intrinsics 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 widget. 

Synopsis 

tfinclude <Xll/StringDef s .h> 

tinclude <Xll/Intrinsic .h> 

^include <Xll/XawMisc .h> 

tinclude <Xll/Box.h> 

widget = XtCreateWidget (widget, boxWidgetClass, 



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



Class Hierarchy 

Core > Composite Box 

Description 

The Box widget provides geometry management of arbitrary widgets in a box of a specified 
dimension. The children are rearranged when resizing events occur either on the Box or when 
children are added or deleted. The Box widget always attempts to pack its children as closely 
as possible within the geometry allowed by its parent. 

Box widgets are commonly used to manage a related set of Command widgets and are 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: 



Name 


Type 


Default 


Description 


XtNbackground 


Pixel 


XtDefault- 


Window background color 






Background 




XtNbackground- 


Pixmap 


None 


Window background pixmap 


Pixmap 








XtNborderColor 


Pixel 


XtDefault- 


Window border color 






Foreground 




XtNborderPixmap 


Pixmap 


None 


Window border pixmap 


XtNborderWidth 


Dimension 


1 


Border width on button box 


XtNdestroy- 


XtCallbackList 


NULL 


Callbacks forXtDestroyWidget 


Callback 








XtNhSpace 


Dimension 


4 


Pixel distance left and right of children 


XtNheight 


Dimension 


See below 


Viewing height of inner window 


XtNmappedWhen- 


Boolean 


TRUE 


Whether XtMapWidget is automatic 


Managed 








XtNtranslations 


TranslationTable 


None 


Event-to-action translations 


XtNvSpace 


Dimension 


4 


Pixel distance top and bottom of chil 








dren 



X Toolkit Intrinsics Reference Manual 



357 



Box 



(continued) 



Xt - Athena Widgets 



Name 


Type 


Default 


Description 


XtNwidth 


Dimension 


width of 


Viewing width of inner window 






widest child 




XtNx 


Position 





Widget location x coordinate 


XtNy 


Position 





Widget location y coordinate 



The Box widget positions its children in rows with XtNhSpace pixels to the left and right of 
each child and xtNvSpace pixels between rows. If the Box width is not specified, the Box 
widget uses the width of the widest child. Each time a child is managed or unmanaged, the Box 
widget will attempt to reposition the remaining children to compact the box. Children are posi 
tioned in order left to right, top to bottom. When the next child does not fit on the current row, 
a new row is started. If a child is wider than the width of the box, the box will request a larger 
width from its parent and will begin the layout process from the beginning if a new width is 
granted. After positioning all children, the Box widget attempts to shrink its own size to the 
minimum dimensions required for the layout. 

Programmatic Interface 

To create a Box widget instance, use xtCreateWidget and specify the class variable 
boxWidgetClass. 

To add a child to the Box, use XtCreateWidget and specify the widget ID of the Box 
as the parent of the new widget. 

To remove a child from a Box, use XtUnmanageChild or xtDestroyWidget and 
specify the widget ID of the child. 

To destroy a Box widget instance, use XtDestroyWidget and specify the widget ID of 
the Box widget. All the children of this box are automatically destroyed at the same time. 

See Also 

Core(3), Composite(3), Command(4). 



358 



X Toolkit Intrinsics Reference Manual 



Xt- Athena Widgets- 



Command 



Name 

commandWidgetClass command button activated by pointer click. 

Synopsis 

tinclude <Xll/StringDef s .h> 

#include <Xll/Intrinsic .h> 

#include <Xll/XawMisc.h> 

tinclude <X11 /Command. h> 

widget = XtCreateWidget (widget, commandWidgetClass, . . .); 



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



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 


Type 


Default 


Description 


XtNbackground 


Pixel 


XtDefault- 


Window background color 






Background 




XtNbackground- 


Pixmap 


None 


Window background pixmap 


Pixmap 








XtNbitmap 


Pixmap 


None 


Pixmap to display in place of the label 


XtNborderColor 


Pixel 


XtDefault- 


Window border color 






Foreground 




XtNborderPixmap 


Pixmap 


None 


Window border pixmap 


XtNborderWidth 


Dimension 


1 


Width of button border 


XtNcallback 


XtCallbackList 


NULL 


Callback for button select 


XtNcursor 


Cursor 


None 


Pointer cursor 


XtNdestroy- 


XtCallbackList 


NULL 


Callbacks forXtDestroyWidget 


Callback 








XtNfont 


XFontStruct* 


XtDefaultFont 


Label font 


XtNforeground 


Pixel 


XtDefault- 


Foreground color 






Foreground 




XtNheight 


Dimension 


Text height 


Button height 


XtNhighlight- 


Dimension 


2 


Width of border to be highlighted 


Thickness 








XtNin sensitive - 


Pixmap 


Gray 


Border when not sensitive 


Border 









X Toolkit Intrinsics Reference Manual 



359 



Command 



(continued) 



Xt - Athena Widgets 



Name 


Type 


Default 


Description 


XtNinternal- 


Dimension 


2 


Internal border height for highlighting 


Height 








XtNinternalWidth 


Dimension 


4 


Internal border width for highlighting 


XtNjustify 


XtJustify 


XtJustifyCenter 


Type of text alignment 


XtNlabel 


String 


Button name 


Button label 


XtNmappedWhen- 


Boolean 


TRUE 


Whether XtMapWidget is automatic 


Managed 








XtNresize 


Boolean 


TRUE 


Whether to auto-resize in SetValues 


XtNsensitive 


Boolean 


TRUE 


Whether widget receives input 


XtNtranslations 


Translation- 


See below 


Event-to-action translations 




Table 






XtNwidth 


Dimension 


Text width 


Button width 


XtNx 


Position 





x coordinate 


XtNy 


Position 





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 of XtNlabel + XtNinternalHeight 



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



XtNinternalHeight 



XtNinternalWidth 



XtNjustify 



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. 

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 



Xt - Athena Widgets 



(continued) 



Command 



XtNlabel 



XtNresize 



XtNsensitive 



XtNwidth 



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

Specifies whether the Command widget should attempt to resize to its pre 
ferred dimensions whenever xtSetValues is called for it. The default 

is TRUE. 

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

Specifies the width of the Command widget. The default value is the min 
imum width that will contain: 

XtNinternalWidth + width of XtNlabel + XtNinternalWidth 

If the width is larger or smaller than the minimum, xtN justify deter 
mines how the label string is aligned. 

Translations and Actions 

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

<EnterWindow> : highlight ( ) 
<LeaveWindow> : reset ( ) 
<BtnlDown>:set ( ) 
<BtnlUp>:notify ( ) unset () 

With these bindings, the user can cancel the action before releasing the button by moving the 
pointer out of the Command widget. 

The Command widget supports the following actions: 

Switching the button between the foreground and background colors with set and 
unset. 

Processing application callbacks with notify. 

Switching the internal border between highlighted and unhighlighted states with high 
light and unhighlight. 

The full list of actions supported by Command is: 

highlightQ Displays the internal highlight border in the XtNf oreground color. 
Displays the internal highlight border in the xtNbackground color. 

Enters the set state, in which notify is possible and displays the inter 
ior of the button, including the highlight border, in the foreground color. 
The label is displayed in the background color. 

Cancels the set state and displays the interior of the button, including the 
highlight border, in the background color. The label is displayed in the 
foreground color. 



unhighlight() 
set() 

unsetQ 



X Toolkit Intrinsics Reference Manual 



361 



Command 

reset() 
notify() 



(continued) 



Xt - Athena Widgets 



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

Executes the xtNcallback callback list if executed in the set state. 
The value of the call_data argument is undefined. 



Programmatic Interface 

To create a Command widget instance, use xtCreateWidget and specify the class vari 
able commandWidgetClass. 

To destroy a Command widget instance, use xtDestroyWidget and specify the widget 
ID of the Command widget. 

See Also 

Box(4), Label(4). 



362 



X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets- 



Dialog 



Name 

dialog WidgetClass dialog box widget. 

Synopsis 

#include <Xll/StringDef s .h> 

#include <Xll/Intrinsic .h> 

tinclude <Xll/XawMisc .h> 

#include <Xll/Dialog.h> 

widget = XtCreateWidget (widget, dialogWidgetClass, . . . ); 



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



Class Hierarchy 

Core Composite > Constraint - Form 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 apreconfiguredform. 

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: 



Name 


Type 


Default 


Description 


XtNbackground 


Pixel 


XtDefault- 


Window background color 






Background 




XtNbackground- 


Pixmap 


None 


Window background pixmap 


Pixmap 








XtNborderColor 


Pixel 


XtDefault- 


Window border color 






Foreground 




XtNborderPixmap 


Pixmap 


None 


Window border pixmap 


XtNborderWidth 


Dimension 


1 


Width of border in pixels 


XtNdestroy- 


XtCallbackList 


NULL 


Callbacks forXtDestroyWidget 


Callback 








XtNheight 


Dimension 


Computed 


Height of dialog 






at create 




XtNlabel 


String 


Label name 


String to be displayed 


XtNmappedWhen- 


Boolean 


TRUE 


Whether xtMapWidget is automatic 


Managed 








XtNmaximumLength 


int 


256 


Maximum number of input characters 


XtNsensitive 


Boolean 


TRUE 


Whether widget receives input 


XtNtranslations 


TranslationTable 


None 


Event-to-action translations 



X Toolkit Intrinsics Reference Manual 



363 



Dialog 



(continued) 



Xt - Athena Widgets 



Name 


Type 


Default 


Description 


XtNvalue 
XtNwidth 


char* 
Dimension 


NULL 

Computed 
at create 


Pointer to default string 
Width of dialog 


XtNx 

XtNy 


Position 
Position 


NULL 
NULL 


x position of dialog 
y position of dialog 



The instance name of the label widget within the Dialog widget is label, and the instance name 
of the Dialog value widget is value. 

Programmatic Interface 

To create a Dialog widget instance, use xtCreateWidget and specify the class variable 

dialogWidgetClass. 

To add a child button to the Dialog box, use XtCreateWidget and specify the widget 
ID of the previously created Dialog box as the parent of each child. When creating but 
tons, you do not have to specify form constraints. The Dialog box will automatically add 
the constraints. 

To return the character string in the text field, use: 

char *XtDialogGetValueString(w) 
Widget w; 

where w specifies the widget ID of the Dialog box. 

If a string was specified in the XtNvalue resource, the Dialog widget will store the input 
directly into the string. 

To remove a child button from the Dialog box, use xtUnmanageChild or Xt- 
DestroyWidget and specify the widget ID of the child. 

To destroy a Dialog widget instance, use Xt Destroy widget and specify the widget ID 
of the Dialog widget All children of the Dialog are automatically destroyed at the same 
time. 

See Also 

Command(4), Form(4), Text(4). 



364 



X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets- 



Form 



Name 

formWidgetClass geometry-managing widget implementing constraints on children. 

Synopsis 

#include <Xll/StringDef s .h> 

#include <Xll/Intrinsic.h> 

#include <Xll/XawMisc .h> /* <Xll/Misc.h> in R2 */ 

^include <Xll/Form.h> 

widget = XtCreateWidget (midget , 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: 



Name 


Type 


Default 


Description 


XtNbackground 


Pixel 


XtDefault- 


Window background color 






Background 




XtNbackground- 


Pixmap 


None 


Window background pixmap 


Pixmap 








XtNborderColor 


Pixel 


XtDefault- 


Window border color 






Foreground 




XtNborderPixmap 


Pixmap 


None 


Window border pixmap 


XtNborderWidth 


Dimension 


1 


Width of border in pixels 


XtNdefault- 


int 


4 


Default value for XtNhorizDi stance 


Distance 






and XtNvertDistance 


XtNdestroy- 


XtCallbackList 


NULL 


Callbacks forXtDestroyWidget 


Callback 








XtNheight 


Dimension 


Computed 


Height of form 






at realize 




XtNmappedWhen- 


Boolean 


TRUE 


Whether XtMapWidget is automatic 


Managed 








XtNsensitive 


Boolean 


TRUE 


Whether widget receives input 



X Toolkit Inthnsics Reference Manual 



365 



Form 



(continued) 



Xt - Athena Widgets 



Name 


Type 


Default 


Description 


XtNtranslations 


Trans 1 at ionTable 


None 


Event-to-action translations 


XtNwidth 


Dimension 


Computed 
at realize 


Width of form 


XtNx 


Position 


NULL 


x position of form 


XtNy 


Position 


NULL 


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. 



Name 


Type 


Default 


Description 


XtNbottom 


XtEdgeType 


XtRubber 


See text 


XtNfromHoriz 


Widget 


NULL 


See text 


XtNfromVert 


Widget 


NULL 


See text 


XtNhorizDi stance 


int 


Xt default Distance 


See text 


XtNleft 


XtEdgeType 


XtRubber 


See text 


XtNresizable 


Boolean 


FALSE 


TRUE if allowed to resize 


XtNright 


XtEdgeType 


XtRubber 


See text 


XtNtop 


XtEdgeType 


XtRubber 


See text 


XtNvert Distance 


int 


XtdefaultDi stance 


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 <X1 I/Form. h> and is one 
of XtChainT op, XtChainBottom, XtChainLef t, XtChainRight, or XtRubber. 



366 



X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets (continued) Form 

The values XtChainTop, XtChainBottom, XtChainLef t, and XtChainRight specify 
that a constant distance from an edge of the child to the top, bottom, left, and right edges 
respectively of the Form is to be maintained. The value Xt Rubber specifies that a propor 
tional distance from the edge of the child to the left or top edge of the Form is to be maintained 
when the form is resized. The proportion is determined from the initial position of the child 
and the initial size of the Form. Form provides a StringToEdgeType conversion procedure 
to allow the resize constraints to be easily specified in a resource file. 

The default width of the Form is the minimum width needed to enclose the children after com 
puting their initial layout, with a margin of XtNdef aultDistance at the right and bottom 
edges. If a width and height is assigned to the Form that is too small for the layout, the children 
will be clipped by the right and bottom edges of the Form. 

Programmatic Interface 

To create a Form widget instance, use xtCreateWidget and specify the class variable 

formWidget Class. 

To add a new child to a Form, use XtCreateWidget and specify the widget ID of the 
previously created Form as the parent of the child. 

To remove a child from a Form, use xtUnmanageChild or XtDestroyWidget and 
specify the widget ID of the child widget. 

To destroy a Form widget instance, use XtDestroyWidget and specify the widget ID 
of the Form. All children of the Form are automatically destroyed at the same time. 

When a new child becomes managed or an old child unmanaged, the Form widget will 
recalculate the positions of its children according to the values of the xtNhoriz- 
Distance, XtNf romHoriz, XtNvertDistance, and XtNf romVert constraints at 
the time the change is made. No re-layout is performed when a child makes a geometry 
request. 

To force or defer a re-layout of the Form widget, use xtFormDoLayout: 

void XtFormDoLayout (w, do_2ayout) 
Widget w; 
Boolean do_layout; 

where: 

w Specifies the Form widget. 

do_layout Enables (if TRUE) or disables (if FALSE) layout of the Form widget. 

When making several changes to the children of a Form widget after the Form has been 
realized, it is a good idea to disable re-layout until all changes have been made, then allow 
the layout. The Form widget increments an internal count each time XtFormDoLayout 
is called with do_layout FALSE and decrements the count when do_layout is TRUE. 
When the count reaches 0, the Form widget performs a re-layout. 



X Toolkit Intrinsics Reference Manual 367 



Grip 



X 



Xt- Athena Widgets- 



Name 

gripWidgetClass attachment point for dragging other widgets. 

Synopsis 

tinclude <Xll/StringDef s .h> 

^include <Xll/Intrinsic .h> 

tfinclude <Xll/XawMisc .h> 

tfinclude <Xll/Grip.h> 

widget = XtCreateWidget (widget, gripWidgetClass, 



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



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 


Pixmap 


None 


Window border pixmap 


XtNborderWidth 


Dimension 





Width of the border in pixels 


XtNcallback 


XtCallbackList 


None 


Action routine 


XtNcursor 


Cursor 


None 


Cursor for the grip 


XtNdestroy- 


XtCallbackList 


NULL 


Callback for XtDestroyWidget 


Callback 








XtN foreground 


Pixel 


XtDefault- 


Window background color 






Foreground 




XtNheight 


Dimension 


8 


Height of the widget 


XtNmappedWhen- 


Boolean 


TRUE 


Whether xtMapWidget is automatic 


Managed 








XtNsensitive 


Boolean 


TRUE 


Whether widget should receive input 


XtNtranslations 


TranslationTable 


None 


Event-to-action translations 


XtNwidth 


Dimension 


8 


Width of the widget 


XtNx 


Position 





x coordinate within parent 


XtNy 


Position 





y coordinate within parent 



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



365 



X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets (continued) Grip 

Translations and Actions 

The Grip widget does not declare any default event translation bindings, but it does declare a 
single action routine named GripAction in its action table. The client specifies an arbitrary 
event translation table giving parameters to the GripAction routine. 

The GripAction action executes the callbacks on the xtNcallback list, passing as 
call_data a pointer to a GripCallData structure, defined in <X1 I/Grip. h>: 

typedef struct _GripCallData { 

XEvent *event; 

String *params; 

Cardinal num_params; 
} GripCallDataRec, *GripCallData; 

In this structure, the event field is a pointer to the input event that triggered the action, and 
pa rams and num_params give the string parameters specified in the translation table for the 
particular event binding. 

The following is an example of a GripAction translation table: 

<BtnlDown> : GripAction (press) 
<BtnlMotion> : GripAction (move) 
<BtnlUp> : GripAction (release) 

Programmatic Interface 

To create a Grip widget instance, use xtCreateWidget and specify the class variable 

gripWidgetClass. 

To destroy a Command button widget instance, use XtDestroyWidget and specify the 
ID of the Grip widget. 

See Also 

Vpaned(4) 



X Toolkit Intrinsics Reference Manual 369 



Label 



X 



- Athena Widgets- 



Name 

labelWidgetClass widget to display a non-editable string. 

Synopsis 

#include <Xll/StringDef s .h> 

#include <Xll/Intrinsic .h> 

#include <Xll/XawMisc ,h> 

#include <Xll/Label .h> 

widget = XtCreateWidget (widget , labelWidgetClass, . . .); 



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



Class Hierarchy 
Core > Simple 



Label 



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: 



Name 


Class Type 


Default 


Description 


XtNbackground 


Pixel 


XtDefault- 


Window background color 






Background 




XtNbackground- 


Pixmap 


None 


Window background pixmap 


Pixmap 








XtNbitmap 


Pixmap 


None 


Pixmap to display in place of the 








label 


XtNborderColor 


Pixel 


XtDefault- 


Window border color 






Foreground 




XtNborderPixmap 


Pixmap 


None 


Window border pixmap 


XtNborderWidth 


Dimension 


1 


Border width in pixels 


XtNcursor 


Cursor 


None 


Pointer cursor 


XtNdestroy- 


XtCallbackList 


NULL 


Callbacks forXtDestroyWidget 


Callback 








XtNfont 


XFontStruct* 


XtDefaultFont 


Label font 


XtN foreground 


Pixel 


XtDefault- 


Foreground color 






Foreground 




XtNheight 


Dimension 


Text height 


Height of widget 


XtNin sensitive- 


Pixmap 


Gray 


Border when not sensitive 


Border 








XtNinternal- 


Dimension 


2 


See note 


Height 








XtNinternalWidth 


Dimension 


4 


See note 


XtNjustify 


XtJustify 


Xt JustifyCenter 


Type of text alignment 


XtNlabel 


String 


Label name 


String to be displayed 



370 



X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets 



(continued) 



Label 



Name 


Class Type 


Default 


Description 


XtNmappedWhen- 
Managed 


Boolean 


TRUE 


Whether XtMapWidget is auto 
matic 


XtNresize 


Boolean 


TRUE 


Whether to auto-resize in Set- 








Values 


XtNsensitive 
XtNwidth 
XtNx 
XtNy 


Boolean 
Dimension 
Position 
Position 


TRUE 

Text width 





Whether widget receives input 
Width of widget 
x coordinate in pixels 
y coordinate in pixels 



Note that the Label widget supports only the xtNdestroyCallback callback list. 
The new resources associated with Label are: 

xtNbitmap Specifies a bitmap to display in place of the text label. The bitmap can be 

specified as a string in the resource data base. The StringToPixmap con 
verter will interpret the string as the name of a file in the bitmap utility for 
mat that is to be loaded into a pixmap. The string can be an absolute or a rel 
ative filename. If a relative filename is used, the directory specified by the 
resource name bitmapFilePath or the resource class BitmapFile- 
Path is added to the beginning of the specified filename. If the bitmap 
FilePath resource is not defined, the default directory on a UNIX-based 
system is lusrlincluddXl 1 /bitmaps . 

xtNheight Specifies the height of the Label widget The default value is the minimum 

height that will contain: 

XtNinternalheight + height of XtN label + XtNinternalHeight 

If the specified height is larger than the minimum, the label string is centered 
vertically. 

XtNinternalHeight 

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

XtNinternalWidth 

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

XtN justify Specifies left, center, or right alignment of the label string within the Label 
widget. If it is specified within an ArgList, one of the values Xt- 
JustifyLeft, Xt JustifyCenter, or Xt Justif yRight can be 
specified. In a resource of type string, one of the values left, center, or 
right can be specified. 

XtN label Specifies the text string that is to be displayed in the button if no bitmap is 

specified. The default is the widget name of the Label widget. 



X Toolkit Intrinsics Reference Manual 



371 



Label 



(continued) 



Xt - Athena Widgets 



xtNresize Specifies whether the Label widget should attempt to resize to its preferred 

dimensions whenever XtSetValues is called for it. 

xtNsensitive If set to FALSE, the Label widget will change its window border to Xt- 
NinsensitiveBorder and will stipple the label string. 

xtNwidth Specifies the width of the Label widget. The default value is the minimum 

width that will contain: 

XtNinternalWidth + width of XtNlabel + XtNinternalWidth 

If the width is larger or smaller than the minimum, xtN justify deter 
mines how the label string is aligned. 

Programmatic Interface 

To create a Label widget instance, use xtCreateWidget and specify the class variable 

labelWidgetClass. 

To destroy a Label widget instance, use xtDestroyWidget and specify the widget ID 
of the label. 



372 



X Toolkit Intrinsics Reference Manual 



Xt- Athena Widgets- 



List 



Name 

HstWidgetClass widget for managing row-column geometry. 

Synopsis 

#include <Xll/StringDef s .h> 

tinclude <Xll/Intrinsic ,h> 

#include <Xll/XawMisc .h> 

tinclude <Xll/List.h> 

widget = XtCreateWidget (widget, listWidgetClass, 



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



Class Hierarchy 

Core > Simple > Grip 

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: 



Name 


Type 


Default 


Description 


XtNbackground 


Pixel 


XtDefault- 


Window background color 






Background 




XtNbackground- 


Pixmap 


None 


Window background pixmap 


Pixmap 








XtNborderColor 


Pixel 


XtDefault- 


Window border color 






Foreground 




XtNborderPixmap 


Pixmap 


None 


Window border pixmap 


XtNborderWidth 


Dimension 


1 


Width of border 


XtNcallback 


XtCallbackList 


NULL 


Selection callback function 


XtNcolumn Spacing 


Dimension 


6 


Space between columns in the list 


XtNcursor 


Cursor 


left_ptr 


Pointer cursor 


XtNde fault Columns 


int 


2 


Number of columns to use 


XtNdestroy- 


XtCallbackList 


NULL 


Callbacks forXtDestroyWidget 


Callback 








XtNfont 


XFontStruct* 


XtDefaultFont 


Font for list text 


XtNforceColumns 


Boolean 


FALSE 


Force the use of XtNdef ault- 








Columns 


XtNforeground 


Pixel 


XtDefault- 


Foreground (text) color 






Foreground 




XtNheight 


Dimension 


Contains list 


Height of widget 






exactly 




XtNin sensitive- 


Pixmap 


Gray 


Border when not sensitive 


Border 









X Toolkit Intrinsics Reference Manual 



373 



List 



(continued) 



Xt - Athena Widgets 



Name 


Type 


Default 


Description 


XtNinternalHeight 


Dimension 


2 


Spacing between list and widget 








edges 


XtNinternalWidth 


Dimension 


4 


Spacing between list and widget 








edges 


XtNlist 


String * 


List name 


An array of strings that is the list 


XtNlongest 


int 


Longest item 


Length of the longest list item 








in pixels 


XtNmappedWhen- 


Boolean 


TRUE 


Whether XtMapWidget is automatic 


Managed 








XtNnumber Strings 


int 


Number of 


Number of items in the list 






strings 




XtNpasteBuf fer 


Boolean 


FALSE 


Copy the selected item to cut buffer 


XtNrowSpacing 


Dimension 


4 


Space between rows in the list 


XtNsensitive 


Boolean 


TRUE 


Whether widget receives input 


XtNtranslations 


Translation- 


None 


Event-to-action translations 




Table 






XtNverticalList 


Boolean 


FALSE 


Specify the layout of list items 


XtNwidth 


Dimension 


Contains list 


Width of widget 






exactly 




XtNx 


Position 





Widget x coordinate 


XtNy 


Position 





Widget y coordinate 



The new resources associated with the List widget are: 



XtNcolumnSpacing 
XtNrowSpacing 

XtNdefaultColumns 



XtNf orceColumns 



XtNheight 



XtNinternalHeight 



XtNinternalWidth 



XtNlist 



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

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 
Nf orceColumns is TRUE. 

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

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

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

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

Specifies the array of text strings that is to displayed in the List 
widget. If the default for xtNnumberSt rings is used, the list must 



374 



X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets 



(continued) 



List 



XtNlongest 



XtNnumberSt rings 



XtNpasteBuffer 



XtNsensitive 



XtNverticalList 



XtNwidth 



be NULL-terminated. If a value is not specified for the list, the number 
of strings is set to 1, and the name of the widget is used as the list. 

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

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

If this is TRUE, then the value of the string selected will be put into X 
cut buffer 0. 

If set to FALSE, the List widget will change its window border to xt- 
NinsensitiveBorder and display all items in the list as stippled 
strings. While the List widget is insensitive, no item in the list can be 
selected or highlighted. 

If this is TRUE, the elements in the list are arranged vertically; if 
FALSE, the elements are arranged horizontally. 

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

Translations and Actions 

The List widget has three predefined actions: Set, Unset, and Notify. Set and Unset allow 
switching the foreground and background colors for the current list item. Notify allows pro 
cessing application callbacks. 

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

<BtnlDown>, <BtnlUp> : Set ( ) Notify ( ) 

Programmatic Interface 

To create a List widget instance, use xtCreateWidget and specify the class variable 

listwidget Class. 

To destroy a List widget instance, use XtDestroyWidget and specify the widget ID of 
the List widget. 

The List widget supports two callback lists: 

XtNdestroyCallback 

XtNcallback 

The notify action executes the callbacks on the the XtNcallback list. 

The call_data argument passed to callbacks on the XtNcallback list is a pointer to an 
XtListReturnStruct structure, defined in <X1 I/List. h>: 

typedef struct _XtListReturnStruct { 

String string; /* string shown in the list */ 



X Toolkit Intrinsics Reference Manual 



375 



List 



(continued) 



Xt - Athena Widgets 



int index; 
} XtListReturnStruct; 



/* index of the item selected */ 



To change the list of strings that is displayed, use: 

void XtListChange (w, list, nitems, longest, resize) 
Widget w; 
String * list; 
int nitems, longest; 
Boolean resize; 

where: 

w Specifies the widget ID. 

list Specifies the new list for the list widget to display. 

nitems Specifies the number of items in the list. If a value less than 1 is speci 
fied, list must be NULL -terminated. 

longest Specifies the length of the longest item in the list in pixels. If a value 
less than 1 is specified, the List widget calculates the value for you. 

resi ze Specifies a Boolean value that indicates whether the List widget should 
try to resize itself (TRUE) or not (FALSE) after making the change. 
Note that the constraints of the parent of this widget are always 
enforced, regardless of the value specified. 

To highlight an item in the list, use: 

void XtListHighlight (w, item); 
Widget w; 
int item; 

where: 

w Specifies the widget ID. 

item Specifies the index into the current list that indicates the item to be 

highlighted. 

Only one item can be highlighted at a time. If an item is already highlighted when Xt 
ListHighlight is called, the highlighted item is immediately unhighlighted and the 
new item is highlighted. 

To unhighlight the currently highlighted item in the list, use: 

void XtListUnhightlight (w) ; 
Widget w; 

where w specifies the widget ID. 
To retrieve an item in the list, use: 

XtListReturnStruct *XtListShowCurrent ( w) ; 
Widget w; 

where w specifies the widget ID. 



376 



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 \ 

v Xt - Athena Widgets 

Name 

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

Synopsis 

#include <Xll/StringDef s .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 used 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, client_data, and the current relative position of 
the thumb. When the thumb is moved using pointer button 2, the callback procedure is invoked 
continuously. When either button 1 or 3 is pressed, the callback procedure is invoked only 
when the button is released and the client callback procedure is responsible for moving the 
thumb. 

Resources 

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



378 X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets 



(continued) 



Scrollbar 



Name 


Type 


Default 


Description 


XtNbackground 


Pixel 


White 


Window background color 


XtNbackground- 
Pixmap 


Pixmap 


None 


Window background pixmap 


XtNborderColor 


Pixel 


XtDefault- 


Window border color 






Foreground 




XtNborderPixmap 


Pixmap 


None 


Window border pixmap 


XtNborderWidth 


Dimension 


1 


Width of button border 


XtNdestroy- 


XtCallbackList 


NULL 


Callbacks forXtDestroyWidget 


Callback 








XtNforeground 


Pixel 


Black 


Thumb color 


XtNheight 


Dimension 


See below 


Height of scroll bar 


XtN jumpProc 


XtCallbackList 


NULL 


Callback for thumb select 


XtNlength 


Dimension 


None 


Major dimension (height of 








Xt orient Vertical) 


XtNmappedWhen- 


Boolean 


TRUE 


Whether XtMapWidget is auto 


Managed 






matic 


Xt Nor lent at ion 


XtOrientation 


Xt or lent Vertical 


Orientation (vertical or horizon 








tal) 


XtNscrollDCursor 


Cursor 


XC_sb_down arrow 


Cursor for scrolling down 


XtNscrollHCursor 


Cursor 


XC_sb_h_double 


Idle horizontal cursor 






arrow 




XtNscrollLCursor 


Cursor 


XC_sb_left_arrow 


Cursor for scrolling left 


XtNscrollProc 


XtCallbackList 


NULL 


Callback for the slide region 


XtNscrollRCursor 


Cursor 


XC_sb_right arrow 


Cursor for scrolling right 


XtNscrollUCursor 


Cursor 


XC_sb_up arrow 


Cursor for scrolling up 


XtNscrollVCursor 


Cursor 


XC_sb_v_double 


Idle vertical cursor 






arrow 




XtNsensitive 


Boolean 


TRUE 


Whether widget receives input 


XtNshown 


float 


NULL 


Percentage the thumb covers 


XtNthickness 


Dimension 


14 


Minor dimension (height if 








Xt orient Horizontal) 


XtNthumb 


Pixmap 


Gray 


Thump pixmap 


XtNtop 


float 


NULL 


Position on scroll bar 


XtNtranslations 


Translation- 


See below 


Event-to-action translations 




Table 






XtNwidth 


Dimension 


See below 


Width of scroll bar 


XtNx 


Position 


NULL 


x position of scroll bar 


XtNy 


Position 


NULL 


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 

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

Scrollbar. 

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

Translations and Actions 

The actions supported by the Scrollbar widget are: 

StartScroll(va-Zue) 

The possible values are Forward, Backward, or Continuous. This must 
be the first action to begin a new movement. 

NotifyScroll(value) 

The possible values are Proportional or FullLength. If the argument 
to StartScroll was Forwarder Backward, Not if yScroll executes 
the xtNscrollProc callbacks and passes either the position of the pointer 
if its argument is Proportional or the full length of the scroll bar if its 
argument is FullLength. If the argument to StartScroll was Con 
tinuous, Notif yScroll returns without executing any callbacks. 

EndScrollQ This must be the last action after a movement is complete. 
MoveThumbQ Repositions the scroll bar thumb to the current pointer location. 

NotifyThumbQ 

Calls the XtNjumpProc callbacks and passes the relative position of the 
pointer as a percentage of the scroll bar length. 

The default bindings for Scrollbar are: 

<BtnlDown>: StartScroll (Forward) 

<Btn2Down>: StartScroll (Continuous) MoveThumb ( ) Notif yThumb () 

<Btn3Down> : StartScroll (Backward) 

<Btn2Motion>: MoveThumb ( ) Not if yThumb ( ) 

<BtnUp> :NotifyScroll (Proportional) EndScroll ( ) 

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

*Scrollbar. Translations: \\e 

~Meta<KeyPress>space : StartScroll (Forward) NotifyScroll (FullLength) \\e 
Meta<KeyPress>space : StartScroll (Backward) NotifyScroll (FullLength) \\e 
EndScroll ( ) 

Programmatic Interface 

To create a Scrollbar widget instance, use xtCreateWidget and specify the class vari 
able scrollbarWidgetClass. 

To destroy a Scrollbar widget instance, use xtDestroyWidget and specify the widget 
ID for the Scrollbar. 

The XtNscrollProc callback is used for incremental scrolling and is called by the 
NotifyScroll action. XtNscrollProc looks like this: 



380 X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets (continued) Scrollbar 

void ScrollProc (scrollbar, client_data, position) 
Widget scrollbar; 
caddr_t client_data; 
caddr_t position; /* int */ 

where: 

scrollbar Specifies the ID of the Scrollbar. 

cl ient_data Specifies the client data. 

posi ti on Returns the pixel position of the thumb in integer form. 

position is a signed quantity and should be cast to an int when used. Using the 
default button bindings, button 1 returns a positive value, and button 3 returns a negative 
value. In both cases, the magnitude of the value is the distance of the pointer in pixels 
from the top (or left) of the Scrollbar. The value will never be less than zero or greater 
than the length of the Scrollbar. 

The xtN jumpProc callback is used for jump scrolling and is called by the Not if y- 
Thumb action. The XtN jumpProc callback procedure looks like this: 

void JumpProc (scrollbar, client_data, percent) 
Widget scrollbar; 
caddr_t clie/3t_data; 
caddr_t percent_ptr; /* float* */ 

where: 

scrollbar Specifies the ID of the scroll bar window. 

cl i en t_da t a Specifies the client data. 

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

The xtN jumpProc callback is used to implement smooth scrolling and is called by the 
Notif yThumb action. percent_ptr must be cast to a pointer to float before use: 

float percent = * (float*) percent_ptr; 

With the default button bindings, button 2 moves the thumb interactively, and the xt- 
N jumpProc is called on each new position of the pointer. 

An older interface used xtNthumbProc and passed the percentage by value rather than 
by reference. This interface is not portable across machine architectures; therefore, it is no 
longer supported. This interface is still implemented for those (nonportable) applications 
that used it 

To set the position and length of a Scrollbar thumb, use xtScrollbarSetThumb: 

void XtScrollbarSetThumb ( w, top, shown) 
Widget w; 
float top; 
float shown; 

where: 



X Toolkit Intrinsics Reference Manual 381 



Scrollbar 



(continued) 



Xt - Athena Widgets 



w Specifies the Scrollbar widget ID. 

t op 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. 

Xt Scrollbar Thumb 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 



Xt- Athena Widgets Template 

Name 

templateWidgetClass widget to create a custom widget. 

Synopsis 

#include <Xll/StringDef s . h> 

^include <Xll/Intrinsic .h> 

#include <Xll/XawMisc .h> /* <Xll/Misc.h> in R2 */ 

^include <Xll/Template .h> 

Description 

Although the task of creating a new widget may at first appear a little daunting, there is a basic 
pattern that all widgets follow. The Athena widget library contains three files that are intended 
to assist in writing a custom widget: Template. h, Template?. h, and Templates. 

Reasons for wishing to write a custom widget include: 

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

Convenient access to user input dispatch and translation management procedures. 

Access to callback mechanism for building higher-level application libraries. 

Customizing the interface or behavior of an existing widget to suit a special application 
need. 

Desire to allow user customization of resources such as fonts, colors, etc., or to allow con 
venient re-binding of keys and buttons to internal functions. 

Converting a non-Toolkit application to use the Toolkit. 

In each of these cases, the operation needed to create a new widget is to "subclass" an existing 
one. If the desired semantics of the new widget are similar to an existing one, then the imple 
mentation of the existing widget should be examined to see how much work would be required 
to create a subclass that will then be able to share the existing class methods. Much time will 
be saved in writing the new widget if an existing widget class Expose, Resize and/or 
GeometryManager method can be shared by the subclass. 

Note that some trivial uses of a "bare-bones" widget may be achieved by simply creating an 
instance of the Core widget. The class variable to use when creating a Core widget is 
widgetClass. The geometry of the Core widget is determined entirely by the parent widget. 

It is very often the case that an application will have a special need for a certain set of functions 
and that many copies of these functions will be needed. For example, when converting an older 
application to use the Toolkit, it may be desirable to have a "Window widget" class that might 
have the following semantics: 

Allocate two drawing colors in addition to a background color. 

Allocate a text font. 



X Toolkit Intrinsics Reference Manual 333 



Template (continued) Xt- Athena Widgets 

Execute an application-supplied function to handle exposure events. 

Execute an application-supplied function to handle user input events. 

It is obvious that a completely general-purpose windowwidget Class could be constructed 
that would export all class methods as callback lists, but such a widget would be very large and 
would have to choose some arbitrary number of resources such as colors to allocate. An appli 
cation that used many instances of the general-purpose widget would therefore unnecessarily 
waste many resources. 

In this section, an outline will be given of the procedure to follow to construct a special-pur 
pose widget to address the items listed above. The reader should refer to the appropriate sec 
tions of Volume Four, X Toolkit Intrinsics Programming Manual, for complete details of the 
material outlined here. 

All Athena widgets have three separate files associated with them: 

A public header file containing declarations needed by applications programmers. 

A private header file containing additional declarations needed by the widget and any sub 
classes. 



A source code file containing the implementation of the widget. 



This separation of functions into three files is suggested for all widgets, but nothing in the 
Toolkit actually requires this format. In particular, a private widget created for a single applica 
tion may easily combine the public and private header files into a single file, or merge the con 
tents into another application header file. Similarly, the widget implementation can be merged 
into other application code. 

In the following example, the public header file <X 11 /Template. h>, the private header file 
<X 11 /Template P. h> and the source code file <X 11 /Template. c> will be modified to produce the 
Window widget described above. In each case, the files have been designed so that you can 
make a global string replacement of Template and template with the name of your new widget, 
using the appropriate case. 

Public Header File 

The public header file contains declarations that will be required by any application module 
that needs to refer to the widget; whether to create an instance of the class, to perform an xt - 
Setvalues operation, or to call a public routine implemented by the widget class. 

The contents of the Template public header file, < XI 1 /Template. h>, are: 

#include <X1 I/copyright . h> 

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

#ifndef _Template_h 
tdefine _Template_h 

/**************************************************************** 
* 
* Template widget 

384 X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets 



(continued) 



Template 












/* Resources: 








Name 


Class 


RepType 


Default Value 


background 


Background 


Pixel 


XtDefault Background 


border 


BorderColor 


Pixel 


Xt Default Foreground 


borderWidth 


BorderWidth 


Dimension 


1 


destroyCallback 


Callback 


Pointer 


NULL 


height 


Height 


Dimension 





mappedWhenManaged 


MappedWhenManaged 


Boolean 


TRUE 


sensitive 


Sensitive 


Boolean 


TRUE 


width 


Width 


Dimension 





X 


Position 


Position 





y 


Position 


Position 





*/ 









/* define any special resource names here * 
* that are not in <Xll/StringDef s .h> */ 

#define XtNtemplateResource "templateResource" 

tdefine XtCTemplateResource "TemplateResource" 

/* declare specific TemplateWidget class and instance datatypes */ 



typedef struct _TemplateClassRec* 
typedef struct TemplateRec* 



TemplateWidget Class ; 
TemplateWidget ; 



/* declare the class constant */ 
extern WidgetClass templateWidgetClass; 
#endif _Template_h 

You will notice that most of this file is documentation. The crucial parts are the last 8 lines 
where macros for any private resource names and classes are defined and where the widget 
class datatypes and class record pointer are declared. 

For the Window widget, we want two drawing colors, a callback list for user input and an Xt - 
NexposeCallback, callback list, and we will declare three convenience procedures, so we 
need to add: 



/* Resources: 

callback 

drawingColorl 

drawingColor2 

exposeCallback 

font 

*/ 



Callback 

Color 

Color 

Callback 

Font 



Callback 

Pixel 

Pixel 

Callback 

XFontStruct ; 



NULL 

Xt Default Foreground 

XtDefault Foreground 

NULL 

XtDefaultFont 



X Toolkit Intrinsics Reference Manual 



385 



Template (continued) Xt- Athena Widgets 

#define XtNdrawingColorl "drawingColorl" 
tdefine XtNdrawingColor2 "drawingColor2" 
#define XtNexposeCallback "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 data that will be required by anticipated subclasses of the 
widget. Information in the private header file is normally hidden from the application and is 
designed to be accessed only through other public procedures, such as Xt Set Values. 

The contents of the Template private header file, <X 11 /Template P. h>, are: 

#include <X1 I/copyright . h> 

/* XConsortium: Template? .h, v 1.2 88/10/25 17:31:47 swick Exp $ */ 
/* Copyright Massachusetts Institute of Technology 1987, 1988 */ 

tifndef _TemplateP_h 
#define _TemplateP_h 

#include "Template. h" 

/* include superclass private header file */ 

tinclude <Xll/CoreP .h> 

/* define unique representation types not found in <Xll/StringDef s . h> */ 
tdefine XtRTemplateResource "TemplateResource" 

typedef struct { 

int empty; 
} TemplateClassPart; 

typedef struct _TemplateClassRec { 

CoreClassPart core_class; 

TemplateClassPart template_class; 
} TemplateClassRec; 

extern TemplateClassRec templateClassRec; 

typedef struct { 

/* resources */ 

char* resource; 

/* private state */ 
} TemplatePart; 

typedef struct _TemplateRec { 
386 X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets (continued) Template 

CorePart core; 

TemplatePart template; 
} TemplateRec; 

#endif _TemplateP_h 

The private header file includes the private header file of its superclass, thereby exposing the 
entire internal structure of the widget. It may not always be advantageous to do this; your own 
project development style will dictate the appropriate level of detail to expose in each module. 

The Window widget needs to declare two fields in its instance structure to hold the drawing 
colors, a resource field for the font and a field for the expose and user input callback lists: 

typedef struct { 

/* resources */ 

Pixel color_l; 

Pixel color_2; 

XFont Struct* font; 

XtCallbackList expose_callback; 

XtCallbackList input_callback; 

/* private state */ 

/* (none) */ 
} WindowPart; 

Widget Source File 

The source code file implements the widget class itself. The unique part of this file is the decla 
ration and initialization of the widget class record structure and the declaration of all resources 
and action routines added by the widget class. 

The contents of the Template implementation file, <X 11 /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> 
tinclude <Xll/StringDef s .h> 
tinclude "Template? . h" 

static XtResource resources [] = { 

tdefine of f set (field) XtOf f set (TemplateWidget, template . field) 

/* {name, class, type, size, offset, default_type, default_addr } , */ 

{ XtNtemplateResource, XtCTemplateResource, XtRTemplateResource, \\e 

sizeof (char*) , of f set (resource) , XtRString, "default" }, 

tundef offset 

}; 

static void TemplateAction (/* Widget, XEvent*, String*, Cardinal* */) ; 

static XtActionsRec actions [] = 
{ 

/* {name, procedure}, */ 



X Toolkit Intrinsics Reference Manual 387 



Template (continued) 

{"template", TemplateAction}, 



Xt - Athena Widgets 



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) SwidgetClassRec, 

"Template", 

sizeof (TemplateRec) , 

NULL, 

NULL, 

FALSE, 

NULL, 

NULL, 

XtlnheritRealize, 

actions, 

XtNumber (actions) , 

resources, 

XtNumber (resources) , 

NULLQUARK, 

TRUE, 

TRUE, 

TRUE, 

FALSE, 

NULL, 

NULL, 

NULL, 

NULL, 

NULL, 

Xt Inherit SetValuesAlmost, 

NULL, 

NULL, 

XtVersion, 

NULL, 

translations, 

XtlnheritQueryGeometry, 

XtlnheritDisplayAccelerator, 

NULL 



WidgetClass templateWidgetClass = (WidgetClass) StemplateClassRec; 



388 



X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets (continued) Template 

The resource list for the Window widget might look like the following: 

static XtResource resources [] = { 

#define of f set (field) XtOf f set (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, XtRFont Struct, sizeof (XFontStruct*) , 

offset (font) , XtRString, XtDefaultFont }, 
{ XtNexposeCallback, XtCCallback, XtRCallback, sizeof (XtCallbackList) , 

offset (expose_callback) , XtRCallback, NULL }, 
{ XtNcallback, XtCCallback, XtRCallback, sizeof (XtCallbackList ), 

offset (input_callback) , XtRCallback, NULL }, 
#undef offset 
}; 

The user input callback will be implemented by an action procedure that passes the event 
pointer as cal l_data. The action procedure is declared as: 

/* ARGSUSED */ 

static void InputAction (w, event, params, num_params) 

Widget w; 

XEvent *event; 

String *params;/* unused */ 

Cardinal *num_params; /* unused */ 
{ 

XtCallCallbacks(w, XtNcallback, (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 



Template (continued) Xt - Athena Widgets 

{ 

XtCallCallbacks (w, XtNexposeCallback, (caddr_t) region) ; 
} 
WindowClassRec windowClassRec = { 

/* expose */ Redisplay, 

The Window widget will also declare three public procedures to return the drawing colors and 
the font ID, saving the application the effort of constructing an argument list for a call to xt- 

GetValues: 

Pixel WindowColorl (w) 

Widget w; 
{ 

return ( (WindowWidget) w) -> window. col or_l; 
} 

Pixel WindowColor2 (w) 

Widget w; 
{ 

return ( (WindowWidget) w) ->window.color_2; 
} 

Font WindowFont (w) 

Widget w; 
{ 

return ( (WindowWidget) w) ->window. font->f id; 
} 

The Window widget is now complete. The application can retrieve the two drawing colors 
from the widget instance by calling either xtGetValues, or the windowColor functions. 
The actual window created for the Window widget is available by calling the Xtwindow func 
tion. 



390 X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets 

Name 

textWidgetClass text-editing widget. 

Synopsis 

#include <Xll/StringDef s .h> 

tinclude <Xll/Intrinsic .h> 

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

#include <Xll/Text.h> 

widget = XtCreateWidget (widget, textWidgetClass , . . . ); 

widget = XtCreateWidget (widget, asciiStringWidgetClass, . . . ) ; 

widget = XtCreateWidget (widget, asciiDiskWidgetClass, . . . ); 

Class Hierarchy 

Core - Simple > Text > asciiString 
Core > Simple > Text > asciiDisk 

Description 

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

The Text widget is divided into three parts: 

Source 

Sink 

Text widget 

The idea is to separate the storage of the text (source) from the painting of the text (sink). The 
Text widget proper coordinates the sources and sinks. There are subclasses of the Text widget 
that automatically create the source and sink for the client. Widgets of class asciiString 
WidgetClass use a string in memory as the source; asciiDiskWidgetClass widgets 
use a disk file. Both use a single-font, single-color ASCII sink. A client can, if it so chooses, 
explicitly create the source and sink before creating the Text widget. 

The source stores and manipulates the text, and determines what editing functions may be per 
formed on the text. 

The sink obtains the fonts and the colors in which to paint the text. The sink also computes 
what text can fit on each line. 

If a disk file is used as the source, two edit modes are available: 

Append 

Read-only 

Append mode lets the user enter text into the window, while read-only mode does not. Text 
may only be entered if the insertion point is after the last character in the window. 



X Toolkit Intrinsics Reference Manual 391 



Text 



(continued) 



Xt - Athena Widgets 



If a string in memory is used as the source, the application must allocate the amount of space 
needed. Three types of edit mode are available: 

Append-only 

Read-only 

Editable 

The first two modes are the same as displaying text from a disk file. Editable mode lets the user 
place the cursor anywhere in the text and modify the text at that position. The text cursor posi 
tion can be modified by using the keystrokes or pointer buttons defined by the event bindings. 
(See Translations and Actions below.) 

Resources 

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



Name 


Type 


Default 


Description 


XtNbackground 


Pixel 


XtDefault- 


Window background color 






Background 




XtNbackground- 


Pixmap 


None 


Window background pixmap 


Pixmap 








XtNborderColor 


Pixel 


XtDefault- 


Window border color 






Foreground 




XtNborderPixmap 


Pixmap 


None 


Window border pixmap 


XtNborderWidth 


Dimension 


4 


Border width in pixels 


XtNcursor 


Cursor 


XC xterm 


Pointer cursor 


XtNdialogHOffset 


int 


10 


Offset of insert file dialog 


XtNdialogVOffset 


int 


10 


Offset of insert file dialog 


XtNdestroy- 


XtCallbackList 


NULL 


Callbacks forxtDestroyWidget 


Callback 








XtNdisplayPosition 


int 





Character position of first line 


XtNeditType 


XtEditType 


XttextRead 


Edit mode (see note) 


XtNfile 


char* 


tmpnam( ) 


File for asciiDiskWidgetClass 


XtN foreground 


Pixel 


Black 


Foreground color 


XtNfont 


XFontStruct* 


Fixed 


Fontname 


XtNheight 


Dimension 


Font height 


Height of widget 


XtNinsertPosition 


int 





Character position of caret 


XtNleftMargin 


Dimension 


2 


Left margin in pixels 


XtNlength 


int 


String length 


Size of the string buffer 


XtNmappedWhen- 


Boolean 


TRUE 


Whether XtMapWidget is auto 


Managed 






matic 


XtNselect Types 


Xt Text Select Type* 


See below 


Selection units for multi-click 


XtNsensitive 


Boolean 


TRUE 


Whether widget receives input 


XtNstring 


char* 


Blank 


String for asciiStringWidget- 








Class 


XtNtextOptions 


int 


None 


See below 


XtNtextSink 


XtTextSink 


None 


See below 



392 



X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets 



(continued) 



Text 



Name 


Type 


Default 


Description 


XtNtextSource 


XtTextSource 


None 


See below 


XtNtranslations 


Trans 1 at ionTable 


See above 


event-to-action translations 


XtNwidth 


Dimension 


100 


Width of widget (pixels) 


XtNx 


Position 





x coordinate in pixels 


XtNy 


Position 





y coordinate in pixels 



Note that: 
1. 



2. 



3. 



You cannot use XtNeditType, XtNf ile, XtNlength, and XtNfont with the Xt- 
TextSetValues and the xtTextGetValues calls. 

The XtNeditType attribute has one of the values xttext Append, XttextEdit, or 
XttextRead. 

If asciiStringWidgetClass is used, the resource XtNstring specifies a buffer 
containing the text to be displayed and edited, asciistringwidget does not copy 
this buffer but uses it in place. 

Text Options 

The options for the XtNtext Options attribute are: 

Whether or not the user is allowed to modify the text 

Makes a request to the parent widget to lengthen the window if all the 
text cannot fit in the window. 

Makes a request to the parent widget to widen the window if the text 
becomes too long to fit on one line. 

Puts a scroll bar on the top of the window. 



editable 
resizeHeight 

resizeWidth 



scrollHorizontal 
scrollOnOverflow 



Automatically scrolls the text up when new text is entered below the 
bottom (last) line. 



scrollVertical 
wordBreak 



Puts a scroll bar on the left side of the window. 

Starts a new line when a word does not fit on the current line. 
These options can be ORed together to set more than one at the same time. 
Selections 

XtNselectionTypes is an array of entries of type xtTextSelectType and is used for 
multiclick. As the pointer button is clicked in rapid succession, each click highlights the next 
"type" described in the array. 

XtselectAll Selects the contents of the entire buffer. 

xtseiectchar Selects text characters as the pointer moves over them. 

xtselectLine Selects the entire line. 

xtselectNull Indicates the end of the selection array. 



X Toolkit Intrinsics Reference Manual 



393 



Text 



(continued) 



Xt - Athena Widgets 



Xt select Paragraph 
Xt select Posit ion 
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 default select Type 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 


Delete 


forward-character 


delete-next-character 


backward-character 


delete-previous-character 


forward-word 


delete-next-word 


backward-word 


delete-previous- word 


forward-paragraph 


delete-selection 


backward-paragraph 




beginning-of-line 




end-of-line 


Selection 


next-line 


select-word 


previous-line 


select-all 


next-page 


select-start 


previous-page 


select-adjust 


beginning-of-file 


select-end 


end-of-file 


extend-start 


scroll-one-line-up 


extend-adjust 


scroll-one-line-down 


extend-end 


New Line 


Miscellaneous 


newline-and-indent 


redraw-display 


newline-and-backup 


insert-file 


newline 


do-nothing 


Kill 


Unkill 


kill-word 


until! 


backward-kill-word 


stuff 


kill-selection 


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: 

Ctrl<Key>B: 

Ctrl<Key>D: 

Ctrl<Key>A: 

Ctrl<Key>E: 

Ctrl<Key>H: 

Ctrl<Key>J: 

CtrKKey>K: 

Ctrl<Key>L: 

Ctrl<Key>M: 

Ctrl<Key>N: 

Ctrl<Key>0: 

Ctrl<Key>P: 

CtrKKey>V: 

Ctrl<Key>W: 

CtrKKey>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>] : 



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\ 



X Toolkit Intrinsics Reference Manual 



395 



Text (continued) Xt - Athena Widgets 

:Meta<Key>[: backward-paragraph () \n\ 

Shift Meta<Key>Delete : delete-previous-word ( ) \n\ 

Shift Meta<Key>Delete: backward-kill-word () \n\ 
"Shift Meta<Key>Backspace : delete-previous-word () \n\ 

Shift Meta<Key>Backspace: backward-kill-word () \n\ 
<Key>Right : f orward-character ( ) \n\ 

<Key>Left: backward-character () \n\ 

<Key>Down : next-line () \n\ 

<Key>Up : previous-line () \n\ 

<Key>Delete: delete-previous-character () \n\ 
<Key>BackSpace : delete-previous-character () \n\ 
<Key>Linefeed: newline-and-indent ( ) \n\ 
<Key>Return: newline ( ) \n\ 
<Key> : insert-char () \n\ 

<FocusIn>: f ocus-in ( ) \n\ 

<FocusOut>: f ocus-out ( } \n\ 

<BtnlDown>: select-start () \n\ 

<BtnlMotion>: extend-ad just { ) \n\ 

<BtnlUp>: extend-end (PRIMARY, CUT_BUFFERO) \n\ 

<Btn2Down>: insert-selection (PRIMARY, CUT_BUFFERO) \n\ 

<Btn3Down>: extend-start ( ) \n\ 

<Btn3Motion>: extend-ad just () \n\ 
<Btn3Up>: extend-end (PRIMARY, CUT_BUFFERO) \ 

A user-supplied resource entry can use application-specific bindings, a subset of the supplied 
default bindings, or both. The following is an example of a user-supplied resource entry that 
uses a subset of the default bindings: 

Xmh*Text .Translations: \\e 

<Key>Right : f orward-character () \\en\\e 

<Key>Left: backward-character () \\en\\e 

Meta<Key>F: forward-word () \\en\\e 

Meta<Key>B: backward-word () \\en\\e 

:Meta<Key>] : forward-paragraph () \\en\\e 

:Meta<Key>[: backward-paragraph () \\en\\e 

<Key>: insert-char () 

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

*Text .Translations: #override \\e 

Buttonl <Btn2Down>: extend-end (CLIPBOARD) 

The Text widget fully supports the X selection and cut buffer mechanisms. The following 
actions can be used to specify button bindings that will cause Text to assert ownership of one or 
more selections, to store the selected text into a cut buffer, and to retrieve the value of a selec 
tion or cut buffer and insert it into the text value. 

insert-selection(na/ne[,na/ne, . . . ]) 

Retrieves the value of the first (left-most) named selection that exists or the cut 
buffer that is not empty and inserts it into the input stream. The specified name can 



396 X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets (continued) Text 

be that of any selection (for example, PRIMARY or SECONDARY) or a cut buffer (i.e., 
CUT_BUFFERO through CUT_BUFFER7). Note that case matters. 

select-startQ 

Unselects any previously selected text and begins selecting new text. 

select -ad j us t() 
ext end-ad j us t() 

Continues selecting text from the previous start position. 

start-extendQ 

Begins extending the selection from the farthest (left or right) edge. 

select -end(na/ne[,na/ne, . . . ]) 

extend-end(na/ne[,name, . . . ]) 

Ends the text selection, asserts ownership of the specified selection(s) and stores 
the text in the specified cut buffer(s). The specified name can be that of a selection 
(for example, PRIMARY or SECONDARY) or a cut buffer (i.e., CUT_BUFFERO 
through CUT_BUFFER7). Note that case is significant. If CUT_BUFFERO is 
listed, the cut buffers are rotated before storing into buffer 0. 

Programmatic Interface 

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

Display text at a specified position. 
Highlight specified text areas. 
Replace specified text areas. 

The text that is selected within a Text window may be assigned to an X selection or copied into 
a cut buffer and can be retrieved by the application with the Intrinsics xtGet Select ion- 
Value or the Xlib XFetchBytes functions respectively. Several standard selection schemes 
(e.g., character/word/paragraph with multiclick) are supported through the event bindings. 

To create a Text string widget, use xtCreateWidget and specify the class variable 

asc list ringWidget Class. 

To create a Text file widget, use XtCreateWidget and specify the class variable 

asciiDiskWidget Class. 

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

To enable an application to select a piece of text, use xtText Set Select ion. 



X Toolkit Intrinsics Reference Manual 397 



Text (continued) Xt - Athena Widgets 

typedef long XtTextPosition; 

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

where: 

w Specifies the window ID. 

left Specifies the character position at which the selection begins. 

right Specifies the character position at which the selection ends. 

If redisplay is not disabled, this function highlights the text and makes it the PRIMARY 
selection. 

To unhighlight previously highlighted text in a window, useXtTextUnsetSelection. 

void XtTextUnsetSelection (w) 
Widget w; 

To enable the application to get the character positions of the selected text, use Xt Text- 
Get Select ionPos. 

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

where: 

w Specifies the window ID. 

posl Specifies a pointer to the location to which the beginning character 

position of the selection is returned. 

pos2 Specifies a pointer to the location to which the ending character 

position of the selection is returned. 

If the returned values are equal, there is no current selection. 
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 Specifies the window ID. 

start_pos Specifies the starting character position of the text replacement. 

end_pos Specifies the ending character position of the text replacement, 

text Specifies the text to be inserted into the file. 



398 X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets (continued) Text 

The xtTextReplace function deletes text in the specified range (startPos, end- 
Pos) and inserts the new text at start_pos. The return value is XawEditDone if the 
replacement is successful, XawPositionError if the edit mode is XttextAppend 
and start_j3os is not the last character of the source, or XawEditError if either the 
source was read-only or the range to be deleted is larger than the length of the source. 

The XtTextBlock structure (defined in <Xll/Text.h> contains: 

typedef struct { 

int firstPos; 

int length; 

char *ptr; 

Atom format; 
} XtTextBlock, *TextBlockPtr; 

The firstPos field is the starting point to use within the ptr field. The value is usually 
zero. The length field is the number of characters that are transferred from the ptr 
field. The number of characters transferred is usually the number of characters in ptr. 
The format field is not currently used, but should be specified as FMT8BIT. The Xt 
TextReplace arguments start_pos and end_pos represent the text source charac 
ter positions for the existing text that is to be replaced by the text in the xtTextRlock 
structure. The characters from start_pos up to but not including end_pos are 
deleted, and the characters that are specified by the text block are inserted in their place. 
If start_pos and end_pos are equal, no text is deleted and the new text is inserted 
after start_pos. 

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

To redisplay a range of characters, use Xt Text Invalidate. 

void Xt Text Invalidate (w, from, to) 
Widget w; 
XtTextPosition from, to; 

The xtText Invalidate function causes the specified range of characters to be 
redisplayed immediately if redisplay is enabled or the next time that redisplay is enabled. 

To enable redisplay, use XtTextEnableRedisplay. 

void XtTextEnableRedisplay (w) 
Widget w; 

The XtTextEnableRedisplay function flushes any changes due to batched updates 
when xtTextDisableRedisplay was called and allows future changes to be 
reflected immediately. 

To disable redisplay while making several changes, use XtTextDisableRedisplay. 

void XtTextDisableRedisplay (w) 
Widget w, 



X Toolkit Intrinsics Reference Manual 399 



Text (continued) Xt - Athena Widgets 

The XtTextDisableRedisplay function causes all changes to be batched until Xt- 
TextDisplay or xtTextEnableRedisplay is called. 

To display batched updates, use xtTextDisplay. 

void XtTextDisplay (w) 
Widget w; 

The XtTextDisplay function forces any accumulated updates to be displayed. 
To notify the source that the length has been changed, use xtTextSetLastPos. 

void XtTextSetLastPos (w, last); 
Widget w; 
XtTextPosition last; 

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

The following procedures are convenience procedures that replace calls to xtSet- 
Values or xt Get Values when only a single resource is to be modified or retrieved. 

To assign a new value to XtNtextOptions resource, use xtTextChangeOptions. 

void XtTextChangeOptions (w, options) 
Widget w; 
int options; 

To obtain the current value of xtNtextOpt ions for the specified widget, use Xt Text - 
GetOptions. 

int XtTextGetOptions (w) 
Widget w; 

To obtain the character position of the left-most character on the first line displayed in the 
widget (that is, the value of XtNdisplayPosit ion), use Xt Text TopPosit ion. 

XtTextPosition XtTextTopPosition (w) 
Widget w; 

To move the insertion caret to the specified source position, use xt Text Set - 
Insert ionPoint. 

void XtTextSetlnsertionPoint (w, position) 
Widget w; 
XtTextPosition position; 

The text will be scrolled vertically if necessary to make the line containing the insertion 
point visible. The result is equivalent to setting the XtNinsertPosition resource. 

To obtain the current position of the insertion caret, use xtTextGetlnsertionPoint. 

XtTextPosition XtTextGetlnsertionPoint (w) 
Widget w; 

The result is equivalent to retrieving the value of the XtNinsertPosition resource. 



400 X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets (continued) Text 

To replace the text source in the specified widget, use xtText Set Source. 

void XtTextSetSource ( w, source, position) 
Widget w; 

XtTextSource source; 
XtTextPosition position; 

A display update will be performed if redisplay has not been disabled. 

To obtain the current text source for the specified widget, use xtText GetSource. 

XtTextSource XtTextGetSource ( w) 
Widget w; 

Creating Sources and Sinks 

The following functions for creating and destroying text sources and sinks are called automati 
cally by asciiStringWidget and asciiDiskWidget and it is therefore only necessary 
for the client to use them when creating an instance of textwidgetClass. 

To create a new ASCII text sink, use XtAsciiSinkCreate. 

XtTextSink XtAsciiSinkCreate (w, args, num_args) 
Widget w; 
ArgList args; 
Cardinal num_args; 

The resources required by the sink are qualified by the name and class of the parent and 
the sub-part name xtNtextSink and class xtCTextSink. 

To deallocate an ASCII text sink, use XtAsciiSinkDestroy. 

void XtAsciiSinkDestroy (sink) 
XtTextSink sink; 

The sink must not be in use by any widget or an error will result. 
To create a new text disk source, use xtDiskSourceCreate. 

XtTextSource XtDiskSourceCreate ( w, args, num_args) 
Widget w; 
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 deallocate a text disk source, use xtDiskSourceDestroy. 

void XtDiskSourceDestroy (source) 
XtTextSource source; 

The source must not be in use by any widget or an error will result. 

To create a new text string source, use XtStringSourceCreate. 

XtTextSource XtStringSourceCreate (w, args, num_args) 
Widget w; 



X Toolkit Intrinsics Reference Manual 40 1 



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 deallocate a text string source, use XtStringSourceDestroy. 

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- 



Viewport 



Name 

viewportWidgetClass scrollable widget for geometry management. 

Synopsis 

^include <Xll/StringDef s .h> 

#include <Xll/Intrinsic .h> 

tinclude <Xll/XawMisc .h> 

tinclude <Xll/Viewport .h> 

widget = XtCreateWidget ( widget, viewportWidgetClass, 



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



Class Hierarchy 

Core > Composite > Viewport 

Description 

The Viewport widget consists of a frame window, one or two Scrollbars, and an inner window 
(usually containing a child widget). The frame window is determined by the viewing size of 
the data that is to be displayed and the dimensions to which the Viewport is created. The inner 
window is the full size of the data that is to be displayed and is clipped by the frame window. 
The Viewport widget controls the scrolling of the data directly. No application callbacks are 
required for scrolling. 

When the geometry of the frame window is equal in size to the inner window, or when the data 
does not require scrolling, the Viewport widget automatically removes any scroll bars. The 
f orceBars option causes the Viewport widget to display any scroll bar permanently. 

Resources 

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



Name 


Type 


Default 


Description 


XtNallowHoriz 


Boolean 


FALSE 


Flag to allow horizontal scroll bars 


XtNallowVert 


Boolean 


FALSE 


Flag to allow vertical scroll bars 


XtNbackground 


Pixel 


XtDefault- 


Window background color 






Background 




XtNbackground- 


Pixmap 


None 


Window background pixmap 


Pixmap 








XtNborderColor 


Pixel 


XtDefault- 


Window border color 






Foreground 




XtNborderPixmap 


Pixmap 


None 


Window border pixmap 


XtNborderWidth 


Dimension 


1 


Width of the border in pixels 


XtNdestroy- 


XtCallbackList 


NULL 


Callback forXtDestroyWidget 


Callback 








XtNforceBars 


Boolean 


FALSE 


Flag to force display of scroll bars 


XtNheight 


Dimension 


height of 


Height of the widget 






child 





X Toolkit Intrinsics Reference Manual 



403 



Viewport 



(continued) 



Xt - Athena Widgets 



Name 


Type 


Default 


Description 


XtNmappedWhen- 
Managed 


Boolean 


TRUE 


Whether XtMapWidget is automatic 


XtNsensitive 
XtNtranslations 


Boolean 
TranslationTable 


TRUE 

None 


Whether widget should receive input 
Event-to-action translations 


XtNuseBottom 
XtNuseRight 
XtNwidth 


Boolean 
Boolean 
Dimension 


FALSE 
FALSE 
width of 
child 


Flag to indicate bottom/top bars 
Flag to indicate right/left bars 
Width of the widget 


XtNx 

XtNy 


Position 
Position 






x coordinate within parent 
y coordinate within parent 



The Viewport widget manages a single child widget. When the size of the child is larger than 
the size of the Viewport, the user can interactively move the child within the Viewport by repo 
sitioning the Scrollbars. 

The default size of the Viewport before it is realized is the width and/or height of the child. 
After it is realized, the Viewport will allow its child to grow vertically or horizontally if Xt- 
NallowVert or xtNallowHoriz were set, respectively. If the corresponding vertical or 
horizontal scrolling were not enabled, the Viewport will propagate the geometry request to its 
own parent and the child will be allowed to change size only if the (grand) parent allows it. 
Regardless of whether or not scrolling was enabled in the corresponding direction, if the child 
requests a new size smaller than the Viewport size, the change will be allowed only if the par 
ent of the Viewport allows the Viewport to shrink to the appropriate dimension. 

Programmatic interface 

To create a Viewport widget instance, use XtCreateWidget and specify the class vari 
able viewportWidgetClass. 

To insert a child into a Viewport widget, use XtCreateWidget and specify the widget 
ID of the previously created Viewport as the parent. 

To remove a child from a Viewport widget, use XtUnmanageChild or XtDestroy- 
widget and specify the widget ID of the child. 

To delete the inner window, any children, and the frame window, use xtDes troy- 
widget and specify the widget ID of the Viewport widget. 

See Also 

Scrollbar 



404 



X Toolkit Intrinsics Reference Manual 



Xt- Athena Widgets- 



VPaned 



Name 

vPanedWidgetClass 



geometry-managing widget for vertical tiles. 



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



Synopsis 

#include <Xll/StringDef s .h> 

^include <Xll/Intrinsic .h> 

finclude <Xll/XawMisc .h> 

^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 XtNskipAd just constraints on the other panes. With the default 
bindings, button 1 resizes the pane above the selected grip, button 3 resizes the pane below the 
selected grip and button 2 repositions the border between two panes only. 

Resources 

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



Name 


Type 


Default 


Description 


XtNbackground 


Pixel 


XtDefault- 


Window background color 






Background 




XtNbackground- 


Pixmap 


None 


Window background pixmap 


Pixmap 








XtNbetweenCursor 


Cursor 


XC_sb_left_arrow 


Cursor for changing the bound 








ary between two panes 


XtNborderColor 


Pixel 


XtDefault- 


Window border color 






Foreground 




XtNborderPixmap 


Pixmap 


None 


Window border pixmap 


XtNborderWidth 


Dimension 


1 


Border width (pixels) 


XtNdestroy- 


XtCallbackList 


NULL 


Callbacks forxtDestroy- 


Callback 






Widget 


XtN foreground 


Pixel 


Black 


Pixel value for the foreground 








color 



X Toolkit Intrinsics Reference Manual 



405 



VPaned 



(continued) 



Xt - Athena Widgets 



Name 


Type 


Default 


Description 


XtNgripCursor 


Cursor 


XC sb v double 


Cursor for grip when not active 






arrow 




XtNgripIndent 


Position 


10 


Offset of grip from margin (pix 








els) 


XtNgrip- 


Trans 1 at ionTable 


Internal 


Button bindings for grip 


Translations 








XtNheight 


Dimension 


sum of 


Height of vPane 






child heights 




XtNlowerCursor 


Cursor 


XC sb down arrow 


Cursor for resizing pane below 








grip 


XtNmappedWhen- 


Boolean 


TRUE 


Whether xtMapWidget is auto 


Managed 






matic 


XtNrefigureMode 


Boolean 


On 


Whether vPane should adjust 








children 


XtNsensitive 


Boolean 


TRUE 


Whether widget receives input 


XtNtranslations 


Tran si at ionTable 


None 


Event-to-action translations 


XtNupperCursor 


Cursor 


XC sb up arrow 


Cursor for resizing pane above 








grip 


XtNwidth 


Dimension 


width of 


Width of vPane 






widest child 




XtNx 


Position 





x position of vPane 


XtNy 


Position 





y position of vPane 



Constraints 

During the creation of a child pane, the following resources, by which the VPaned widget con 
trols the placement of the child, can be specified in the argument list or retrieved from the 
resource database: 



Name 


Type 


Default 


Description 


XtNallowResize 


Boolean 


FALSE 


If FALSE, ignore child resize requests 


XtNmax 


Dimension 


Unlimited 


Maximum height for pane 


XtNmin 


Dimension 


1 


Minimum height for pane 


XtNskipAdjust 


Boolean 


FALSE 


TRUE if the VPaned widget should not auto 








matically resize pane 



Programmatic Interface 

To create a VPaned widget instance, use xtCreateWidget and specify the class vari 
able vPanedWidgetClass. 

Once the parent frame is created, you then add panes to it. Any type of widget can be 
paned. 

To add a child pane to a VPaned frame, use XtCreateWidget and specify the widget 
ID of the VPaned widget as the parent of each new child pane. 



406 



X Toolkit Intrinsics Reference Manual 



Xt - Athena Widgets (continued) VPaned 

To delete a pane from a vertically paned window frame, use XtUnmanageWidget or 
XtDestroyWidget and specify the widget ID of the child pane. 

To enable or disable a child s request for pane resizing, use xtPanedAllowResize. 

void XtPanedAllowResize (w, allow_resize) 
Widget w; 
Boolean allow_resize; 

where: 

w Specifies the widget ID of the child widget pane. 

all ow_resi ze Enables or disables a pane window for resizing requests. 

If allow_resize is TRUE, the VPaned widget allows geometry requests from the child 
to change the pane s height. If allow_resize is FALSE, the VPaned widget ignores 
geometry requests from the child to change the pane s height. The default state is TRUE 
before the VPaned widget is realized and FALSE after it is realized. This procedure is 
equivalent to changing the xtNallowResize resource for the child. 

To change the minimum and maximum height settings for a pane, use XtPanedSetMin- 
Max. 

void XtPanedSetMinMax (w, min, max) 
Widget w; 
int min, max; 

where: 

w Specifies the widget ID of the child widget pane. 

min is the minimum height of the child, expressed in pixels. 

max is the maximum height of the child, expressed in pixels. 

This procedure is equivalent to setting the xtNmin and xtNmax resources for the child. 

To enable or disable automatic recalculation of pane sizes and positions, use XtPaned- 
SetRef igureMode. 

void XtPanedSetRef igureMode (w, mode) 
Widget w; 
Boolean mode; 

where: 

vf Specifies the widget ID of the VPaned widget 

mode Enables or disables refiguration. 

You should set the mode to FALSE if you add multiple panes to or remove multiple panes 
from the parent frame after it has been realized, unless you can arrange to manage all the 
panes at once using xtManageChildren. After all the panes are added, set the mode to 
TRUE. This avoids unnecessary geometry calculations and "window dancing." 



X Toolkit Intrinsics Reference Manual 407 



VPaned (continued) Xt - Athena Widgets 

To delete an entire VPaned widget and all associated data structures, use xtDes troy- 
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 



X Toolkit Intrinsics 
Appendices 



This section of the book contains release notes, handy lists of functions, macros, 
and procedures, as well useful reference information on data types, translation table 
syntax, resource file format, standard errors, and the like. 



Alphabetical and Group Summaries 



This quick reference is intended to help you find and use the right function for a particular 
task. It organizes the Section 1 and Section 2 reference pages into two lists: 

Alphabetical listing of functions, macros, and prototype procedures. 

Listing of functions, macros, and prototype procedures by groups. 



Alphabetical Listing 

In Table A-l below, all entries begin with Xt. Some entries are indented under a heading to 
improve readability; the heading should be prefixed to the entry names. 

Table A-1. Alphabetical Listing of Functions 



Function 



Description 



XtAcceptFocusProc 
XtActionProc 
XtAdd . . . 

Actions 

Callback 

Callbacks 

Converter 

Event Handler 

ExposureToRegion 

Grab 

Input 

RawEvent Handler 

TimeOut 

WorkProc 
XtAlmostProc 



Prototype procedure to accept or reject keyboard focus. 
Prototype procedure for registering action tables. 

Register an action table with the Resource Manager. 

Add a callback procedure to a widget s callback resource. 

Add a list of callback procedures to a given widget s callback list. 

Register a new resource converter. 

Register a procedure to handle events. 

Merge Expose and GraphicsExpose events into a region. 

Redirect user input to a modal widget 

Register a new file as an input source for an application. 

Register an event handler without selecting for the event 

Create a timeout value. 

Register a work procedure for an application. 

Prototype set_values_almost method. 



Appendix A: Alphabetical and Group Summaries 



411 



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



Function 



Description 



XtApp . . . 

AddActions 

AddConverter 

Addlnput 

AddTimeOut 

AddWorkProc 

CreateShell 

Error 

ErrorMsg 

GetErrorDat abase 

GetErrorDatabaseText 

Get Select ionTimeout 

MainLoop 

NextEvent 

PeekEvent 

Pending 

ProcessEvent 

SetError Handler 

SetErrorMsgHandler 

Set Select ionTimeout 

SetWarningHandler 

SetWarningMsgHandler 

Warning 

WarningMsg 
XtArgsFunc 
XtArgsProc 

Xt Augment Translations 
XtBuildEventMask 
XtCallAcceptFocus 
XtCallbackExclusive 
XtCallbackNone 
XtCallbackNonexclusive 
XtCallbackPopdown 
XtCallbackProc 
XtCallCallbacks 
XtCalloc 
XtCaseProc 
XtCheckSubclass 
XtClass 

XtCloseDi splay 
XtConfigureWidget 
XtConvert 
XtConvertCase 
XtConverter 



Declare an action table and register it with the Resource Manager. 

Register a new resource converter 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 called on fatal error conditions. 

Register a procedure to be called on fatal error conditions. 

Set the Intrinsics selection timeout 

Register a procedure to be 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. 

Prototype set_values_hook method. 

Prototype 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_f ocus 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 converter procedure. 



412 



X Toolkit Intrinsics Reference Manual 



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



Function 



Description 



XtConvert Selection? roc 
XtCreate . . . 

ApplicationContext 
ApplicationShell 
ManagedWidget 
PopupShell 
Widget 
Window 
XtDatabase 
XtDestroy . . . 

ApplicationContext 
GC 

Widget 

Xt Direct Convert 
XtDisownSelection 
XtDispatchEvent 
XtDisplay 

XtDi splay Initialize 
XtError 

XtErrorHandler 
XtErrorMsg 
XtErrorMsgHandler 
XtEventHandler 
XtExposeProc 
XtFree 

XtGeometryHandler 
XtGet . . . 

Appli cat ionRe sources 
ErrorDatabase 
ErrorDatabaseText 
GC 

ResourceList 
Select ionTimeout 
Select ionValue 
Select ionValues 
Subresources 
Subvalues 
Values 

XtHasCallbacks 
Xtlnitialize 
XtlnitProc 
XtlnputCallbackProc 



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 



Description 



Xtlnstall . . . 
Accelerators 
All Accelerators 

XtlsComposite 

XtlsConstraint 

XtlsManaged 

XtlsRealized 

XtlsSensitive 

XtlsShell 

XtlsSubclass 

XtKeyProc 

XtLoseSelectionProc 

XtMainLoop 

XtMakeGeometryRequest 

XtMakeResizeRequest 

XtMalloc 

XtManageChild 

XtManageChildren 

XtMapWidget 

XtMergeArgLists 

XtMoveWidget 

XtNameToWidget 

XtNew 

XtNewString 

XtNextEvent 

XtNumber 

XtOffset 

X t Ope nDi splay 

XtOrderProc 

XtOverrideTranslations 

XtOwnSelection 

XtParent 

XtParse . . . 

Accelerator Table 
TranslationTable 

XtPeekEvent 

XtPending 

XtPopdown 

XtPopup 

XtProc 

XtProcessEvent 



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 



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



Function 



Description 



XtQueryGeometry 

XtRealizeProc 

XtRealizeWidget 

XtRealloc 

XtRegisterCaseConverter 

XtReleaseGC 

XtRemove . . . 

AllCallbacks 

Callback 

Callbacks 

EventHandler 

Grab 

Input 

RawEvent Handler 

TimeOut 

WorkProc 
XtResizeWidget 
XtResizeWindow 
XtRe sour ceDefaultP roc 

XtScreen 

Xt Select ionCallbackP roc 

XtSelectionDoneProc 

XtSet . . . 
Arg 

ErrorHandler 
ErrorMsgHandler 
KeyboardFocus 
KeyTranslator 
MappedWhenManaged 
Select ionTimeout 
Sensitive 
Subvalues 
Values 
ValuesFunc 
WarningHandler 
WarningMsgHandler 

XtStringConver si on- 
Warning 
XtStringProc 
XtSuperclass 
XtTimerCallbackProc 
XtToolkit Initialize 



Query a child widget s preferred geometry. 

Prototype procedure called when widget is realized. 

Realize a widget instance. 

Change the size of an allocated block of storage. 

Register a case converter. 

Deallocate a shared GC when it is no longer needed. 

Delete all procedures from a callback list. 

Delete a procedure from a callback list 

Delete a list of procedures from a callback list 

Remove a previously registered event handler. 

Redirect user input from modal widget back to normal destination. 

Cancel source of alternate input events. 

Remove a raw event handler. 

Clear a timeout value. 

Remove a work procedure. 

Resize a child or sibling widget 

Resize a widget according to the values of its core dimensions. 

Prototype procedure passed as a resource converter of type 

XtRCallProc. 

Return the screen pointer for the specified widget 

Prototype procedure called when requested selection data arrives. 

Prototype procedure called after a data transfer completes. 

Construct or modify an argument list dynamically. 
Register a procedure to be called on fatal error conditions. 
Register a procedure to be called on nonfatal error conditions. 
Redirect keyboard input to a child widget 
Register a key translator. 

Change the value of a widget s map_when_managed field. 
Set value of selection timeout 
Set the sensitivity state of a widget 
Copy from ArgList to base-offset resource list 
Copy resources from ArgList to widget 
Prototype procedure for various set_values methods. 
Register a procedure to be called on nonfatal error conditions. 
Register a high-level procedure to be called on nonfatal error condi 
tions. 
Emit boilerplate string conversion error message. 

Prototype procedure for display_accelerator method. 
Obtain a widget s superclass. 

Prototype callback procedure invoked when timeouts expire. 
Initialize the X Toolkit internals. 



Appendix A: Alphabetical and Group Summaries 



415 



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



Function 



XtTranslateCoords 

XtTranslateKey 
Xt Trans 1 at eKey code 
XtUninstall Translations 
XtUnmanageChild 
XtUnmanageChildren 
XtUnmapWidget 
XtUnrealizeWidget 
XtWarning 
XtWarningMsg 
XtWidgetProc 
XtWidgetToAppli cat ion- 
Context 
XtWindow 
XtWindowToWidget 
XtWorkProc 



Description 



Translate an x-y coordinate pair from widget coordinates to root coor 
dinates. 

Invoke the currently registered keycode-to-keysym translator. 
Invoke the currently registered keycode-to-keysym translator. 
Remove existing translations. 
Remove a widget from its parent s managed list 
Remove a list of children from a parent widget s managed list. 
Unmap a widget explicitly. 

Destroy the windows associated with a widget and its descendants. 
Call the installed low-level warning handler. 
Call the installed high-level warning handler. 
Common prototype procedure for widget methods. 
Get the application context for a given widget. 

Return the window of the specified widget. 

Translate a window and display pointer into a widget instance. 

Perform background processing. 



Group Listing with Brief Descriptions 



The Section 1 and Section 2 reference pages are listed under the following groups: 



Application Contexts 
Argument Lists 
Callbacks 
Error Handling 
Event Handling 
Geometry Management 

Application Contexts 



Graphics Context 
Initialization 
Keyboard Handling 
Memory Allocation 
Methods 
Pop Ups 



Resource Management 
Selections 

Translations and Actions 
Widget Information 
Widget Lifecycle 
Window Manipulation 



XtApp* 

XtCreateApplicationContext 
XtDestroyApplicationContext 
XtDi splay Initialize 
XtOpenDi splay 
XtToolkitlnitialize 



Application-context versions of other Xt functions. 
Create an application context 
Destroy an application context and close its displays. 
Initialize a display and add it to an application context. 
Open, initialize, and add a display to an application context. 
Initialize the X Toolkit internals. 



416 



X Toolkit Intrinsics Reference Manual 



Argument Lists 

XtNumber 
XtOffset 
XtSetArg 

Callbacks 



Determine the number of elements in a fixed-size array. 
Determine the byte offset of a field within a structure. 
Construct or modify an argument list dynamically. 



XtAddCallback 
XtAddCallbacks 

XtCallbackProc 

XtCallCallbacks 

XtHasCallbacks 

XtRemoveAllCallbacks 

XtRemoveCallback 

XtRemoveCallbacks 

Error Handling 



Add a callback procedure to a widget s callback resource. 

Add a list of callback procedures to a given widget s callback 

list 

Prototype callback procedure. 

Execute the procedures in a widget s callback list 

Determine the status of a widget s callback list. 

Delete all procedures from a callback list. 

Delete a procedure from a callback list. 

Delete a list of procedures from a callback list. 



XtAppError 

XtAppErrorMsg 

XtAppGetErrorDat abase 

XtAppGetErrorDatabaseText 

XtAppSetErrorHandler 

XtAppSetErrorMsgHandler 

XtAppSetWarningHandler 

XtAppSetWarningMsgHandler 

XtAppWarning 

XtAppWarningMsg 

XtError 

XtErrorHandler 

XtErrorMsg 

XtErrorMsgHandler 

XtGetErrorDat abase 

XtGetErrorDatabaseText 

XtSetErrorHandler 

XtSetErrorMsgHandler 

XtSetWarningHandler 

XtSetWarningMsgHandler 

XtStringConversionWarning 

XtWarning 

XtWarningMsg 



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. 

Register a procedure to be called on fatal error conditions. 

Register a procedure to be called on fatal error conditions. 

Register a procedure to be 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. 

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. 

Obtain the error database. 

Obtain the error database text for an error or a warning. 

Register a procedure to be called on fatal error conditions. 

Register a procedure to be called on nonfatal error conditions. 

Register a procedure to be called on nonfatal error conditions. 

Register a high-level procedure to be called on nonfatal error 

conditions. 

Emit boilerplate string conversion error message. 

Call the installed low-level warning handler. 

Call the installed high-level warning handler. 



Appendix A: Alphabetical and Group Summaries 



417 



Event Handling 



XtAddEventHandler 

XtAddExposureToRegion 

XtAddlnput 

XtAddRawEvent Handler 

XtAddTimeOut 

XtAddWorkProc 

XtAppAddlnput 

XtAppAddTimeOut 

XtAppAddWorkProc 

XtAppMainLoop 

XtAppNextEvent 

XtAppPeekEvent 

XtAppPending 

XtAppProcessEvent 

XtBuildEventMask 

XtDispatchEvent 

XtEventHandler 

XtlnputCallbackProc 

XtMainLoop 

XtNextEvent 

XtPeekEvent 

XtPending 

XtProcessEvent 
XtRemoveEvent Handler 
Xt Remove Input 
XtRemoveRawEvent Handler 
XtRemoveTimeOut 
XtRemoveWorkProc 
XtTimerCallbackProc 
XtWorkProc 

Geometry Management 



Register a procedure to handle events. 

Merge Expose and GraphicsExpose events into a region. 

Register a new file as an input source for an application. 

Register an event handler without selecting for the event 

Create a timeout value. 

Register a work procedure 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. 

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 

Retrieve a widget s event mask. 

Dispatch registered handlers for an event 

Prototype procedure to handle input events. 

Prototype procedure called to handle file events. 

Continuously process events. 

Return next event from 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 

Remove a previously registered event handler. 

Cancel source of alternate input events. 

Remove a raw event handler. 

Clear a timeout value. 

Remove a work procedure. 

Prototype callback procedure invoked when timeouts expire. 

Perform background processing. 



XtAlmostProc 

XtConfigureWidget 

Xt Geometry Handler 

XtMakeGeometryRequest 

XtMakeResizeRequest 

XtMoveWidget 

XtOrderProc 

XtQueryGeometry 
XtResizeWidget 
XtUnmanageChild 
XtUnmanageChildren 



Prototype set_values_almost method. 

Move and/or resize widget 

Prototype procedure to handle geometry requests. 

Request parent to change child s geometry. 

Request parent to change child s size. 

Move a widget on the display. 

Prototype procedure for ordering the children of composite 

widget instances. 

Query a child widget s preferred geometry. 

Resize a child or sibling widget 

Remove a widget from its parent s managed list 

Remove a list of children from a parent widget s managed list 



418 



X Toolkit Intrinsics Reference Manual 



Graphics Context 



DestroyGC 

XtGetGC 

XtReleaseGC 

Initialization 



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

Obtain a read-only, sharable GC. 

Deallocate a shared GC when it is no longer needed. 



XtAppCreateShell 
XtCloseDi splay 
XtCreateApplicationShell 
Xtlnitialize 

Keyboard Handling 



Create additional top-level widget. 

Close a display and remove it from an application context 

Create an additional top-level widget. 

Initialize toolkit and display. 



XtAcceptFocusProc 

XtCallAcceptFocus 

XtCaseProc 

XtConvertCase 

XtKeyProc 

XtRegisterCaseConverter 

XtSetKey Translator 

XtSetKeyboardFocus 

XtTranslateKey 

XtTranslateKeycode 

Memory Allocation 



Prototype procedure to accept or reject keyboard focus. 

Call a widget s accept_f ocus procedure. 

Prototype procedure called to convert the case of keysyms. 

Determine upper-case and lower-case versions of a keysym. 

Prototype procedure to translate a key. 

Register a case converter. 

Register a key translator. 

Redirect keyboard input to a child widget 

Invoke the currently registered keycode-to-keysym translator. 

Invoke the currently registered keycode-to-keysym translator. 



XtCalloc 

XtDestroyGC 

XtFree 

XtGetGC 

XtMalloc 

XtMergeArgLists 

XtNew 

XtNewString 

XtRealloc 

XtReleaseGC 

Methods 



Allocate an array and initialize elements to zero. 

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

Free an allocated block of storage. 

Obtain a read-only, sharable GC. 

Allocate storage. 

Merge two ArgList structures. 

Allocate storage for one instance of a data type. 

Copy an instance of a string. 

Change the size of an allocated block of storage. 

Deallocate a shared GC when it is no longer needed. 



XtAlmostProc 

XtArgsFunc 

XtArgsProc 

XtExposeProc 

XtGeometryHandler 

XtlnitProc 

XtOrderProc 

XtProc 

XtRealizeProc 

XtSetValuesFunc 

XtStringProc 

XtWidgetProc 



Prototype set_values_almost method. 
Prototype set_values_hook method. 
Prototype procedure for get_values_hook method. 
Prototype expose method used in Core widget class. 
Prototype procedure to handle geometry requests. 
Prototype initialize procedure for a widget class. 
Procedure for ordering the children of composite widget in 
stances. 

Prototype procedure to initialize data for a widget class. 
Prototype procedure called when widget is realized. 
Prototype procedure for various set_values methods. 
Prototype procedure fordisplay_accelerator method. 
Common prototype procedure for widget methods. 



Appendix A: Alphabetical and Group Summaries 



419 



Pop Ups 

MenuPopdown 

MenuPopup 

XtAddGrab 

XtCallbackExclusive 

XtCallbackNone 

XtCallbackNonexclusive 

XtCallbackPopdown 

XtCreatePopupShell 

XtRemoveGrab 

XtPopdown 
XtPopup 

Resource Management 



Built-in action for popping down a widget. 
Built-in action for popping up a widget 
Redirect user input to a modal widget 
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. 
Create a pop-up shell. 

Redirect user input from modal widget back to normal destina 
tion. MenuPopdown MenuPopup 
Unmap a pop-up shell. 
Map a pop-up shell. 



XtAddConverter 

XtAppAddConverter 

XtArgsFunc 

XtArgsProc 

XtConvert 

XtConverter 

XtDatabase 

XtDirectConvert 

Xt Get Appli cat ionRe sources 

XtGetResourceList 

Xt Get Subre sources 

XtGetSubvalues 

XtGetValues 

XtResourceDefaultProc 

XtSetMappedWhenManaged 
XtSetSensitive 
XtSetSubvalues 
XtSetValues 

Selections 



Register a new resource converter. 

Register a new resource converter for an application. 

Prototype set_values_hook method. 

Prototype procedure for get_values_hook method. 

Convert resource type. 

Prototype of a resource converter procedure. 

Obtain the resource database for a particular display. 

Perform resource conversion and cache result 

Update base-offset resource list (by application). 

Retrieve default values for a resource list. 

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. 

Prototype procedure passed as a resource converter of type Xt- 

RCallProc. 

Change the value of a widget s map_when_managed field. 

Set the sensitivity state of a widget 

Copy from ArgList to base-offset resource list 

Copy resources from ArgList to widget 



XtAppGet Select ionTimeout 
XtAppSet Select ionTimeout 
XtConvert Select ionP roc 
XtDisownSelection 
XtGet Select ionTimeout 
XtGet Select ionValue 
XtGet Select ionValues 
XtLoseSelectionProc 

XtOwnSelection 

Xt Set Select ionTimeout 

XtSelectionCallbackProc 

XtSelectionDoneProc 



Get the current selection timeout value. 
Set the Intrinsics selection timeout 
Prototype procedure to return selection data. 
Indicate that selection data is no longer available. 
Get the current selection timeout value. 
Obtain the complete selection data. 
Obtain selection data in multiple formats. 
Prototype procedure called by the Intrinsics when another client 
claims the selection. 
Indicate that selection data is available. 
Set value of selection timeout 

Prototype procedure called when requested selection data ar 
rives. 
Prototype procedure called after a data transfer completes. 



420 



X Toolkit Intrinsics Reference Manual 



Translations and Actions 



XtActionProc 
XtAddActions 
Xt AppAddAct i on s 

Xt Augment Translations 

Xt Install Accelerators 
Xt Install All Accelerators 

XtOverrideTranslations 
XtParseAcceleratorTable 
XtParseTranslationTable 
XtUninst all Translations 

Widget Information 



Prototype procedure for registering action tables. 
Register an action table with the Resource Manager. 
Declare an action table and register it with the Resource Man 
ager. 

Nondestructively merge new translations with widget s existing 
ones. 

Install a widget s accelerators on another widget. 
Install all accelerators from a widget and its descendants onto a 
destination. 

Merge new translations, overwriting widget s existing ones. 
Compile an accelerator table into its internal representation. 
Compile a translation table into its internal representation. 
Remove existing translations. 



XtCheckSubclass 
XtClass 
XtDisplay 
XtlsComposite 

XtlsConstraint 

XtlsManaged 

XtlsRealized 

XtlsSensitive 

XtlsShell 

XtlsSubclass 

XtNameToWidget 

XtParent 

XtScreen 

Xt Super class 

XtWidgetToApplicationContext 

XtWindow 

XtWindowToWidget 



In DEBUG mode, verify a widget s class. 

Obtain a widget s class. 

Return the display pointer for the specified widget. 

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. 

Translate a widget name to a widget instance. 

Return the parent widget for the specified widget 

Return the screen pointer for the specified widget 

Obtain a widget s superclass. 

Get the application context for a given widget. 

Return the window of the specified widget 

Translate a window and display pointer into a widget instance. 



Widget Lifecycle 



XtCreateManagedWidget 

XtCreateWidget 

XtDestroyWidget 

XtManageChild 

XtManageChildren 

XtMapWidget 

XtRealizeWidget 

XtUnmapWidget 

XtUnrealizeWidget 



Create and manage a child widget 
Create an instance of a widget. 
Destroy a widget instance. 

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. 
Realize a widget instance. 
Unmap a widget explicitly. 

Destroy the windows associated with a widget and its descen 
dants. 



Appendix A: Alphabetical and Group Summaries 



421 



Window Manipulation 



xtcreatewindow Create widget s working window. 

xtResizeWindow Resize a widget according to the values of its core dimensions. 

xtTranslateCoords Translate an x-y coordinate pair from widget coordinates to root 

coordinates. 



X Toolkit Intrinsics Reference Manual 



B 
X Toolkit Data Types 



This appendix summarizes the data types used as arguments or return values in Xt Intrinsics 
functions. Unless otherwise noted, these types are defined in the header file XI 1 /Intrinsic. h. 
Data types (which include simple typedefs as well as structures and enums) are listed alpha 
betically. Defined symbols (for example, constants used to specify the value of a mask or a 
field in a structure) or other data types used only to set structure members are listed with the 
data type in which they are used. 

ArgList 

An ArgList is used for setting resources in calls to create a widget (xtCreate- 
Widget, XtCreateManagedWidget, XtCreatePopupShell) as well as in 
calls to set or get resources (xtSetValues, xtGetValues, xtSetSubvalues, 
XtGetSubvalues, XtSetSubresources, XtGetSubresources). It is 
defined as follows in <X1 II Intrinsic. h>: 

typedef struct { 

String name; 

XtArgVal value; 
} Arg, *ArgList; 

The name field is typically a defined constant of the form xtNresourcena/ne from 
either <XlllStringdefs.h> or a widget public header file. It identifies the name of the 
argument to be set. The value field is an XtArgVal, a system -dependent typedef 
chosen to be large enough to hold a pointer to a function or a long. In the MIT R3 
release, it is a long. 

Atom 

To optimize communication with the server, a property is never referenced by name, but 
by a unique integer ID called an Atom. Standard atoms are defined in <XlllXatom.h> 
using defined symbols beginning with XA_; nonstandard atoms can be obtained from the 
server by calling the Xlib function XinternAtom. The Xmu library supports an atom- 
caching mechanism to reduce the number of XinternAtom calls that may be required. 
For more information, see Chapter 10, Inter client Communication, in Volume Four, X 
Toolkit Intrinsics Programming Manual. 



Appendix B: X Toolkit Data Typos 423 



Boolean 

A typedef from <X1 II Intrinsic. h> used to indicate TRUE (1) or FALSE (0). Use either the 
symbols TRUE or FALSE, defined in <Xll/Xlib.h> or TRUE or FALSE, defined in 
<X1 II Intrinsic. h>. 

Cardinal 

A typedef from <X1 II Intrinsic. h> used to specify any unsigned numeric value. 

Dimension 

A typedef from <X1 II 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 <XlllXlib.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 <X11 1 Intrinsic. 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 



Circumstances 



Event Mask Symbol 



NoEventMask 

KeyPressMask 

KeyReleaseMask 

ButtonPressMask 

ButtonReleaseMask 

EnterWindowMask 

LeaveWindowMask 

Point erMotionMask 

PointerMotionHintMask 

ButtonlMotionMask 

Button2MotionMask 

Button3MotionMask 

Button4MotionMask 

ButtonSMotionMask 

ButtonMotionMask 

KeymapStateMask 

ExposureMask 

VisibilityChangeMask 
Struct ureNotifyMask 
ResizeRedirectMask 
SubstructureNotifyMask 



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 EnterNotif y, 

LeaveNotif y, Focusln, 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 



Event Mask Symbol 



SubstructureRedirectMask 

FocusChangeMask 

PropertyChangeMask 

ColormapChangeMask 

OwnerGrabButtonMask 



Circumstances 



Redirect reconfiguration of children 
Any change in keyboard focus 
Any change in property 
Any change in colormap 
Modifies handling of pointer events 



GC 



plus the following symbol defined in <X11 /Intrinsic. h>: 
xtAllEvents All of the above masks: ( (EventMask) -1L) 

See Appendix C, Event Reference, for more information on each of the events selected by 
these mask values. The XtBuildEventMask function returns the event mask repre 
senting the logical OR of all event masks registered on the widget with xtAddEvent- 
Handler, as well as event masks registered as a result of translations and accelerators 
installed on the widget 

A Graphics Context. A pointer to a structure of this type is returned by the Xlib call 
XGreateGC or the Xt call xtGetGC. (The latter call does client-side caching of GCs 
to reduce the number of identical GCs that are created.) GCs are used by all Xlib draw 
ing calls. The members of this structure should not be accessed directly. Values can be 
changed by passing an XGCValues structure to XtGetGC or the Xlib XGreateGC or 
XChangeGC. Values can be read with XGetGCValues. 

Opaque 

As its name implies, a typedef designed for portability, whose contents are not to be 
used. 

Position 

A typedef from <X11 /Intrinsic. h> used to specify x and y coordinates. The Position 
data type was introduced in R3 to increase portability. R2 applications that specified 
coordinates as int should use Position instead. 

Region 

An arbitrary set of pixels on the screen. Usually, a region is either a rectangular area, 
several overlapping or adjacent rectangular areas, or a general polygon. A Region is 
actually a typedef from <Xll/Xutil.h> pointing to an internal data structure called an 
_XRegion. There are a number of Xlib functions for creating and manipulating 
regions; the members of the structure should not be accessed directly. For more informa 
tion, see Volume Two, Xlib Reference Manual. In Xt, the only use is in the call Xt Add- 
ExposureToRegion. 

Screen 

A structure that describes the characteristics of a screen (one or more of which make up a 
display). A pointer to a list of these structures is a member of the Display structure. A 
pointer to a structure of this type is returned by XGetwindowAttributes. Xlib 
Macros are provided to access most members of this structure. 



typedef struct { 

XExtData *ext data; 



/* hook for extension to hang data */ 



Appendix B: X Toolkit Data Types 



425 



struct _XDisplay ^display; 
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 */ 

/* list 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 xt Screen macro can be used in Xt to return the current screen. 

String 

Atypedef for char *. 

Time 

An unsigned long value containing a time value in milli seconds. 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 structure returned by calls to create a widget, such as xtlnitialize, xtCreate- 
widget, XtCreateManagedWidget, and XtCreatePopupShell. The mem 
bers of this structure should not be accessed directly 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 maintained 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 thirty event structures. The first 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 <Xll/Xlib.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; / 

unsigned long plane mask; / 



logical operation */ 
plane mask */ 



unsigned long foreground; /* foreground pixel */ 
unsigned long background; /* background pixel */ 



426 



X Toolkit Intrinsics Reference Manual 



/ 



/ 



/* line width *7 

LineSolid, LineOnOf fDash, 

LineDoubleDash */ 
/* CapNotLast, CapButt, 

CapRound, CapProjecting */ 
/* JoinMiter, JoinRound, JoinBevel 
/* FillSolid, FillTiled, 

FillStippled, FillOpaqueStippled */ 
/* EvenOddRule, WindingRule */ 
/* ArcChord, ArcPieSlice */ 

pixmap for tiling operations */ 

1 plane pixmap for stippling */ 



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; /* offset for tile or stipple operations */ 

int ts_y_origin; 

Font font; /* default text font for text operations */ 

int subwindow_mode;/* ClipByChildren, Includelnferiors */ 

Bool graphics_exposures; /* should exposures be generated? */ 



/* 
/* 



int clip_x_origin; 
int clip_y_origin; 
Pixmap clip_mask; 
int dash_offset; 
char dashes; 
} XGCValues; 



/* origin for clipping */ 

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



For more information on the meaning and use of each of the members, see Chapter 5, The 
Graphics Context, in Volume One, Xlib Programming Manual. The second argument of 
XtGetGC is a mask that specifies which members of the structure are being set See 
XtGCMask below for details. 

XrmDatabase 

A pointer to an internal resource manager datatype. Members of this structure should not 
be accessed directly. An XrmDatabase can be returned by the Xt calls xtDatabase 
(a resource database) or xtGetErrorDatabase (an error message database). 

XrmOptionDescRec 

A structure used to define command line options, passed to xtlnitialize, xt- 
Displaylnitialize, or xtOpenDisplay. The structure is defined as follows in 
<X1 1 /Xresource.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 value for the argKind element is specified by one of the following enum values, 
defined in the same file: 



typedef enum { 

XrmoptionNoArg, / 
XrmoptionlsArg, / 



Value specified in OptionDescRec .value 
Value is the option string itself */ 



XrmoptionStickyArg, /* Value immediately follows option */ 



XrmoptionSepArg, X 1 
XrmoptionResArg, / 
XrmoptionSkipArg, / 



Value is next argument in argv */ 
Resource and value in next arg in argv */ 
Ignore this opt and next arg in argv */ 



Appendix B: X Toolkit Data Types 



427 



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

XrmOptionKind 

See XrmOptionDescRec. 

XrmValue 

A structure defined in <Xll/Xresource.h>, used in xt Convert and other resource con 
version routines. 

typedef struct { 

unsigned int size; 

caddr_t addr; 

} XrmValue, *XrmValuePtr; 

XrmValuePtr 
See XrmValue. 

XtAccelerators 

A pointer to an opaque internal type, a compiled accelerator table. A pointer to an Xt 
Accelerators structure is returned by a call 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 <X11 /Intrinsic. h>: 

typedef struct _XtActionsRec *XtActionList; 

typedef struct _XtActionsRec{ 

char *string; 

XtActionProc proc; 
} XtActionsRec; 

Actions are added by calls 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 files, which are made up entirely of strings. 

x t Ac t i onP r oc 

The typedef for an action procedure. See xtActionProc(2) for details. 

XtAddres sMode 

An enumerated type that specifies the possible values for the address_mode field of 
an xtConvertArgRec. See xtConvertArgRec below for details. 

XtAppContext 

A pointer to an internal structure used to hold data specific to a particular application 
context. An XtAppContext can be returned by a call to 



428 X Toolkit Intrinsics 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. 

XtCallbacJcList 

A structure defined as follows in <X1 II Intrinsic. 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 that set resources, including xtCreateWidget. In most documentation, the 
closure member is referred 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 used in calls to XtAddConverter to specify how the converter will access 
the values to be converted. The structure is defined as follows in <X1 II Intrinsic. h>: 

typedef struct [ 

XtAddressMode address_mode; 

caddr_t address_id; 

Cardinal size; 

} XtConvertArgRec, *XtConvertArgList; 

The enumerated type XtAddressMode specifies the possible values for the 
address_mode field, which controls how the address_id field should be inter 
preted. 

typedef enum { 

XtAddress, /* address */ 

XtBaseOffset, /* offset */ 

Xt Immediate, /* constant */ 

XtResourceString, /* resource name string */ 

XtResourceQuark /* resource name quark */ 
} XtAddressMode; 



Appendix B: X Toolkit Data Types 429 



By specifying the address mode as xtBaseOf f set, you can use xtof f set to find 
the appropriate widget resource, much as you do in a resource list. 

Xt Conve rtArgRec 

See XtConvertArgList. 

XtConverter 

The typedef for resource converters. See xtConverter(2) for details. 

XtConvertSelectionProc 

The typedef for the selection conversion procedure registered by a call to xtOwn- 
Selection. See xtConvertSelectionProc(2) for details. 

XtErrorHandler 

The typedef for low-level error or warning handlers. 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 


Mask 


Default 


function 


GCFunction 


GXcopy 


plane mask 


GCPlaneMask 


alli s 


foreground 


GCForeground 





background 


GCBackground 


i 


line width 


GCLineWidth 





line_style 


GCLineStyle 


LineSolid 


cap style 


GCCapStyle 


CapButt 


join_style 


GCJoinStyle 


JoinMiter 


fill_style 


GCFillStyle 


FillSolid 


fill_rule 


GCFillRule 


EvenOddRule 


tile 


GCTile 


pixmap filled with 






foreground pixel 


stipple 


GCStipple 


pixmap filled with 1 s 


ts x origin 


GCTileStipXOrigin 





ts y origin 


GCTileStipYOrigin 





font 


GCFont 


(implementation 






dependent) 


subwindow mode 


GCSubwindowMode 


ClipByChildren 


graphics exposures 


GCGraphicsExposures 


TRUE 


clip x origin 


GCClipXOrigin 





clip y origin 


GCClipYOrigin 





clip_mask 


GCClipMask 


None 



430 



X Toolkit Intrinsics Reference Manual 



Member 


Mask 


Default 


dash offset 
dashes 
arc mode 


GCDashOffset 
GCDashList 
GCArcMode 




4 (i.e., the list [4, 4]) 

ArcPieSlice 



XtGeometryMask 

See Xt Widget Geometry. 

XtGeoxnet ry Result 

An enumerated type used as the return value of the XtQueryGeometry, xtMake- 
GeometryRequest, and XtMakeResizeRequest functions. It is defined as fol 
lows in <X11 /Intrinsic. h>: 



typedef enum { 
XtGeomet ry Yes , 
XtGeometryNo, 
XtGeomet ryAlmost , 
XtGeometryDone 

} XtGeometryResult ; 



/* Request accepted */ 

/* Request denied */ 

/* Request denied but willing to take reply */ 

/* Request accepted and done */ 



XtGrabKind 

An enumerated type used in calls to Xt Popup to specify the nature of the grab to be 
asserted by the pop-up widget 

typedef enum { 

XtGrabNone, 

XtGrabNonexclusive, 

XtGrabExclusive 
} XtGrabKind; 

An exclusive grab constrains input to the widget actually making the grab (the latest 
widget in a pop-up cascade), while a non-exclusive grab allows input to any widget in the 
cascade. 

XtlnputCallbacJcProc 

The typedef for the procedure registered by a call to xtAddlnput. See Xt input - 
Callback? roc(2) for details. 

Xtlnputld 

A unique ID returned by a call to XtAddlnput; used to remove an input source with 
XtRemove Input. 

XtlnputMask 

A mask used in calls to XtProcessEvent to indicate which types of events should be 
processed. This mask is made up of a bitwise OR of the following symbols defined in 
<X1 II Intrinsic. h>: 



XtlMXEvent 
XtlMTimer 
XtlMAlternatelnput 
XtlMAll 



Process X Events. 

Process timeouts registered with xtAddTimeout . 

Process alternate input sources registered with xtAddlnput . 

Process all three types of events. 



Appendix B: X Toolkit Data Types 



431 



An xtlnputMask is returned by xt Pending to indicate what type of events are in 
the event queue. Don t confuse these values with xtlnputNoneMask, xt Input - 
WriteMask, xtlnputReadMask, and XtlnputExceptMask, which are used in 
calls to Xt Addlnput to indicate whether the file should be monitored for reads, writes, 
or exception conditions. 

Xtlntervalld 

A unique ID returned by a call to xtAddTimeout; used to remove a timeout with xt- 
RemoveTimeout. Remember that timeouts are automatically removed when the time 
expires. 

XtLoseSelectionProc 

The typedef for the lose selection procedure registered by a call to xtOwnSelection. 
See xtLoseSelectionProc(2) for details. 

XtResourceList 

A structure used to declare widget or application resources, and to retrieve the current 
value of resources using xtGetSubresources, XtGetSubvalues, or XtGet- 
ResourceList. It is defined as follows in <X1 II Intrinsic. h>\ 

typedef struct _XtResource { 

String resource_name; /* specify using XtN symbol */ 

String resource_class; /* specify using XtC symbol */ 

String resource_type; /* actual data type of variable */ 

Cardinal resource_size; /* specify using sizeofO */ 

Cardinal resource_of f set; /* specify using XtOffsetO */ 

String def ault_type; /* will be conv ted to resource_type */ 

caddr_t default_address; /* address of default value */ 
} XtResource; 

typedef struct _XtResource *XtResourceList; 

See Chapter 9, Resource Management and Type Conversion, in Volume Four, X Toolkit 
Intrinsics Programming Manual, for a detailed description of the XtResource struc 
ture. 

XtSelectionCallbackProc 

The typedef for the selection callback procedure registered by a call to xtGet- 
SelectionValue or XtGetSelectionValues. See XtSelection- 
CallbackProc(2) for details. 

Xt Select ionDoneP roc 

The typedef for the selection completion procedure registered by a call to XtOwn 
Selection. See XtSelectionDoneProc(2) for details. 

Xt Time rCallbackP roc 

The typedef for the procedure to be invoked after a timeout registered by a call to Xt 
AddTimeout. See XtTimerCallbackProc(2) for details. 

XtTranslations 

A pointer to an opaque internal type, a compiled translation table. A pointer to an Xt 
Translations structure is returned by a call to xtParseTranslationTable. 



432 X Toolkit Intrinsics Reference Manual 



Usually, the compiled translation table is produced automatically by resource conversion 
of a string translation table stored in a resource file. 

XtWidget Geometry 

A structure used to pass in and return data about widget geometry in calls to xt Query- 
Geometry and XtMakeGeometryRequest. It is defined as follows in 
<X11 /Intrinsic. h>: 

typedef struct { 

XtGeometryMask request_mode; 

Position x, y; 

Dimension width, height, border_width; 

Widget sibling; 

int stack_mode; 
} XtWidgetGeometry; 

The request_mode field specifies which of the other fields are to be used, or (for 
returned structures) contain valid values. It is made up of a bitwise OR of the following 
symbols defined in <Xll/X.h>: 

tdefine CWX (10) 

tdefine CWY (11) 

tdefine CWWidth (12) 

f define CWHeight (13) 

tdefine CWBorderWidth (14) 

tdefine CWSibling (15) 

tdefine CWStackMode (16) 

plus the following symbol from <X11 /Intrinsic. h>: 
tdefine XtCWQueryOnly (1 7) 

which means that this call is a query only, and none of the values should be used; the 
return value should show what would happen if the geometry request were made. (In 
case you re wondering, the CW prefix stands for "ConfigureWindow" these symbols 
are also used by the Xlib XConf igurewindow call.) 

The stack_mode field specifies the relationship between the current widget and a 
sibling widget specified in the same call. It is specified using one of the following 
symbols defined in <Xll/X.h>: 

Below Place widget below sibling or on bottom of stack if no sibling. 

Top i f Place widget on top of stack if obscured. 

Bottom I f Place widget on botton if it obscures sibling. 

opposite If sibling occludes the widget, put widget on top of stack, but if 

widget occludes sibling, put widget on the bottom. 

plus the following symbol from <XJ1 /Intrinsic. h>: 

xtSMDontchange Don t change the stacking order. 

If no sibling widget is specified in the call, the stacking order is relative to any sibling. 



Appendix B: X Toolkit Data Types 433 



XtWorkProc 

The typedef for the work procedure registered by a call to xtAddWorkProc. See xt- 
WorkProc(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 



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-l 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 



Event Type 



Structure 



KeyPressMask 

KeyReleaseMask 

ButtonPressMask 

ButtonReleaseMask 

Owner GrabButtonMask 

KeymapStateMask 

PointerMotionMask 
Point erMotionHintMask 
ButtonMotionMask 
Button IMotionMask 
Button2MotionMask 
Button3MotionMask 
Button4MotionMask 
ButtonSMotionMask 

EnterWindowMask 
LeaveWindowMask 
FocusChangeMask 



KeyPress 

KeyRelease 

ButtonPress 

ButtonRe lease 

n/a 

KeymapNotify 

MotionNotify 



XKeyPressedEvent 
XKeyReleasedEvent 
XButtonPressedEvent 
XButtonReleasedEvent 

n/a 

XKeymapEvent 
XPointerMovedEvent 



EnterNotify 
LeaveNotify 
Focusln 



XEnterWindowEvent 
XLeaveWindowEvent 
XFocusInEvent 



Appendix C: Event Reference 



435 



Table C-1. Event Masks, Event Types, and Event Structures (continued) 



Event Mask 



Event Type 



Structure 



ExposureMask 

(selected in GC by 
graphics_expose member) 

ColormapChangeMask 

PropertyChangeMask 

VisibilityChangeMask 

ResizeRedirectMask 

StructureNotifyMask 



SubstructureNotifyMask 



SubstructureRedirectMask 

(always selected) 
(always selected) 
(always selected) 
(always selected) 
(always selected) 



FocusOut 
Expose 

GraphicsExpose 
NoExpose 

ColormapNotify 
PropertyNotify 
VisibilityNotify 
ResizeRequest 

CirculateNotify 

ConfigureNotify 

DestroyNotify 

GravityNotify 

MapNotify 

ReparentNotify 

UnmapNotify 

CirculateNotify 

ConfigureNotify 

CreateNotify 

DestroyNotify 

GravityNotify 

MapNotify 

ReparentNotify 

UnmapNotify 

CirculateRequest 
ConfigureRequest 
MapRequest 

MappingNotify 
ClientMessage 
Select ionClear 
Select ionNot if y 
Select ionRequest 



XFocusOutEvent 
XExposeEvent 

XGraphicsExposeEvent 
XNoExposeEvent 

XColormapEvent 
XPropertyEvent 
XVisibilityEvent 
XResizeRequestEvent 

XCirculateEvent 

XConfigureEvent 

XDestroyWindowEvent 

XGravityEvent 

XMapEvent 

XReparent Event 

XUnmapEvent 

XCirculateEvent 

XConfigureEvent 

XCreateWindowEvent 

XDestroyWindowEvent 

XGravityEvent 

XMapEvent 

XReparentEvent 

XUnmapEvent 

XCirculateRequestEvent 
XConfigureRequestEvent 
XMapRequestEvent 

XMappingEvent 

XClientMessageEvent 

XSetSelectClearEvent 

XSelectionEvent 

XSelectionRequestEvent 



436 



X Toolkit Intrinsics Reference Manual 



Meaning of Common Structure Elements 

Example C-l 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). 

Example C-1. XEvent union and XAnyEvent structure 

typedef union _XEvent { 

int type; /* must not be changed; first member */ 

XAnyEvent xany; 

XButtonEvent xbutton; 

XCirculateEvent xcirculate; 

XCirculateRequest Event xcirculaterequest; 

XClientMessageEvent xclient; 

XColormapEvent xcolormap; 

XConf igureEvent xconfigure; 

XConf igureRequestEvent xconf igurerequest ; 

XCreateWindowEvent xcreatewindow; 

XDestroyWindowEvent xdes troy window; 

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; 

XSelectionClearEvent xselectionclear; 

XSelectionEvent xselection; 

XSelectionRequest Event xselectionrequest; 

XVisibilityEvent xvisibility; 
} XEvent; 

typedef struct { 
int type; 
unsigned long serial;/* I of last request processed by server */ 

/* TRUE if this came from SendEvent request */ 

/* display the event was read from */ 

/* window on which event was requested in 

* event mask */ 



Bool send_event; 
Display *display; 
Window window; 



} XAnyEvent; 



Appendix C: Event Reference 



437 



The first member of the XE vent union is the type of event When an event is received (with 
XNextEvent, for example), the application checks the type member in the XEvent 
union. Then the specific event type is known and the specific event structure (such as 
xbutton) is used to access information specific to that event type. 

Before the branching depending on the event type, only the XEvent union is used. After 
the branching, only the event structure which contains the specific information for each event 
type should be used in each branch. For example, if the XEvent union were called 
report, the report .xexpose structure should be used within the branch for Expose 
events. 

You ll notice that each event structure also begins with a type member. This member is 
rarely used, since it is an identical copy of the type member in the XEvent union. 

Most event structures also have a window member. The only ones that don t are selection 
events (SelectionNotify, SelectionRequest, and SelectionClear) and 
events selected by the graphics_exposures member of the GC (GraphicsExpose 
and NoExpose). The window member indicates the event window that selected and 
received the event This is the window where the event arrives if it has propagated through 
the hierarchy as described in Section 7.2.1., in Volume Four, X Toolkit Intrinsics Program 
ming Manual. One event type may have two different meanings to an application, depending 
on which window it appears in. 

Many of the event structures also have a display and/or root member. The display 
member identifies the connection to the server that is active. The root member indicates 
which screen the window that received the event is linked to in the hierarchy. Most programs 
only use a single screen and therefore don t need to worry about the root member. The 
display member can be useful since you can pass the display variable into routines by 
simply passing a pointer to the event structure, eliminating the need for a separate display 
argument 

All event structures include a serial member, that gives the number of the last protocol 
request processed by the server. This is useful in debugging, since an error can be detected 
by the server but not reported to the user (or programmer) until the next routine that gets an 
event That means several routines may execute successfully after the error occurs. The last 
request processed will often indicate the request that contained the error. 

All event structures also include a send_event flag, which if True indicates that the 
event was sent by xSendEvent (i.e., by another client rather than by the server). 

The following pages describe each event type in detail. The events are presented in alphabet 
ical order, each on a separate page. Each page describes the circumstances under which the 
event is generated, the mask used to select it, the structure itself, its members, and useful pro 
gramming notes. Note that the description of the structure members does not include those 
members common to many structures. If you need more information on these members, 
please refer to this introductory section. 



438 X Toolkit Intrinsics Reference Manual 



x button 



J ButtonPress, ButtonRelease 



When Generated 

There are two types of pointer button events: ButtonPress and ButtonRelease. Both 
contain the same information. 

Translation Abbreviations 

In translation tables, the event type ButtonPress or ButtonRelease may be used, or use 
one of the abbreviations shown in the following table. 



Abbreviation 



BtnDown 

BtnlDown 

Btn2Down 

Btn3Down 

Btn4Down 

BtnSDown 

BtnUp 

BtnlUp 

Btn2Up 

Btn3Up 

Btn4Up 

BtnSUp 



Description 



Any pointer button pressed 
Pointer button 1 pressed 
Pointer button 2 pressed 
Pointer button 3 pressed 
Pointer button 4 pressed 
Pointer button 5 pressed 
Any pointer button released 
Pointer button 1 released 
Pointer button 2 released 
Pointer button 3 released 
Pointer button 4 released 
Pointer button 5 released 



Select With 

May be selected separately, using ButtonPressMask and ButtonReleaseMask. 

XEvent Structure Name 

typedef union _XEvent { 
XButtonEvent xbutton; 
} XEvent; 



Event Structure 

typedef struct { 
int type; 

unsigned long serial, 
Bool send_event; 
Display *display; 
Window window; 
Window root; 
Window subwindow; 
Time time; 
int x, y; 

int x_root, y_root; 
unsigned int state; 
unsigned int button; 



/* of event */ 

/* # of last request processed by server */ 

/* TRUE if this came from SendEvent request */ 

/* display the event was read from */ 

/* event window it is reported relative to */ 

/* root window that the event occurred under */ 

/* child window */ 

/* when event occurred, in milliseconds */ 

/* pointer coords relative to receiving window */ 

/* coordinates relative to root */ 

/* mask of all buttons and modifier keys */ 

/* button that triggered event */ 



X Toolkit Intrinsics Reference Manual 



439 



ButtonPresS, ButtonRelease (continued) xbutton 

Bool same_screen; /* same screen flag */ 

} XButtonEvent; 

typedef XButtonEvent XButtonPressedEvent; 

typedef XButtonEvent XButtonReleasedEvent; 

Event Structure Members 

subwindow If the source window is the child of the receiving window, then the subwindow 
member is set to the ID of that child. 

time The server time when the button event occurred, in milliseconds. Time is 

declared as unsigned long, so it wraps around when it reaches the maxi 
mum value of a 32 bit number (every 49.7 days). 

x, y If the receiving window is on the same screen as the root window specified by 

root, then x and y are the pointer coordinates relative to the receiving win 
dow s origin. Otherwise, x and y are zero. 

When active button grabs and pointer grabs are in effect (see Volume One, Xlib 
Programming Manual, Section 9.4 and Volume Four, X Toolkit Intrinsics Pro 
gramming Manual, Section 12.2.2) the coordinates relative to the receiving win 
dow may not be within the window (they may be negative or greater than win 
dow height or width). 

x_root, y_root 

The pointer coordinates relative to the root window which is an ancestor of the 
event window. If the pointer was on a different screen, these are zero. 

state The state of all the buttons and modifier keys just before the event, represented 

by a mask of the button and modifier key symbols: ButtonlMask, But- 
ton2Mask, ButtonSMask, Button4Mask, ButtonSMask, Shif tMask, 
ControlMask, LockMask, ModlMask, Mod2Mask, ModSMask, Mod4- 
Mask, and ModSMask. If a modifier key is pressed and released when no other 
modifier keys are held, the Button? ress will have a state member of and 
the ButtonRelease will have a nonzero state member indicating that itself 
was held just before the event 

button A value indicating which button changed state to trigger this event One of the 
constants: Buttonl, Button2, Buttons, Button4, or Buttons. 

same_screen 

Indicates whether the pointer is currently on the same screen as this window. 
This is always TRUE unless the pointer was actively grabbed before the auto 
matic grab could take place. 

Notes 

Unless an active grab already exists, or a passive grab on the button combination that was 
pressed already exists at a higher level in the hierarchy than where the ButtonPress 
occurred, an automatic active grab of the pointer takes place when a ButtonPress occurs. 
Because of the automatic grab, the matching ButtonRelease is sent to the same application 



440 X Toolkit Intrinsics Reference Manual 



x button (continued) Button Press, Button Release 

that received the ButtonPress event If OwnerGrabButtonMask has been selected, the 
But tonRe lease event is delivered to the window which contained the pointer when the but 
ton was released, as long as that window belongs to the same client as the window in which the 
ButtonPress event occurred. If the ButtonRelease occurs outside of the client s win 
dows, or OwnerGrabButtonMask was not selected, the ButtonRelease is delivered to 
the window in which the ButtonPress occurred. The grab is terminated when all buttons 
are released. During the grab, the cursor associated with the grabbing window will track the 
pointer anywhere on the screen. 

If the application has invoked a passive button grab on an ancestor of the window in which the 
ButtonPress event occurs, then that grab takes precedence over the automatic grab, and the 
ButtonRelease will go to that window, or it will be handled normally by that client depend 
ing on the owner_e vents flag in the XGrabButton call. 



X Toolkit Intrinsics Reference Manual 44 1 



CirculateNotify 



\ 



xclrculate 



When Generated 

A CirculateNotify event reports a call to change the stacking order, and it includes 
whether the final position is on the top or on the bottom. This event is generated by 
XCirculateSubwindows, XCirculateSubwindowsDown, or XCirculate- 
SubwindowsUp. See also the CirculateRequest and Conf igureNotif y events. 

Translation Abbreviations 

In translation tables, the event type CirculateNotify may be used, or use the abbreviation 
Circ. 

Select With 

This event is selected with StructureNotifyMask in the XSelectlnput call, for the 
window to be moved, or with SubstructureNotifyMask, for the parent of the window to 
be moved. 

XEvent Structure Name 

typedef union _XEvent { 

XCirculateEvent xcirculate; 
} XEvent; 

Event Structure 

typedef struct { 

int type; 

unsigned long serial; 

Bool send_event; 

Display *display; 

Window event; 

Window window; 

int place; 
} XCirculateEvent; 




/* PlaceOnTop, PlaceOnBottom */ 



Event Structure Members 

event The window receiving the event If the event was selected by Structure 
NotifyMask, event will be the same as window. If the event was selected by 
SubstructureNotifyMask, event will be the parent of window. 

window The window that was restacked. 

place Either PlaceOnTop or PlaceOnBottom. Indicates whether the window was 
raised to the top or bottom of the stack. 



442 



X Toolkit Intrinsics Reference Manual 



xcircu laterequest 



CirculateRequest 



When Generated 

A CirculateRequest event reports when XCirculateSubwindows, XCirculate- 
SubwindowsDown, XCirculateSubwindowsUp, or XRestackWindows is called to 
change the stacking order of a group of children. 

This event differs from CirculateNotif y in that it delivers the parameters of the request 
before it is carried out This gives the client that selects this event (usually the window man 
ager) the opportunity to review the request in the light of its window management policy before 
executing the circulate request itself or to deny the request. (CirculateNotif y indicates 
the final outcome of the request) 

Translation Abbreviations 

In translation tables, the event type CirculateNotif y may be used, or use the abbreviation 

CircRec. 

Select With 

This event is selected for the parent window with SubstructureRedirectMasJc. 

XEvent Structure Name 

typedef union _XEvent { 

XCirculateRequest Event xcirculaterequest; 
} XEvent; 

Event Structure 

typedef struct { 

int type; 

unsigned long serial; 

Bool send_event; 

Display *display; 

Window parent; 

Window window; 

int place; 
} XCirculateRequestEvent; 

Event Structure Members 

parent The parent of the window that was restacked. This is the window that selected the 
event 

window The window being restacked. 

place PlaceOnTop or PlaceOnBottom. Indicates whether the window was to be 
placed on top or on the bottom of the stacking order. 



/* # of last request processed by server */ 
/* TRUE if this came from SendEvent request */ 
/* display the event was read from */ 



/* PlaceOnTop, PlaceOnBottom */ 



X Toolkit Intrinsics Reference Manual 



443 



ClientMessage \ 



xclient 



When Generated 

A ClientMessage event is sent as a result of a call to XSendEvent by a client to a particu 
lar window. Any type of event can be sent with XSendEvent, but it will be distinguished 
from normal events by the send_event member being set to TRUE. If your program wants to 
be able to treat events sent with XSendEvent as different from normal events, you can check 
the send_event member, or you can provide a translation for ClientMessage events. 

Translation Abbreviations 

In translation tables, the event type ClientMessage may be used, or use the abbreviation 
Message. 

Select With 

There is no event mask for ClientMessage events, and they are not selected with 
XSelect Input. Instead XSendEvent directs them to a specific window, which is given as 
a window ID: the PointerWindow or the InputFocus. 

XEvent Structure Name 

typedef union _XEvent { 

XClientMessageEvent xclient; 
} XEvent; 

Event Structure 

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; 
Atom message_type; 
int format; 
union { 

char b[20]; 

short s[10] ; 

long 1[5]; 
} data; 
} XClientMessageEvent; 

Event Structure Members 

me s s a ge_t ype 

An atom that specifies how the data is to be interpreted by the receiving client. 
The X server places no interpretation on the type or the data, but it must be a list of 
8-bit, 16-bit, or 32-bit quantities, so that the X server can correctly swap bytes as 
necessary. The data always consists of twenty 8-bit values, ten 16-bit values, or 
five 32-bit values, although each particular message might not make use of all of 
these values. 



444 X Toolkit Intrinsics Reference Manual 



xcliont 



(continued) 



ClientMessage 



format Specifies the format of the property specified by message_type. This will be on 
of the values 8, 16, or 32. 



X Toolkit Intrinsics Reference Manual 



445 



ColormapNotify 



X 



xcolormap 



When Generated 

A ColormapNotify event reports when the colormap attribute of a window changes or 
when the colormap specified by the attribute is installed, uninstalled, or freed. This event is 
generated by XChangeWindowAttributes, XFreeColormap, XInstallColormap, 
and XUninstallColormap. 

Translation Abbreviations 

In translation tables, the event type ColormapNotify may be used, or use the abbreviation 

Clrmap. 

Select With 

This event is selected with ColormapChangeMask. 

XEvent Structure Name 

typedef union _XEvent { 

XColormapEvent xcolormap; 
} XEvent; 

Event Structure 

typedef struct { 

int type; 

unsigned long serial, 

Bool send_event; 

Display *display; 

Window window; 

Colormap colormap; 

Bool new; 

int state; 
} XColormapEvent; 



/* # of last request processed by server */ 

/* TRUE if this came from SendEvent request * 

/* display the event was read from */ 

/* A colormap or None */ 

/* Colormaplnstalled, ColormapUninstalled */ 



Event Structure Members 

window The window whose associated colormap or attribute changes. 

colormap The colormap associated with the window, either a colormap ID or the constant 
None. It will be None only if this event was generated due to an XFree 
Colormap call. 

new TRUE when the colormap attribute has been changed, or FALSE when the color- 

map is installed or uninstalled. 

state Either Colormaplnstalled or ColormapUninstalled; it indicates 

whether the colormap is installed or uninstalled. 



446 



X Toolkit Intrinsics Reference Manual 



xconfigure- 



ConfigureNotify 



When Generated 

A ConfigureNotify event announces actual changes to a window s configuration (size, 
position, border, and stacking order). See also the CirculateReo^iest event 

Translation Abbreviations 

In translation tables, the event type ConfigureNotify may be used, or use the abbreviation 

Configure. 

Select With 

This event is selected for a single window by specifying the window ID of that window with 
StructureNotif yMask. To receive this event for all children of a window, specify the 
parent window ID with SubstructureNotif yMask. 

XEvent Structure Name 

typedef union _XEvent { 

XConfigureEvent xconfigure; 
} XEvent; 

Event Structure 

typedef struct { 

int type; 

unsigned long serial 

Bool send_event; 

Display *display; 

Window event; 

Window window; 

int x, y; 

int width, height; 

int border_width; 

Window above; 

Bool override_redirect; 
} XConfigureEvent; 

Event Structure Members 

event The window that selected the event The event and window members are identi 
cal if the event was selected with StructureNotif yMask. 

window The window whose configuration was changed. 

x, y The final coordinates of the reconfigured window relative to its parent 

width, height 

The width and height in pixels of the window after reconfiguration. 

border_width 

The width in pixels of the border after reconfiguration. 



# of last request processed by server */ 
TRUE if this came from SendEvent request 



/* display the event was read from */ 



X Toolkit Intrinsics Reference Manual 



447 



ConfigureNotify 



(continued) 



xconflgure 



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 attribute of the reconfigured window. If TRUE, it 
indicates that the client wants this window to be immune to interception by the 
window manager of configuration requests. Window managers normally should 
ignore this event if override_redirect is TRUE. 



448 



X Toolkit Intrinsics Reference Manual 



xconf igurerequest- 



ConfigureRequest 



When Generated 

A ConfigureRequest event reports when another client attempts to change a window s 
size, position, border, and/or stacking order. 

This event differs from Conf igureNotif y in that it delivers the parameters of the request 
before it is carried out This gives the client that selects this event (usually the window man 
ager) the opportunity to revise the requested configuration before executing the 
XConf igureWindow request itself or to deny the request (Conf igureNotify indicates 
the final outcome of the request) 

Translation Abbreviations 

In translation tables, the event type ConfigureRequest may be used, or use the abbrevia 
tion Conf igureReq. 

Select With 

This event is selected for any window in a group of children by specifying the parent window 
with SubstructureRedirectMask. 

XEvent Structure Name 

typedef union _XEvent { 

XConf igureRequestEvent xconf igurerequest ; 
} XEvent; 

Event Structure 

typedef struct { 

int type; 

unsigned long serial 

Bool send_event; 

Display *display; 

Window parent; 

Window window; 

int x, y; 

int width, height; 

int border_width; 

Window above; 

int detail; 

unsigned long value_mask; 
} XConf igureRequestEvent; 



# of last request processed by server */ 
TRUE if this came from SendEvent request 
display the event was read from */ 



/* Above, Below, Toplf, Bottomlf, Opposite */ 



Event Structure Members 

parent The window that selected the event This is the parent of the window being config 
ured. 

window The window that is being configured. 

x, y The requested position for the upper-left pixel of the window s border relative to 
the origin of the parent window. 



X Toolkit Intrinsics Reference Manual 



449 



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, Toplf , Bottomlf , or Opposite. Specifies the sibling 
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 XConf igurewindow request that triggered the event 



450 



X Toolkit Intrinsics Reference Manual 



xcreatewindow- 



CreateNotify 



When Generated 

A CreateNotify event reports when a window is created. 

Translation Abbreviations 

In translation tables, the event type CreateNotify may be used, or use the abbreviation 
Create. 

Select With 

This event is selected on children of a window by specifying the parent window ID with 
SubstructureNotifyMask. (Note that this event type cannot be selected by 
StructureNotifyMask). 

XEvent Structure Name 

typedef union _XEvent { 

XCreateWindowEvent xcreatewindow; 
} XEvent; 

Event Structure 

typedef struct { 

int type; 

unsigned long serial; 

Bool send_event; 

Display *display; 

Window parent; 

Window window; 

int x, y; 

int width, height; 

int border_width; 

Bool override_redirect, 
} XCreateWindowEvent; 



/* # of last request processed by server */ 
* TRUE if this came from SendEvent request */ 



display the event was read from */ 

parent of the window */ 

window ID of window created */ 

window location */ 

size of window */ 

border width */ 

creation should be overridden */ 



Event Structure Members 

pa rent The ID of the created window s parent 

window The ID of the created window. 

x, y The coordinates of the created window relative to its parent 

width, height The width and height in pixels of the created window. 

border_width The width in pixels of the border of the created window. 

override_redirect 

The override_redirect attribute of the created window. If TRUE, it 
indicates that the client wants this window to be immune to interception 
by the window manager of configuration requests. Window managers 
normally should ignore this event if override_redirect is TRUE. 



X Toolkit Intrinstcs Reference Manual 



451 



CreateNotify 



(continued) 



xcreatewindow 



Notes 

For descriptions of these members, see the XCreateWindow function and the XSet- 
WindowAttributes structure. 



452 



X Toolkit Intrinsics Reference Manual 



xdestroywindow- 



DestroyNotify 



When Generated 

A DestroyNotify event reports that a window has been destroyed. 

Translation Abbreviations 

In translation tables, the event type DestroyNotify may be used, or use the abbreviation 
Destroy. 

Select With 

To receive this event type on children of a window, specify the parent window ID and pass 
SubstructureNotifyMask as part of the event_mask argument to XSelectlnput. 
This event type cannot be selected with StructureNotif yMask. 

XEvent Structure Name 

typedef union _XEvent { 

XDestroyWindowEvent xdestroywindow; 
} XEvent; 



Event Structure 

typedef struct { 
int type; 

unsigned long serial; / 
Bool send_event; / 
Display *display; / 
Window event; 
Window window; 

} XDestroyWindowEvent; 



# of last request processed by server */ 
TRUE if this came from SendEvent request 
display the event was read from */ 



Event Structure Members 

event The window that selected the event. 

window The window that was destroyed. 



X Toolkit Intrinsics Reference Manual 



453 



EnterNotify, LeaveNotify 



X 



xcrosslng 



When Generated 

EnterNotify and LeaveNotify events occur when the pointer enters or leaves a window. 

When the pointer crosses a window border, a LeaveNotify event occurs in the window 
being left and an EnterNotify event occurs in the window being entered. Whether or not 
each event is queued for any application depends on whether any application selected the right 
event on the window in which it occurred. 

In addition, EnterNotify and LeaveNotify events are delivered to windows that are vir 
tually crossed. These are windows that are between the origin and destination windows in the 
hierarchy but not necessarily on the screen. Further explanation of virtual crossing is provided 
two pages following. 

Translation Abbreviations 

In translation tables, the event types EnterNotify and LeaveNotify may be used, or use 
one of the abbreviations shown in the following table. 



Abbreviation 



Enter 

EnterWindow 
Leave 
LeaveWindow 



Description 



Pointer entered window 
Pointer entered window 
Pointer left window 
Pointer left window 



The Core widget field compress_enterleave controls whether pairs of EnterNotify 
and LeaveNotify events with no intervening events are ignored. For more information, see 
Chapter 8, More Input Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual. 

Select With 

Each of these events can be selected separately with XEnterWindowMask and XLeave- 
WindowMask. 

XEvent Structure Name 

typedef union _XEvent { 

XCrossingEvent xcrossing; 
} XEvent; 



Event Structure 

typedef struct 
int type; 



/* of event */ 



unsigned long serial; /* # of last request processed by server */ 



Bool send_event; 
Display *display; 
Window window; 
Window root; 
Window subwindow; 



/* TRUE if this came from SendEvent request */ 

/* display the event was read from */ 

/* event window it is reported relative to */ 

/* root window that the event occurred on */ 

/* child window */ 



454 



X Toolkit Intrinsics Reference Manual 



xcrosslng 



(continued) 



EnterNotify, LeaveNotify 



Time time; 
int x, y; 
int x_root, 
int mode; 
int detail; 



y root, 



Bool same_screen; 

Bool focus; 

unsigned int state 
} XCrossingEvent; 
typedef XCrossingEvent 
typedef XCrossingEvent 



/* milliseconds */ 

/* pointer x, y coordinates in receiving window * 

/* coordinates relative to root */ 

/* NotifyNormal, NotifyGrab, NotifyUngrab */ 

/* NotifyAncestor, NotifyVirtual, Notifylnferior, 

* NotifyNonLinear, NotifyNonLinearVirtual */ 

/* same screen flag */ 

/* Boolean focus */ 

/* key or button mask */ 

XEnterWindowEvent ; 
XLeaveWindowE vent ; 



Event Structure Members 

subwindow In a LeaveNotify event, if the pointer began in a child of the receiving win 
dow then the child member is set to the window ID of the child. Otherwise, it 
is set to None. For an EnterNotify event, if the pointer ends up in a child of 
the receiving window then the child member is set to the window ID of the 
child. Otherwise, it is set to None. 

time The server time when the crossing event occurred, in milliseconds. Time is 

declared as unsigned long, so it wraps around when it reaches the maxi 
mum value of a 32 bit number (every 49.7 days). 

x , y The point of entry or exit of the pointer relative to the event window. 

x_root, y_root 

The point of entry or exit of the pointer relative to the root window. 

mode Normal crossing events or those caused by pointer warps have mode Not if y- 

Normal; events caused by a grab have mode NotifyGrab; and events caused 
by a released grab have mode NotifyUngrab. 

detail The value of the detail member depends on the hierarchical relationship 
between the origin and destination windows and the direction of pointer transfer. 
Determining which windows receive events and with which detail members 
is quite complicated. This topic is described in the next section. 

same_screen 

Indicates whether the pointer is currently on the same screen as this window. 
This is always TRUE unless the pointer was actively grabbed before the auto 
matic grab could take place. 

focus If the receiving window is the focus window or a descendant of the focus win 

dow, the focus member is TRUE; otherwise it is FALSE. 

state The state of all the buttons and modifier keys just before the event, represented 

by a mask of the button and modifier key symbols: ButtonlMask, 



X Toolkit Intrinsics Reference Manual 



455 



EnterNotify, LeaveNotify (continued) xcrossing 

Button2Mask, ButtonSMask, Button4Mask, ButtonSMask, Shift- 
Mask, ControlMask, LockMask, ModlMask, Mod2Mask, ModSMask, 
Mod4Mask, and ModSMask. 

Virtual Crossing and the detail Member 

Virtual crossing occurs when the pointer moves between two windows that do not have a 
parent-child relationship. Windows between the origin and destination windows in the hierar 
chy receive EnterNotify and LeaveNotify events. The detail member of each of 
these events depends on the hierarchical relationship of the origin and destination windows and 
the direction of pointer transfer. 

Virtual crossing is an advanced topic that you shouldn t spend time figuring out unless you 
have an important reason to use it I have never seen an application that uses this feature, and I 
know of no reason for its extreme complexity. With that word of warning, proceed. 

Let s say the pointer has moved from one window, the origin, to another, the destination. First 
we ll specify what types of events each window gets, and then the detail member of each of 
those events. 

The window of origin receives a LeaveNotify event and the destination window receives an 
EnterNotify event, if they have requested this type of event If one is an inferior of the 
other, the detail member of the event received by the inferior is Not if yAncestor and the 
detail of the event received by the superior is Notif yinf erior. If the crossing is between 
parent and child, these are the only events generated. 

However, if the origin and destination windows are not parent and child, other windows are vir 
tually crossed and also receive events. If neither window is an ancestor of the other, ancestors 
of each window up to but not including the least common ancestor receive LeaveNotify 
events if they are in the same branch of the hierarchy as the origin and EnterNotify events 
if they are in the same branch as the destination. These events can be used to track the motion 
of the pointer through the hierarchy. 

In the case of a crossing between a parent and a child of a child, the middle child receives a 
LeaveNotify with detail Notif yVirtual. 

In the case of a crossing between a child and the parent of its parent, the middle child 
receives an EnterNotify with detail Notif yVirtual. 

In a crossing between windows whose least common ancestor is two or more windows 
away, both the origin and destination windows receive events with detail Not if y- 
Nonlinear. The windows between the origin and the destination in the hierarchy, up to 
but not including their least common ancestor, receive events with detail Not if y- 
NonlinearVirtual. The least common ancestor is the lowest window from which both 
are descendants. 

If the origin and destination windows are on separate screens, the events and details gen 
erated are the same as for two windows not parent and child, except that the root windows 
of the two screens are considered the least common ancestor. Both root windows also 
receive events. 



456 X Toolkit Intrinsics Reference Manual 



xcrossing 



(continued) 



EnterNotlfy, LeaveNotify 



Table C-2 shows the event types generated by a pointer crossing from window A to window B 
when window C is the least common ancestor of A and B. 

Table C-2. Border Crossing Events and Window Relationship 



LeaveNotify 



EnterNotify 



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 



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 



Table C-3 lists the detail members in events generated by a pointer crossing from window A 
to window B. 

Table C-3. Event detail Member and Window Relationship 



detail Flag 



Window Deli vered To 



NotifyAncestor 
Notify Inferior 
NotifyVirtual 

NotifyNonlinear 
NotifyNonlinearVirtual 



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. 



X Toolkit Intrinsics Reference Manual 



457 



EnterNotlfy, LeaveNotify 



(continued) 



xcrossing 



For example, Figure C-l shows the events that are generated by a movement from a window 
(window A) to a child (window Bl) of a sibling (window fl). This would generate three events: 
a LeaveNotify with detail Not if yNonlinear for the window A, an EnterNotif y with 
detail NotifyNonlinearVirtual for its sibling window 5, and an EnterNotify with 
detail Not if yNonlinear for the child (window Bl). 









RootWindow 
(no event) 


^^ \^ 


A B 

LeaveNotify event with EnterNotify event with 
detail NotifyNonlinear \ detail NotifyNonlinea 


1 

rVirtual 


\ 




A1 \ 

no event 


B1 

LeaveNotify event W 
detail NotifyNonlin* 


nth 

sar 









Figure C-1. Events generated by a move between windows 

EnterNotify and LeaveNotify events are also generated when the pointer is grabbed, if 
the pointer was not already inside the grabbing window. In this case, the grabbing window 
receives an EnterNotify and the window containing the pointer receives a LeaveNotify 
event, both with mode Not if yUngrab. The pointer position in both events is the position 
before the grab. The result when the grab is released is exactly the same except that the two 
windows receive EnterNotify instead of LeaveNotify and vice versa. 



458 



X Toolkit Intrinshs Reference Manual 



xcrossing 



(continued) 



EnterNotlfy, LeaveNotlfy 



Figure C-2 demonstrates the events and details caused by various pointer transitions, indicated 
by heavy arrows. 




LeaveNotify, 
Ancestor 



LeaveNotlfy, 
Inferior 



EnterNotlfy, 




LeaveNotify, 
NonLinearVirtual 



LeaveNotify, 
NonLinearVirtual 



LeaveNotify, 



LeaveNotify, 
NonLinear 



EnterNotify, 



LeaveNotify, 
NonLinear 



EnterNotify, 



EnterNotlfy, 
NonLinear 



Figure C-2. Border crossing events and detail member for pointer movement from window A to 
window B, for various window relationships 



X Toolkit Intrinsics Reference Manual 



459 



Expose 



X 



xexpose- 



When Generated 

An Expose event is generated when a window becomes visible or a previously invisible part 
of a window becomes visible. Only inputOutput windows generate or need to respond to 
Expose events; inputOnly windows never generate or need to respond to them. The 
Expose event provides the position and size of the exposed area within the window and a 
rough count of the number of remaining exposure events for the current window. 

Only when an application adds drawing capability to a widget from the application will a trans 
lation or event handler for Expose events be necessarily. Xt automatically calls the expose 
method of each widget in response to these events. 

Translation Abbreviations 

In translation tables, the event type Expose is the only valid string; there are no abbreviations. 

The Core widget field compress_exposures controls whether contiguous Expose events 
are coalesced before calling a widget s expose method. For more information, see , in . 

Select With 

This event is selected with ExposureMask. 

XEvent Structure Name 

typedef union _XEvent { 

XExposeEvent xexpose; 
} XEvent; 

Event Structure 

typedef struct { 

int type; 

unsigned long serial; 

Bool send_event; 

Display *display; 

Window window; 

int x, y; 

int width, height; 

int count; 
} XExposeEvent; 



/* # of last request processed by server */ 
/* TRUE if this came from SendEvent request */ 
/* display the event was read from */ 



/* if nonzero, at least this many more */ 



Event Structure Members 

x, y The coordinates of the upper-left corner of the exposed region relative to 

the origin of the window. 

widt h , he ight The width and height in pixels of the exposed region. 

count The approximate number of remaining contiguous Expose events that 

were generated as a result of a single function call. 

Notes 



460 



X Toolkit Intrinsics Reference Manual 



xexpose (continued) Expose 

Notes 

A single action such as a window movement or a function call can generate several exposure 
events on one window or on several windows. The server guarantees that all exposure events 
generated from a single action will be sent contiguously, so that they can all be handled before 
moving on to other event types. This allows an application to keep track of the rectangles 
specified in contiguous Expose events, set the clip__mask in a GC to the areas specified in 
the rectangle using XSetRegion or XSetClipRectangles, and then finally redraw the 
window clipped with the GC in a single operation after all the Expose events have arrived. 
The last event to arrive is indicated by a count of 0. In Release 2, XUnionRectwith- 
Region can be used to add the rectangle in Expose events to a region before calling XSet 
Region. 

If your application is able to redraw partial windows, you can also read each exposure event in 
turn and redraw each area. 



X Toolkit Intrinsics Reference Manual 46 1 



Focusln, FocusOut 



X 



xfocus 



When Generated 

Focusln and FocusOut events occur when the keyboard focus window changes, as a result 
of an XSetlnputFocus call. They are much like EnterNotify and LeaveNotify 
events except that they track the focus rather than the pointer. 

When a focus change occurs, a FocusOut event is delivered to the old focus window and a 
Focusln event to the window which receives the focus. In addition, windows in between 
these two windows in the window hierarchy are virtually crossed and receive focus change 
events, as described below. Some or all of the windows between the window containing the 
pointer at the time of the focus change and the root window also receive focus change events, 
as described below. 

Translation Abbreviations 

In translation tables, the event types Focusln and FocusOut may be used; there are no 
abbreviations. 

Select With 

Focusln and FocusOut events are selected with FocusChangeMask. They cannot be 
selected separately. 

X Event Structure Name 

typedef union _XEvent { 

XFocusChangeEvent xfocus; 
} XEvent; 



Event Structure 

typedef struct { 
int type; 

unsigned long serial; 
Bool send_event; 
Display *display; 
Window window; 
int mode; 
int detail; 



} XFocusChangeEvent; 
typedef XFocusChangeEvent 
typedef XFocusChangeEvent 



/* Focusln or FocusOut */ 

/* # of last request processed by server */ 

/* TRUE if this came from SendEvent request */ 

/* display the event was read from */ 

/* window of event */ 

/* NotifyNormal, NotifyGrab, NotifyUngrab */ 

/* NotifyAncestor, NotifyVirtual, Not if y- 

* Inferior, NotifyNonLinear, NotifyNonLinear- 

* Virtual, NotifyPointer, NotifyPointerRoot, 

* NotifyDetailNone */ 

XFocusInEvent; 
XFocusOutEvent ; 



Event Structure Members 

mode For events generated when the keyboard is not grabbed, mode is Notify 
Normal; when the keyboard is grabbed, mode is NotifyGrab; and when a key 
board is ungrabbed, mode is NotifyUngrab. 



462 



X Toolkit Intrinsics Reference Manual 



xfocus (continued) Focusln, FocusOut 

detail The detail 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 Focusln and 
FocusOut events. 

When a focus change occurs, A FocusOut event is delivered to the old focus window and a 
Focusln 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 Focusln 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 LeaveNotif y and EnterNotif y events, but with 
even more permutations to make life complicated. 

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 Toolkit 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 



Focusln 



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 Flag 



Window Delivered To 



NotifyAncestor 
Notify Inferior 
NotifyVirtual 

NotifyNonlinear 
NotifyNonlinearVirtual 



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 



xfocus 



detail Rag 



NotifyPointer 



NotifyPointerRoot 



NotifyDetailNone 



(continued) 



Window Delivered To 



Focusln, FocusOut 



Window P and windows up to but not including the 
origin or destination windows. 

Window P and all windows up to its root, and all 
other roots, when focus is set to or from Pointer- 
Root. 

All roots, when focus is set to or from None. 



The following two pages show all the possible combinations of focus transitions and of origin, 
destination, and pointer windows and shows the types of events that are generated and their 
detail member. Solid lines indicate branches of the hierarchy. Dotted arrows indicate the 
direction of transition of the focus. At each end of this arrow are the origin and destination 
windows, windows A to B. Arrows ending in a bar indicate that the event type and detail 
described are delivered to all windows up to the bar. 

In any branch, there may be windows that are not shown. Windows in a single branch between 
two boxes shown will get the event types and details shown beside the branch. 



X Toolkit Intrinsics Reference Manual 



465 



Focusln, FocusOut 



(continued) 



xfocus 



Focusln, 
inferior 




window P 

is between A and B, 
windows from P up to but 
not including B get 

Focus in with detail 
Notifylnterior 




Roots of other Screens: 

Focusln With detal PointerRoot 



FocusOut, 
NonLinearVirtual 




Focusln, 

NonLinearVirtual 



Focusln, 
NonLinear 



PointerRoot 




FocusOut, 
NonLinearVirtual 



FocusOut 
Pointer 



NonLinearVirtual 



NonLinearVirtual 




Roots of other Screens: 

Focusln with detal None 



FocusOut 
Pointer 



Focusln 
Pointer 




FocusOut, 
NonLinearVirtual 



FocusOut 
Pointer 



Figure C-3. Focusln and FocusOut event schematics 



466 



X Toolkit Intrinsics Reference Manual 



xfocus 



(continued) 



Focusln, FocusOut 



Roots of other Screens: 

FocusOut with detail PointerRoot 



PointerRoot 




Focusln, 
NonLinear Virtual 



Focusln, 
NonLinear 



Focusln 
Pointer 



Roots of other Screens: 

FocusOut With detail None 




Focusln, 
NonLinearVirtual 



Focusln, 
NonLinear 



Focusln 
Pointer 



FOCUS Change from PointerRoot to None 

All Root Windows: 

FocusOut With detail PointerRoot 



FocusOut, 
PointerRoot 




All Root Windows: 

FocusOut With detail None 



PointerRoot 




Figure C-3. Focusln and FocusOut event schematics (continued) 

Focusln and FocusOut events are also generated when the keyboard is grabbed, if the focus 
was not already assigned to the grabbing window. In this case, all windows receive events as if 
the focus was set from the current focus to the grab window. When the grab is released, the 
events generated are just as if the focus was set back. 



X Toolkit Intrinsics Reference Manual 



467 



GraphicsExpose, NoExpose , moexpose - 

When Generated 

GraphicsExpose events indicate that the source area for a XCopyArea or XCopyPlane 
request was not available because it was outside the source window or obscured by a window. 
NoExpose events indicate that the source region was completely available. 

Neither of these events are used in Xt s automatic processing of Expose events. If a widget 
needs to use them, it must provide a translation or event handler for them and then call its 
expose method directly. 

Translation Abbreviations 

In translation tables, the event types GraphicsExpose and NoExpose may be used, or use 
the abbreviations GrExp or NoExp. 

Select With 

These events are not selected with XSelect Input but are sent if the GC in the XCopyArea 
or XCopyPlane request had its graphics_exposures flag set to TRUE. If graph- 
ics_exposures is TRUE in the GC used for the copy, either one NoExpose event or one or 
more GraphicsExpose events will be generated for every XCopyArea or XCopyPlane 
call made. 

XEvent Structure Name 

typedef union _XEvent { 

XNoExposeEvent xnoexpose; 
XGraphicsExposeEvent xgraphicsexpose ; 

} XEvent; 

Event Structure 

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 */ 
Drawable drawable; 
int x, y; 

int width, height; 

int count; /* if nonzero, at least this many more */ 

int major_code; /* core is CopyArea or CopyPlane */ 
int minor_code; /* not defined in the core */ 

} XGraphicsExposeEvent; 

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 */ 
Drawable drawable; 



468 X Toolkit Intrinsics Reference Manual 



xnoexpose 



(continued) 



GraphicsExpose, NoExpose 



int major_code; 
int minor_code; 
} XNoExposeEvent; 



/* core is CopyArea or CopyPlane */ 
/* not defined in the core */ 



Event Structure Members 

drawable A window or an off-screen pixmap. This specifies the destination of the 

graphics request that generated the event. 

x, y The coordinates of the upper-left comer of the exposed region relative to 

the origin of the window. 

widt h , he igh t The width and height in pixels of the exposed region. 

count The approximate number of remaining contiguous GraphicsExpose 

events that were generated as a result of the XCopyArea or XCopy- 
Planecall. 

ma j or_code The graphics request used. This may be one of the symbols CopyArea or 
CopyPlane, or a symbol defined by a loaded extension. 

minor_code Zero unless the request is part of an extension. 

Notes 

Expose events and GraphicsExpose events both indicate the region of a window that was 
actually exposed (x, y, width, and height). Therefore they can often be handled similarly. 



X Toolkit Intrinsics Reference Manual 



469 



Gravity Notify 



X 



xgravity 



When Generated 

A GravityNotif y event reports when a window is moved because of a change in the size of 
its parent This happens when the win_gravity attribute of the child window is something 
other than StaticGravity or UnmapGravity. 

Translation Abbreviations 

In translation tables, the event type GravityNotify may be used, or use the abbreviation 
Grav. 

Select With 

This event is selected for a single window by specifying the window ID of that window with 
StructureNotif yMask. To receive notification of movement due to gravity for a group of 
siblings, specify the parent window ID with SubstructureNotif yMask. 

XEvent Structure Name 

typedef union _XEvent { 

XGravityEvent xgravity; 
} XEvent; 

Event Structure 

typedef struct { 

int type; 

unsigned long serial; / : 

Bool send_event; / 

Display ^display; / 

Window event; 

Window window; 

int x, y; 
} XGravityEvent; 

Event Structure Members 

event The window that selected the event 

window The window that was moved. 

x, y The new coordinates of the window relative to its parent 



# of last request processed by server */ 
TRUE if this came from SendEvent request */ 
display the event was read from */ 



470 



X Toolkit Intrinsics Reference Manual 



xkeymap- 



KeymapNotify 



When Generated 

A KeymapNotify event reports the state of the keyboard and occurs when the pointer or key 
board focus enters a window. KeymapNotify events are reported immediately after 
EnterNotify or Focus In events. This is a way for the application to read the keyboard 
state as the application is "woken up," since the two triggering events usually indicate that the 
application is about to receive user input. 

Translation Abbreviations 

In translation tables, the event type KeymapNotify may be used, or use the abbreviation 
Keymap. 

Select With 

This event is selected with KeymapStateMask. 
XEvent Structure Name 

typedef union _XEvent { 

XKeymapEvent xkeymap; 
} XEvent; 



Event Structure 

typedef struct { 

int type; 

unsigned long serial, 

Bool send_event; 

Display *display; 

Window window; 

char key_vector [32] ; 
} XKeymapEvent; 

Event Structure Members 



/* # of last request processed by server */ 
/* TRUE if this came from SendEvent request 
/* display the event was read from */ 



window Reports the window which was reported in the window member of the 

proceeding EnterNotify or Focus In event 

key_vector A bit vector or mask, each bit representing one physical key, with a total of 
256 bits. For a given key, its keycode is its position in the keyboard vector. 
You can also get this bit vector by calling XQueryKeymap. 

Notes 

The serial member of KeymapNotify does not contain the serial number of the most 
recent Protocol Request processed, because this event always follows immediately after 
Focusln or EnterNotify events in which the serial member is valid. 



X Toolkit Intrinsics Reference Manual 



471 



KeyPress, KeyRelease 



\ 



xkey 



When Generated 

KeyPress and KeyRelease events are generated for all keys, even those mapped to modi 
fier keys such as Shift or Control. 

Translation Abbreviations 

In translation tables, the event types KeyPress and KeyRelease may be used, or use one of 
the abbreviations shown in the following table. 



Abbreviation 



Key 
KeyDown 

Ctrl 
Meta 
Shift 
Key Up 



Description 



Key pressed 

Key pressed 

KeyPress with Ctrl modifier 

KeyPress with Meta modifier 

KeyPress with Shift modifier 

Key released 



To execute an action in response to the press or release of an individual key, you can use any of 
the above abbreviations in combination with a detail. For example, in the translation: 

<Key>a : append ( ) 

the append action is invoked when the key "a" is pressed, regardless of which modifiers are 
being held. For more information on how to use translations to manage key events, see Chapter 
7, Events, Translations, and Accelerators, in Volume Four, X Toolkit Intrinsics Programming 
Manual. 

Select With 

Each type of keyboard event may be selected separately with KeyPressMask and Key- 
ReleaseMask. 

XEvent Structure Name 

typedef union _XEvent { 

XKeyEvent xkey; 
} XEvent; 



Event Structure 

typedef struct { 
int type; 

unsigned long serial; 
Bool send_event; 
Display *display; 
Window window; 
Window root; 
Window subwindow; 
Time time; 



/* of event */ 

/* # of last request processed by server */ 

/* TRUE if this came from SendEvent request */ 

/* display the event was read from */ 

/* event window it is reported relative to */ 

/* root window that the event occurred on */ 

/* child window */ 

/* milliseconds */ 



472 



X Toolkit Intrinsics Reference Manual 



xkey 



(continued) 



KeyPress, KeyRelease 



int x, y; 

int x_root, y_root; 
unsigned int state; 
unsigned int keycode, 
Bool same screen; 



/* pointer coords relative to receiving window */ 

/* coordinates relative to root */ 

/* modifier key and button mask */ 

/* server-dependent code for key */ 

/* same screen flag */ 



} XKeyEvent; 

typedef XKeyEvent XKeyPressedEvent; 

typedef XKeyEvent XKeyReleasedEvent; 

Event Structure Members 

subwindow If the source window is the child of the receiving window, then the subwindow 
member is set to the ID of that child. 

time The server time when the button event occurred, in milliseconds. Time is 

declared as unsigned long, so it wraps around when it reaches the maxi 
mum value of a 32-bit number (every 49.7 days). 

x, y If the receiving window is on the same screen as the root window specified by 

root, then x and y are the pointer coordinates relative to the receiving win 
dow s origin. Otherwise, x and y are zero. 

When active button grabs and pointer grabs are in effect (see Volume One, Xlib 
Programming Manual, Section 9.4 and Volume Four, X Toolkit Intrinsics Pro 
gramming Manual, Chapter 12, Menus, Gadgets, and Cascaded Pop Ups, Sec 
tion 12.2.1), the coordinates relative to the receiving window may not be within 
the window (they may be negative or greater than window height or width). 

x_root, y_root 

The pointer coordinates relative to the root window which is an ancestor of the 
event window. If the pointer was on a different screen, these are zero. 

state The state of all the buttons and modifier keys just before the event, represented 

by a mask of the button and modifier key symbols: ButtonlMask, But- 
ton2Mask, Button3Mask, Button4Mask, ButtonSMask, Shif tMask, 
ControlMask, LockMask, ModlMask, Mod2Mask, ModSMask, Mod4- 
Mask, and ModSMask. 

keycode The keycode member contains a server-dependent code for the key that 
changed state. As such it should be translated into the portable symbol called a 
keysym before being used. It can also be converted directly into ASCII with 
XLookupString. For a description and examples of how to translate key- 
codes, see Volume One, Section 9.1.1, and Volume Four, Section 13.4. 

Notes 

Remember that not all hardware is capable of generating release events, and that only the main 
keyboard (a-z, A-Z, 0-9), Shift, and Control keys are always found. 



X Toolkit Intrinsics Reference Manual 



473 



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 Intrinsics Reference Manual 



xmap, xunmap- 



MapNotify, UnmapNotify 



When Generated 

The X server generates MapNotify and UnmapNotify events when a window changes state 
from unmapped to mapped or vice versa. In most cases, Xt widgets are mapped in the final step 
of the process of realizing the application, initiated with XtRealizeWidget. 

Translation Abbreviations 

In translation tables, the event types MapNotify and UnmapNotify may be used, or use the 
abbreviations Map or Unmap. 

Select With 

To receive these events on a single window, use StructureNotifyMask in the call to 
xselect input for the window. To receive these events for all children of a particular par 
ent, specify the parent window ID and use SubstructureNotif yMask. 

XEvent Structure Name 

typedef union _XEvent { 

XMapEvent xmap; 
XUnmapEvent xunmap; 

} XEvent; 

Event Structure 

typedef struct { 

int type; 

unsigned long serial; / 

Bool send_event; / : 

Display *display; / 

Window event; 

Window window; 

Bool override_redirect; 
} XMapEvent; 



# of last request processed by server */ 
TRUE if this came from SendEvent request 
display the event was read from */ 



/* Boolean, is override set */ 



typedef struct { 

int type; 

unsigned long serial; / 

Bool send_event; A 

Display *display; / 

Window event; 

Window window; 

Bool from_configure; 
} XUnmapEvent; 



Event Structure Members 

event The window that selected this event. 

window The window that was just mapped or unmapped. 



# of last request processed by server */ 
TRUE if this came from SendEvent request 
display the event was read from */ 



X Toolkit Intrinsics Reference Manual 



475 



MapNotlfy, UnmapNotlfy (continued) xmap, xunmap 

override_redirect (XMapEvent only) 

TRUE or FALSE. The value of the override_redirect attribute of the window 
that was just mapped. 

f rom_conf igure (XUnmapEvent only) 

TRUE if the event was generated as a result of a resizing of the window s parent 
when the window itself had a win_gravity of UnmapGravity. See the 
description of the win_gravity attribute in Volume One, Section 4.3.4. FALSE 
otherwise. 



X Toolkit Intrinsics Reference Manual 



xmapping- 



MappingNotify 



When Generated 

A MappingNotify event is sent when any of the following is changed by another client: the 
mapping between physical keyboard keys (keycodes) and keysyms, the mapping between mod 
ifier keys and logical modifiers, or the mapping between physical and logical pointer buttons. 
These events are triggered by a call to XSetModifierMapping or XSetPointer- 
Mapping, if the return status is MappingSuccess, or by any call to XChangeKeyboard- 
Mapping. 

This event type should not be confused with the event that occurs when a window is mapped; 
that is a MapNotify event Nor should it be confused with the KeymapNotify event, 
which reports the state of the keyboard as a mask instead of as a keycode. 

Translation Abbreviations 

In translation tables, the event type MappingNotify may be used, or use the abbreviation 
Mapping. 

Select With 

The X server sends MappingNotify events to all clients. It is never selected and cannot be 
masked with the window attributes. 

XEvent Structure Name 

typedef union _XEvent { 

XMappingEvent xmapping; 
} XEvent; 

Event Structure 

typedef struct { 
int type; 

unsigned long serial, 
Bool send_event; 
Display *display; 
Window window; 
int request; 

int first_keycode; 
int count; 
} XMappingEvent; 



/* # of last request processed by server */ 

/* TRUE if this came from SendEvent request 

/* display the event was read from */ 

/* unused */ 

/* one of MappingModif ier, MappingKeyboard, 

* MappingPointer */ 

/* first keycode */ 

/* range of change with first keycode*/ 



Event Structure Members 

request The kind of mapping change that occurred: MappingModif ier for a successful 
XSetModifierMapping (keyboard Shift, Lock, Control, Meta keys), 
MappingKeyboard for a successful XChangeKeyboardMapping (other 
keys), and MappingPointer for a successful XSetPointerMapping 
(pointer button numbers). 



X Toolkit Intrinsics Reference Manual 



477 



MapplngNotlfy (continu&d) xmapplng 

first_keycode 

If the request member is MappingKeyboard or MappingModif ier, then 
f irst_keycode indicates the first in a range of keycodes with altered map 
pings. Otherwise it is not set. 

count If the request member is MappingKeyboard or MappingModif ier, then 
count indicates the number of keycodes with altered mappings. Otherwise it is 
not set 

Notes 

If the request member is MappingKeyboard, clients should call XRef reshKeyboard- 
Mapping. 

The normal response to a request member of MappingPointer or MappingModif ier 
is no action. This is because the clients should use the logical mapping of the buttons and mod 
ifiers to allow the user to customize the keyboard if desired. If the application requires a partic 
ular mapping regardless of the user s preferences, it should call XGetModif ierMapping or 
XGetPointerMapping to find out about the new mapping. 



X Toolkit Intrinsics Reference Manual 



. S MapRequest 

xmaprequest r 

When Generated 

A MapRequest event occurs when the functions XMapRaised and XMapWindow are 
called. 

This event differs from MapNot if y in that it delivers the parameters of the request before it is 
carried out This gives the client that selects this event (usually the window manager) the 
opportunity to revise the size or position of the window before executing the map request itself 
or to deny the request (MapNot if y indicates the final outcome of the request.) 

Translation Abbreviations 

In translation tables, the event type MapRequest may be used, or use the abbreviation Map- 
Req. 

Select With 

This event is selected by specifying the window ID of the parent of the receiving window with 
SubstructureRedirectMask. (In addition, the override_redirect member of the 
XSetWindowAttributes structure for the specified window must be FALSE.) 

XEvent Structure Name 

typedef union _XEvent { 

XMapRequestEvent xmaprequest; 
} XEvent; 

Event Structure 

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 parent; 
Window window; 

} XMapRequestEvent; 

Event Structure Members 

pa rent The ID of the parent of the window being mapped. 

window The ID of the window being mapped. 



X Toolkit Intrinsics Reference Manual 479 



MotionNotify 



\ 



xmotion 



When Generated 

A MotionNotify event reports that the user moved the pointer or that a program warped the 
pointer to a new position within a single window. 

Translation Abbreviations 

In translation tables, the event type MotionNotify may be used, or use one of the abbrevia 
tions shown in the following table. 



Abbreviation 


Description 


Motion 
PtrMoved 
MouseMoved 
BtnMotion 
BtnlMotion 
Btn2Motion 
Btn3Motion 
Btn4Motion 
BtnSMotion 


Pointer moved 
Pointer moved 
Pointer moved 
Pointer moved with any button held down 
Pointer moved with button 1 held down 
Pointer moved with button 2 held down 
Pointer moved with button 3 held down 
Pointer moved with button 4 held down 
Pointer moved with button 5 held down 



The Core widget field compress_motion determines whether the widget gets all motion 
events or only periodic position updates. For more information, see Chapter 8, More Input 
Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual. 

Select With 

This event is selected with PointerMotionMaslc, PointerMotionHintMask, 
ButtonMotionMask, ButtonlMotionMasJc, Button2MotionMask, Button3- 
MotionMask, Button4MotionMask, and ButtonSMotionMask. These masks deter 
mine the specific conditions under which the event is generated. 

XEvent Structure Name 

typedef union _XEvent { 

XMotionEvent xmotion; 
} XEvent; 



Event Structure 

typedef struct { 

int type; /* 
unsigned long serial; /* 

Bool send_event; /* 

Display *display; /* 

Window window; /* 

Window root; /* 

Window subwindow; /* 

Time time; /* 



of event */ 

# of last request processed by server */ 

TRUE if this came from SendEvent request */ 

display the event was read from */ 

event window it is reported relative to */ 

root window that the event occurred on */ 

child window */ 

milliseconds */ 



480 



X Toolkit Intrinsics Reference Manual 



xmotlon 



(continued) 



MotlonNotify 



/* pointer coords relative to receiving window */ 



coordinates relative to root */ 
button and modifier key mask */ 
is this a motion hint */ 
same screen flag */ 



int x, y; 

int x_root, y_root; / 

unsigned int state; / ; 

char is_hint; / 

Bool same_screen; / 
} XMotionEvent; 
typedef XMotionEvent XPointerMovedEvent; 

Event Structure Members 

subwindow If the source window is the child of the receiving window, then the subwindow 
member is set to the ID of that child. 

time The server time when the button event occurred, in milliseconds. Time is 

declared as unsigned long, so it wraps around when it reaches the maximum 
value of a 32 bit number (every 49.7 days). 

x, y If the receiving window is on the same screen as the root window specified by 

root, then x and y are the pointer coordinates relative to the receiving win 
dow s origin. Otherwise, x and y are zero. 

When active button grabs and pointer grabs are in effect (see Section 9.4 in Vol 
ume One, Xlib Programming Manual, and Section 12.2.1 in Volume Four, X 
Toolkit Intrinsics Programming Manual) the coordinates relative to the receiv 
ing window may not be within the window (they may be negative or greater than 
window height or width). 

x_root, y_root 

The pointer coordinates relative to the root window which is an ancestor of the 
event window. If the pointer was on a different screen, these are zero. 

state The state of all the buttons and modifier keys just before the event, represented 

by a mask of the button and modifier key symbols: ButtonlMask, But- 
ton2Mask, Button3Mask, Button4Mask, ButtonSMask, Shif tMask, 
ControlMask, LockMask, ModlMask, Mod2Mask, Mod3Mask, Mod4- 
Mask, and ModSMask. 

is_hint Either the constant NotifyNormal or NotifyHint. NotifyHint indi 
cates that the PointerMot ionHintMask was selected. In this case, just one 
event is sent when the mouse moves, and the current position can be found by 
calling XQueryPointer, or by examining the motion history buffer with 
XGetMotionE vents, if a motion history buffer is available on the server. 
NotifyNormal indicates that the event is real, but it may not be up to date 
since there may be many more later motion events on the queue. 

same_screen 

Indicates whether the pointer is currently on the same screen as this window. 
This is always TRUE unless the pointer was actively grabbed before the auto 
matic grab could take place. 



X Toolkit Intrinsics Reference Manual 



481 



MotlonNotlfy (continued) xmotion 

Notes 

If the processing you have to do for every motion event is fast, you can probably handle all of 
them without requiring motion hints. However, if you have extensive processing to do for each 
one, you might be better off using the hints and calling XQueryPointer or using the history 
buffer if it exists. XQueryPointer is a round-trip request, so it can be slow. 

EnterNotify and LeaveNotify events are generated instead of MotionEvents if the 
pointer starts and stops in different windows. 



X Toolkit Intrinsics Reference Manual 



xproperty- 



PropertyNotify 



When Generated 

A PropertyNotify event indicates that a property of a window has changed or been 
deleted. This event can also be used to get the current server time (by appending zero-length 
data to a property). PropertyNotify events are generated by XChangeProperty, 
XDeleteProperty, XGetWindowProperty, or XRotateWindowProperties. 

Translation Abbreviations 

In translation tables, the event type PropertyNotify may be used, or use the abbreviation 
Prop. 

Select With 

This event is selected with PropertyChangeMask. 

XEvent Structure Name 

typedef union _XEvent { 

XPropertyEvent xproperty; 
} XEvent; 

Event Structure 

typedef struct { 

int type; 

unsigned long serial; 

Bool send_event; 

Display *display; 

Window window; 

Atom atom; 

Time time; 

int state; 
} XPropertyEvent; 



/* # of last request processed by server */ 
/* TRUE if this came from SendEvent request 
/* display the event was read from */ 



/* NewValue, Deleted */ 



Event Structure Members 

window The window whose property was changed, not the window that selected the event 

atom The property that was changed. 

state Either PropertyNewValue or PropertyDelete. Whether the property was 
changed to a new value or deleted. 

time The time member specifies the server time when the property was changed. 



X Toolkit Intrinsics Reference Manual 



483 



ReparentNotify 



. 

V arent- 



When Generated 

A ReparentNotify event reports when a client successfully reparents a window. 

Translation Abbreviations 

In translation tables, the event type ReparentNotify may be used, or use the abbreviation 

Reparent. 

Select With 

This event is selected with Subst ructureNot if yMask by specifying the window ID of the 
old or the new parent window or with StructureNotif yMask by specifying the window 
ID. 

XEvent Structure Name 

typedef union _XEvent { 

XReparentEvent xreparent; 
} XEvent; 

Event Structure 

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 event; 

Window window; 

Window parent; 

int x, y; 

Bool override_redirect; 
} XReparentEvent; 

Event Structure Members 

window The window whose parent window was changed. 

pa rent The new parent of the window. 

x, y The coordinates of the upper-left pixel of the window s border relative to the new 
parent window s origin. 

override_redirect 

The override_redirect attribute of the reparented window. If TRUE, it indi 
cates that the client wants this window to be immune to meddling by the window 
manager. Window managers normally should not have reparented this window to 
begin with. 



484 X Toolkit Intrinsics Reference Manual 



xreslzerequest- 



j ResizeRequest 



When Generated 

A ResizeRequest event reports another client s attempt to change the size of a window. 
The X server generates this event type when another client calls XConf igurewindow, 
XResizeWindow, or XMoveResizeWindow. If this event type is selected, the window is 
not resized. This gives the client that selects this event (usually the window manager) the 
opportunity to revise the new size of the window before executing the resize request or to deny 
the request itself. 

Translation Abbreviations 

In translation tables, the event type ResizeRequest may be used, or use the abbreviation 
ResReq. 

Select With 

To receive this event type, specify a window ID and pass ResizeRedirectMask as part of 
the event_mask argument to XSelect Input. Only one client can select this event on a 
particular window. When selected, this event is triggered instead of resizing the window. 

XEvent Structure Name 

typedef union _XEvent { 

XResizeRequestEvent xresizerequest; 
} XEvent; 

Event Structure 

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; 
int width, height; 

} XResizeRequestEvent; 

Event Structure Members 

window The window whose size another client attempted to change. 

widt h , he igh t The requested size of the window, not including its border. 



X Toolkit Intrinsics Reference Manual 485 



SelectionClear A 



xselectionclear 



When Generated 

A SelectionClear event reports to the current owner of a selection that a new owner is 
being defined. 

Translation Abbreviations 

In translation tables, the event type SelectionClear may be used, or use the abbreviation 
SelClr. 

However, all selection events are normally handled automatically by Xt s selection mechanism, 
and therefore no translations are needed. 

Select With 

This event is not selected. It is sent to the previous selection owner when another client calls 
XSetSelectionOwner for the same selection. 

XEvent Structure Name 

typedef union _XEvent { 

XSelectionClearEvent xselectionclear; 
} XEvent; 

Event Structure 

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; 

Atom selection; 

Time time; 
} XSelectionClearEvent; 

Event Structure Members 

window The window that is receiving the event and losing the selection, 

selection The selection atom specifying the selection that is changing ownership, 

t ime The last-change time recorded for the selection. 



486 

X Toolkit Intrinsics Reference Manual 



xse lection 



J SelectionNotify 



When Generated 

A SelectionNotify event is sent only by clients, not by the server, by calling XSend- 
Event. The owner of a selection sends this event to a requestor (a client that calls 
XConvertSelection for a given property) when a selection has been converted and stored 
as a property or when a selection conversion could not be performed (indicated with property 
None). 

Translation Abbreviations 

In translation tables, the event type SelectionNotify may be used, or use the abbreviation 
Select. 

However, all selection events are normally handled automatically by Xt s selection mechanism, 
and therefore no translations are needed. 

Select With 

There is no event mask for SelectionNotify events, and they are not selected with 
XSelect Input. Instead XSendEvent directs the event to a specific window, which is 
given as a window ID: PointerWindow, which identifies the window the pointer is in, or 
Input Focus, which identifies the focus window. 

XEvent Structure Name 

typedef union _XEvent { 

XSelectionEvent xselection; 
} XEvent; 

Event Structure 

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 requestor; /* must be next after type */ 
Atom selection; 
Atom target; 

Atom property; /* Atom or None */ 
Time time; 

} XSelectionEvent; 

Event Structure Members 

The members of this structure have the values specified in the XConvertSelection call 
that triggers the selection owner to send this event, except that the property member will 
return either the atom specifying a property on the requestor window with the data type speci 
fied in target, or it will be None, which indicates that the data could not be converted into 
the target type. 



X Toolkit Intrinsics Reference Manual 487 



SelectionRequest \ 



xselectlonrequest 



When Generated 

A SelectionRequest event is sent to the owner of a selection when another client requests 
the selection by calling XConvert Select ion. 

Translation Abbreviations 

In translation tables, the event type SelectionRequest may be used, or use the abbrevia 
tion SelReq. 

However, all selection events are normally handled automatically by Xt s selection mechanism, 
and therefore no translations are needed. 

Select With 

There is no event mask for SelectionRequest events, and they are not selected with 
XSelect Input. 

XEvent Structure Name 

typedef union _XEvent { 

XSelect ionRequestEvent xselect ionrequest ; 
} XEvent; 

Event Structure 

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 owner; /* must be next after type */ 
Window requestor; 
Atom selection; 
Atom target; 
Atom property; 
Time time; 
} XSelect ionRequestEvent; 

Event Structure Members 

The members of this structure have the values specified in the XConvert Select ion call 
that triggers this event 

The owner should convert the selection based on the specified target type, if possible. If a 
property is specified, the owner should store the result as that property on the requestor win 
dow, and then send a SelectionNotif y event to the requestor by calling xSendEvent. If 
the selection cannot be converted as requested, the owner should send a SelectionNotif y 
event with property set to the constant None. 



488 X Toolkit Intrinsics Reference Manual 



x visibility- 



VisibilityNotify 



When Generated 

A VisibilityNotify event reports any change in the visibility of the specified window. 
This event type is never generated on windows whose class is inputOnly. All of the win 
dow s subwindows are ignored when calculating the visibility of the window. 

Translation Abbreviations 

In translation tables, the event type VisibilityNotify may be used, or use the abbrevia 
tion Visible. 

Most widgets do not need to provide a translation for this event, because the Core widget field 
visible_interest provides a simplified form of the same information. For more informa 
tion, see Chapter 8, More Input Techniques, in Volume Four, X Toolkit Intrinsics Programming 
Manual. 

Select With 

This event is selected with visibilityChangeMask. 

XEvent Structure Name 

typedef union _XEvent { 

XVisibilityEvent xvisibility; 
} XEvent; 

Event Structure 

typedef struct { 
int type; 

unsigned long serial, 
Bool send_event; 
Display *display; 
Window window; 
int state; 



# of last request processed by server */ 
TRUE if this came from SendEvent request */ 
display the event was read from */ 



VisibilityUnobscured, */ 
VisibilityPartiallyObscured, 
VisibilityObscured */ 



or */ 



} XVisibilityEvent; 



Event Structure Members 

state A symbol indicating the final visibility status of the window: visibility 
Unobscured, VisibilityPartiallyObscured, or Visibility- 
Obscured. 



Notes 



Table C-6 lists the transitions that generate VisibilityNotify events and the correspond 
ing state member of the XVisibilityEvent structure. 



X Toolkit Intrinsics Reference Manual 



489 



VislbllltyNotlfy 



(continued) 



xvisibility 



Table C-6. The State Element of the XVisibilityEvent Structure 



Visibility Status Before 



Visibility Status After 



State Member 



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 



Viewable and com 
pletely unobscured 

Viewable and partially 
obscured 



Viewable and partially 
obscured 



VisibilityUnobscured 



VisibilityPartially- 
Obscured 



VisibilityPartially- 
Obscured 



490 



X Toolkit Intrinsics Reference Manual 



Standard Errors and Warnings 



The two sections below summarize all errors and warnings that the Toolkit can generate. The 
information has this form: 



Message Name 

Message Type 



Default message 



Note that many messages have more than one type; however, all Toolkit errors and warnings 
have class xtToolkitError. 



Error Messages 



allocError 

calloc 
malloc 
realloc 

communicationError 

select 

internalError 

shell 

invalid ArgCount 
xtGetValues 
xtSetValues 

invalidClass 

const raintSetValue 

xtAppCreateShell 

xtCreatePopupShell 

xtCreateWidget 

xtPopdown 

xtPopup 

invalidDimension 

xtCreateWindow 

shel IReal ize 



Cannot perform calloc 
Cannot perform malloc 
Cannot perform realloc 

Select failed 

Shell s window manager interaction is broken 



Argument count > on NULL argument list in XtGetValues 
Argument count > on NULL argument list in XtSetValues 



Subclass of Constraint required in CallConstraintSetValues 
XtAppCreateShell requires non-NULL widget class 
XtCreatePopupShell requires non-NULL widget class 
XtCreateWidget requires non-NULL widget class 
XtPopdown requires a subclass of shellWidgetClass 
XtPopup requires a subclass of shellWidgetClass 



Widget %s has zero width and/or height 
Shell widget %s has zero width and/or height 



Appendix D: Standard Errors and Warnings 



491 



invalidDisplay 

xtlnitialize 

invalidGeometryManager 

xtMakeGeometryRequest 

invalidParameter 

removePopupFromParent 
xtAddlnput 

invalidParameters 

xtMenuPopupAction 
xtmenuP opdown 

invalidParent 

realize 

xtCreatePopupShell 

xtCreateWidget 

XtMakeGeometryRequest 

xtMakeGeometryRequest 

xtManageChi Idren 

xtUnmanageChildren 

invalidPopup 

xtMenuPopup 
xtMenuPopup 

invalidProcedure 

inheritanceProc 
realizeProc 

invalidWindow 

event Handler 

missingEvent 

shell 

noAppContext 

widget ToAppli cat ion- 
Context 

noPerDisplay 

closeDi splay 
getPerDisplay 

noSelectionProperties 

freeSelectionProperty 

nulIProc 

insert Child 

subclassMismatch 

xtCheckSubclass 



Cannot open display 



XtMakeGeometryRequest - parent has no geometry manger 



RemovePopupFromParent requires non-NULL popuplist 
Invalid condition passed to XtAddlnput 



MenuPopup wants exactly one argument 
XtMenuPopdown called with num_params != or 1 



Application shell is not a windowed widget? 
XtCreatePopupShell requires non-NULL parent 
XtCreateWidget requires non-NULL parent 
XtMakeGeometryRequest -NULL parent Use SetValues instead 
XtMakeGeometryRequest - parent not composite 
Attempt to manage a child when parent is not Composite 
Attempt to unmanage a child when parent is not Composite 



Cannot find pop up in _XtMenuPopup 
Cannot find pop up in _XtMenuPopup 



Unresolved inheritance operation 
No realize class procedure defined 

Event with wrong window 

Events are disappearing from under Shell 

Couldn t find ancestor with display information 

Couldn t find per display information 
Couldn t find per display information 

Internal error no selection property context for display 

NULL insert_child procedure 

Widget class %s found when subclass of %s expected: %s 



492 



X Toolkit Intrinsics Reference Manual 



translationError 

mergingTablesWithCycles Trying to merge translation tables with cycles, and cannot resolve 

this cycle 



wrongParameters 

cvtlntOrPixelToXColor 
cvtStringToCursor 
cvtStringToFont 
cvtStringToFont Struct 
cvtStringToPixel 



Pixel-to-color conversion needs screen and colormap arguments 
String-to-cursor conversion needs screen argument 
String-to-font conversion needs screen argument 
String-to-cursor conversion needs screen argument 
String-to-pixel conversion needs screen and colormap arguments 



Warning Messages 



ambigiousParent 

xtManageChildren 
xtUnmanageChildren 

communicationError 

windowManager 

conversionError 

string 

dispIayError 

invalidDi splay 

grabError 

grabDestroyCallback 
grabDestroyCallback 
xtRemoveGrab 

initializatiooError 

xtlnitialize 

invalidArgCount 

get Re sources 

invalidCallbackList 

xtAddCallbacks 
xtCallCallback 
xtOverrideCallback 
xtRemoveAllCallback 

xtRemoveCall backs 

invalidChild 

xtManageChildren 
xtUnmanageChildren 

invalidDepth 

setValues 



Not all children have same parent in XtManageChildren 
Not all children have same parent in XtUnmanageChildren 



Window Manager is confused 



Cannot convert string "%s" to type "%s" 



Cannot find display structure 



XtAddGrab requires exclusive grab if spring_loaded is TOUE 
XtAddGrab requires exclusive grab if spring_loaded is TOUE 
XtRemoveGrab asked to remove a widget not on the grab list 



Initializing Resource Lists twice 



Argument count > on NULL argument list 



Cannot find callback list in XtAddCallbacks 
Cannot find callback list in XtCallCallbacks 
Cannot find callback list in XtOverrideCallbacks 
Cannot find callback list in XtRemoveAllCallbacks 
Cannot find callback list in XtRemoveCallbacks 



NULL child passed to XtManageChildren 
NULL child passed to XtUnmanageChildren 



Cannot change widget depth 



Appendix D: Standard Errors and Warnings 



493 



invalidGeometry 

xtMakeGeometryRequest 

invalidParameters 

compileAccelerators 
compileTranslations 
mergeTranslations 

invalidParent 

xtCopyFromParent 

invalidPopup 

unsupportedOperation 

invalidProcedure 

deleteChild 

inputHandler 

set_values_almost 

invalidResourceCount 

get Re sources 

invalidResourceName 

computeArgs 

invalidShell 

xtTranslateCoords 

invalidSizeOverride 

xt Dependencies 

invalidTypeOverride 

xtDependencies 

invalidWidget 

remove? opupFromParent 

noColormap 

cvtStringToPixel 

registerWindowError 

xtRegi sterWindow 
xtUnregisterWindow 

translation error 

nullTable 
nullTable 

transIationError 

ambigiousActions 

mergingNullTable 

nullTable 

unboundActions 

xtTranslatelnitialize 



Shell subclass did not take care of geometry in XtSetValues 



String to AcceleratorTable needs no extra arguments 
String to TranslationTable needs no extra arguments 
MergeTM to TranslationTable needs no extra arguments 



CopyFromParent must have non-NULL parent 

Pop-up menu creation is only supported on ButtonPress or Enter- 
Notify events 



NULL delete_child procedure in XtDestroy 
XtRemovelnput: Input handler not found 
set_values_almost procedure shouldn t be NULL 



Resource count > on NULL resource list 



Cannot find resource name %s as argument to conversion 



Widget has no shell ancestor 



Representation size %d must match superclass s to override %s 



Representation type %s must match superclass s to override %s 



RemovePopupFromParent, widget not on parent list 



Cannot allocate colormap entry for "%s" 



Attempt to change already registered window 
Attempt to unregister invalid window 



Cannot remove accelerators from NULL table 
Tried to remove non-existant accelerators 



Overriding earlier translation manager actions 
Old translation table was null, cannot modify 
Cannot translate event through NULL table 
Actions not found: %s 
Initializing Translation manager twice 



494 



X Toolkit Intrinsics Reference Manual 



translationParseKrror 

showLine 

parseError 

parseString 

typeConversionError 

noConverter 

versionMismatch 

widget 

wrongParameters 

cvtlntToBool 

cvtlntToBoolean 

cvtlntToFont 

cvtlntToPixel 

cvtlntToPixmap 

cvtlntToShort 

cvtStringToBool 

cvtStringToBoolean 

cvtStringToDi splay 

cvtStringToFile 

cvtStringToInt 

cvtStringToShort 



. . . 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. intrinsics %d 



Liteger-to-Bool conversion needs no extra arguments 
Integer-to-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-to-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 
String-to-integer conversion needs no extra arguments 



String-to-integer conversion needs no extra arguments 
cvtStringToUnsignedChar String -to -Integer conversion needs no extra arguments 
cvtxcolorToPixel Color-to -Pixel conversion needs no extra arguments 



Appendix D: Standard Errors and Warnings 



495 



Resource File Format 



A resource file contains text representing the default resource values for an application or set 
of applications. The resource file is an ASCII text file that consists of a number of lines with 
the following EBNF syntax: 



resourcefile 

line 

comment 

production 

resourcename 

string 

name 



= {line "\n") 

= (comment I production) 

= "!" string 

= resourcename ":" string 

= ["*"] name {("." I "*") name) 

= {<any character not including eol>) 



If the last character on a line is a backslash (S), that line is assumed to continue onto the next 
line. 

To include a newline character in a string, use\n. 



Appendix E: Resource File Format 



497 



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" } "\n" 

production = Ins ":" rhs "\n" 

Ihs = ( event I keyseq ) { "," (event I keyseq) } 

keyseq = """ keychar {keychar} """ 

keychar = [ """ I "$" I V ] <ISO Latin 1 character 

event = [modifier_list] "<"event_type">" [ "(" count["--"] ")" ] {detail} 

modifier_list =(["!" I ":"] {modifier} ) I "None" 

modifier = ["""] modifier_name 

count =("1" I "2" I "3" I "4" I ...) 

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 



quoted_string = """ {<Latin 1 character^ """ 

unquoted_string = {<Latin 1 character except space, tab, ",", newline, ")">} 

It is often convenient to include newlines in a translation table to make it more readable. In 
C, indicate a newline with a "Vn": 

"<BtnlDown> : DoSomething ( ) \\en\\e 
<Btn2Down> : DoSomethingElse ( ) " 



Modifier Names 

The modifier field is used to specify normal X keyboard and button modifier mask bits. Mod 
ifiers are legal on event types KeyPress, KeyRelease, ButtonPress, Button- 
Release, MotionNotify, EnterNotify, LeaveNotify, and their abbreviations; 
however, parsing a translation table that contains modifiers for any other events generates an 
error. 

If the modi fier_l 1st has no entries and is not None, it means "don t care" on all 
modifiers. 

If an exclamation point (!) is specified at the beginning of the modifier list, it means that 
the listed modifiers must be in the correct state and no other modifiers can be asserted. 

If any modifiers are specified and an exclamation point (!) is not specified, it means that 
the listed modifiers must be in the correct state and "don t care" about any other modifi 
ers. 

If a modifier is preceded by a tilde (~), it means that that modifier must not be asserted. 

If None is specified, it means no modifiers can be asserted. 

If a colon (:) is specified at the beginning of the modifier list, it directs the Intrinsics to 
apply any standard modifiers in the event to map the event key code into a keysym. The 
default standard modifiers are Shift and Lock, with the interpretation as defined in Vol 
ume Zero, X Protocol Reference Manual. The resulting keysym must exactly match the 
specified keysym, and the nonstandard modifiers in the event must match the modi- 
fierJisL For example, : <Key>a is distinct from :<Key>A, and : Shif t<Key>A is 
distinct from : <Key>A. 

If a colon (:) is not specified, no standard modifiers are applied. Then, for example, 
"<Key>A" and "<Key>a" are equivalent. 

In key sequences, a circumflex O is an abbreviation for the Control modifier, a dollar sign ($) 
is an abbreviation for Meta, and a backslash (\) can be used to quote any character, in particu 
lar a double quote ("), a circumflex Q, a dollar sign ($), and another backslash (\). Briefly: 

No modifiers: None <event> detail 

Any modifiers: <event> detail 

Only these modifiers: ! modi mod2 <event> detail 

These modifiers and any others: modi mod2 <event> detail 



500 x Toolkit Intrinsics Reference Manual 



The use of None for a modi f ier_l 1st is identical to the use of and exclamation point 
with no modifcrs. 



Table F-1. Modifier Keys 



Modifier 


Abbreviation 


Meaning 


Ctrl 


c 


Control modifier bit 


Shift 


s 


Shift modifier bit 


Lock 


1 


Lock modifier bit 


Meta 


m 


Meta key modifier (see below) 


Hyper 


h 


Hyper key modifier (see below) 


Super 


su 


Super key modifier (see below) 


Alt 


a 


Alt key modifier (see below) 


Modi 




Modi modifier bit 


Mod2 




Mod2 modifier bit 


Mod3 




Mod3 modifier bit 


Mod4 




Mod4 modifier bit 


Mod5 




Mod5 modifier bit 


Buttonl 




Buttonl modifier bit 


Button2 




Button2 modifier bit 


Button3 




ButtonS modifier bit 


Button4 




Button4 modifier bit 


Buttons 




ButtonS modifier bit 


ANY 




Any combination 



A key modifier is any modifier bit whose corresponding keycode contains the corresponding 
left or right keysym. For example, m or Meta means any modifier bit mapping to a keycode 
whose keysym list contains XK_Meta_L or XK_Meta_R. Note that this interpretation is 
for each display, not global or even for each application context. The Control, Shift, and 
Lock modifier names refer explicitly to the corresponding modifier bits; there is no additional 
interpretation of keysyms for these modifiers. 

Because it is possible to associate arbitrary keysyms with modifiers, the set of modifier key 
modifiers is extensible. The "<2>" <keysym> syntax means any modifier bit whose cor 
responding keycode contains the specified keysym. 

A modif ier_list/keysym combination in a translation matches a modifiers/keycode 
combination in an event in the following cases: 

If a colon (:) is used, the Intrinsics call the display s XtKeyProc with the keycode and 
modifiers. To match: 

(modifiers & ~ modif iers_return) 
must equal modif ier_list, and keysym_return must equal the given keysym. 

If (:) is not used, the Intrinsics mask off all "don t care" bits from the modifiers. This 
value must be equal to modif ier_list. Then, for each possible combination of 
"don t care" modifiers in the modif ier_l 1st, the Intrinsics call the display s 



Appendix F: Translation Table Syntax 



501 



xtKeyProc with the keycode and that combination ORed with the cared-about modi 
fier bits from the event keysym_return must match the keysym in the translation. 

Event Types 

The EventType field describes XEvent types. Currently defined EventType values 
are listed in Table F-2 below. 

Table F-2. EventType Values 



Type 


Meaning 


Key or KeyDown 


KeyPress 


KeyUp 


KeyRelease 


BtnDown 


ButtonPress 


BtnUp 


ButtonRelease 


Motion, PtrMoved, 


MotionNotify 


Or MouseMoved 




Enter or EnterWindow 


EnterNotify 


Leave or LeaveWindow 


LeaveNotify 


Focusln 


Focusln 


FocusOut 


FocusOut 


Keymap 


KeymapNotify 


Expose 


Expose 


GrExp 


GraphicsExpose 


NoExp 


NoExpose 


Visible 


VisibilityNotify 


Create 


CreateNotify 


Destroy 


DestroyNotify 


Unmap 


UnmapNotify 


Map 


MapNotify 


MapReq 


MapRequest 


Reparent 


ReparentNotify 


Configure 


ConfigureNotify 


ConfigureReq 


ConfigureRequest 


Grav 


GravityNotify 


ResReq 


ResizeRequest 


Circ 


CirculateNotify 


CircReq 


CirculateRequest 


Prop 


PropertyNotify 


SelClr 


Select ionClear 


SelReq 


Select ionRequest 


Select 


Select ionNot if y 


Clrmap 


ColormapNotify 


Message 


ClientMessage 


Mapping 


MappingNot i f y 



502 



X Toolkit Intrinsics Reference Manual 



The supported abbreviations are listed in Table F-3. 
Table F-3. Modifier Key Abbreviations 



Abbreviation 



Meaning 



Ctrl 

Meta 

Shift 

BtnlDown 

BtnlUp 

Btn2Down 

Btn2Up 

BtnSDown 

BtnSUp 

Btn4Down 

Btn4Up 

BtnSDown 

BtnSUp 

BtnMotion 

BtnlMotion 

Btn2Motion 

Btn3Motion 

Btn4Motion 

Btn5Motion 



KeyPress with control 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 ButtonS modifier 
MotionNotify with Button4 modifier 
MotionNotify with ButtonS modifier 



The detail field is event-specific and normally corresponds to the detail field of an 
XEvent, for example, <Key>A. If no detail 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, 
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 
<Xlllkeysymdef.h> 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 display_accelerator 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 } 

production = Ins ":" rhs "\W 

Ihs = event { "," event } 

event = [modifierjist] "<"event_type">" [ "(" count["+"] ")" ] {detail} 

modifierjist = ["!" I ":"] {modifier} 

modifier = ["""] modifier_name 

count =("1" I "2" I "3" I "4" I ...) 

modifier_name = "@" <keysym> I <see canonical modifier names below> 

event_type = <see canonical event types below> 

detail = <event specific details> 

rhs = { name "(" [params] ")" } 

name = namechar { namechar } 

namechar = { V-"z" I "A"-"Z" I "0"-"9" I "$" I "_" } 

params = string {"," string}. 

string = quoted_string 

quoted_string = """ {<Latin 1 characters- } """ 

The canonical modifier names are: 

Buttonl Modi Ctrl 

Button2 Mod2 Shift 

Button3 Mod3 Lock 

Button4 Mod4 

Buttons Mod5 

The canonical event types are: 

ButtonPress DestroyNotify KeyPress PropertyNotify 

ButtonRelease EnterNotify KeyRelease ReparentNotify 

CirculateNotify Expose LeaveNotify ResizeRequest 

CirculateRequest Focusln MapNotify SelectionClear 

ClientMessage FocusOut MappingNotify SelectlonNotify 

ColormapNotify GraphicsExpose MapRequest SelectionRequest 

ConfigureNotify GravityNotify MotionNotify UnmapNotify 

ConfigureRequest KeymapNotify NoExpose VisibilityNotify 
CreateNotify 



504 X Toolkit Intrinsics Reference Manual 



Examples 

Always put more specific events in the table before more general ones: 

Shift <BtnlDown> : twas()\n\ 
<BtnlDown> : brilligO 

For double-click on Button 1 Up with Shift, use this specification: 

Shift <BtnlUp>(2) : and() 
This is equivalent to the following line with appropriate timers set between events: 

Shift <BtnlDown>, Shift<BtnlUp>, Shift<BtnlDown>, Shift <BtnlUp> : and () 

For double-click on Button 1 Down with Shift, use this specification: 

Shift<BtnlDown>(2) : the() 

This is equivalent to the following line with appropriate timers set between events: 
Shift <BtnlDown>, Shift <BtnlUp>, Shift <BtnlDown> : the() 

Mouse motion is always discarded when it occurs between events in a table where no 
motion event is specified: 

<BtnlDown>,<BtnlUp> : slithyO 

This is taken, even if the pointer moves a bit between the down and up events. Similarly, 
any motion event specified in a translation matches any number of motion events. If the 
motion event causes an action procedure to be invoked, the procedure is invoked after 
each motion event 

If an event sequence consists of a sequence of events that is also a non-initial subse 
quence of another translation, it is not taken if it occurs in the context of the longer 
sequence. This occurs mostly in sequences like the following: 

<BtnlDown>,<BtnlUp> : toves()\n\ 
<BtnlUp> : did() 

The second translation is taken only if the button release is not preceded by a button press 
or if there are intervening events between the press and the release. Be particularly 
aware of this when using the repeat notation, above, with buttons and keys because their 
expansion includes additional events, and when specifying motion events because they 
are implicitly included between any two other events. In particular, pointer motion and 
double-click translations cannot coexist in the same translation table. 

For single click on Button 1 Up with Shift and Meta, use this specification: 

Shift Meta <BtnlDown>, Shift Meta<BtnlUp>: gyre ( ) 

You can use a plus sign (+) to indicate "for any number of clicks greater than or equal to 
count"; for example: 

Shift <BtnlUp>(2+) : and() 



Appendix F: Translation Table Syntax 505 



To indicate EnterNotif y with any modifiers, use this specification: 
<Enter> : gimbleO 

To indicate EnterNotif y with no modifiers, use this specification: 

None <Enter> : in() 

To indicate EnterNotify with Button 1 Down and Button 2 Up and "don t care" 
about the other modifiers, use this specification: 

Buttonl ~Button2 <Enter> : the{) 

To indicate EnterNotify with Buttonl Down and Button2 Down exclusively, use this 
specification: 

! Buttonl Button2 <Enter> : wabe() 

You do not need to use a tilde (~) with an exclamation point (!). 



506 X Toolkit Intrinsics Reference Manual 



StringDefs.h Header File 



This appendix lists the contents of the StringDefs.h header file. The contents are classified 
by resource names, class types, representation types, and constants. 



Table G-1. Resource Names 



Resource Name 



Value 



XtNaccelerators 

vXtNallowHoriz 

XtNallowVert 

XtNancest or Sensitive 

XtNbackground 

XtNbackgroundP ixmap 

XtNborderColor 

XtNborder 

XtNborderP ixmap 

XtNborderWidth 

XtNcallback 

XtNcolormap 

XtNdepth 

XtNdestroyCallback 

XtNeditType 

XtNfont 

XtNforceBars 

XtN foreground 

XtNfunction 

XtNheight 

XtNhSpace 

XtNindex 

XtNinnerHeight 

XtNinnerWidth 

XtNinnerWindow 

XtNinsertPosition 

XtNinternalHeight 



"accelerators" 

"allowHoriz" 

"allowVert" 

"ancestorSensitive 1 

"background" 

"background? ixmap" 

"border Color" 

"border Color" 

"border? ixmap" 

"borderWidth" 

"callback" 

"colormap" 

"depth" 

"destroyCallback" 

"editType" 

"font" 

"forceBars" 

"foreground" 

"function" 

"height" 

"hSpace" 

"index" 

"innerHeight" 

"innerWidth" 

"innerWindow" 

"insert Position" 

"internalHeight" 



Appendix G: StringDefs.h Header File 



507 



Table G-1. Resource Names (continued) 



Resource Name 



Value 



XtNinternalWidth 

XtNjustify 

XtNknobHeight 

XtNknoblndent 

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 

XtNtext Source 

XtNthickness 

XtNthumb 

XtNthumbProc 

XtNtop 

XtNtranslations 

XtNuseBottom 

XtNuseRight 

XtNvalue 

XtNvSpace 



"internalWidth" 

"justify" 

"knobHeight" 

"knoblndent" 

"knobPixel" 

"knobWidth" 

"label" 

"length" 

"lowerRight" 

"mappedWhenManaged" 

"menuEntry" 

"name" 

"notify" 

"orientation" 

"parameter" 

"popupCallback" 

"popdownCallback" 

"reverseVideo" 

"screen" 

"scrollProc" 

"scrollDownCursor" 

"scrollHorizontalCursor 1 

"scrollLeftCursor" 

"scrollRightCursor" 

"scrollUpCursor" 

"scrollVerticalCursor" 

"selection" 

"selectionArray" 

"sensitive" 

"shown" 

"space" 

"string" 

"textOptions" 

"textSink" 

"textSource" 

"thickness" 

"thumb" 

"thumbProc" 

"top" 

"translations" 

"useBottom" 

"useRight" 

"value" 

"vSpace" 



508 



X Toolkit Intrinsics Reference Manual 



Table G-1. Resource Names (continued) 



Resource Name 



Value 



XtNwidth 
XtNwindow 
XtNx 
XtNy 



"width" 

"window 1 

"x" 



Table G-2. Class Types 
Class "type 



Value 



XtCAccelerators 

XtCBackground 

XtCBoolean 

XtCBorderColor 

XtCBorderWidth 

XtCCallback 

XtCColormap 

XtCColor 

XtCCursor 

XtCDepth 

XtCEditType 

XtCEventBindings 

XtCFile 

XtCFont 

XtCForeground 

XtCFraction 

XtCFunction 

XtCHeight 

XtCHSpace 

XtCIndex 

XtCInterval 

XtCJustify 

XtCKnoblndent 

XtCKnobPixel 

XtCLabel 

XtCLength 

XtCMappedWhenManaged 

XtCMargin 

XtCMenuEntry 

XtCNotify 

XtCOrientation 

XtCParameter 

XtCPixmap 



"Accelerators" 

"Background" 

"Boolean" 

"Border Color" 

"BorderWidth" 

"Callback" 

"Colormap" 

"Color" 

"Cursor" 

"Depth" 

"EditType" 

"EventBindings" 

"File" 

"Font" 

"Foreground" 

"Fraction" 

"Function" 

"Height" 

"HSpace" 

"Index" 

"Interval" 

"Justify" 

"Knoblndent" 

"KnobPixel" 

"Label" 

"Length" 

"MappedWhenManaged 1 

"Margin" 

"MenuEntry" 

"Notify" 

"Orientation" 

"Parameter" 

"Pixmap" 



Appendix G: StringDefs.h Header File 



509 



Table G-2. Class Types (continued) 



Class Type 



Value 



XtCPosition 

XtCScreen 

XtCScrollProc 

XtCScrollDCursor 

XtCScrollHCursor 

XtCScrollLCursor 

XtCScrollRCursor 

XtCScrollUCursor 

XtCScrollVCursor 

XtCSelection 

XtCSensitive 

XtCSelectionArray 

XtCSpace 

XtCString 

XtCText Options 

XtCTextPosition 

XtCTextSink 

XtCTextSource 

XtCThickness 

XtCThumb 

XtCTranslations 

XtCValue 

XtCVSpace 

XtCWidth 

XtCWindow 

xtcx 

XtCY 



"Position" 

"Screen" 

"ScrollProc" 

"ScrollDownCursor" 

"ScrollHorizontalCursor 1 

"ScrollLeftCursor" 

"ScrollRightCursor" 

"ScrollUpCursor" 

"ScrollVerticalCursor" 

"Selection" 

"Sensitive" 

"SelectionArray" 

"Space" 

"String" 

"TextOptions" 

"TextPosition" 

"TextSink" 

"TextSource" 

"Thickness" 

"Thumb" 

"Translations" 

"Value" 

"VSpace" 

"Width" 

"Window" 

"X" 

"Y" 



Table G-3. Representation Types 
Representation Type Value 



XtRAcceleratorTable 

XtRBoolean 

XtRCallback 

XtRCallProc 

XtRColor 

XtRCursor 

XtRDimension 

XtRDisplay 

XtREditMode 

XtRFile 



"AcceleratorTable 1 

"Boolean" 

"Callback" 

"CallProc" 

"Color" 

"Cursor" 

"Dimension" 

"Display" 

"EditMode" 

"File" 



510 



X Toolkit Intrinsics Reference Manual 



Table G-3. Representation Types (continued) 



Representation Type 



Value 



XtRFont 

XtRFontStruct 

XtRFunction 

XtRGeometry 

XtRImmediate 

XtRInt 

XtRJustify 

XtRLongBoolean 

XtROrientation 

XtRPixel 

XtRPixmap 

XtRPointer 

XtRPosition 

XtRShort 

XtRString 

XtRStringTable 

XtRUnsignedChar 

XtRTranslationTable 

XtRWindow 



"Font" 

"FontStruct" 

"Function" 

"Geometry" 

"Immediate" 

"Int" 

"Justify" 

"LongBoolean" 

"Orientation" 

"Pixel" 

"Pixmap" 

"Pointer" 

"Position" 

"Short" 

"String" 

"StringTable" 

"UnsignedChar" 

"TranslationTable 1 

"Window" 



Table G-4. Constants 



Constant 



Value 



Boolean Enumeration: 

XtEoff 

XtEfalse 

XtEno 

XtEon 

XtEtrue 

XtEyes 

Orientation Enumeration: 

XtEvertical 
XtEhorizontal 

Text Edit Enumeration: 

XtEtextRead 

XtEtextAppend 

XtEtextEdit 



"off" 

"false 1 

"no" 

"on" 

"true" 

"yes" 



vertical" 
horizontal 

"read" 

append" 

edit" 



Appendix G: StringDefs.h Header File 



511 



JabteG-4. Constants (continued) 
Constant 



Value 



Color Enumeration: 

XtExtdefaultbackground 
Xt Ext default foreground 

Font 

XtExtdefaultfont 



xtdefaultbackground 1 
xt default foreground 1 

xt default font" 



512 



X Toolkit Intrinsics Reference Manual 



H 

Release Notes 



This appendix summarizes the changes to the Intrinsics between Release 2 and Release 3. 
Where significant, these differences have also been noted on the appropriate page in this 
manual. 

Many bugs have been fixed, including the ability to create more than 896 widgets, to des 
troy the last widget in an application, to call xtDestroyWidget from within a 
destroy_callback, to call XtNextEvent recursively from input or timer call 
backs, and to call XtOverrideTranslations or XtAugmentTranslations 
after the target widget has been realized. 

An additional source for application resource specifications has been added; see 
XAPPLRESDIR under xtDisplaylnitialize. 

In Release 2, xt Get Values would overwrite an entire longword, regardless of the size 
of the resource being retrieved. XtGet Values now works correctly on most machine 
architectures. Applications that relied on the broken behavior will have to be fixed. In 
particular, only the number of bytes specified by the resource size will be copied; not an 
entire (long) word. 

The definitions of the types Dimension and Position have changed. Correct code 
will not be affected by this, but code that assumed that Dimensions and Positions 
were ints may break. In particular, all cases where pointers to such fields are used will 
need to be checked. In the standard interfaces, the only such places are calls to Xt- 
MakeResizeRequest and xtGetValues. Widgets that pass pointers in callbacks 
or other public interfaces will also need to be checked. This change plus the preceeding 
bugfix require all application calls to XtGetValues to be checked for correctness, 
especially those that refer to XtNx, XtNy, xtNwidth, xtNheight and xt- 
NborderWidth. 

XtGetValues and XtSetValues on callback lists now work consistently with the 
public callback list structures. That is, in Release 2, when you used XtGetValues on 
a callback list, it did not return anxtCallbackList.as would be expected. This has 
been fixed in Release 3. 

xtSetKeyboardFocus works correctly in Release 3; it was broken in Release 2, 
especially in handling grabs. 

The link Atoms. h has been removed; use StringDefs.h. 

Appendix H: Release Notes 513 



Support for selections has been added. 

New syntax in translation tables allows resource specifications to provide translations 
that are merged with the default widget translations, rather than completely replacing 
them. See XtAugmentTranslations and XtOverrideTranslations. 

The translation table syntax has been extended to completely support keysym names as 
modifier and detail fields. Better support for indicating upper/lower case sensitivity in 
translations has been added, plus hooks for providing non-standard case converters and 
non-standard keycode to keysym converters. 

Application contexts have been added to several interfaces to allow for re-entrant 
libraries. The old interfaces remain supported for compatibility and will use a global 
default context. See xtCreateApplicationContext. 

Multiple display connections are now supported. Displays opened with XOpen- 
Display can also be registered with the Toolkit by making a call to xtDisplay- 
Initialize. 

A new routine, XtReleaseGC, must be used in place of xtDestroyGC if the appli 
cation is using XtGetGC on multiple displays. 

xt Initialize has been split up into four separate routines: xtToolkit- 
Initialize, XtCreateApplicationContext, XtOpenDisplay, and Xt- 
AppCreateShell. Xtlnitialize remains supported as a convenience routine for 
simple applications. 

Additional standard command line options have been defined: -selectionTimeout and 
asynchronous. 

The resource database created by the Intrinsics can now be accessed directly, using Xrm 
routines, if desired. 

A per-user application class defaults file has been added, which will be loaded into the 
resource database immediately after the system-wide application class defaults and 
before the user preference resources. 

Widget subclasses can now provide default values for superclass resources that override 
the superclass s default before the superclass initialize procedure is called. 

Resource lists can now specify as default values the Black and white pixels and the 
default font assigned by the server. Reverse video is implemented only for these two pix 
els. See XtDef aultForeground, XtDef aultBackground and XtDef ault- 
Font. 

Support for computing default values for resources at run-time has been added. See xt- 
RCallProc. 

Additional error and warning message interfaces have been defined that allow customiza 
tion of error messages and provide for textual substitution in the message. All internal 
error messages generated by the Intrinsics use these new interfaces. 

A routine to determine if X input, alternate input, or timer input is available without actu 
ally processing any has been added. See xtAppPending. 



514 X Toolkit Intrinsics Reference Manual 



XtDispatchEvent now returns a Boolean indicating whether or not a widget was 
found to which to dispatch the event 

A function to return the full event mask for a widget has been added. See xtBuild- 
EventMask. 

Limited support for background processing has been added. See xtAddWorkProc. 

Support for accelerators has been added to the translation manager. Accelerators are 
event bindings that trigger actions in a widget other than the one in which the event(s) 
occurred. SeeXtlnstallAccelerators. 

Resource hierarchies are no longer qualified by an additional name and class to the left of 
the ApplicationShellwidget name and class. This may have compatibility 
implications for existing resource files that contain full resource names, and for applica 
tions that used XtCreateApplicationShell. 

Colormap and depth fields have been added to the Core widget class so that widgets can 
specify values different from their parent s values. 

The Core class has two new fields: a display_accelerator method for the new 
accelerators capability and a field to allow future additions to the Core class without 
requiring a recompile of all widgets. Widget class initializers should be updated to ini 
tialize these to XtlnheritDisplayAccelerator and NULL, respectively. Old 
widgets will continue to work without updating. 

The interface to the accept_f ocus procedure now has a time parameter and a new 
interface to it, XtCallAcceptFocus, has been added. The accept_f ocus proce 
dure must now return a Boolean to indicate whether or not the widget actually wanted the 
focus. Widgets implementing an accept_f ocus procedure will have to be updated. 

The Composite widget class dropped the move_focus_to_next and 
move_f ocus_to_prev fields. The Composite class also added a field to allow for 
future expansion. Widget class initializers for all composite widgets must be modified to 
remove the initializers for the first two and initialize the last to NULL. 

The num_mapped_children field has been dropped from the CompositePart. 
Most widgets that used this field probably had bugs. 

A new flag, CWQueryOnly, has been added to geometry requests. A geometry man 
ager is expected to return the same information whether or not this flag is set, but to not 
actually make any geometry changes if CWQueryOnly is set Geometry managers will 
have to be updated. 

Any widget may be specified as the parent in xtCreateWidget. Children of non- 
composite widgets may not be managed (via XtManageChild) , nor may they make 
geometry requests. 

The inquiry function xtlsManaged has been added. 

A new routine, XtGetResourceList has been added to return the complete resource 
list for a widget class. 

The built-in MenuPopdown action procedure now accepts an optional (shell) widget 
name. 



Appendix H: Release Notes 515 



xtRealizeWidget now respects the map_when_managed attribute for all widg 
ets, including Shells. 

XtCreateWindow and ShellRealize will now report more helpful error messages 
when a widget is to be realized with a width or height of 0. 

Shell will now allow geometry changes via xtSetValues when the xtNallow- 
ShellResize resource is FALSE. 

The new argument to set__values routines now contains the real widget (was formerly 
the current argument). This will affect widgets that make explicit geometry requests 
within their set_values routine. Widgets should never assume the geometry in 
"new" is what they will actually get; instead, they should rely on a call to their Resize 
procedure to inform them of changes. 

xtDestroyWidget will now automatically call XtRemoveAllCallbacks on 
every callback list for each destroyed widget; widget destroy procedures are no longer 
required to do so. 



X Toolkit Intrinsics Reference Manual 



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



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 holding 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 XtlnstallAccelerators) 

(see also XtlnstallAUAccelerators) 

compiling accelerator table PM:210; RM:201 

defining default table in code PM:210 

display _accelerator method PM:21 1 ; 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 : 1 1 3 
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:113 
registering (see adding) 
using event data PM:222; example 

RM:27 1-272 

widget instance pointer PM: 185 
widget/application conflicts PM: 1 46 
(see also XtAddActions, XtAppAddActions) 
aliasing font names PM:443 
AlmostProc RM:328 
Alt key (see modifiers) 
ancestor PM:496 
anonymous ftp PM:34 
application contexts, about PM:97-99, 
393-396, 496 



Index 



519 



adding display RM:135-136; XtOpenDisplay 

PM:98, 396; RM: 195-196 
creating RM: 115-1 16 
destroying and closing displays RM:127 
explicit PM:98 

main loop for multiple PM:394 
multiple PM:394 

(see also XtCreateApplicationContext) 
(see also XtDestroyApplicationContext) 
(see also XtWidgetToApplicationContext) 
application, application resources PM:80; data 
structure PM:81; retrieving values PM:85 
application-defaults file, about PM:32, 36, 
245; directory PM:36; naming conven 
tions PM:32, 36 
applicationShellWidgetClass PM:270; 

RM:346-353 
Arg structure PM:92 
argc PM:33,91,272 
ArgList (see argument lists) 
ArgsProc RM:327 
ARGSUSED PM:42 

arguments, argument lists; about PM:92, 496; 
constructing/modifying dynamically 
RM:232-233; creating PM:92; creating 
dynamically PM:93; creating with 
XtSetArg PM:93-94; example PM:92-93; 
merging ArgList RM:186; XtMergeAr- 
gLists RM:186 
argument styles PM:90 
command line RM:13 
to actions PM:113, 124 
to type converters PM:259-260 
argv PM:33,91,272 
array, (see also XtNumber) 
allocating RM:105 

elements, determining number RM:192 
(see also XtCalloc) 
aspect ratio PM:274 
Athena widgets, about PM:17, 496 
Box PM:66; RM:357-358 
Command PM: 19, 40-43, 47, 65; RM:359-362 
Dialog PM:71, 75, 340-341 ; RM:363-364 
Form PM:68-69, 325-340; RM:365-367 
Grip PM:66; RM:368-369 
inheritance among PM : 1 8 
Label PM:19, 36, 240; RM:370-372 
List RM:373-377 
MenuButton PM:367 

Scroll PM:15, 39, 42, 66, 109; RM:378-382 
Simple PM:19 

SimpleMenu PM:349, 367-371, 378-381 
Template RM:383-390 



Text PM:75, 150, 264, 280; RM:39 1-402 

Viewport PM:107,310,314;RM:403-404 

Vpaned PM:66 

VPaned PM:310 

Vpaned RM:405-408 
atoms, about PM:288, 496 

obtaining; example PM:291,292 

predefined PM:291 

standard PM:299 
augmenting translations PM:48 



B 



background PM:53, 496 

background processing PM:231; RM:323-324 

pixmap PM:53 

window attribute PM:156 
backing store PM:257, 496 

window attribute PM:156 
binding, tight vs. loose (resources) PM:244 
bit gravity PM:496 
bit plane PM:497 

bit_gravity window attribute PM:156 
bitmap PM:279,497 

bitmap files PM:104 

BitmapEdit widget, about PM:66, 104, 177, 
314,461 

BitmapEditClassRec, example PM: 138-139 

BitmapEditRec, example PM:139 
bitwise RM:50,95 
Boolean values PM:253 
border PM:497 

border crossing events RM:454-459 

border width PM:306 

border window attribute PM:156 
bounding box PM:171; RM:295 
Box widget PM:21, 61-71, 206-211, 351-358 

examples PM:61-66 

geometry management RM:357-358 

resources RM:357-358 
Bulletin Board widget PM:409 
ButtonPress events PM:196, 353; RM:439-441 
ButtonRelease events PM: 196, 353; 

RM:439-441 
buttons, (see also command buttons) 

grabbing PM:497 

mapping RM:477 
byte order PM:497 



520 



X Toolkit Intrinsics Reference Manual 



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; XtCaUbackNone RM:100; 
XtCallbackNonexclusive RM:101; 
XtCaUbackPopdown RM:102-103; XtCall- 
CaUbacks RM:104; XtHasCallbacks 
RM-.160; XtRemoveCallback RM:219; 
XtRemoveCaUbacks RM:220 
contrasted 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 XtAddCaUback, XtCaUbackProc) 
(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) 
changejnanaged method PM:306-308, 319, 

497; RM:340 

in constraint widgets PM:338-339 
CirculateNotify events RM:442 
CirculatcRcqucst 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 
structures PM: 136-1 62 
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; instaUing 

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 
destroying RM:362 
resources RM:359-361 
compiling Xt PM:34 
composite widgets, 
as parent and child PM:320 
change_managed 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 



subclass; XtlsComposite RM:169 
using within other widgets PM:306 
compound widgets PM:340, 341 
compress_exposures event filter PM:172 
compression filters (see event filters) 
conditional compilation PM:36 
ConfigureNotify events RM:447-448 
ConfigureRequest events RM:449-450 
connection PM:499 
constraint widgets, about PM: 67, 305, 499; 

RM:16, 343-345 
class, about PM:22, 137; refiguring child 

locations PM:333-335 
constraint class part PM:329 
constraint management PM:325-340 
constraint methods; change_managed 

PM:338; set_values PM:338 
constraint_destroy method RM:345 
constraint_initialize method RM:345 
destroy method PM:329 
geometry_manager method PM:332 
initialize method PM:329 
part structure PM:327 
resize method PM:336 
resources PM:327, RM:343-345; example 

PM:68, 69 

set_values method RM:343 
(see also XtlsConstraint) 
containment PM:499 
conventions, action function names PM:42 
application-defaults file PM:32, 36 
callback function names PM:42 
font naming PM:439 
Xtlnherit constants PM:156 
function typedef naming PM:148 
gadget internals PM:375 
instance variables order PM:140 
keysym naming PM:195 
public function names PM:1 14, 449 
resource; class PM:144; names PM:144; 
representation types PM:144; resource 
names PM:240 
widget PM: 449-450; internals PM:136; 

source file names PM:136; structure decla 
rations PM:140, 162 
converters PM:25 1-264 
color name to pixel value PM: 120, 253, 276 
Convert.h PM:260 
filename to pixmap PM:257 
fontname to font PM:253 
fontname to font struct PM:253 
function pointer to callback list PM:258 
int to Boolean PM:254 



int to Dimension PM:254 

int to float PM:254 

int to font PM:254 

int to pixel PM:254 

int to pixmap PM:254 

int to Position PM:254 

int to short PM:254 

int to unsigned char PM:254 

inttoXColor PM:254 

invoking directly PM:261 

Pixel to XColor PM:254 

registering RM:48, 62-64; case converter 
RM:216 

string to accelerator table PM:253 

string to boolean PM:253 

string to cursor PM:253, 257 

string to Dimension PM:253 

string to Display PM:253 

string to file descriptor PM:253 

string to float PM:253 

string to int PM:253 

string to orientation mode PM:257 

string to Position PM:253 

string to short PM:253 

string to translation table PM:253 

string-to-justify mode PM:257 

widget name to widget ID PM:257 

widgets (R2 to 3) PM:453 

writing a converter PM:262-264 

XColor to Pixel PM:254 

(see also XtConvert, XtDirectConvert) 
coordinate system PM:3, 499 
Core 

Core class part fields 

accept_focus method, PM:154, 389, 391, 495; 
callback_private PM:151; class_initialize 
method PM:153, 258, 381, 498; RM:331; 
class_inited PM:150; class_part_init 
method PM:153, 331; RM:331; 
class_name PM:150; compress_enterleave 
PM:150; compress_exposure PM:150; 
compress_motion PM:150; destroy method 
PM:154, 165, 183, 500; RM:332; dis 
play _accelerator field PM:150; extension 
PM:151; get_values_hook PM:150; ini- 
tiaUze_hook PM: 150; initialize method 
RM:328-329, 330-331; query_geometry 
methodPM:154, 165, 180-182, 306, 321, 
508; RM:336-337; realize method realize 
method PM:153, 274, 310, 315, 509; 
RM:331-332;set_values_hook PM:150; 
superclass PM:149; trnjable PM:150; 
version PM:151; visible_interest PM:150; 



522 



X Toolkit Intrinsics Reference Manual 



widget_size PM:150; xrm_clas PM:150; 
resize method PM:154, 165, 177-180,306, 
309, 316, 336-337, 380, 510; RM:333; 
set_values method PM:154, 165-166, 
174-176, 311-312, 315, 512; RM:319, 
334-335, 343 
Core class part initializing; example 

PM: 148-149 
Core class structure; compress_exposures field 

PM:172, RM:297; in gadgets PM:375 
Core widget class (see also XtExposeProc); 

XtN (see resources) 

Core widget class PM:17, 19, 52, 137, 499; 
RM:327-337; class pointer PM:119; 
class_initialize method RM:331; 
class_part_initialize method RM:331; 
compress_enterleave field PM:234; com- 
press_exposure field PM:234; com- 
press_motion field PM:234; destroy 
method RM:332; display_accelerator 
method RM:336; drawing into from appli 
cation PM:117, 118, 119; expose method 
PM:171-172; RM:296, 332-333; get_val- 
ues_hood method RM:335; hidden superc 
lasses PM:155; initialize method 
RM:328-329, 330-331; initiaUze_hook 
method RM:336; instance default size 
PM:119; methods RM:330; query_geome- 
try method RM:336-337; realize method 
RM:331-332; resize method RM:333; 
resources PM:52; set_values method 
RM:334-335; set_values_almost method 
RM:335; set_values_hood method 
RM:335; superclasses PM:374; visi- 
blejnterest field PM:230; widgetClass 
class pointer PM:119 
CoreClassPart structure PM:139 
CorePart structure PM:139 
instance record; height field PM:308; width 

field PM:308 
instance; setting size PM:119 

counter Incrementing inside XtSetArg PM:51 

CreateNotify events RM:451-452 

Ctrl key (see modifiers) 

cursor PM: 157, 253, 499 
cursor window attribute PM:157 

cut and paste (see selections) 



D 



data types RM:423 

database (see also XtDatabase); obtaining for 

display RM:126 
DECNet PM:280 
decoration PM:3 1,279 
default size PM:180 
delete_child method PM:306, 323-324, 500; 

RM:340 

depth PM:53, 169,500 
dereference PM:500 
descendants PM:500 
destroy method PM:154, 165, 183, 500; 

RM:332 

DestroyNotify events RM:453 
details in translations (see translations) 
device PM:500 
dialog boxes PM:371 
cascading PM:371 
grabs in PM:371 
without grabs PM:371 
Dialog widget RM:363-364 
adding children RM:364 
creating RM:364 
destroying RM:364 
removing children RM:364 
resources RM:363-364 
DirectColor PM:500 
directories, font PM:438 
display, (see also XtDisplaylnitialize) 
about PM:6, 500 

adding; XtOpenDisplay RM:195-196 
closing RM:108 
connecting to multiple PM:396 
depth PM:436 

DISPLAY environment variable PM:53 
lists PM:171;RM:295 
pointer; returning for widget RM:134 
display_accelerator method, (see also 

XtStringProc); PM:211; RM:320, 336 
initializing RM: 135-136 
(see also XtCloseDisplay) 
distributed processing, about PM:7 
DoesBackingStore Xlib macro PM:156 
DoesSaveUnders Xlib macro PM:156 
double-cUcks PM:43,201 
downward chaining PM:152 
drawing, about PM:119-120, 140, 150-152, 

165, 170-174 

after Expose event PM:153 
bitmap cells PM:161 
coordinate system PM:3 



Index 



523 



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) 



E 



elements (see array) 
encapsulation PM:29, 500 
enter/leave compression PM:234 
EnterNotify 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; calUng error resource 
database PM:386; calling fatal error han 
dler RM:71-73, 85-86, 137-139, 234; .XF 2 

Usting RM:491 

string 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 

canceUing 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:45 1-452 

DestroyNotify 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; 
XtBuildEventMask 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-1 1 

event_mask window attribute PM:157 

expose PM:10 

Expose PM:23, 153, 235; RM:460-461 

Focusln 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; XtRemovelnput RM:224 

KeymapNotify RM:471 

KeyPress RM:472474 

KeyRelease RM:472-474 

LeaveNotify PM:234; RM:454-459 

LeaveWindow PM:216 

Ust 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; returning RM:191 

NoExpose PM:193;RM:468-469 

nonmaskable PM:191,207, 218 

processing RM:176 



524 



X Toolkit Intrinsics Reference Manual 



processing one event; XtProcessEvent 
RM:209 

propagation PM:207 

PropertyNotify RM:483 

ReparentNotify 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 data in PM:222; 
widget actions PM:184-185 

adding; accelerators PM:206; event handler 
PM:21 8-219; RM:294; resource list to class 
structure PM:145; scrollbars to application 
PM:109, 111; work procedure 
PM:23 1-232 

application resource data structure PM:81 

BitmapEditClassRec PM: 138-139, 138 

BitmapEditRec PM:139 

calculating scrollbar thumb size PM:1 13-1 16 

cascading pop-up menu PM:363, 365 

constraint resources PM:68-69 

constraint widget change_managed 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 
withXtSetArg PM:93, 94; GCs from ini 
tialize method PM:169-170; iconpixmap 
PM:278-279 

creating pop up; work procedure RM:323 

creating; widget hierarchy PM:61-63 

declaring; resource Ust 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 

initiaHze method PM:166-168; in constraint 
widget PM:330 

initiaUzing; 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:3 17-3 19 

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-down menu 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 file 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 Ust PM:82-83 

resource value; getting PM:51 

retrieving; application resources PM:85-86; 
resource default at run-time PM:256 

setting; 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:27 1-272; popups 
PM:71-74; timeouts PM:229 

writing type converter PM:262-263 

xbitmapl PM: 104-107 

xbitmap2 PM: 107-1 16 

xbitmapS PM:1 16-122 

xbitmap4 PM: 123-132 

XEvent RM:271 

XEvent casting PM:221 

xfarewell.c PM:43-45 

xgoodbye.c PM:40 

xheUo.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 handling (see errors) 
fatal error (see errors) 
file input, registering file RM:65-66 
files, file events (see event handlers) 
file input PM:224-226; registering file 

RM:54-55; source masks PM:224; XtAd- 

dlnput RM:54-55; XtAppAddlnput 

RM:65-66 

filenames; 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), holding 

PM:xxviii; RM:viii 



italics PM:xxviii; RM:viii 

typewriter font PM:xxviii; RM:viii 
fonts PM:502 

aliasing PM:442 

creating databases (mkfontdir) PM:444 

directories PM:438 

display (xfd) PM:438 

families PM:438,441 

fonts .dir files PM:444 

naming convention PM:439 

printer PM:438 

screen PM:438 

specifying PM:433; as resources PM:253 

using file 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 XtGeometry Almost) 
(see also XtGeometryDone return value) 
(see also XtGeometry No return value) 
(see also XtGeometry Result enum) 
(see also XtGeometry Yes return value) 
(see also XtlnheritDeleteChild constant) 
(see also XtlnheritGeometryManager constant) 
(see also XtlnheritlnsertCriild constant) 
(see also XtlnheritSetValuesAlmost 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 

constraint class part PM:329 

constraint management PM:325 

constraints 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 constraint 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:31 1-312; resize method 
PM:306, 309 
scope PM:306 

scrollable widget RM:403-404 
set_values method PM:3 1 1 -3 1 2, 3 1 5 
set_values_almost method PM:312, 322, 323 
size preferences PM:320 
stacking order PM:306, 341 
trickle-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 



obtaining RM:146-147 

read-only PM:168 

reasons for PM:119 

setting with resources PM:170 
graphics (see also drawing) 

GraphicsExpose events PM:193, 220; RM:51, 
468-469 

graphics primitive PM:503 
gravity PM:503 
GravityNotify events RM:470 
Grayscale PM:503 
Grip widget class PM:19; RM:368-369 

resources RM:368 



H 



hardcoding, resources PM:38, 91,92 

translations PM:48 
header files, not included twice PM:139 

private PM:508 

public PM:508 
height PM:308 

checking in initialize method PM:166 
hello world in Xt PM:31 
hexadecimal color specification PM:434 
hints PM:270-279, 503 

icon position PM:273 

position PM:55 

size PM:273 

size increment PM:273 
hook RM: 158, 244 
host access list PM:503 
hotspot, in cursor PM:503 
Hyper key (see modifiers) 



ICCCM PM:1 1,269, 288, 29 1,298-302 
icon, pop-ups PM:272 

setting; name PM:278; pixmap PM:269, 
277-278 

starting application as PM:273 
identifier PM:503 
if ndef statement, to prevent include files from 

being read in twice PM:139 
implementation file (see widget) 
include files PM:30, 50, 53, 136, 139 

in widget implementation PM: 141 
inferiors PM:503 
inheritance, about PM:18, 49, 54, 148-158 

adding features to superclass PM:157 



among Athena Widgets PM:18 

among Motif widgets PM:399 

among Open Look widgets PM:399 

in widget class and instance record 
PM:137-138 

of AT&T PM:405 

of chained methods PM:152 

of conflicting methods PM:157 

of Core resources PM:52, 54 

of self-contained methods PM:151-152 

of superclass method PM:155 

resources PM: 143-145 

single vs. multiple PM:503 

specifying NULL for chained methods 
PM: 152-153 

styles PM:151-152 

using Xtlnherit constants PM: 151 

widget not using resource value PM:56 
initial size PM:308 

hiitialize method PM:153, 165-170, 315, 503; 
RM:328-331 

(see also XtlnitProc) 

(see also XtProc) 

calUng XInternAtom from PM:291 

in constraint widget PM:330 
initialize_hook method PM:153, 265, 503; 

RM:336 
input queue, determining events RM:83, 205 

(see also XtAppNextEvent) 

(see also XtAppPeekEvent) 

(see also XtAppPending) 

(see also XtPeekEvent) 

examining head RM:8 1-82, 204 
input, from file PM:224-226 

from pipe PM:226-227 

input events method RM:293-294 

input focus PM:504 

input manager PM:504 

input source masks PM:224 

InputOnly window PM:504 

InputOutput window PM:504 
InputOutput window RM:460 
msert_child method PM:306, 323-324, 504; 

RM:339-340 

insertjposition method RM:339, 342 
instance, about PM:18, 504 

instance record PM:136; adding variables to 
PM:139; allocating storage PM:140; Bit- 
mapEdit widget PM:139; contents 
PM:136 

instance structure PM:166 

part structure; constraints in PM:327 

structures PM: 135-1 62 



528 



X Toolkit Intrinsics Reference Manual 



Inter-Client Communication Conventions 

Manual (see ICCCM) 
Intrinsics, about PM:8, 504; RM:2 
functions and macros; MenuPopdown 

PM:352; MenuPopup PM:352 
Intrinsic.h PM:30, 141 
IntrinsicP.h PM:141 
selection timeout RM:87 



JumpProc RM:381 



key events (see events or translations) 
key translation, registering RM:238 

(see also XtKeyProc) 

(see also XtSetKeyTranslator) 
keyboard focus, about PM:274, 389, 391, 504 

(see also XtAcceptFocusProc) 

(see also XtNinput resource) 

(see also XtSetKeyboardFocus) 

accept/reject method RM:269 

redirecting input RM:236-237 

setting PM:275 

styles PM:275 

window RM:462 
keyboard grabbing (see grabs) 
keyboard, mapping RM:477 

shortcuts (see accelerators) 
keycodes, about PM: 194, 391,505 

translating; keycode-to-keysym RM:252-255; 
XtTranslateKey RM:252-253; XtTransla- 
teKeycode RM:254-255 
Key mapNotify events RM:471 
KeyPress events PM:194, 196, 391; 

RM:472-474 

KeyRelease events PM:194, 196; RM:472-474 
keysyms, about PM:194, 391, 505 

(see also XtCaseProc) 

(see also XtConvertCase) 

converting case PM:200; RM:28 1-282 

determining case RM:114 

key generated PM:198 

keysymdef.h PM:194, 197 

naming conventions PM:195 



Label widget class, about PM:177; 
RM:370-372 

creating RM:372 

destroying RM:372 

resources RM:370-372 
laying out child widgets, example PM:317, 

319 

layout Form method PM:329 
LeaveNotify events PM: 195-196, 234, 353; 

RM:454-459 

LeaveWindow events PM:216 
lint PM:42 
List widget class, about PM:19, RM:373-377 

creating RM:375 

destroying RM:375 

listWidgetClass RM:373-377 

resources RM:373-375 
loose bindings PM:244, 505 



M 



macros PM:388-389 
mam loop PM:30, 34 

(see also XtAppMainLoop) 

(see also XtMainLoop) 

customizing; example PM:233 

internals PM:233 
mapping, about PM:33, 53, 505 

(see also widget, mapping) 

button RM:477 

keyboard RM:477 

MapNotify events RM:475-476 

MappingNotify events PM:193; RM:477-478 

MapRequest events RM:479 

pop-up shell; XtPopup RM:207-208 

unmapping pop-up shell; XtPopdown 
RM:206 

widgets; XtMapWidget RM:185 
mechanism without policy PM:1 0,269 
memory allocation PM:392 

for widget instance record PM: 1 50 
MenuPopdown PM:352; RM:39 
MenuPopup PM:352,357; RM:40-41 

argument to PM:358 
menus, about PM:345-381, 408 

accelerators in PM:367, 371 

cascading PM:347, 362 

drop-down PM:347, 359 

grabbing pointer PM:353 

panes in PM:349 



Index 



529 



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 
pulldown 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 
initiaUze_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; Alt 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 
MotionNotify events PM:196, 202, 216, 234, 

353; RM:480-482 
multiple toplevel shells PM:395 



N 



naming conventions, (see also conventions) 

widgets PM:449 
newUnes, 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) 



O 



object, about PM:28, 506 
Object class PM:374 
object-oriented programming PM:28-29 



530 



X Toolkit Intrinsics Reference Manual 



object-oriented programming, about PM:506 

obscure PM:506 

occlude PM:506 

OOP (see object-oriented programming) 

optimization PM:124, 179,394 

options -xrm PM:86, 88 

options, abbreviating PM:87 

argument styles PM:90 

command line PM:86; styles PM:90 

custom PM:246 

defining your own PM:88 

handling errors in PM:91 

options table; example PM:88-89; xbitmap 
PM:106 

standard PM:86, 87; RM:13-14 
OR operator RM:50, 95, 221, 225 
overriding, override redirect PM:272 

override_redirect window attribute PM:157 

OverrideShell widget class PM:272; 
RM:346-353 

standard options PM:91 

translations PM:48-49 



padding PM:506 
parent PM:506 

parent window PM:507 
parsing, command-line arguments PM: 88-91 

translations PM:48 
part (vs. record) PM:137 
pipe input PM:226-227 
pixel values PM: 120, 507 
pixmap, about PM:53, 171, 257, 507; RM:295 

freeing PM:183 

icon PM:277 

updating in widget PM: 116 
placing, drop-down menu; example 
PM:360-361 

pop-up menu; example PM:354, 357 
plane PM:507 

(see also bit plane) 

plane mask PM:507 
pointer PM:507 

events (see events or translations) 

grabbing (see also grabs), PM:507 

pointing device PM:507 
pop ups, about PM:17, 70, 507; RM:8 

cascading pop ups; about PM:345 

creating in work procedure PM:232; RM:323 

creating just before popping up PM:76 

from callback function PM:75 



linking group PM:272 

modal PM:348, 505 

modeless PM:348, 506 

moving to desired position PM:75 

OverrideShell PM:272 

sensitivity PM:372 

spring-loaded PM:348, 513; RM:8 

using PM:71-74 

when application is iconified PM:272 
pop-up menus PM:345 

(spring-loaded) using Box widget PM:354-358 
pop-up shell, (see also XtCreatePopupShell) 

creating RM: 119-121 

mapping RM:207-208 

unmapping RM:206 
portability PM:92, 224, 376, 39 1-394 
position, about PM:55, 253 

hints PM:273 

relative to root window PM:279 

setting with resources PM:55 
PRIMARY selection PM:281 
printer fonts, see (fonts) 
private header file (see widget) 
private instance variables PM:140 
process input RM:79 

(see also XtAppMainLoop) 
program structure PM:30 
properties, about PM:280, 508 

and atoms PM:288 
PropertyNotify events RM:483 
protocol, about PM:5 
PseudoColor PM:508 

public, functions, about PM:104, 158; naming 
conventions PM:114; reasons to use 
PM:106 

header file (see widget) 

instance variables (see resources) 

routines PM:340 
pull down menu (see menus) 



quarks PM:262, 508 

query_geometry method, about PM:154, 165, 
180-182, 306, 321, 508; RM:336-337 

in composite widget PM:316-317 

in constraint widget PM:339 

in gadgets PM:378 
querying preferred geometry PM:320 



Index 



531 



R4 PM:96 

initializejiook and set_values_hook obsoles 
cence RM:277 
raise PM:509 

raw event handlers PM:220; RM:56-57 
real estate PM:509 

realization, about PM:33, 172, 176; RM:296 
realize method PM:153, 274, 310, 315, 509; 

RM:331-332 
RealizeProc RM:327 
rectangle PM:509 
RectObj class PM:155, 374, 377 
redirect PM:509 
redrawing PM:23 
reference pages, list RM:41 1, 416 
regions PM:172,379; RM:51,297 
registering/declaring actions (see actions) 
registering, callbacks RM:44-45; list 
RM:46-47 

converters PM:257-260; RM:48, 62-64, 216 

event handlers PM:21 8-220; RM:49-50 

fatal error condition procedure PM:385-388; 
RM:85-86, 234 

file RM:54-55, 65-66 

nonf atal error condition procedure 

PM:385-388; RM:88-89, 235, 246-247 

raw event handlers RM:56-57 

work procedures PM:231-233; RM:59, 68 
Release 4, (R4) PM:36, 345-346, 372 
removing, callbacks RM:218-220 

grabs RM:223 

input RM:224 

raw event handlers RM:225-226 

timeouts RM:227; example PM:229-230 

work procedures PM:232 
reparenting, about PM:279, 361, 509 
ReparentNotify events RM:484 
reply PM:509; RM:341 
representation type PM:81-83, 239, 241, 509 
request PM:510 
resize method PM:154, 165, 177-180,306 309 

316, 336-337, 380, 510; RM:333 
ResizeRequest events RM:485 
resizing, about PM:65, 305, 311 

caching old size PM:179 

parent widget RM:333 

reasons PM:322 
resource conversion RM:131 
resource list, copying (see also XtGetSub- 

values, XtSetSubvalues) 
copying from ArgList RM:242-243 



copying to argument list RM:156-157 
resource list, retrieving, (see also 

XtGetResourceList) 
(see also XtGetApplicationResources) 
resource list, updating, (see also 

XtGetSubResources) 
default values; retrieving RM:148-149 
updating RM:141-143; by name or class 

RM:154-155 
resources RM:338-339 
resources, (see also resource list) 
about PM:22-23, 32, 36, 49, 52-54, 239-242, 

510;RM:6-8 

advantages of hardcoding PM:38 
and set_values method PM: 1 74- 1 76 
application PM:80 
changing value PM:174 
checking validity PM:166 
class PM:83 

classes and instances PM:37 
comment character in files PM:244 
constraint PM:68 
constraint widget RM:343-345 
copying; from ArgList to widget 

RM:244-245; from widget to argument list 
RM: 158-159; XtGetValues RM: 158-159; 
XtSetValues RM:244-245 
declaring resource list; example PM:240 
default address; interpreting PM:242 
default value; converting PM:254-255; set 
ting PM:83,255 
defined by Core PM:52 
defined in widget implementation file 

PM: 143-145 

defining characteristics PM:83-84 
defining in widget PM: 143-145 
Form widget PM:68, 326 
format; of definitions PM:243-244 
getting from application PM:50 
getting resource value; example PM:51 
in instance record PM:140 
inheritance of PM:49, 143-145 
interactions between PM:54-57; example 

PM:55 
loading; from .Xdefaults PM:55; withxrdb 

PM:55 

looking up values PM:243-251 
loose bindings PM:244 
name PM:83 

naming conventions PM:240 
precedence rules PM.-249-251 
registering resource converter, example 
PM:258 



532 



X Toolkit Intrinsics Reference Manual 



representation types PM:81, 83, 241 

resource conversion PM:83; converters in 
Xmu PM:253; method RM:314-315; (see 
also XtConverter, XtDirectConvert, 
XtResourceDefaultProc) 

resource database PM:510; obtaining for dis 
play RM:126 

resource database, (see also XtDatabase) 

resource database sources PM:245 

resource file format RM:497 

resource list; example PM:82-83; format 
PM:83-84 

Resource Manager PM:510 (see also actions) 

RESOURCE_MANAGER property PM:245 

resource name RM:11 

resource setting PM:510 

resource types RM:11 

retrieving; application resources PM:85-86; 
resource default at run-time PM:256 

setting; for multiple widgets PM:63-64; for 
widget hierarchy PM:64; for widget hierar 
chy PM:64; in application PM:50; with 
XtSetValues PM:50; XtNinput PM:276 

size PM:242 

sources priority PM:246 

specifications PM:249-251; errors in PM:37; 
format PM:37-38; merging of duplicate 
PM:245-246; wildcards in PM-.243 

symbolic constants PM:38, 50 

tight bindings PM:244 

type conversion PM:38, 251-264 

type converter, XtConvert RM: 111-113 

types table PM:241 

use of classes PM:241 

XtN constants PM:158 

XtNaccelerators (Core) PM:52 

XtNaUowShellResize (SheU) PM:272 

XtNancestorSensitive (Core) PM:52 

XtNargc (Shell) PM:27 1-272 

XtNargv (SheU) PM:27 1-272 

XtNbackground (Core) PM:52 

XtNbackgroundPixmap (Core) PM:52 

XtNbaseHeight (SheU) PM:272-273 

XtNbasewidth (SheU) PM:272 

XtNbaseWidth (SheU) PM:273 

XtNborderColor (Core) PM:52 

XtNborderPixmap (Core) PM:52 

XtNborderWidth (Core) PM:52 

XtNcolormap (Core) PM:52 

XtNcreatePopupChUdProc (SheU) PM:271 

XtNdefaultDistance (Form) PM:325 

XtNdepth (Core) PM:52 

XtNdestroyCaUback (Core) PM:42, 52 



XtNgeometry (SheU) PM:27 1-274 
XtNheight(Core) PM:52 
XtNheightlnc (SheU) PM:272-273 
XtNhorizDistance (constraint) PM:325 
XtNiconic (SheU) PM:27 1-273 
XtNiconMask (SheU) PM:272 
XtNiconName (SheU) PM:272, 278 
XtNiconPixmap (SheU) PM:272, 278 
XtNiconWindow (SheU) PM:272 
XtNiconX (SheU) PM:27 1-273 
XtNiconY (SheU) PM:27 1-273 
XtNinitialState (SheU) PM:272 
XtNinput (SheU) PM:272, 275-276 
XtNinsertPosition (composite) PM:324 
XtNmappedWhenManaged (Core) PM:52, 

319 

XtNmaxAspectX (SheU) PM:272-273 
XtNmaxAspectY (SheU) PM:272-273 
XtNmaxHeight (SheU) PM:272-273 
XtNmaxWidth (SheU) PM:272-273 
XtNminAspectX (SheU) PM:272-273 
XtNminAspectY (SheU) PM:272-273 
XtNminHeight (SheU) PM:272-273 
XtNminWidth (SheU) PM:272-273 
XtNoverrideRedirect (SheU) PM:27 1-272 
XtNpixmap (Core) PM:116 
XtNpopdownCaUback (SheU) PM:360 
XtNpopupCaUback (SheU) PM:360-361 
XtNsaveUnder(SheU) PM:272 
XtNscreen (Core) PM:52 
XtNsensitive (Core) PM:52 
XtNtitle (SheU) PM:27 1,278 
XtNtransient(SheU) PM:27 1-272 
XtNtranslations (Core) PM:47, 49, 52, 112 
XtNvertDistance (constraint) PM:325 
XtNwaitForWm (SheU) PM:272-272 
XtNwidth (Core) PM:52 
XtNwidthlnc (SheU) PM:272-273 
XtNwindowGroup (SheU) PM:27 1-272 
XtNwmTimeout (SheU) PM:27 1-272 
XtNx (Core) PM:52 
XtNy (Core) PM:52 

RGB, color model PM:435-436 

root PM:511 
root window PM:53, 511 

round trip request PM:30, 260, 511 

rubber-band outline PM: 177, 287 



Index 



533 



save-sct PM:511 

save_under window attribute PM:156 

saving under PM:156 

scan line PM:511 

order PM:511 
screen, screen fonts (see fonts) 

about PM:6,511 
scrollbars, about PM:15, 409, 422, 512 

adding to application PM:109; example 
PM:109 

adding to xbitmap PM:108 

and Expose events PM:114 

calculating thumb size PM: 113-1 16; example 
PM:113-116 

controlling scrolling area RM:378-382 

creating PM:112 

Scroll widget PM:19 

Scrollbar widget PM:108-111; RM:378-382; 
creating RM:380; destroying RM:380; 
resources RM:378-380 

scrollbarWidgetClass RM:378-382 

setting thumb values RM:381 
selections PM:269, 280-302, 5 12 

SelectionClear events RM:486 

SelectionNotify events RM:487 

SelectionRequest events RM:488 

and CurrentTime PM:289 

asserting ownership PM:288-289 

converting; selection PM:293-294; standard 
selections PM:299-301; RM:284-285 

deleting PM:301 

disowning PM:302 

handling large selections PM:301; RM:285 

highlighting selected data PM:284, 287-288 

highlighting selection; example PM:284, 
287-288 

losing selection PM:289-297 

pasting data PM:292 

pasting selection PM:295-297; example 
PM:295-296 

querying for desired target PM:298-302 

requesting selection PM:289-290 
selections, selection data RM:132, 198-199 

method RM:316-317; obtaining RM:151; 
obtaining in multiple formats RM: 152-153 

(see also XtConvertSelectionProc) 

(see also XtDisownS election, XtSelection- 
CallbackProc) 

(see also XtGetSelectionValue, XtGetSelec- 
tion Values) 

(see also XtOwnS election) 



selections, selection method 
(see XtLoseSelectionProc, XtSelection- 

DoneProc) 

selections, selection timeout (see timeouts) 
SelectionClear events PM:280, 289 
SelectionNotify events PM:280, 290, 295 
SelectionRequest events PM:193, 280, 282, 

290-291 

setting timeout PM:302 
target types PM:290-292 
XA_CLIPBOARD PM:288,301-302 
XA_MULTIPLE PM:301; RM:285 
XA_PRIMARY PM:281,288 
XA_SECONDARY PM:288 
XAJTARGETS PM:29 1,298 
self-contained methods (see inheritance) 
sensitivity PM:54,75,92 
checking state; XtlsSensitive RM:173 
in pop-up callbacks PM:372 
setting state; XtSetSensitive RM:241 
server, about PM:6, 512 
server code; guide to PM:491 
server grabbing PM:512 
server resources; freeing PM:183 
set_values method PM:154, 165- 166, 174-176, 

311-312, 315, 512; RM:319, 334-335, 343 
(see also XtSetArgsFunc, XtSetValues, XtSet- 

ValuesFunc) 
change to PM:456 
in composite widget PM:316 
redrawing due to changes in PM:175 
set_values_almost method PM:154, 312, 
~ 322-323, 512; RM:273-274, 335 
in gadgets PM:378 
set_values_hook method PM:154, 265-266, 

512;RM:275-276,335 
Shell RM:346-353 

environment variables (see environment vari 
ables) 

Shell, default value PM:458; RM:351-352 
Shell types; ApplicationShell RM:346; Over- 
rideShell RM:346; Shell RM:347; 
TopLevelShell RM:346; TransientShell 
RM:346; VendorShell RM:347; WMShell 
RM:347 

Shell widget class, about PM:17, 21, 32, 55, 
61, 66, 269; RM:346-353; reason for invisi 
bility PM:63; resources PM:271, 272-277, 
279; types RM:346-347; XtlsShell 
RM:174; XtNbasewidth PM:272 
sibling PM:512 



534 



X Toolkit Intrinsics Reference Manual 



single-line input Held 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:135 
source, in Athena Text widget PM:264 
spring-loaded pop up (see pop ups) 
stacking order PM:306, 341, 513 
StaticCoIor PM:513 
StaticGray PM:513 
status PM.-513 
stdio.h PM:141 
stipple PM:513 
storage, storage block 

allocating RM.-181; for data type RM:189; 
XtNew RM:189 

freeing RM:140; (see also XtFree) 

resizing RM:215 

(see also XtMalloc) 

string, copying ; XtNewString RM:190 
StringDefs.h PM:83 
StringDefs.h header file PM :30, 50, 141; 

RM:507 
strhig, error message; XtStringConver- 

sionWarning RM:248 
StringToWidget resource converter PM:69 
structure, (see also XtOffset) 

determining field s byte offset RM:193-194 

of Xt applications PM:30 
subclass, about PM:19,513 
submenus (menus, cascading) 
subparts PM: 150, 154,264-266 
sub resources PM:150, 154, 264-266 
Super key (see modifiers) 
superclass, about PM:19, 149, 513 
syntax functions PM:91 



TCP/IP PM:280 

templateWidgetClass RM:383-390 
Text widget, about PM:19, 414, 424; 
RM:39 1-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 timeout RM:67 

removing PM:229-230 

selection timeout; setting RM:240; value 
RM:78, 87, 150 

(see also XtAddTimeout, XtAppAddTimeOut) 

(see also XtAppSetSelectionTimeout, XtGet- 
SelectionTimeout) 

(see also XtRemoveTimeOut, XtSetSelection- 
Timeout) 

(see also XtTimerCallbackProc) 
toolkits, initializing internals RM:250 

initializing toolkit and display RM: 161-165 

(see also Xtlnitialize, XtToolkitlnitialize) 
top-level widget (see Shell widget) 

top-level window PM:514 

topLevelShell widget class PM:270; 

RM:346-353 
training in Xlib PM:489 
TransientShell 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 initiaHzed PM:147; XtParseTransla- 

tionTable RM:202-203 
defining; 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 



Index 



535 



in widget implementation file PM : 1 45 - 1 47 

inheritance PM:146 

interactions between PM:203-207 

keyboard events PM: 194-195 

merging PM: 112, 203 

merging widget translations RM:93-94 

merging/overwriting RM:197 

modifiers PM: 196-201, 198 

modifiers and event sequences PM:202 

Motion events PM:202 

newlinesin PM:190 

*Notify details PM:195 

order PM:203-204 

overriding PM:48-49 

parsing PM:48 

removing RM:256 

replacing PM:48,49 

resource converters PM:253 

syntax PM:190 

tilde modifier symbol PM:199 

translation table PM:514; RM:499; example 
PM:47; syntax PM:457 

(see also XtAugmentTranslations) 

(see also XtUninstallTranslations) 
traversal, post-order PM:508 

pre-order PM:508 
TrueColor PM:514 
type converters, (see also resources) 

about PM:93 

caching PM:260 

explicitiy invoking PM:261; example 
PM:261 

format PM:262-264 

passing arguments to PM:259 

registering PM:257-260 
type property PM:514 
typedefs PM:140 

types converters, passing arguments to; 
example PM:259 



U 



unmanaging widget PM:319 
UnmapNotify events RM:475-476 
upward chaining PM:152 
uunet PM:34 
uwm PM:346 



varargs PM:95,427 

variables, resource PM:446 

VendorSheil widget class PM:275 

viewable PM:514 

Viewport widget, creating RM:404 

Viewport, Viewport widget; destroying 

RM:404; inserting child RM:404; remov 
ing child RM:404; resources RM:403-404 
ViewportWidgetClass RM:403-404 

virtual colormaps PM:276 

virtual crossing RM:456 

visibility hiterest PM: 150, 230-231 

VisibilityNotify events PM:150, 193; 
RM:489-490 

visible PM:514 

visual PM:514 
class PM:514 

VPaned, VPaned widget; about RM:405-408; 
adding pane RM:406; change height set 
tings RM:407; child resources RM:406; 
deleting pane RM:406; destroying 
RM:408; disabling auto-reconfiguring 
RM:407; disabUng pane resizing RM:407; 
disabling resources RM:405-406; enabling 
auto-reconfiguring RM:407; enabling pane 
resizing RM:407 
VPanedWidgetClass RM:405-408 



W 



warnings (see error handling) 
calling high-level RM:91-92, 261-262 
handler, (see XtAppWamingMsg, XtWarning, 

XtWamingMsg) 
listing RM:491 
widget 

about PM:8, 15,514;RM:2 
actions; example PM:184-185 
adding to parent list PM:17; RM:182-184; 

XtManageChild RM:182; XtManageChil- 

dren RM:183-184 
application context PM:97-98; getting 

RM:263; XtWidgetToApplicationContext 

RM:263 

as data type PM:33 

BitmapEdit PM:66, 103-132, 177,314,461 
Box widget PM:21,351;RM:357-358; 

example PM:61 

call accept_focus method RM:97 
callback list (see callbacks) 



536 



X Toolkit Intrinsics Reference Manual 



child widget; about RM:15; creating/manag 
ing PM:61,307;RM:118; layout of 
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 for writing PM:305; writing PM:312 

compound PM:340-341 

constraint widget, about PM:22, 305; RM:16, 
170,343-345; management PM: 3 25; 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; 
XtDestroy Widget 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 file 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 
Ufecycle 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 XtCreateWidget) 
modal widget; redirecting input RM:52-53, 

223; XtAddGrab RM:52-53; XtRemo- 

veGrab RM:223 
moving/resizing PM:53; RM: 109-1 10; 

XtConfigureWidget RM:109-110; XtMo- 

veWidget RM:187 
naming conventions PM:449 
necessary include files PM:136 
parent widget PM:111; 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 
retuming screen pointer, XtScreen RM:231 
Scroll widget PM:257 

ScroUbar widget PM:19, 66, 108; RM:378-382 
ScrollBox widget PM:314 



Index 



537 



scrolling viewing area in another widget 

RM:378-382 
sensitivity PM:54,235 

sets; about PM:8, 17, 18; Motif PM:18; spe 
cial defaults PM:275 
SheU widget, about PM:17, 21, 61, 104, 269; 

RM:174 

source file PM:135; RM:387 
subclass; XtlsSubclass RM:175 
superclass; inheritance PM:54; obtaining 

RM:249; XtlsSuperclass RM:249; XtSu- 

perclass RM:249 
techniques for writing PM:160 
Text widget PM:19, 75, 264, 414, 424; 

RM:39 1-402 

text-editing widget RM:39 1-402 
translating; coordinates RM:251; name to 

instance RM:188; window and display 

pointer RM:265; XtNameToWidget 

RM:188; XtTranslateCoords RM:251; 

XtWindowToWidget RM:265 
unmapping; XtUnmapWidget RM:259 
Viewport PM:21, 108; RM:403-404 
VPaned widget PM:20, 66; RM:405-408 
WidgetProc RM:327 

WidgetToApplicationContext macro PM:394 
WidgetWrap PM:96 
Window widget RM:385 
window; destroying RM:260; returning 

RM:264; XtUnreaHzeWidget RM:260; 

XtWindow RM:264 
windowless (see gadgets) 
widget classes, about PM:17 
applicationShell (Intrinsics) PM:270 
Box (Athena) PM:66 
Command (Athena) PM:19, 40-43, 47, 65 
composite (Intrinsics) PM:16, 61, 137 
constraint (Intrinsics) PM:137 
Core (Intrinsics) PM:17, 52, 137; RM:327-337 
Dialog (Athena) PM:71,75 
Form (Athena) PM:68-69 
Grip (Athena) PM:66 
inheritance among (Athena) PM:18 
initialize method; XtlnitProc RM:302-303; 

XtProc RM:311 
Label (Athena) PM: 19, 36, 240 
OverrideSheU (Intrinsics) PM:270, 272 
Scroll (Athena) PM: 15, 39, 42, 66 
Shell (Intrinsics) PM:17, 32, 55, 61, 66, 269 
Simple (Athena) PM:19 
Text (Athena) PM:75,264 
topLevelSheU (Intrinsics) PM:270 
TransientShell (Intrinsics) PM:70, 74, 270 



VendorShell (Intrinsics) PM:275 
VPaned (Athena) PM:66 
WidgetWrap PM:429 
width PM:308 

checking in initialize method PM:166 
wildcards, in font names PM:441 

in resource specifications PM:37, 243 
window, (see also XtCreateWindow) 
creating widget s working window 

RM:124-125 
geometry PM:445 
InputOutput RM:460 
keyboard focus RM:462 
background PM:156 
backing_store PM:156 
bit_gravity PM:156 
border PM:156 
colormap PM:156 
cursor PM:157 
event_mask PM:157 
override_redirect PM:157 
save_under PM:156 
setting in realize method PM:157 
window gravity PM:515 
window manager, about PM:11, 31, 65-66, 

269-279, 305, 5 15; RM:352 
and decoration PM:279 
and icons PM:277-279 
click-to-type PM:274 
colormaps PM:276, 277 
focusing styles PM:196 
hints PM:1 1,270-279 
input models PM:274 
interacting with PM:270-279 
keyboard focus PM:274-276 
listener PM:505 
pointer-focus PM:274 
real-estate-driven PM:274 
reparenting PM:279, 361 
screen layout PM:273-274 
WindowObj class PM:155, 375 
work procedures, about PM:23 1-233, RM:59 
(see also XtAddWorkProc, XtAp- 

pAddWorkProc) 
(see also XtAppRemoveWorkProc, 

XtWorkProc) 

creating pop up in, example RM:323 
registering RM:68 
removing PM:232; RM:228 



538 



X Toolkit Intrinsics Reference Manual 



X Consortium address PM:490 

X protocol PM:5, 280 

X source software PM:485 

X Toolkit (see toolkits) 

X, about PM:3 

XA_CLIPBOARD (see selections) 

XA_MULTIPLE property (see selections) 

XA_MULTIPLE property (see selections) 

XAPPLRESDIR 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 

xbitmap application; PM:461 
xbitmapl; example PM:104-107 
xbitmap2; example PM: 107-1 16 
xbitmap3; example PM:1 16-122 
xbitmap4; example PM: 123-132 
XChangeGC Xlib function PM:168 
XChangeKeyboardMapping RM:477 
XClear Area Xlib function PM:175 
xcllpboard PM:300-302 
XConfigureWindow PM:341, RM:449-450, 

485 

XConvertSelection RM:487 
XCopyArea Xlib function PM:122, 174, 193; 

RM:297 
XCop yColormap AndFrcc Xlib function 

PM:277 
XCopyPlane Xlib function PM:122, 174, 193; 

RM:297 

XCreateGC Xlib function PM:120, 166 
XCreate Window Xlib function PM:158 
Xdefaults file PM:55,245 
xedit PM:280 
XENVIRONMENT environment variable 

PM:245 
xev PM:198 
XEvent union RM:437 
xfarewelLc, example PM:43-45 
xfd (font displayer) PM:441 
XFlush Xlib function PM:394 
XGC Values structure PM:168 
XGetlconSizes Xlib function PM:279 
XGetModifierMapping RM:478 
XGetMotion Events RM:481 



XGetPointerMapping RM:478 
XGetStandardColormap Xlib function 

PM:277 

xgoodbye.c, example PM:40 
XGrabButton Xlib function PM:353 
XGrabKey Xlib function PM:353 
XGrabPointer Xlib 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 Xlib function PM:391 
XLowerWindow Xlib function PM:341 
XMapRaised RM:479 
XMapWindow RM:479 
xmh PM:68,280 
xmodmap PM:198 
XMoveResizeWindow RM:485 
Xmu PM:36, 259, 299 
X muCon vertS tandardSelection PM:300-301 ; 

RM:285 
XmuConvertStandardSelection Xmu function 

PM:299 

XmuIntcrnAtom PM:299 
XmuInternAtom Xmu function PM:299 
Xmu, resource converters in PM:253 
XNextEvent Xlib function PM:3 1 1 
XParseGeometry Xlib function PM:274 
XQueryPointer RM:481 
XRaiseWindow Xlib function PM:341 
xrdb PM:55, 243, 245 
XRectlnRegion Xlib function PM:172; 

RM:297 

XRefreshKeyboardMapping RM:478 
XResizeWindow RM:485 
XRestackWindows Xlib 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 
XrmoptionSkipArg argument style PM:90 
XrmoptionSkipLine argument style PM:90 
XrmoptionStickyArg argument style PM:90 
XrmStrlngToQuark Xlib function PM:262 



Index 



539 



XSelecflnput Xlib function PM:207,216 
XSendEvent RM:444, 487-488 
XSetErrorHandler Xlib function PM:385 
XSetlnputFocus RM:463 
XSetlnputFocus Xlib function PM:390; 

RM:463 

XSetlOErrorHandler Xlib function PM:385 
XSetPointerMapping RM:477 
XSync Xlib function PM:394 
Xt Intrinsics (see Intrinsics) 
XtAcceptFocusProc RM:269 
XtActionProc PM:46; RM:270-272 
XtAddActions PM:45, 47, 145, 381, 393; 

RM:42-43 
XtAddCallback PM:42, 253; RM:44-45 

arguments PM:42 

XtAddCallbacks PM:80; RM:46-47 
XtAddConverter PM:259, 393; RM:48 

arguments PM:258 
XtAddEventHandler PM:215-216; RM:49-50 

arguments PM:218 

when to call PM:218 
XtAddExposureToRegion RM:51 
XtAddGrab PM:372; RM:52-53 
XtAddlnput PM:224, 226, 393; RM:54-55 
XtAddRawEventHandier PM:220; RM:56-57 
Xt Address address mode constant PM:260 
XtAddressModc enum PM:260 
XtAddTimeOut PM:227; RM:58 
XtAddWorkProc PM:231;RM:59 
XtAlmostProc RM:273-274, 335 
XtAppAddActions PM:98, 393; RM:60-61 
XtAppAddConverter PM:393; RM:62-64 
XtAppAddlnput PM:393; RM:65-66 
XtAppAdd TimeOut RM:67 
XtAppAddWorkProc RM:68 
XtAppContext PM:97 
XtAppCreateShell PM:30, 98, 270, 393, 395; 

RM:69-70 

XtAppError PM:386,393; RM:71 
XtAppErrorMsg PM:393; RM:72-73 
XtAppGetErrorDatabase PM:393; RM:74 
XtAppGetErrorDatabaseText PM:393; 

RM:75-77 

XtAppGetSelectionTimeout PM:393 
XtAppInitialize PM:97,243 
XtAppMainLoop PM:98, 393; RM:79 
XtAppNextEvent PM:393-394; RM:80 
XtAppPeekEvent PM:393-394; RM:81-82 
XtAppPending PM:393-394; RM:83 
XtAppProcessEvent PM:393-394; RM:84 



XtAppSelectionTimeout RM:78 
XtAppSetErrorHandler PM:393; RM:85 
XtAppSetErrorMsgHandler PM:393; RM:86 
XtAppSetSelectionTimeout PM:393; RM:87 
XtAppSetWarningHandler PM:393; RM:88 
XtAppSetWarningMsgHandler PM:393; 

RM:89 

XtAppTimeOut PM:393 
XtAppWarning PM:386, 393; RM:90 
XtAppWarningMsg PM:393;RM:91-92 
XtAppWorkProc PM:393 
XtArgsFunc RM:275-276, 335 
XtArgsProc RM:277-278, 335-336, 339 
XtArgVal PM:92 
XtAsciiSinkCreate RM:401 
XtAsciiSinkDestroy RM:401 
XtAugmentTranslations PM:48, 113; 

RM:93-94 

reasons to use PM:112 

XtBaseOffset address mode constant PM:260 
XtBuildEventMask RM:95-96 
XtCallAcceptFocus PM:154, 390-391; RM:97 
XtCallbackExclusive PM:79, 352; RM:98-99 
XtCallbackList RM:279 
XtCallbackNone PM:79,352; RM:100 
XtCallbackNonexclusive PM:79, 352; RM:101 
XtCallbackPopdown PM:352;RM: 102-103 
XtCallbackProc RM:279-280 
XtCallbackRec RM:279 

format PM:80 

XtCallCallbacks PM:39; RM:104 
XtCalloc PM:183,392;RM:105 
XtCaseProc RM:28 1-282 
XtCaseProc function prototype PM:392 
XtCheckSubclass RM:106 
XtClass RM:107 
XtCloseDisplay RM:108 
XtConfigureWidget PM:52; RM:109-110, 334, 

341 

XtConvert PM:93,261;RM:111-113 
XtConvertArgRec PM:259 
XtConvertCase PM:392;RM:114 
XtConverter RM:286-289 
XtConvertSelectionProc PM:282, 289; 

RM:283-285 
XtCreateApplkationContext PM:30, 97-99; 

RM:115-116 
XtCreateApplkationShell PM:393, 395; 

RM:117 
XtCreateManagedWidget PM:30, 33, 64, 94, 

140, 243; RM:14, 118.340 



540 



X Toolkit Intrinsics Reference Manual 



XtCreatePopupSheU PM:74, 270, 348; 

RM:119-121 
XtCreateWidget PM:30, 63, 140, 165, 243; 

RM:122-123,339,344 
hardcoding resources with PM:92 
XtCreateWlndow PM:158; RM:124-125 
XtCWQueryOnly mask PM:322; RM:340-341 
Xt Database RM:126 
XtDefaultBackground PM:277 
XtDefauItBackground constant PM:253, 264 
XtDefaultFont constant PM:253 
XtDefaultForeground constant PM:253, 264, 

277 

XtDestroyApplicationContext RM:127 
XtDestroyGC PM:176;RM:128 
XtDestroyWidget PM:165, 324; RM:129-130, 

339, 345 

XtDIrectConvert PM:261; RM:131 
XtDlskSourceCreate RM:401 
XtDiskSourceDestroy RM:401 
XtDisownSelection PM:302; RM:132 
XtDispatchEvent PM:233; RM:133 
XtDisplay RM:134 
XtDLsplay macro PM:261 
XtDisplaylnitialize PM:30;RM: 135-136 
xterm PM:274,346 
XtError PM:386, 387, 393; RM:137 
XtErrorHandler RM:290 
XtErrorMsg PM:386, 387, 393; RM:138-139 
XtKrrorMsg Handler RM:29 1-292 
xtetrls PM:227, 228-229 
XtEventHandler RM:293-294 
XtExposcProc PM:147;RM:295-298,332 
XtFree PM: 183, 297, 392; RM: 140 
XtGeometryAlmost PM:321;RM:335,341 
XtGeome try Almost return value PM:182 
XtGeometryDone RM:340 
XtGeometryDone return value PM:321 
XtGeometryHandler RM:299-30 1,336 
XtGeometryMask RM:178, 21 1,273, 300 
XtGeometryNo PM:182; RM:341 
XtGeometryNo return value PM:321 
XtGeometryResult PM:320-321;RM:178, 180, 

211,300 

XtGeometryResult enum PM:182 
XtGeometryYes PM:182; RM:340 
XtGeometryYes return value PM:321 
XtGetApplicationResources PM:80, 243, 260; 

RM:141-143 

XtGetErrorDatabase PM:387,393; RM:144 
XtGetErrorDatabaseText PM:387,393; 



RM:145 
XtGetGC PM:120, 166, 168, 176; RM:146-147 

when not to use PM: 1 69 
XtGetResourceList PM:145; RM: 148-149 
XtGetSelectionTimeout PM:302, 393; RM:150 
XtGetSelection Value PM:282, 289-291, 299; 

RM:151 

XtGetSelection Values PM:302; RM: 152-153 
XtGetSubresources PM:260, 266; 

RM:154-155, 156-157 
XtGetSubvalues PM:266;RM: 156-157 
XtGetValues PM:23, 50-51, 75, 136, 361; 

RM:158-159,345 
bugfix PM:458 

XtGrabNone grab mode PM:371 
XtHasCallbacks PM:388; RM:160 
XtlMAlternatelnput constant PM:234 
Xtlm mediate address mode constant PM:260 
XtlMTimer constant PM:234 
XtlMXEvent constant PM:234 
X tin her it constants PM:151 
XflnheritDeleteChild constant PM:324 
XtlnheritGeometryManager constant 

PM:321 

XflnheritlnsertChild RM:339 
XanherittnsertChild constant PM:324 
XtlnheritRealize constant PM:155 
XflnheritSetValuesAlmost RM:335 
XanherltSetValuesAlmost constant PM:323 
Xtlnltiallze PM:30, 32, 74, 87, 170, 243, 246; 

RM:161-165 
arguments PM:32, 33 
passing options table to PM:90 
XttnitProc RM:302-303, 330, 345 
XtlnputCallbackProc RM-.304-305 
XtlnstallAccelerators PM:205;RM:166-167 
XttnstallAllAccelerators PM:205, 209; 

RM:168 

XtlnternAtom Xlib function PM:288 
XtlsComposite PM:388;RM:169 
XtlsConstraint RM:170 
XttsManaged PM:388;RM:171 
XttsRealized PM:172,388;RM:172,296 
XttsSensitive PM:388;RM:173 
XttsShell RM:174 
XtlsSubclass PM:388;RM:175 
XtKeyProc RM:306-308 
XtKeyProc function prototype PM:392 
XtLoseSelectionProc PM:289; RM:309 
XtMainLoop PM:30, 34, 141, 230, 311, 393; 

RM:176 
and multiple application contexts PM:394 



Index 



541 



XtMakeGeometryRequest PM:31 1-312, 320; 

RM: 177-179, 340 

XtMakeResizeRequest PM-.322; RM:180 
XtMalloc PM:183, 392; RM:181 
XtManageChild PM:33; RM:182 
XtManageChildren PM:30, 33; RM:183-184 
XtMapWidget PM:319;RM:185 
XtMergeArgLists PM:95;RM:186 
XtMoveWidget PM:52, 308, 319; RM:187, 341 
XtNameToWidget PM:388 
XtNbasewidth (Shell) PM:272 
XtNew PM:266,392;RM:189,275 
XtNewString PM:392;RM:190 
XtNextEvent PM:233, 393; RM:191 
XtNsensitive resource PM:75 
XtNumber RM:192 
XtOffset RM: 193-1 94 
XtOffset macro PM:83, 242 
XtOpenDisplay PM:98, 396; RM: 195-196 
XtOrderProc RM:310,342 
XtOverrideTranslatlons PM:49, 112-113; 

RM:197 

reasons to use PM:112 
XtOwnSelection PM:281, 288-289; 

RM:198-199 

XtPanedAllowResize RM:407 
XtPanedSetMinMax RM:407 
XtPanedSetRefigureMode RM:407 
XtParent RM:200 

XtParseAcceleratorTable PM:210; RM:201 
XtParseTranslationTable PM:48, 113, 147, 

210; RM:202-203 

XtPeekEvent PM:234, 393; RM:204 
XtPending PM:234, 393; RM:205 
XtPointer PM:376 
XtPointer data type PM:256 
XtPopdown PM:71,352,357;RM:206,352 
XtPopup PM:71, 352, 365; RM:207-208, 347, 

352 

XtPopupSpringLoaded (R4) PM:353 
XtProc RM:31 1,327 
XtProcessEvent PM:234, 393; RM:209 
XtQueryGeometry PM:308,310,312; 

RM:210-212 
XtRAcceleratorTable representation type 

PM:253 

XTranslateCoordinates Xlib function PM:361 
XtRBackingStore representation type 

PM:257 

XtRBool representation type PM:253 
XtRBoolean representation type PM:253 



XtRCallback representation type PM:258 
XtRCallProc representation type PM:242, 

255 

XtRCursor representation type PM:253, 257 
XtRDimension representation type PM:253 
XtRDisplay representation type PM:253 
XtRealizeProc RM:312-313,331 
XtRealizeWidget PM:30, 33, 153, 308, 

310-311, 319; RM:213-214 
XtRealloc PM:392; RM:215 
XtRegisterCaseConverter PM:392; RM:216 
XtReleaseGC PM:176; RM:217 
XtRemoveAccelerators PM:206 
XtRemoveActions PM:145 
XtRe move A 11 Actions PM:145 
XtRcmoveAHCallbacks RM:218 
XtRemoveCallback PM:80, 360; RM:219 
XtRemoveCallbacks PM:80; RM:220 
XtRemoveEventHandler PM: 183, 220; 

RM:22 1-222 

XtRemoveGrab PM:372; RM:223 
XtRemovelnput PM:226; RM:224 
XtRemoveRawEventHandler PM:220; 

RM:225-226 

XtRemoveTimeOut PM: 183, 229; RM:227 
XtRemoveWorkProc PM:231, 232; RM:228, 

323 

XtResizeWidget PM:308, 319; RM:229, 341 
XtResizeWindow RM:230 
XtResource PM:239 
XtResourceDefaultProc RM:314-315 

example PM:256 
XtResourceQuark address mode constant 

PM:260 
XtResourceString address mode constant 

PM:260 

XtRFile representation type PM:253 
XtRFloat representation type PM:253 
XtRFont representation type PM:253 
XtRFontStruct representation type PM:253 
XtRFunction representation type PM:258 
XtRI mmcdiate representation type PM:242, 

255 

XtRInt representation type PM:253 
XtRJustify representation type PM:257 
XtROrientation representation type PM:257 
XtRPixei representation type PM:253 
XtRPixmap representation type PM:257 
XtRPosition representation type PM:253 
XtRShort representation type PM:253 
XtRTranslationTable representation type 



542 



X Toolkit Intrinsics Reference Manual 



PM:253 
XtRUnsignedChar representation type 

PM:253 

XtRWidget representation type PM:257 
XtScreen RM:231 
XtScrolIbarSetThumb 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 
XtSetSelectionTimeout 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 
XtStringConversionWarning PM:263, 387; 

RM:248 

XtStringProc RM:320,336 
XtStringSourceCreate RM:401 
XtStringSourceDestroy RM:402 
XtSuperclass RM:249 
XtTextBlock RM:399 
XtTextChangeOptions RM:400 
XtTextDisableRedisplay RM:399 
XtTextDisplay RM:400 
XtTextEnableRedisplay RM:399 
XtTextGetlnsertionPoint RM:400 
XtTextGetOptions RM:400 
XtTextGetSelectionPos RM:398 
XtTextGetSource RM:401 
XtTextlnvalidate RM:399 
XtTextRepIace RM:398 
XtTextSettnsertionPoint RM:400 
XtTextSetLastPos RM:400 
XtTextSetSelection RM:397 
XtTextSetSource RM:401 
XtTextTopPosition RM:400 
XtTextUnsetSelection RM:398 
XtTimeOut PM:393 



XtTimerCallbackProc RM:321 
XtToolkittnitialize PM:30, 98, 243; RM:250 
XtTranslateCoords PM:75, 360-361; RM:251 
XtTranslateKey PM:392; RM:252-253 
XtTranslateKeycode PM:392; RM:254-255 
Xtl ninstallTransIations RM:256 
XtUnmanageChild PM:319; RM:257 
XtUnmanageChildren PM:319; RM:258 
XtUnmapWidget PM:319; RM:259 
XtUnrealizeWidget RM:260 
XtVaCreateArgsList PM:428 
XtVaGetAppIicationResources PM:260 
XtVaGetSubresources PM:260 
XtVersion constant PM:151 
XtVersionDontCheck constant PM:151 
XtWarning PM:386-387, 393; RM:261 
XtWarningMsg PM:386-387, 393; RM:262 
XtWidgetGeometry PM:320-323 
XtWidgetGeometry structure PM: 180- 182 
XtWidgetProc PM: 148; RM:322, 332-345 
XtWidgetToApplicationContext RM:263 
XtWindow PM:176,378;RM:264 
XtWindowToWidget PM:389; RM:265 
XtWorkProc PM:393; RM:323-324 
XUnGrabPointer Xlib function PM:352 
XView PM:10 
XYPixmap PM:515 



zoomed window PM:515 
ZPixmap PM:515 



Index 



543 




O Reilly & Associates, Inc. 
Creators and Publishers of Nutshell Handbooks 




Nutshell Handbooks 

Learning the UNIX Operating System 
DOS Meets UNIX 
Learning the vi Editor 
UNIX in a Nutshell. System V 
UNIX in a Nutshell. Berkeley- 
Handbooks on Communications: 
!%@:: A Directory of Electronic 

Mail Addressing and Networks 
Using UUCP and Usenet 
Managing UUCP and Usenet 
Handbooks on Programming: 
Using C on the UNIX System 
Checking C Programs with lint 
Understanding and Using COFF 
Programming with curses 
termcap and terminfo 
Managing Projects with make 



The X Window System series 

Vol. X Protocol Reference Manual 
Vol. 1 XI ih Programming Manual 
Vol. 2 Xlih Reference Manual 
Vol. 3 X Window System User s Guide 
Vol. 4 X Toolkit Intrinsics 

Programming Manual 
Vol. 5 X Toolkit Intrinsics Reference 

Manual 
Vol. 7 XView Programming Manual 

For HyperCard on Macintosh: 

UNIX in a Nutshell for HyperCard 
(includes 1 .8MB of HyperCard 
stackware, User s Guide, and a copy of 
Learning the UNIX Operating System) 

Other UNIX books: 

UNIX Te.\t Processing 



Send me more information on: 

Retail sales 

1 I Licensing 

I I Review copies for instructors 

CD Magazine press kits for new books 

I I Education policy 

I I Bookstore locations 

LJ Overseas distributors 

I I Additional copy of Nutshell News 

I I Upcoming books on the subject: 



LJ Writing a Nutshell Handbook 




O Reilly & Associates, Inc. 
Creators and Publishers of Nutshell Handbooks 



HANDBOOKS 




Nutshell Handbooks 

Learning the UNIX Operating System 
DOS Meets UNIX 
Learning the \ i Editor 
UNIX in a Nutshell, System V 
UNIX in a Nutshell. Berkeley 

Handbooks on Communications: 

!%@:: A Directory of Electronic- 
Mail Addressing and Networks 
Using UUCP and Usenet 
Managing UUCP and Usenet 
Handbooks on Programming: 
Using C on the UNIX System 
Checking C Programs with lint 
Understanding and Using COFF 
Programming with curses 
termcap and terminfo 
Managing Projects with make 



The X Window System series 

Vol. X Protocol Reference Manual 
Vol. 1 Xlih Programming Manual 
Vol. 2 Xlih Reference Manual 
Vol. 3 X Window System User s Guide 
Vol. 4 X Toolkit Intrinsics 

Programming Manual 
Vol. 5 X Toolkit Intrinsics Reference 

Manual 
Vol. 7 XView Programming Manual 

For HyperCard on Macintosh: 

UNIX in a Nutshell for HyperCard 
(includes 1.8MB of HyperCard 
stackware. User s Guide, and a copy of 
Learning the UNIX Operating System) 

Other UNIX books: 

UNIX Text Processing 



Send me more information on: 

CD Retail sales 

I I Licensing 

Q Review copies for instructors 

I I Magazine press kits for new books 

I I Education policy 

I I Bookstore locations 

I I Overseas distributors 

I I Additional copy of Nutshell News 
LJ Upcoming books on the subject: 



CH Writing a Nutshell Handbook 



D 



Please send me the information 
I have asked for on the reverse 
side of this card. 



Name 



Company 
Address - 



City 



State, ZIP 



(Fill out or tape 
business card here) 




Nutshell Handbooks 

O Reilly & Associates, Inc. 




632 Petaluma Avenue 

HANDBOOKS SebaStOpol CA 95472 



D 



Name 



Please send me the information 
I have asked for on the reverse 
side of this card. 



Company 
Address - 



City 



State, ZIP 



(Fill out or tape 
business card here) 




Nutshell Handbooks 



NUTSHELL 



O Reilly & Associates, Inc. 
632 Petaluma Avenue 



HANDBOOKS Sebastopol CA 95472 




Overseas Distributors 



Effective January 1. 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 inquiries) 

Addison-Wesley Publishers, Pty. Ltd. 

6 Byfield Street 

North Ryde. N.S.W. 2113 

AUSTRALIA 

Telephone: 61-2-888-2733 

FAX: 61-2-888-9404 

UNITED KINGDOM & AFRICA 
(orders and inquiries) 
Addison-Wesley Publishers. Ltd. 
Finchampstead Road 
Wokingham. Berkshire RG1 I 2NZ 
ENGLAND 

Telephone: 44-734-794-000 
FAX: 44-734-794-035 

EUROPE & THE MIDDLE EAST 
(orders and inquiries) 
Addison-Wesley Publishers B.V. 
De Lairessestraat 90 
1071 PJ Amsterdam 
THE NETHERLANDS 
Telephone: 31-20-764-044 
FAX: 31-20-664-5334 



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 

ASIA orders (excluding Japan) 

Addison-Wesley Publishing Co., Inc. 

International Order Department 

Route 128 

Reading, Massachusetts 01867 U.S.A. 

Telephone: 1-617-944-3700 

FAX: 1-617-942-2829 

JAPAN 

(orders and inquiries) 
Toppan Company. Ltd. 
Ochanomizu Square B. 1-6 
Kanda Surugadai 
Chiyoda-ku, Tokyo 101 
JAPAN 

Telephone: 81-3-295-3461 
FAX: 81-3-293-5963 



X Toolkit Intrinsics Reference Manual 



Volume Five, X Toolkit Intrinsics Reference Manual, is a complete pro 
grammer s reference for X Toolkit (Xt). Xt is a library of C language routines 
designed to facilitate the design of user interfaces, with reusable components 
called widgets. This book covers the X Toolkit Intrinsics in depth and contains 

reference pages for the Athena widgets. Contents include: 

V" 
*\ 

Reference pages for each of the Xt Intrinsics and macros, organized 

alphabetically for ease of reference 

Reference pages for the Core, Compoaite^Constraint and Shell 
widget classes defined by Xt 

Reference pages for the function prototypes used to declare widget 
methods and other internal functions . 

X- 

Reference pages for the Athena widgets 

Permuted index 

Master index for Volumes Four and Five 

Numerous appendices and quick reference aids 

This book is designed to be used with Volume Four, X Toolkit Intrinsics 
Programming Manual, which describes how to build applications using the Xt 
Intrinsics and provides a complete tutorial with programming examples. 

One or more manuals in this series have been adopted by workstation 
manufacturers as their official X Window System documentation: Sun, Apollo, 
Silicon Graphics, Concurrent, Motorola, Stardent, Graphic Software Systems, 
Sony, Sequent, NCR, Intergraph, Pyramid, INTERACTIVE Systems, Inc., 
Locus, Megatek, CDC, BBN and Calcomp. Manuals in this series are also 
officially recommended by HP, SCO, IBM, Visual, Network Computing 
Devices, and sold through the Apple Programmers and Developers Association. 



558 pages Volume 5 alone ISBN: 0-937175-35-8 Set with Volume 4 ISBN: 0-937175-33-1 



O Reilly & Associates, Inc.