The Definitive Guides to the X Wi System Volume Five X Toolkit Insics Reference Manual for X Version 11 O'Reilly & Associates, Inc. IABRARY COl Volume Five X Toolkit Intrinsics Reference Manual for Version 11 of the X Window System Edited by Tim O'Reilly Introduction by Mark Langley O'Reilly & Associates, Inc. Table of Contents Page Preface ...................................................................................................................................... vii Chapter I Introduction ...................................................................................................... 1 Permuted Index .................................................................................................................... 19 Section 1: X Toolkit Intrinsics Functions and Macros ..................................... 37 Section 2: Prototype Procedures ............................................................................... 267 Section 3: Intrinsics-mandated Widget Classes ................................................. Section 4: Athena Widgets ........................................................................................... 355 Section 5: Appendices ..................................................................................................... 409 A Alphabetical and Group Summaries .......................................................................... 411 B X Toolkit Data Types ..................................................................................................... 423 C Event Reference ............................................................................................................. 435 D Standard Errors and Warnings ................................................................................... 491 E Resource File Format .................................................................................................... 497 F Translation Table Syntax .............................................................................................. 499 G StringDefs.h Header File .............................................................................................. 507 H Release Notes .................................................................................................................. 513 Master Index ........................................................................................................................ 519 Table of Contents v Preface About the X Toolkit The X Toolkit is the collective name for two C language subroutine libraries (Xt and Xaw) designed to simplify the development of X Window System applications using reusable com- ponents called widgets. Typical widgets include scrollbars, menus, dialog boxes, text-editing areas, drawing areas, etc. Each widget is made up of its own X window, but most of the work that goes on in that window has already been taken care of---all the application programmer has to do is assemble the widgets and write application-specific code that will be called in response to events in the widgets. The Xt library (the Intrinsics) consists of routines for using and building widgets. Widgets are defined using an object-oriented classing mechanism. The Xaw widget library is based on Xt and provides a small number of widgets that can be used to write simple application programs. The Xt Intrinsics are written using Xlib, the lowest level C language interface to the X Win- dow System. Both the Xt Intrinsics and Xlib are required by the X standard (established by the X Consortium) on any system that allows programming of X applications. Xaw was developed by MIT's Project Athena, and the acronym Xaw stands for Athena Widg- ets. Primarily, Xaw was designed as a simple demonstration and test of the Intrinsicsmnot as a complete set of widgets for writing demanding applications. There are numerous other widget sets provided by system vendors to implement particular user-interface styles. Most notably, HP has supplied a fairly extensive widget set (referred to as the HP Widgets) that is also provided on the MIT X release tape. In the future, though, the dominant widget set is likely to be one provided by OSF, as part of a product called OSF/Motif. Motif includes a widget set based on the I-IP Widgets and an extended version of the Intrinisics developed by Digital Equipment Corporation. There will also be widget sets that implement an AT&T user interface standard called OPEN LOOK. The X Toolkit Intrinsics will work the same way with any of these Xt-compatible widget sets. In fact, it is possible, though not always aesthetically or economically desirable, to combine widgets from different widget sets in the same application.* *Note that there are other X toolkits (note the lower-case "t" in "toolkits") that have nothing whatever to do with the X Toolkit (Xt), except that they have similar goals--namely, to make it easier to write standard X applications. These toolkits include Andrew (from Carnegie-Mellon University), InterViews (from Stanford), and Xview (from Sun). These are not merely different widget sets but are entirely different toolkits. They are not compatible with Xt. Preface vii About This Book This book is the fifth volume in the O'Reilly & Associates X Window System Series. It includes reference pages for each of the Xt Intrinsics functions, for useful macros and func- tion prototypes, for the base widget classes defined by the Intrinsics, and for the Athena Widgets. Reference pages are organized alphabetically for ease of access; a permuted index and numerous appendices and quick reference aids are also provided. Volumes Four and Five are designed to be used together. Volume 4 provides an explanation of the X Toolkit, including tutorial material and numerous programming examples. Arranged by task or topic, each chapter brings together a group of X Toolkit functions, describes the conceptual foundation they are based on, and illustrates how they are most often used in writ- ing applications. This volume is structured so as to be useful as a tutorial and also as a task- oriented reference. To get the most out of the examples in Volume Four, you will need the exact calling sequences of each function from Volume Five. To understand fully how to use each of the functions described in Volume Five, all but the most experienced Toolkit "hacker" will need the explanation and examples in Volume Four. Even though the Toolkit is intended to hide the low-level X interface provided by Xlib, there are times in writing widgets when Xlib functions will be necessary because no Xt feature exists to do the same thing. Volume Four describes the most common occasions for using Xlib but does not provide a reference to the particular functions involved. For that, see Vol- ume One, Xlib Programming Manual, and Volume Two, Xlib Reference Manual. How This Book is Organized Volume Five consists of reference pages for Toolkit functions. It also contains numerous helpful appendices. The book is organized as follows: Preface describes the organization of the book, and the conventions it follows. Chapter 1, Introduction, provides an overview of the functional areas the reference pages fall into. Permuted Index provides a standard UNIX ptx for all reference pages, regardless of section. Section 1, X Toolkit lntrinsics Functions and Macros, contains reference pages for the Intrinsics functions and macros. The header on each reference page states whether the function applies to using or building widgets, but all are organ- ized alphabetically. Section 2, Prototype Procedures, lists the prototypes used for declaring application callback routines, actions, widget methods, and other user-supplied func- tions. Section 3, lntrinsics-mandated Widget Classes, contains reference pages for the required widget classes--Core, Composite, Constraint, and Shell. viii X Toolkit Intrinsics Reference Manual Section 4, Appendix A, Appendix B, Appendix C, Appendix D, Appendix E, Appendix F, Appendix G, Appendix H, Master Index Athena Widgets, contains reference pages for the Athena widgets. Alphabetical and Group Summaries, provides quick reference tables that list each Intrinsics function alphabetically and by logical groups. X Toolkit Data Types, lists and explains, in alphabetical order, the struc- tures, enums and other typedefs used for arguments to Xt functions and macros. Event Reference, describes each event type in a reference page format. Each page includes information on how to select the events, when they are generated, the contents of the event structures, and notes on how to use them. Standard Errors and Warnings, lists the possible errors or warnings returned by the X Toolkit, along with their possible cause. Resource File Format, explains the EBNF syntax used the resource file. Translation Table Syntax, explains the EBNF syntax used the translation table. It discusses modifiers and event types. StringsDefs.h Header File, groups the identifiers found in StringDefs.h. Release Notes, summarizes the changes between these two releases. provides a thorough, combined index to Volumes Four and Five, making it easy to look up all the appropriate references to a topic, in either volume. Assumptions This book makes no assumptions about the reader's knowledge of object-oriented proam- ming or the X Window System. However, for many advanced topics, the reader will need to consult the earlier volumes in this series--Volume One, Xlib Programming Manual, and Volume Two, Xlib Reference Manual. Readers should be proficient in the C proamming language, although examples are pro- vided for infrequently used features of the language that are necessary or useful when pro- gramming with the X Toolkit. In addition, general familiarity with the principles of raster graphics will be helpful. Preface ix Bulk Sales Information This manual is being resold as the official X Window System documentation by many work- station manufacturers. For information on volume discounts for bulk purchase, call O'Reilly and Associates, Inc., at 800-338-6887 (in California, 800-533-6887), or send e-mail to linda@ora.com. For companies requiring extensive customization of the book, source licensing terms are also available. Obtaining the X Window System Software The X Window system is copyrighted but freely distributed. The only restriction this places on its use is that the copyright notice identifying the author and the terms of use must accom- pany all copies of the software or documentation. Thanks to this policy, the software is avail- able for nominal cost from a variety of sources. See Appendix G, Sources of Additional Information, in Volume Four, X Toolkit lntrinsics Programming Manual, for a listing of these sources. Acknowledgements As mentioned above, this manual is based in part on the Xt Toolkit lntrinsics---C Language Interface, by Joel McCormack, Paul Asente, and Ralph Swick, and on the X Toolkit Athena Widgets--C Language Interface, by Ralph Swick and Terry Weissman. We have done our best to incorporate all the useful information from these documents, while reorganizing them into alphabetical reference manual pages. We have clarified and expanded the descriptions of Intrinsics functions, added examples and cross references, and in general tried to make it useful for reference purposes. We would like to thank the authors of this document, and the X Consortium, for the copyright policy that allows others to build upon their work. Their generosity of spirit not only has made this book possible, but is the basis for the unparallelled speed with which the X Win- dow System has been adopted as a de facto standard. We would also like to thank the reviewers of the companion volume, X Toolkit Programming Manual. Even though they didn't directly review this book, their comments are often reflected in its pages. They were David Lewis and Peter Winston of Integrated Computer Solutions (ICS), Wendy Eisner of Sunquest Information Systems, Dan Heller of Island Graphics, Inc. (now working with O'Reilly and Associates), Miles O'Neal of Systems and Software Solutions, Inc., Chris Peterson of MIT Project Athena, and Ian Darwin of SoftQuad. Extra thanks are due to Ralph Swick and Chris Peterson, who answered many questions dur- ing the development of these books. Preface xi We are grateful to Sony Microsystems for the loan of a Sony NEWS workstation running their implementation of the X Window System. The speed and power of the Sony workstation, and the support of their staff, was a great help in developing these books. Additional devel- opment was done on a Sun-3 workstation running MIT's sample server, a Visual 640 X Dis- play Station, and an NCD16 Network Display Station. Mark Langley edited an early version of this book. He also authored the introduction to the current version and provided some of the examples on the reference pages. His help is greatly appreciated. Many staff members of O'Reilly and Associates assisted in producing this manual, particu- larly Donna Woonteiler, who coordinated the final production. The cover design is by Edie Freedman. Kathryn Ellis produced the master index. Other assistance came in many differ- ent forms from Daniel Gilly, Lenny Muellner, Linda Mui, Sue Willing, and Ruth Terry. Of course, we alone take responsibility for any errors or omissions that remain. --Tim O'Reilly xfi X Toolkit Intrinsics Reference Manual 1 Introduction The classic problem in constructing software manuals is how to resolve the conflicting needs of tutorial and reference. Over time, we have found that the alphabetical "man page"* approach of the UNIX Reference Manual has consistently made it the most accessible refer- ence manual we have ever used. However, as has often been pointed out by detractors of UNIX, this approach can make the manual impenetrable to a novice. We believe that the ideal solution is a programming manual/reference manual pair, in which the tutorial programming manual gives an understanding of the whole and the alphabetical reference manual supplies all of the additional details. However, in order to make this refer- ence manual more useful as a stand-alone document, we have also added a level of structure beyond alphabetization. First, the manual is divided into four major sections (plus appendices): the Xt Inlrinsics (and macros), function typedefs for widget methods and other internal routines, Inlrinsics- mandated widget classes, and the Athena widgets. Pages themselves are unnumbered; how- ever, cross-references to pages in other sections use the familiar UNIX parenthetical section notation--e.g., Core(3). Within the f'trst section, which includes Intrinsics function calls and macros, the page header indicates a general subject area for related routines. In this introduction, we have also provided a high-level discussion of various general topics, ranging from the Widget Lifecycle to Event Handling. Table 1-1 below associates various reference pages in Section 1 with the corresponding section in this introduction. In addition, the See Also section of each reference page refers back to the appropriate discussion in this introduction, as well as to relevant chapters in Volume Four, X Toolkit Intrinsics Program- ming Manual. *That is, manual pagcwor reference page, as we'll call it. Introduction I Table 1-1. Overview of the Intrinsics Introduction Topic Widget Lifecycle Classes and Subclasses Core, etc. Application Interface Events Using Wldgets XtCreateApplication- Shell XtCreateManaged- Widget XtCreateWidget XtDestroyWidget XtInitialize XtIsManaged XtIsRealized XtMainLoop XtManageChild XtManageChildren XtRealizeWidget XtUnmanageChild XtUnmanageChildren XtApplicationClass XtApplicationName XtClass XtCreateWidget XtIsSubclass XtSuperclass XtAddActions XtAddCallback XtAddCallbacks XtMergeArgLists XtOverrideCallback XtSetArg See also Resoue Management below Translations XtMainLoop Building Wldgets XtIsSubclass XtCallCallbacks XtHasCallbacks XtRemoveAllCallbacks XtRemoveCallback Function typedefs XtRemoveCallbacks XtExposeProc RemoveTimeOut XtAddEventHandler XtAddInput XtAddRawEvent- Handler XtAddTimeOut XtAppProcessEvent XtDispatchEvent XtHasInput XtNextEvent XtPeekEvent XtRemoveEvent- Handler XtRemoveInput XtRemoveRawEvent- Handler XtInitProc XtProc XtRealizeProc XtWidgetProc XtCallbackRec Event masks XEvent 2 X Toolkit Intrinsics Reference Manual Table 1-1. Overview of the Intrinsics (continued) Introduction Topic Translations and ctions Graphics Popups Resource Management Geometry Management Using Wldgets Xlib Interface MenuPopup MenuPopdown XtAddActions XtAugment- Translations XtOverride- Translations XtParseTranslation- Table MenuPopdown MenuPopup XtCallbackExclusive XtCallbackNone XtCallback- Nonexclusive XtCallbackPopdown XtCreatePopupShell XtPopdown XtPopup XtGetValues XtSetValues XtConfigureWidget XtMakeGeometryRequest XtMakeResizeRequest XtMoveWidget XtQueryGeometry XtResizeWidget XtResizeWindow XtUnmanageChild XtUnmanageChildren Building Wldgets XtDestroyGC XtGetGC XtReleaseGC XtMoveWidget XtNameToWidget XtAddConverter XtConvert XtDirectConvert XtGetApplication- Resources XtGetResources XtGetSubResources XtGetSubvalues XtStringConversion- Warning XtAddExposureToRegion Function typede XtActionProc XtDisplay XtScreen XtWindow XtSetValuesFunc Composite XtArgsProc Introduction 3 1.2 Classes and Subclasses The class mechanism allows X Toolkit programs to exploit object-oriented programming techniques. The widget is the basic object in the Toolkit; it is a template containing code and providing fields for data. In particular, a widget is defined by a class and instance structure. For more details on particular classes supplied with the X Toolkit, see Core, Composite, Con- straint, and Shell in Section 3 of this manual. For a detailed description of how widget class and instance structures are implemented, see Chapters 5 and 6 in Volume Four, X Toolkit lntrinsics Programming Manual. 1.3 Application Interface An application program can communicate with widgets in several ways. A widget makes certain state information available through resources, which an application can both read and write. A widget can also pass control back to an application to handle some designated event. When an application creates a widget, it passes an argument list of resources that specify how a widget is to do its job. These argument lists can be created statically or can be con- trolled at run time with XtSetArg. (To see a complete example of this, see Chapter 3, Other Widget Programming Techniques, in Volume Four, X Toolkit lntrinsics Programming Manual.) The application program can write selected values inside a widget instance by using xt- SetValues and can read values using XtGetValues. Using XtSetValues causes the widget to be notified of changes asynchronously through the Core set values -- method, so the widget can be assured of working with current data. These same resource mechanisms can be used analogously with nonwidget data, as well. (See XtSet- Subvalues and XtGetSubvalues.) 1.3.1 Callbacks A widget can return control to the application using Callbacks. Namely, by specifying a resource of type XtRCallback, an application can pass a list of procedures for the widget to invoke when certain things happen. (The types of events that result in a callback must be agreed upon between the widget and the application in advance.) The Intrinsics maintain callback lists in an internal format, so once a resource of type Xt- RCallback is passed to a widget, it cannot be accessed directly. To access callback lists, use one of the functions XtAddCallback, XtAddCallbacks, XtRemove- Callbacks, or XtRemoveAllCallbacks. The name of the resource for which the application can supply a callback list is often exported from the widget's public include file. If a widget has only one resource of type call- back, it will probably be called XtNcallback. 6 X Toolkit Intrinsics Reference Manual 1.6 Pop Ups A pop-up widget is a widget that bypasses geometry management and appears to pop up and pop down again when it is no longer needed. Pop ups are treated in detail in Chapter 12, Menus, Gadgets and Cascaded Pop Ups, in Vol- ume Four. Pop ups can be popped up or down as a result of a translation action (MenuPopup and MenuPopdown). They can also be popped up or down by specifying particular Intrinsics procedures in a callback list (namely, XtCallbackExclusive, XtCallback- Exclusive, XtCallbackNone, XtCallbackPopdown.) To use a pop up, first a shell must be created with XtCreatePopupShell. Then it can be popped up specifically using xtPopup or one of the aforementioned techniques. Any widget can have pop-up children: it does not need to be a subclass of Composite(3). Subsequently, the pop-up shell created with XtCreatePopupShell can be given its single normal child with XtCreateManagedWidget, specifying the pop-up shell as par- ent. It bypasses a widget's insert child method, even if it has one. A pop up can be spring-loaded so that it pops up as a result of a translation. A spring-loaded pop up invoked from a translation table already must exist at the time that the translation is invoked, so the translation manager can find the shell by name. Creating the pop-up shell and child in advance makes the user's act of popping up faster. Pop ups invoked expl'_'-citly with xtPopup or XtCallbackExclusive can be created as they are needed. Delaying the creation of the pop up is particularly useful when you pop up an unspecified number of them. The program does not have to create the shell until it is needed the first time, then after popping it down, it can preserve it until it is needed again. 1.7 Resources Resources are a list of name-value pairs. The X server has a set of the name-value pairs that can be used as defaults. The Intrinsics maintain name-value pairs in the same form in the widget structure. Using resources, an application can communicate with a widget and vice versa. Arguments to widgets are also passed as resources. The X Window System maintains a database of resources and their values on the server. Individual program execution may override the values obtained from the server's database for the context of the program's execution. xt r nit i a li z e sets up the original context for program execution. The routines XtSetValues and XtGetValues use a resource list to set and get widget state. The updating of resource values from the widget class and the resource database occurs transparently to the widget. The Intrinsics update the widget class structure before calling the widget's Initialize method. 8 X Toolkit Intrinsics Reference Manual Table 1-2. Overview of Resource Management Functions Procedure XtSetValues XtGetValues XtSetSubvalues XtGetSubvalues XtGetResourceList XtGetAppResources XtGetSubresources From ArgList Widget ArgLJst RList+Base Resource Manager Widget,ArgList Widget,ArgList Widget ArgList RList+Base ArgList Rnist (de) RList+Base RList+Base Used for/Lookup by Widget instance variables Nonwidget resources Default values By widget By name/class Each nction can be looked up sepately m understand e exact details of e routine. Routines to tch values of resources, le XtGetApplicationResources, accept a list of resources and a base poinmr. The portable and recommended way m access resources in a resource list is to decide a sucte that contains fields for values and to pass a pomr to is structe as e base address. Then xgoffseg can be used to demrmine e relative address of e field in the structure. Here is a short program that se up a resource gument list and accesses it. /* res.c - access application resources */ #include #include #include #include #include /* * fields to be filled in from resources * Note that instance variables must be defined as a pointer... -- */ typedef struct instance variables { -- -- String label; XFontStruct *font struct; -- long foreground; } instance variable rec, *instance variables; instance vriables nstanceVariabls; -- static XtResource resources[] = { { XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel), XtOffset(instance variables, foreground), -- XtRString, "XtDefaultForeground" }, { XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct *), XtOffset(instance variables, font struct), -- -- XtRString, "XtDefaultFont" }, 10 X Toolkit Intrinsics Reference Manual The XtRImmediate type indicates that the value in the default address field is the resource value itself, not a resource. For the Intrinsics to find and correctly handle callback lists, they should be declared with a resource type of XtRCallback. Whenever a widget contains a callback list for use by cli- ents, it also exports in its public .h file the resource name of the callback list. Applications and client widgets never access callback list fields directly. Instead, they always identify the desired callback list by using the exported resource name. The callback manipulation func- tions described here check that the requested callback list is implemented by the widget 1.7.4 Command Line Arguments Command line arguments given to a program can be used to set resource values. Any resource in a program can be accessed from the command line using the -xrm argument For example, in the above program to change label, the following would work: ride% cc res.c -iXt -IXll ride% a.out -xrm '*label: New Label String' The standard command line arguments are shown in Table 1-4. Table 1-4. Command Line Arguments Option -background -bd -bw -borderwidth -bordercolor -display -fg -fn -font -foreground -geometry -iconic -name -reverse -selectionTimeout -synchronous +synchronous -title -xrm Resource *background *background *borderColor .borderWidth .borderWidth *borderColor .display *foreground *font *font *foreground .geometry .iconic .name Value next argument next argument next argument next argument next argument next argument next argument next argument next argument next argument next argument next argument "on" next argument Sets background color background color border color width of border in pixels width of border in pixels color of border server to use foreground color font name font name foreground color size and position start as an icon name of application *reverseVideo *reverseVideo *reverseVideo .selectionTimeout .synchronous .synchronous .title vueofargument ' '0/I' ' "on" "off" Null "on" "off" next argument next argument reverse video reverse video No Reverse Video selection timeout synchronous debug mode synchronous debug mode title of application depends on argument Introduction 13 The Intrinsics also provide a scheme to improve the efficiency of Graphics Contexts. See also xt_.Got_.GC and Xl:Dosl:-oyGC. Examples using these functions are presented in Vol- ume Four. --Mark Langley 18 X Too/k# Intrinsics Reference Manual Permuted Index How to Use the Permuted Index The permuted index takes the brief descriptive string from the title of each command page and rotates (permutes) the string so that each keyword will at one point start the second, or center, column of the line. The beginning and end of the original string are indicated by a slash when they are in other than their original position; if the string is too long, it is trun- cated. To find the command you want, simply scan down the middle of the page, looking for a key- word of interest on the fight side of the blank gutter. Once you find the keyword you want, you can read (with contortions) the brief description of the command that makes up the entry. If things still look promising, you can look all the way over to the fight for the name of the relevant command page. The Permuted Index internal//compile an its descendants//'install all /'install a widget's /prototype procedure to /call a widget's XtResizeWindow: resize a widget MenuPopdown: built-in MenuPopup: built-in XtAppAddActions: declare an XtAddActions: register an procedure for registering /command button widget's/XtAddCallback: context/open, initialize, and procedures to a/XtAddCallbacks: list of managed/XtManageChild: [initialize a display and list of/XtManageChildren: XtAppCreateShell: create /create an dements to zero XtCalloc: accelerator table into its ............................ XtParseAcceleratorTable(1 ) accelerators from a widget and ................ XtInstallAllAccelerators(l) accelerators on another widget ................. XtInstallAccelerators(l) accept or reject keyboard focus ................ XtAcceptFocusProc(2) accept_focus procedure ............................ XtCallAcceptFocus(l) according to the values of its/ ................... XtResizeWindow(l) action for popping down a widget ........... MenuPopdown(1) action for popping up a widget ................ MenuPopup(l ) action table and register it/ ........................ XtAppAddActions(l) actaon table with the/ ................................. XtAddActions(l) action tables/prototype ............................ XtActionProc(2) activated by pointer click .......................... Command(4) add a callback procedure to a ................... XtAddCallback(l) add a display to an application ................. XtOpenDisplay(1) add a list of callback ................................. XtAddCaUbacks(l) add a widget to its parent's ....................... XtManageChild(l) add it to an application context ................ XtDisplayInitialize(l ) add widgets to their parent's .................... XtManageChildren(1) additional top-level widget ....................... XtAppCreateShell(l ) additional top-level widget ....................... XtCreateApplicationShetl(l) allocate an array and initialize .................. XtCalloc(l) Permuted Index 19 widget Core Widget for a/Constraint Widget in DEBUG mode, verify a widget's Xtclass: obtain a widget's method used in Core widget resource list (by name or procedure for a widget subclass of the Composite widget of the Constraint widget a subclass of the Shell widget a widget is a subclass of a to initialize data for a widget XtRemoveTimeOut: button activated by pointer /by the Intrinsics when another from an/XtcloseDisplay: an application context and pointer/commandWidgetclass: button activated by pointer/ widget methods XtWidgetProc: XtDestroyGC: Release 2 its/XtParseTranslationTable: into/XtParseAcceleratorTable: XtGetSelectionValue: obtain the called after a data transfer methods for geometry management a widget is a subclass of the /for ordering the children of to be called on fatal error to be called on fatal error to be called on nonfatal error to be called on nonfatal error to be called on fatal error to be called on nonfatal error to be called on nonfatal error to be called on nonfatal error provides data structures for a] a widget is a subclass of the /widget implementing list dynamically XtSetArg: /destroy an application /get the application remove it from an application /create an application and add it to an application add a display to an application XtMainLoop: scrollbarWidgetclass: widget to /perform resource /emit boilerplate string XtConvert: /prototype procedure called to /register a new resource /procedure passed as a resource /prototype of a resource register a new resource /register a case coordinates to//translate an x-y Class: fundamental, top-level ................... Core(3 ) Class: provides data structures ................. Constraint(3) class XtCheckSubclass: ........................... XtCheckSubdass(1) class ............................................................ Xtclass(1) class/prototype expose ............................ XtExposeProc(2) class)/update base-offset ......................... XtGetSubresources(1) class/prototype initialize ......................... XtInitProc(2) class/whether a widget is a ...................... XtlsComposite(1) class/a widget is a subclass ..................... XtlsConstraint(1) class/test whether a widget is .................. XtlsShell(1) class/determine whether .......................... XtlsSubclass(1) class/prototype procedure ....................... XtProc(2) clear a timeout value ................................. XtRemoveTimeOut(1) click/command ........................................ Command(4) client claims the selection ......................... XtLoseSelectionProc(2) close a display and remove it ................... XtcloseDisplay(1) close its displays/destroy ......................... XtDestroyApplicationContext(1) command button activated by .................. Command(4) commandWidgetclass: command ........... Command(4) common prototype procedure for ............ XtWidgetProc(2) compatible function to free up/ ................ XtDestroyGC(1) compile a translation table into ................ XtParseTranslationTable(1) compile an accelerator table ..................... XtParseAcceleratorTable(1) complete selection data ............................. XtGetSelectionValue(1) completes/prototype procedure .............. XtSelectionDoneProc(2) Composite Widget Class: defines ............ Composite(3) Composite widget class/whether ............ XtlsComposite(1) composite widget instances ...................... XtOrderProc(2) conditions/register a procedure .............. XtAppSetErrorHandler(1) conditions/register a procedure .............. XtAppSetErrorMsgHandler(1) conditions/register a procedure .............. XtAppSetWamingHandler(1) conditions./a procedure ........................... XtAppSetWamingMsgHandler(1) conditions/register a procedure .............. XtSetErrorHandler(1) conditions/register a procedure .............. XtSetErrorMsgHandler(1) conditions/register a procedure .............. XtSetWamingHandler(1) conditions /high-level procedure ............. XtSetWamingMsgHandler(1) Constraint Widget Class: .......................... Constraint(3) Constraint widget class/whether ............. XtlsConstraint(1) constraints on children .............................. Form(4) construct or modify an argument ............. XtSetArg(1) context and close its displays ................... XtDestroyApplicationContext(1) context for a given widget ........................ XtWidgetToApplicationContext(1) context/close a display and ..................... XtCloseDisplay(1) context ........................................................ XtCreateApplicationContext( 1 ) context/initialize a display ...................... XtDisplayInitialize(1) context/open, initialize, and .................... XtOpenDisplay(1) continuously process events ..................... XtMainLoop(l) control scrolling of viewing/ .................... Scrollbar(4) conversion and cache result ..................... XtDirectConvert(1) conversion error message ......................... XtStringConversionWaming(1) convert resource type ................................ XtConvert(1) convert the se of keysyms ..................... XtCaseProc(2) converter for an application ...................... XtAppAddConverter(1) converter of type XtRCallProc ................. XtResourceDefaultProc(2) converter procedure .................................. XtConverter(2) converter XtAddConverter: ..................... XtAddConverter(l) converter .................................................... XtRegisterCaseConverter(1) coordinate pair from widget ..................... XtTranslateCoords(l) 22 X Toolkit Intrinsics Reference Manual XtNumber: determine the XtGetGC: XtClass: XtSuperclass: multiple/XtGetSelectionValues: data XtGetSelectionValue: for/XtAppGetErrorDatabaseText: for an/XtGetErrorDatabaseText: XtAppGetErrorDatabase: XtGetErrorDatabase: a particular/XtDatabase: XtOffset: determine the byte display to an/XtOpenDisplay: /prototype procedure for ones/merge new translations, /transhte an x-y coordinate data structures for a widget's XtMakeGeometryRequest: request XtMakeResizeRequest: request widget XtParent: return the /remove a list of children from a a widget is managed by its children/add a widget to its children/add widgets to their /remove a widget from its of type//prototype procedure XtWorkProc: cache result XtDirectConvert: gripWidgetClass: attachment /command button activated by XtDisplay: return the display XtScreen: return the screen /translate a window and display callback/XtCallbackPopdown: /callback function to /callback function to /callback function to MenuPopdown: built-in action for MenuPopup: built-in action for XtCreatePopupShell: create a XtPopdown: unmap a XtPopup: map a /que a child widget's XtRemoveEventHandler: rcmove a XtAppAddTimeOut: invoke a XtSelectionDoneProc: prototype XtLoseSelectionProc: prototype case of/XtCaseProc: prototype XtInputCalibackProc: prototype selection data//prototype XtRealizeProc: prototype application/register a work XtInitProc: prototype initialize XtAddWorkProc: register a work XtStringProc: prototype method XtArgsProc: prototype children/XtOrderProc: prototype tables XtActionProc: prototype number of elements in a/ .......................... XtNumber(1) obtain a read-only, sharable GC ............... XtGetGC(1) obtain a widget's class .............................. Xtclass(1) obtain a widget's superclass ..................... XtSuperclass(1) obtain selection data in ............................. XtGetSelectionValues(1) obtain the complete selection ................... XtGetSelectionValue(1) obtain the error database text ................... XtAppGetErrorDatabaseText(1) obtain the error database text ................... XtGetErrorDatabaseText(1 ) obtain the error database ........................... XtAppGetErrorDatabase(1 ) obtain the error database ........................... XtGetErrorDatabase(1) obtain the resource database for ............... XtDatabase(1) offset of a field within a/ ........................... XtOffset(1) open, initialize, and add a ......................... XtOpenDisplay(1) ordering the childrcn of/ ........................... XtOrderProc(2) overwriting widget's existing ................... XtOverrideTranslations(1) pair from widget coordinates to/ .............. XtTranslateCoords(1) parent/Widget Class: provides ................ Con straint(3) parent to change child's/ ........................... XtMakeGeometRequest(1 ) parent to change child's size .................... XtMakeResizeRequest(l ) parcnt widget for the specified ................. XtParcnt(1) parent widget's managed list .................... XtUnmanageChildren(1) parcnt/determine whether ....................... XtlsManaged(1) parcnt's list of managed ............................ XtManageChild(1) parcnt's list of managed ............................ XtManageChildren(1) parcnt's managed list ................................ XtUnmanageChild(1) passed as a rcsource converter ................. XtResourceDcfaultProc(2) perform background processing .............. XtWorkProc(2) perform rcsource conversion and ............. XtDircctConvert(1) point for dragging other widgets .............. Grip(4) pointer click ............................................... Command(4) pointer for the specified widget ................ XtDisplay(1) pointer for the specified widget ................ XtScrcen(1) pointer into a widget instance ................... XtWindowToWidget(1) pop down a widget from a ........................ XtCallbackPopdown(1) pop up a widget ......................................... XtCallbackExclusive(1) pop up a widget ......................................... XtCallbackNone(1) pop up a widget ......................................... XtCallbackNonexclusive(1) popping down a widget ............................ MenuPopdown(1) popping up a widget .................................. MenuPopup(1) pop-up shell ............................................... XtCrcatePopupShell(1) pop-up shell ............................................... XtPopdown(1) pop-up shell ............................................... XtPopup(1) preferred geomet .................................... XQueGeometry(1) previously rcgistercd event/ ..................... XtRemoveEventHandler(1 ) procedurc after a specified/ ...................... XtAppAddTimeOut(1) procedure called after a data/ ................... XtSelectionDoneProc(2) procedure called by the/ ............................ XtLoseSelectionProc(2) procedure called to convert the ................ XtCaseProc(2) procedure called to handle file/ ................ XtInputCallbackProc(2) procedurc called when requested ............. XtSelectionCallbackProc(2) procedurc called when widget is/ ............. XtRealizeProc(2) procedure for a given ................................ XtAppAddWorkProc(1) procedure for a widget class ..................... XtInitProc(2) procedure for an application ..................... XtAddWorkProc(1) procedure for/ ............................................ XtStringProc(2) procedure for get_values_hook ................ XtArgsProc(2) procedure for ordering the ........................ XtOrderProc(2) procedure for registering action ............... XtActionProc(2) Permuted Index 29 table into its internal geometry XtMakeGeometryRequest: size XtMakeResizeRequest: /prototype procedure called when procedure to handle geometry XtResizeWidget: values of its/XtResizeWindow: XtConfigureWidget: move and/or result XtDirectConvert: perform application/register a new /prototype procedure passed as a XtConverter: prototype of a XtAddConverter: register a new XtDatabase: obtain the /update base-offset /update base-offset list/copy from base-offset /retrieve default values for a copy from ArgList to base-offset table and register it with the XtConvert: convert procedure to a widget's callback argument list XtGetValues: copy XtSetValues: copy Shell Widget Class: application XtBuildEventMask: resource/XtGetResourceList: application's/XtAppNextEvent: queue XtNextEvent: /prototype procedure to the specified widget XtDisplay: specified widget XtParent: the specified widget XtScreen: specified widget XtWindow: pair from widget coordinates to down a widget from a callback /widget for managing widget XtScreen: return the management viewportWidgetClass: control scrolling of viewing/ another//widget to control /an event handler without /procedure called when requested XtGetSelectionValues: obtain XtOwnSelection: indicate that XtDisownSelection: indicate that /prototype procedure to return /obtain the complete /get the current /get the current /set the htrinsics /set value of when another client claims the XtIsSensitive: check the current XtSetSensitive: set the XtAppSetSelectionTimeout: widget XtSetSensitive: XtSetSelectionTimeout: representation/a translation ..................... XtParseTranslationTable(1) request parent to change child's ............... XtMakeGeometryRequest(1) request parent to change child's ............... XtMakeResizeRequest(1 ) requested selection data arrives ................ XtSelectionCallbackProc(2) requests/prototype ................................... XtGeometryHandler(2) resize a child or sibling widget ................. XtResizeWidget(1) resize a widget according to the ............... XtResizeWindow(1) resize widget .............................................. XtConfigureWidget(1) resource conversion and cache ................ XtDirectConvert(1) resource converter for an .......................... XtAppAddConverter(1) resource converter of type/ ....................... XtResourceDefaultProc(2) resource converter procedure ................... XtConverter(2) resource converter ..................................... XtAddConverter(1) resource database for a/ ............................ XtDatabase(1 ) resource list (by application) .................... XtGetApplicationResources(1) resource list (by name or class) ................ XtGetSubresources(1) resource list to the argument .................... XtGetSubvalues(1) resource list ................................................ XtGetResourceList(1) resource list XtSetSubvalues: .................. XtSetSubvalues(1) Resource Manager/an action .................. XtAppAddActions(1) resource type ............................................. XtConvert(1 ) resource/add a callback ........................... XtAddCallback(1) resources from a widget to the ................. XtGetValues(1) resources from ArgList to widget ............ XtSetValues(1) resources linking window/ ........................ ShellO) retrieve a widget's event mask ................. XtBuildEventMask(l) retrieve default values for a ...................... XtGetResourceList(1) return next event from an ......................... XtAppNextEvent(l) return next event from input ..................... XtNextEvent(l) return selection data .................................. XtConvertSelectionProc(2) return the display pointer for .................... XtDisplay(1) return the parent widget for the ................ XtParent(l) return the screen pointer for ..................... XtScreen(l) return the window of the ........................... XtWindow(1) root coordinates/x-y coordinate .............. XtTranslateCoords(1) routine XtCallbackPopdown: pop ........... XtCailbackPopdown(1) row-column geometry ............................... List(4) screen pointer for the specified ................ XtScreen(1) scrollable widget for geometry ................. Viewport(4) scrollbarWidgetClass: widget to .............. Scrollbar(4) scrolling of viewing area in ...................... Scrollbar(4) selecting for the event ............................... XtAddRawEventHandler(l ) selection data arrives ................................. XtSelectionCallbackProc(2) selection data in multiple/ ......................... XtGetSelectionValues(1) selection data is available ......................... XtOwnSelection(1) selection data is no longer/ ....................... XtDisownSelection(1) selection data ............................................. XtConvertSelectionProc(2) selection data ............................................. XtGetSelectionValue(1) selection timeout value ............................. XtAppGetSelectionTimeout(1) selection timeout value ............................. XtGetSelectionTimeout(1) selection timeout ....................................... XtAppSetSelectionTimeout(l) selection timeout ....................................... XtSetSelectionTimeout(1) selection/by the Intrinsics ....................... XtLoseSelectionProc(2) sensitivity state of a widget ...................... XtIsSensitive(1) sensitivity state of a widget ...................... XtSetSensitive(1) set the Intrinsics selection/ ........................ XtAppSetSelectionTimeout(1) set the sensitivity state of a ....................... XtSetSensitive(1) set value of selection timeout .................. XtSetSelectionTimeout(1) 32 X TooAkit Intrinsics Reference Manual /set the Intrinsics selection set value of selection callback procedure invoked when Xtlnitiallze: initialize fmitiallze the X Core Widget Class: fundamental. /create additional /create an additional procedure called after a data prototype procedure to widget instance XtNameToWidget: pointer into/XtWindowToWidget: from widget/XtTranslateCoords: an action table with the internal//compile a widget's existing//merge new /nondestructively merge new /remove existing register a key registered keycode-to-keysym registered keycode-to-keysym XtMergeArgLists: merge XtConvert: convert resource for one instance of a data as a resource converter of XtPopdown: XtUnmapWidget: (by/XtGetApplicationResources: (by name or/XtGetSubresources: XtConvertCase: determine back to/XtRemoveGrab: redirect XtAddGrab: redirect map_when_managed//change the XtSetSelectionTimeout: set XtAddTimeOut: create a timeout the current selection timeout the current selection timeout XtRemoveTimeOut: clear a timeout /retrieve default /resize a widget according to the XtCheckSubclass: in DEBUG mode, upper-case and lower-case /geometry-managing widget for /widget to control scrolling of widget for geometry management geometry-managing widget for/ /call the installed high-level call the installed low-level call the installed high-level for low-level error and for high-level error and database text for an error or a database text for an error or a of its/XtResizeWindow: resize a fmstall all accelerators from a /the windows associated with a /redirect user input from modal geometry-managing box time.out ....................................................... XtAppSetSelectionTimeout(1) time.out XtSetSelectionTimeout: ............ XtSetSelectionTimeout(1) timeouts expire/prototype ....................... XtTimerCallbackProc(2) toolkit and display ..................................... Xtlnitiallze(1) Toolkit internals ......................................... XtToolkitInitialize(1) top-level widget ......................................... Core(3) top-level widget ......................................... XtAppCreateShell(1) top-level widget ......................................... XtCreateAppllcationShell(1 ) transfer completes/prototype .................. XtSelectionDoneProc(2) translate a key XtKeyProc: ...................... XtKeyProc(2) translate a widget name to a ..................... XtNameToWidget(1) translate a window and display ................ XtWindowToWidget(1) translate an x-y coordinate pair ................ XtTranslateCoords(1) Translation Manager/register .................. XtAddActions(1) translation table into its ............................. XtParseTranslationTable(1) translations, overwriting ........................... XtOverrideTranslations (1) translations with widget's/ ........................ XtAugmentTranslations(1) translations ................................................. XtUninstallTranslation s (1) translator XtSetKeyTranslator: ................ XtSetKeyTranslator(1) translator fmvoke the currently ................ XtTranslateKey(1) translator fmvoke the currently ................ XtTranslateKeycode(1 ) two ArgList structures ............................... XtMergeArgLists(1) type ............................................................. XtConvert(1) type XtNew: allocate storage ................... XtNew(1) type XtRCallProc/passed ........................ XtResourceDefaultProc(2) unmap a pop-up shell ................................ XtPopdown(1) unmap a widget explicitly ........................ XtUnmapWidget(1) update base-offset resource list ................ XtGetApplicationResources(1) update base-offset resource list ................ XtGetSubresources(1) upper-case and lower-case/ ...................... XtConvertCase(1) user input from modal widget .................. XtRemoveGrab(1) user input to a modal widget .................... XtAddGrab(1) value of a widget' s .................................... XtSeLMappedWhenManaged(1 ) value of selection timeout ......................... XtSetSelectionTimeout(1) value ........................................................... XtAddTimeOut(1) value/get ................................................... XtAppGetSelectionTimeout(1) value/get ................................................... XtGetSelectionTimeout(1) value ........................................................... XtRemoveTimeOut(1) values for a resource list ........................... XtGetResourceList(1) values of its core dimensions ................... XtResizeWindow(1) verify a widget's class ............................... XtCheckSubclass(1) versions of a keysym/determine ............. XtConvertCase(1) vertical Kles ................................................ VPaned(4) viewing area in another widget ................ Scrollbar(4) viewportWidgetclass: scrollable ............. Viewport(4) vPanedWidgetclass: ................................. VPaned(4) warning handler ......................................... XtAppWamingMsg (1) warning handler XtWaming: ................... XtWaming(1) warning handler XtWamingMsg: ............ XtWamingMsg(1) warning handlers/prototype .................... XtErrorHandler(2) waming handlers/prototype .................... XtErrorMsgHandler(2) warning/obtain the error .......................... XtAppGetErrorDatabaseText(1) waming/obtain the error .......................... XtGetErrorDatabaseText(1) widget according to the values ................. XtResizeWindow(1) widget and its descendants onto/ .............. XtInstaHA11Accelerators(1) widget and its descendants ....................... XtUnrealizeWidget(1) widget back to normal/ ............................. XtRemoveGrab(1) widget boxWidgetclass: .......................... Box(4) 34 X Toolkit Intrinsics Reference Manual resources linking window/Shell for geometry/Composite top-level widget Core structures for a/Constraint expose method used in Core initialize procedure for a is a subclass of the Composite is a subclass of the Constraint is a subclass of the Shell to initialize data for a /an x-y coordinate pair from Class: fundamental, top-level dialogWidgetclass: dialog Box XtUnmapWidget: unmap a viewportWidgetclass: scrollable geometry listWidgetclass: XtParent: return the parent /geometry-managing XtCallbackPopdown: pop down a list XtUnmanageChild: remove a /determine whether a on children/geometry-managing XtDestroyWidget: destroy a translate a widget name to a XtRealizeWidget: realize a and display pointer into a the children of composite /determine whether a XtIsComposite: test whether a XtsConstraint: test whether a Shell/XtIsShell: test whether a XtIsManaged: determine whether a /prototype procedure called when action for popping down a built-in action for popping up a common prototype procedure for XtNameToWidget: translate a XtMoveWidget: move a of viewing area in another widget to create a custom textWidgetclass: text-editing viewing/scrollbarWidgetclass: templateWidgetclass: string labelWidgetclass: XtMapWidget: map a managed/XtManageChild: add a /copy resources from a redirect user input to a modal create additional top-level callback function to pop up a callback function to pop up a callback function to pop up a move and/or resize /create an additional top-level create and manage a child create an instance of a pointer for the specified widget's accelerators on another Widget Class: application ......................... Shell(3) Widget Class: defines methods ................ Composite(3) Widget Class: fundamental ....................... Core(3) Widget Class: provides data ..................... Constraint(3) widget class/prototype ............................. XtExposeProc(2) widget class/prototype ............................. XtinitProc(2) widget class/whether a widget ................ XtIsComposite(1) widget class/whether a widget ................ XtIsConstraint(1) widget class/whether a widget ................ XtisShell(1) widget class/procedure ............................ XtProc(2) widget coordinates to root/ ....................... XtTranslateCoords(1) widget Core Widget .................................. Core(3) widget ......................................................... Dialog(4) widget explicitly ........................................ XtUnmapWidget(1) widget for geometry management ........... Viewport(4) widget for managing row-column ............ List(4) widget for the specified widget ................ XtParent(1) widget for vertical tiles ............................. VPaned(4) widget from a callback routine ................. XtCallbackPopdown(1) widget from its parent's managed ............ XtUnmanagcChild(1) widget has been realized ........................... XtIsRealized(1) widget implementing constraints ............. Form(4) widget instance .......................................... XtDestroyWidget(1) widget instance XNameToWidget: ........ XtNameToWidget(1) widget instance .......................................... XtRealizeWidget(1) widget instance/a window ....................... XtWindowToWidget(1) widget instances/for ordering ................. XtOrderProc(2) widget is a subclass of a class .................. XtIsSubclass(1) widget is a subclass of the/ ....................... XtIsComposite(1) widget is a subclass of the/ ....................... XtIsConstraint(1) widget is a subclass of the ........................ XtIsShell(1) widget is managed by its parent ............... XtIsManaged(1) widget is realized ....................................... XtRealizeProc(2) widget MenuPopdown: built-in ............... MenuPopdown(1) widget MenuPopup: ................................. MenuPopup(1) widget methods XtWidgetProc: .............. XtWidgetProc(2) widget name to a widget instance ............ XtNameToWidget(1) widget on the display ................................ XtMoveWidget(1) widget/to control scrolling ...................... Scrollbar(4) widget templateWidgetclass: .................. Template(4) widget ......................................................... Text(4) widget to control scrolling of ................... Scrollbar(4) widget to create a custom widget ............. Template(4) widget to display a non-editable .............. Label(4) widget to its display .................................. XtMapWidget(1) widget to its parent's list of ...................... XtManageChild(1) widget to the argument list ....................... XtGetValues(1) widget XtAddGrab: .................................. XtAddGrab(1) widget XtAppCreateShell: ....................... XtAppCreateShell(1) widget XtCallbackExclusive: .................. XtCallbackExclusive(1 ) widget. XtCallbackNone: ......................... XtCallbackNone(1) widget. XtCallbackNonexclusive: ........... XtCallbackNonexclusive(1) widget XtConfigureWidget: .................... XtConfigureWidget(1) widget ......................................................... XtCreateApplicationShell(1) widget XtCreateManagedWidget: ........... XtCreateManagedWidget(l) widget XtCreateWidget: ........................... XtCreateWidget(1) widget/retum the display ......................... XtDisplay(1) widget fmstall a ......................................... Xt/nstallAccelerators(1) Permuted Index 35 X Toolkit Intrinsics Functions and Macros This section contains alphabetically-organized reference pages for each lntrinsics function and macro. Each page contains a synopsis of the routine's calling sequence, its arguments, a description of its function, and a reference to related routines. Xt- Pop Ups (continued) MenuPopup MenuPopup gets to the application widget and cannot find a matching shell, it generates an error. See Also MenuPopdown, XtPopDown, XtPopup. X Toolkit Intrinsics Reference Manual 41 Xt- Callbacks (continued) XtAddCallback Callbacks differ from actions in the way that the registered function is invoked. For callbacks, the trigger is an abstract occurrence defined by the widget, which may or may not be event- related. The routines on a widget's callback lists are invoked by the widget code, using a call to XgCaZZCaZZbacks. Actions, on the other hand, are invoked directly by Xt, as the result of an event combination specified by the translations mechanism. Another major difference between an action function and a callback function is that action functions are called with an event as an argument, while actions do not have the c2ient daea or ca22 daea arguments present for callback functions. This means the __ -- only way to pass application data into an action function is through global variables. On the other hand, the presence of the event argument means that you can use the contents of the event structure in the action function. See Also Section 1.3, "Application Interface," Xt AddCa i iba c k s, Xt Ca 1 iCa 1 iba c k s, Xt RemoveAl iCa 1 iba c k s, Xt Remove- Cal iback, XtRemoveCallbacks, XtCa i ibac kP roc(2). X Toolkit Intrinsics Reference Manual 45 Xt - Callbacks (continued) XtAddCallbacks to XtCallCallbacks. Actions, on the other hand, are invoked directly by Xt, as the result of an event combination specified by the translations mechanism. Another major difference between an action function and a callback function is that action functions are called with an event as an argument, while actions do not have the client_data or call_data arguments present for callback functions. This means the only way to pass application data into an action function is through global variables. On the other hand, the presence of the event argument means that you can use the contents of the event structure in the action function. There are many cases where you might want to add more than one callback function to the same callback list. The use of XtCallbackExclusive et al. provides a good case in point. There are Intrinsics-defined callback functions that can be used to pop up a widget However, they do not place the pop up. To pop up a dialog box upon the press of a command button, you would typically add two call- back functions to the Command widget's XtNcallback list: one of the Intrinsics-supplied XtCallback* functions, and one of your own to place the pop up. One way to add more then one callback function is to call XtAddCallback more than once. Another way is to call XtAddCallbacks, which takes an XtCallbackRect array as an argument This array is usually initialized at compile time, as shown in the example below. The final NULL, NULL entry terminates the list. (This particular list registers the functions place_popup and XtCallbackExclusive and passes them both 0 as client_data.) XtCallbackRec quit_callback_list [] = { {place_popup, 0 } {XtCallbackExclusive, 0}, { (XtCallbackProc) NULL, (caddr t) NULL}, -- } This form of XtCallbackRec list can also be used to replace a callback list with XtSet- Values (but not to get a callback list, because Xt compiles the list into an internal form). Structures typedef struct XtCallbackRec* -- typedef struct XtCallbackRec { -- XtCallbackProc callback; caddr t client data; _ -- } XtCallbackRec, *XtCallbackList; XtCallbackList; See Also Section 1.3, "Application Interface," XtAddCallback, XtCallCallbacks, XtRemoveAllCallbacks, XtRemove- Callback, XtRemoveCallbacks, XtCa 1 ibackP ro c(2). X Toolkit Intrinsics Reference Manual 47 XtAddConverter Xt - Resource Management--- Name XtAddConverter B register a new resource converter. Synopsis void XtAddConverter (from_type, to_type, num_args) String from_type; String to_type; XtConverter converter; XtConvertArgList convert_args; Cardinal num_args; converter, convert_args, Arguments from_type to_type converter Specifies the source type of the resource to be converted. Specifies the destination type to which the resource is to be converted. Specifies the converter procedure. See xtConverter(2). convert_args Specifies how to obtain additional arguments needed for the conversion; if no arguments are provided, this should be NULL. See the Structures section below for a detailed description of the format of convere_args. n um_a rgs Specifies the number of additional arguments to the convener or zero. Description XtAddConverter obtains the default application context and invokes XtAppAdd- Converter. XtAddConverter is a simplified interface to XtAppAddConverter, and the calling sequences are identical, except that you do not need to specify an application con- text. Since most applications have only one application context, XtAddConverter does not require the application to pass app_context explicitly. See XtAppAddConverter for additional details. See xtConverter(2) for a description of the contents of a resource con- vener. Structures typedef struct { XtAddressMode address mode; caddr t address id; _ -- Cardinal size; } XtConvertArgRec, *XtConvertArgList; See Also Xt AppAddConve rt e r, Xt Co nve rte r(2). 48 X Toolkit Intrinsics Reference Manual XtAddGrab Xt - Pop Ups m Name XtAddGrab -- redirect user input to a modal widgeL Synopsis void XtAddGrab(w, exclusive, spring_loaded) Widget w; Boolean exclusive; Boolean spring_loaded; Arguments Specifies the widget to add to the modal cascade. excl usi ve Specifies whether user events should be dispatched exclusively to this widget or also to previous widgets in the cascade. spring_l oaded Specifies whether this widget was popped up because the user pressed a pointer button. Description XtAddGrab appends a widget to a modal cascade. Modal widgets are widgets that, except for the input directly to them, lock out user input to the application. XtAddGrab affects only Xt's event dispatching--it does not request a key or button grab on the server. When a modal menu or modal dialog box is popped up, user events (keyboard and pointer events) that occur outside the modal widget should be delivered to the modal widget or ignored. In no case should user events be delivered to a widget outside the modal widget. Menus can pop up submenus, and dialog boxes can pop up further dialog boxes to create a pop-up cascade. In this case, user events may be delivered to one of several modal widgets in the cascade. Display-related events should be delivered outside the modal cascade so that Expose events and the like keep the application's display up to date. Any event that occurs within the cascade is delivered as usual. The user events that are delivered to the most recent spring-loaded shell in the cascade when they occur outside the cascade are called remap events. These events are KeyPress, KeyRelease, ButtonPress, and ButtonRelease. The user events that are ignored whcn thcy occur outsidc thc cascadc arc MotionNotify, EnterNotify, and LeaveNotify. All other events are delivered normally. xtPopup uses the XtAddGrab and XtRemoveGrab functions to constrain user events to a modal cascade and subsequently to remove a grab when the modal widget goes away. Usually you should have no need to call them explicitly. XtAddGrab is called implicitly by Xt- CallbackExclusive and other calls. The XtAddGrab function appends the widget (and associated parameters) to the modal cas- cade and checks that exclusive is TRUE if spring_loaded is TRUE. If these are not both TRUE, XtAddGrab generates a warning and asserts an exc2 usive grab anyway. 52 X Toolkit Intrinsics Reference Manual Xt- Pop Ups (continued) XtAddGrab When the modal cascade holds at least one widget, XtDispatchEvent determines if the event should be delivered or held. It starts with the last cascade entry and follows the cascade till it finds the youngest cascade entry added with exc2 us_/ve TRUE. If it finds a widget in the cascade interested in the event, it delivers the event to it. This modal cascade, along with all descendants of the widgets it contains, comprise the active subset. User events that occur outside the widgets in this subset are ignored or remapped. Modal menus generally add pop-up submenus to the cascade with exc2 us_/ve set to FALSE, SO that the submenu can receive input event after it pops up. Modal dialog boxes that resa'ict user input to the most deeply nested dialog box add a subdialog widget to the cascade with excl usi ve set to TRUE. User events that occur within the active subset are delivered to the appropriate widget, which is usually a descendant of the modal widget. Regardless of where they occur on the display, redirected events are always delivered to the most recent widget in the active subset of the cascade that has spring_loaded TRUE, if any such widget exists. See Also XtCallbackExclusive, XtCreatePopupShell, XtDispatchEvent, XtPopup, XtRemoveGrab. X Toolkit Intrinsics Reference Manual 53 XtAddlnput Xt- Event Handling Name XtAddlnput -- register a new file as an input source for an application. Synopsis Xt Input Id XtAddInput (source, int source; caddr t condition; Xt InputCallbackProc proc; caddr t client data; condition, proc, client_data) Arguments source condition proc client data Specifies the source file descriptor (on a UNIX-based system) or other operating-system-dependent device specification. Specifies a mask that indicates a read, write, or exception condition or some operating-system-dependent condition. Specifies the procedure that is to be called when input is available. See Xt- Input Ca 1 ibac kP r oc(2). Specifies the argument to be passed to the specified procedure when input is available. Description XtAddInput obtains the default application context and invokes XtAppAddInput. Xt- AddInput is a simplified interface to XtAppAddInput, and except that you do not need to specify an application context, the calling sequences are identical. Since most applications have only one application context, XtAddTnput does not require the application to pass app_con t ext explicitly. While most applications are driven only by X events, some applications need to incorporate other sources of input. XtAppAddTnput allows an application to integrate notification of pending file data into the event mechanism. The application uses XtAppAddTnput tO regis- ter a file with the Intrinsics read routine. When I/O is pending on the file source, the regis- tered callback procedure proc is invoked, source is usually file input but can also be file output. (Note that "file" means any sink or source of data.) XtAppAddInput alSO specifies the condi ti on under which source can generate events. The legal values for condition are operating-system-dependent. On a UNIX-based system, the possible values are xt InputReadMask, Xt InputWriteMask, or Xt InputExcept- Mask. The masks cannot be ORed together. These limit the invocation of proc tO either a pending read, write, or exception condition on the source file. See the UNIX system select call for discussion of these conditions. Callback procedures that are used when there are file events are of type xt TnputCallback- Proc. 54 X Toolkit Intrinsics Reference Manual Xt- Event Handling (continued) XtAddlnput Note that when reading from a socket, you should be careful not to close the end of the socket that is waiting before exiting the XtHainr,oop. If you do this, you will get an infinite loop, in which the proc is called repeatedly, while the Intrinsics wait for an EOF to be read. See Chapter 8, More Input Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual, for a complete example using this function. See Also XtAppAddInput, XtRemoveInput, Xt InputCa llbackP roc(2). X Toolkit Intfinsics Reference Manual 55 Xt - Event Handling (continued) XtAd d RawEventHan die r See Also Sectionl.4,"Even," XtAddEventHandler, XtRemoveRawEventHandler, XtEventHandler(2). X Toolkit Intrinsics Reference Manual 57 --Xt- Event Handling XtAddWorkProc Name XtAddWorkProc -- register a work procedure for an application. Synopsis XtWorkProcId XtAddWorkProc (proc, client data) -- XtWorkProc proc; caddr t client data; Arguments proc Specifies the procedure to be called when the application is idle. client data Specifies the argument to be passed to the specified procedure when it is called. Description XtAddWorkProc obtains the default application context and invokes XtAppAddWork- Proc. It is a simplified interface to XtAppAddWorkProc. Since most applications have only one app_context, XtAddWorkProc does not require the application to pass an app_ c on t ex t explicitly. XtWorkProc(2) discusses the responsibilities of the application's background processing rou- tine. See Also XtAppAddWorkP roc, XtRemoveWorkP roc, XtWo rkP roc(2). X Toolkit Intrinsics Reference Manual 59 XtAppAddConverter Xt - Resource Management m Name XtAppAddConverter -- register a new resource converter for an application. Synopsis void XtAppAddConverter ( app_context, from_type, to_type, converter, convert_args, num_args) XtAppContext app_context ; String from_type; String to_type; XtConverter converter; XtConvertArgList convert_args; Cardinal num_args; Arguments app_context from_type t o_ type converter convert_args n um_a rgs Specifies the application context. Specifies the source type of the resource to be converted. Specifies the destination type to which the resource is to be converted. Specifies the converter procedure. See xtConverter(2). Specifies how to obtain additional arguments needed for the conversion; if no arguments are provided, this should be NUT.T.. See the Structures sec- tion below for a detailed description of the format of convert_args. Specifies the number of additional arguments to the converter or zero. Description Resource converters provide a general way to pass specific data structures, and to hide the details of the data structures themselves. Using XtAppAddConverter or XtAdd- Converter, an application can register a converter to transform data of a given type to another specified type. The types themselves are arbitrary, and are specified by a string. For example, the converter mechanism can convert data of type String to an application data type of Menu if the application has registered the appropriate converter; to the application, the data type Menu is opaque. Some converters need additional arguments, which can be obtained from fields within the widget or as constants. The enumerated type XtAddressMode and the structure Xt- ConvertArgRec specify how each argument is delved. The are defined in , as follows: typedef enum { /* address mode parameter representation */ XtAddress, /* address */ XtBaseOffset, /* offset */ XtImmediate /* constant */ XtResourceString XtResourceQuark } XtAddressMode; /* resource name string */ /* resource name quark */ 62 X Toolkit Intrinsics Reference Manual XtAppAddConverter (continued) Xt- Resource Management See Also XtAddConverter, XtDirectConvert, XtConverter(2). 64 X Toolkit Intrinsics Reference Manual XtAppAddlnput (continued) Xt- Event Handling See Also XtAddInput, XtRemoveInput, XtInputCallbackProc(2). 66 X Toolkit Intrinsics Reference Manual XtAppAddWorkProc Xt- Event Handling Name XtAppAddWorkProc -- register a work procedure for a given application. Synopsis XtWorkProcId XtAppAddWorkProc (app_context, proc, client data) XtAppContext app_context ; XtWorkProc proc; caddr t client data; Arguments app_context Specifies the application context that identifies the application. proc Specifies the procedure that is to be called when the application is idle. c2ient_data Specifies the argument to be passed to the specified procedure when it is called. Description Xt supports a limited form of background processing. Most applications spend most of their time waiting for input; to do useful work during this idle time, you can register a work proce- dure that will run when the application would otherwise block in XtAppNextEvent or Xt- AppP roces sEvent. XtAppAddWorkProc adds the specified proc for the application identified by app_context. XtWorkProcTd is an opaque identifier unique to this work procedure. Multiple work procedures can be registered, and the most recently added one is always the one that is called. However, if a work procedure itself adds another work procedure, the newly added one has lower priority than the current one. Passing the XtWorkProcId returned from the XtWorkProc to XtRemoveWorkProc causes proc tO stop being called. Work procedures are of type XtWorkProc. XtWorkProc discusses the responsibilities of the application's background processing routine. XtAddWorkProc is a simplified interface to this function. See Also Xt AddWo rkP roc, XtAppNext Event, XtAppP roce s s Event, Xt RemoveWo rkP roc, XtWorkProc(2). 68 X Toolkit Intrinsics Reference Manual m Xt - Initialization XtAppCreateShell Name XtAppCreateShell m create additional top-level widgeL Synopsis Widget XtAppCreateShell (application_name, application_class, widget_class, display, args, num_args) String application name; String application class; -- WidgetClass widget_class; Display *display; ArgList args; Cardinal num_args; Arguments application name Specifies the name of the application instance. If this argument is NULL, the application name passed to XtDisplayTnitialize is used. application class -- Specifies the class name of this application. widget_class Specifies the widget class that the application top-level widget should be (normally app i i c at i onS he i iWidget C i a s s). di spl ay args hum args -- Specifies the display from which to get the resources. Specifies the argument list in which to set in the WM_COMMAND property. Specifies the number of arguments in the argument list. Description An application can have multiple top-level widgets, which can potentially be on many different screens. An application uses XtAppCreateShell if it needs to have several independent windows. (A help system that stayed on the screen and could be moved and resized indepen- dently of the application is an example of such an independent top-level window.) The Xt- AppCreateShell function creates a top-level widget that is the root of a widget tree. application name and application class become the left-most components in all widget resource names for this new application. They are used for qualifying all subsequent widget resource specifiers. XtAppCreateShell should be used to create a new logical application within a program or to create a shell on another display. In the first case, XtAppCreateShell allows the specifi- cation of a new root in the resource hierarchy. If XtAppCreateShell is used to create shells on multiple displays, it uses the resource database associated with display. X Toolkit Intrinsics Reference Manual 69 Xt- Error Handling (continued) XtAppErrorMsg (XtAppWarning calls the corresponding non-fatal error handler. Xt AppWa rn ingMs g call the corresponding high-level handlers.) The Intrinsics internal errors all have class XtToolkitError. XtAppErrorMsg and See Also XtAppError, XtAppSetErrorHandler, XtAppSetErrorMsgHandler, XtAppSet- WarningHandler, XtAppSetWarningMsgHandler, XtAppWarning, XtApp- WarningMsg, XtError, XtErrorHandler, XtErrorMsg, XtErrorMsgHandler, XtSetErrorHandler, XtSetErrorMsgHandler, XtSetWarningHandler, XtSet- WarningMsgHandler, XtWarning, XtWarningMsg. X Toolkit Intrinsics Reference Manual 73 XtAppGetErrorDatabaseText (continued) Xt - Error Handling Intrinsics. The first four arguments to XtAppGetErrorDatabaseText () are just passed in from the XtErrorMsg ( ) call in XtMalloc ( ). The XtMalloc ( ) call assumes that the default error database (errorDB) has an error message for resource name allocError.malloc of class XtToolkitError. If not found, the default error message "Cannot perform malloc" will be used instead. You do not need to use this function unless you are writing an Xt error message handler of your own. char * XtMalloc(size) unsigned { size; char *ptr; if ((ptr = malloc(size)) == NULL) XtErrorMsg("allocError", "malloc", "XtToolkitError", "Cannot perform malloc", (String *) NULL, (Cardinal *) NULL); return (ptr); } void XtErrorMsg(name, type, class, defaultp, params, num_params) String name, type, class, defaultp; String *params; Cardinal *num_params; char buffer[1000], message[1000]; XtGetErrorDatabaseText(name, type, class, defaultp, buffer, I000); /* * Need better solution here, perhaps use lower-level * printf primitives? */ if (num_params == NULL) XtError(buffer); else { (void) sprintf(message, buffer, params[0], params[l], params[2], params[3], params[4], params[5], params[6], params[7], params[8], params[9]); XtDefaultError(message); -- } } static void XtDefaultError(message) String message; extern void exit(); 76 X Toolkit Intrinsics Reference Manual Xt - Error Handling (continued) XtAppGetErrorDatabaseText (void) fprintf(stderr, "X Toolkit Error: %s\n", message); exit(l); } void XtGetErrorDatabaseText(name, type, class, defaultp, buffer, nbytes) register char *name, *type, *class; char *defaultp; char *buffer; int nbytes; { XtAppGetErrorDatabaseText(_XtDefaultAppContext(), name, type, class, defaultp, buffer, nbytes, NULL); ) See Also XtAppGetErrorDatabase, XtGetErrorDatabase, XtGetErrorDatabaseText, XtErrorMsgHandler(2). X Toolkit Intrinsics Reference Manual 77 XtAppGetSelectionTimeout Xt - Selections m Name XtAppGetSelectionTimeout m get the current selection timeout value. Synopsis unsigned int XtAppGetSelectionTimeout(app_context) XtAppContext app_context; Arguments app_c on t ex t Specifies the application context. Description XtAppGet Se lect ionTimeout returns the current selection timeout value for the specified application context, in milliseconds. (XtGetSelectionTimeout performs the same func- tion for the default application context.) The selection timeout is the time within which the two communicating applications must respond to one another. The initial timeout value is set by the selectionTimeout application resource, or if selectionTimeout is not specified, it defaults to 5000 milliseconds (5 seconds). A new value can be set by a call to XtAppSet- SelectionTimeout or XtSetSelectionTimeout. See Also XtAppSetSelectionTimeout, XtGetSelectionTimeout, XtSetSelection- Timeout. 78 X Toolkit Intrinsics Reference Manual XtAppNextEvent Xt - Event Handling B Name XtAppNextEvent -- return next event from an application's input queue. Synopsis void XtAppNextEvent(app_context, XtAppContext app_context; XEvent *event return; -- event_ret urn) Arguments app_context event return Specifies the application context that identifies the application. Returns the event information from the dequeued event structure. Description If a server has queued an event for the specified application, XtAppNextEvent removes the event from the queue and returns it to the caller. If there are no events in the X input queue, XtAppNextEvent flushes the X output buffer and waits for an event from the X server or auxiliary input sources or for a timeout value to expire. If a timer pseudo-event or auxiliary input event occurs, XtAppNextEvent dispatches the designated callbacks. When an X event occurs, XtAppNextEvent removes it from the queue and returns it. The events returned by XtAppNextEvent should be dispatched with Xt- DispatchEvent. XtAppNextEvent dispatches XtWorkProcs and XtTimer- CallbackProcs dectly that are registered for app_context. See XtAppAddWork- Proc and XtAppAddTimeOut. XtAppNextEvent blocks until an event occurs. An application can instead use this wait time by interleaving background processing with calls to XtAppPending. Programs rarely need this much control over the event dispatching mechanism. Most programs use XtAppMainLoop or XtMainLoop. See Also XtAppAddWorkProc, XtAppMainLoop, XtAppPeekEvent, XtAppPending, XtApp- ProcessEvent, XtDispatchEvent, XtMainLoop, XtNextEvent, XtWorkProc. 80 X Toolkit Intrinsics Reference Manual -- Xt - Event Handllng XtAppPeekEvent Name XtAppPeekEvent -- nondestructively examine the head of an application's input queue. Synopsis Boolean XtAppPeekEvent ( app_context, event_return) XtAppContext app_context; XEvent *event return; Arguments app_ c on t ext Specifies the application context that identifies the application. event return Returns the event information from the head event structure in the queue. Description XtAppPeekEvent returns the value from the head of a given application's event queue with- out removing the value from the queue. If a server has queued an event for the application, XtAppPeekEvent fills in the event and returns a nonzero value. It returns TRUE if the event returned is an X event and FALSE other- wise (i.e., if it is a Timer or alternate input event). If there is no X event in the queue, XtAppPeekEvent flushes the output buffer and waits for an event from the X server or auxiliary input sources or for a timeout value to expire. If timer pseudo-events expire, it dispatches them itself, the same way XtAppNextEvent does. If the input is an event, XtAppPeekEvent fills in the event and returns a nonzero value. Other- wise, if input is from an alternate input source, XtAppPeekEvent returns NULL for the event. Programs rarely need this much control over the event dispatching mechanism. Most programs use XtAppMainLoop or XtMainLoop. However, all event sources depend on idle time in the application to return XtMainLoop where Xt can check to see if input is available from any of the various sources. If an applica- tion has long calculations to make, the progrm may not return to XtMainLoop frequently enough to detect important input in a timely fahsion. The application itself should, if possible, suspend important calculations for a moment to check whether input is available. Then it can determine whether to process the input before continuing or finish the calculation. To detect whether input from any input source is available, you can call XtPending. To find out what the first event in the queue contains, you can call XtPeekEvent. This func- tion returns an event structure without removing the event from Xlib's queue. It is also possible to remove and process a single evenL XtProcessEvent combines some (but not all) of the functions from XtNextEvent and XtDispatchEvent. That is, while XtNextEvent takes the next event from the queue, whatever it is, XtProcessEvent allows you to specify as a mask a bitwise OR of the symbolic constants XtIMXEvent, Xt- rMTimer, and XtIMAlternateInput. This lets you select only some of these event types X Toolkit Intn'nsics Reference Manual 81 XtAppPeekEvent (continued) Xt- Event Handling for processing. In addition, XtProcessEvent actually calls XtDispatchEvent to dis- patch X events, so only this one call is necessary. See Also XtAppMainLoop, XtAppNextEvent, XtAppPending, XtAppProcessEvent, Xt- DispatchEvent, XtPeekEvent. 82 X Toolkit Intrinsics Reference Manual XtAppProcessEvent Xt - Event Handling m Name XtAppProcessEvent m process one input event. Synopsis void XtAppProcessEvent(app_context, mask) XtAppContext app_context; XtInputMask mask; Arguments app_context Specifies the application context for which to process input. mask Specifies what types of events to process. The mask is the bitwise inclusive OR of XtTMXEvont (X event), XtTHTiraor (timer events), or Xt- IMAlternateInput (alternate input events). The symbolic name Xt- IMAll is the bitwise inclusive OR of all event types. Description While most widgets will use the Resource Manager to handle events, the X Toolkit does pro- vide a mechanism for widgets or application code to handle X events directly. Every client interested in X events on a widget uses XtAddEventHandler to register which events it is interested in and a procedure (event handler) that is to be called when the event happens in that window. The handler can then use XtAppProcessEvent to actually handle the events. XtAppProcessEvent processes an X event, a timer event, or an alternate input event. If there is nothing to process, XtAppProcessEvent blocks until there is. If there is more than one type of event available, the one that will get processed is undefined. XtAppProcessEvent processes timer events and alternate input events by calling the appropriate callbacks, the same way XtAppPeekEvent and XtAppNextEvent do. Xt- AppProcessEvent calls XtDispatchEvent tO handle X events. When an X event is received, it is passed to XtDispatchEvent, which calls the appropriate event handlers and passes them the widget, the event, and client-specific data registered with each procedure. If there are no handlers registered for that event, the event is ignored and the dispatcher simply returns. The order in which the handlers are called is undefined. Programs rarely need this much control over the event dispatching mechanism. Most programs use XtAppMainLoop. See Also Section 1.5, "Translations and Actions," XtAppMainLoop, XtAppNextEvent, XtAppPeekEvent, XtAppPending, Xt- DispatchEvent, XtProcessEvent. 84 X Toolkit Intrinsics Reference Manual XtAppSetErrorMsgHandler Xt- Error Handling m Name XtAppSetErrorMsgHandler -- register a procedure to be called on fatal error conditions. Synopsis void XtAppSetErrorMsgHandler (app_context, msg_handler) XtAppContext app_context; XtErrorMsgHandler msg_handl er; Arguments app_context Specifies the application context. msf_handler Specifies the new fatal error message handling procedure, which should not return. Description The default error handler provided by the Intrinsics constructs a string from the error resource database (see XtAppGetErrorDatabase) and cIs XtError. Using XtAppSetErrorMsgHandler (or XtSetErrorMsgHandler), you can replace the default handler with one of your own. Note that if you simply want to change the way the message is displayed (rather than the way the message database is used), you should probably replace the low-level error handler (using XtAppSetErrorHandler) instead. Fatal error message handlers should not return. If one does, subsequent X Toolkit behavior is undefined. See XtErrorMsgHandler(2) for details. Note that application-context-specific error handling is not implemented on many systems. Most implementations will have just one set of error handlers. If they are set for different application contexts, the one performed last will prevail. See Also XtAppError, XtAppErrorMsg, XtAppSetErrorHandler, XtAppSetWarning- Handler, XtAppSetWarningMsgHandler, XtAppWarning, XtAppWarningMsg, XtError, XtErrorHandler, XtErrorMsg, XtErrorMsgHandler, XtSetError- Handler, XtSetErrorMsgHandler, XtSetWarningHandler, XtSetWarningMsg- Handler, XtWarning, XtWarningMsg. 86 X Toolkit Intrinsics Reference Manual XtAppWarningMsg (continued) Xt - Error Handling (XtAppWarning calls the corresponding non-fatal error handler. XtAppErrorMsg and Xt AppWa rn ingMs g call the corresponding high-level handle.) See Also XtAppError, XtAppErrorMsg, XtAppSetErrorHandler, XtAppSetErrorMsg- Handler, XtAppSetWarningHandler, XtAppSetWarningMsgHandler, XtApp- Warning, XtError, XtErrorHandler, XtErrorMsg, XtErrorMsgHandler, Xt- SetErrorHandler, XtSetErrorMsgHandler, XtSetWarningHandler, XtSet- WarningMsgHandler, XtWarning, XtWarningMsg. 92 X Toolkit Intrinsics Reference Manual XtBuildEventMask (continued) Xt- Event Handling Event Mask Symbol ExposureMask VisibilityChangeMask StructureNotifyMask ResizeRedirectMask SubstructureNotifyMask SubstructureRedirectMask FocusChangeMask PropertyChangeMask ColormapChangeMask OwnerGrabButtonMask Circumstances Any exposure (except GraphicsExpose and NoExpose) Any change in visibility Any change in window configuration. Redirect resize of this window Notify about reconfiguration of children Redirect reconfiguration of children Any change in keyboard focus Any change in property Any change in colormap Modifies handling of pointer events See Also Section 1.4, "Events," Section 1.5, "Translations and Actions," Xt AddEvent Handle r, Xt AddRawEvent Handle r, XtRea i i zeWidget. 96 X Toolkit Intrinsics Reference Manual -- Xt - Keyboard Handling XtCallAcceptFocus Name XtCallAcceptFocus -- call a widget's accept_focus procedure. Synopsis Boolean XtCallAcceptFocus (w, time) Widget w; Time *time; Arguments time Specifies the widget. Specifies the X time of the event that is causing the accept focus. Description XtCallAcceptFocus calls the specified widget's accept_focus method, passing it the specified widget and time, and rettLrns whatever the accept_focus method returns. If the accept_focus procedure is NULL, XtCallAcceptFocus returns FALSE. XtCallAcceptFocus does not actually set the keyboard focus; it is used to determine if the widget would take the focus if offered. XtSetKeyboardFocus and the Xlib function XSetInputFocus actually pass the focus to a child. The accept_focus method is part of the Core class structure. See Also XtSetKeyboardFocus, XtAcceptFocusProc(2). X Toolkit Intrinsics Reference Manual 97 Xt - Pop Ups (continued) XtCallbackExclusive The callback list cb in Args is an argument to a widget. When the widget invokes XtCall- Callbacks on its XtNcallback resource, the polu p shell pshell will be popped up. A companion example to the one above is prentcd on XtCallbackPopdown. See Also Sdon 1.6, "Pop Ups," XtCallbackNone, XtCallbackPopdown, XtCallCallbacks, XtMoveWidget, Xt- Popdown, XtPopup, XtSetSensitive. X Toolkit Intrinsics Reference Manual 99 Xt- Pop Ups (continued) XtCallbackPopdown When the widget invokes XtCallCallbacks on its resource XtNCallback, the pop-up shell pshell will be popped down. See the companion example in XtCallback- Exc lu s ire. See Also Section 1.6, "Pop Ups," XtCallbackExclusive, XtCallCallbacks, XtPopdown, XtSetSensitive. X Toolkit Intrinsics Reference Manual 103 -- Xt - Memory Allocation XtCalloc Name XtCalloc B allocate an array and initialize elements to zero. Synopsis char *XtCalloc(num, size) ; unsigned int num; unsigned int size; Arguments num size Specifies the number of array elements to allocate. Specifies the size of an array element in bytes. Description XtCalloc allocates space for the specified number of array elements of the specified size and initializes the space to zero. If there is insufficient memory to allocate the new block, xt- Calloc terminates by calling Xt:ErrorMsg. xtCaZZoc differs from Xt:HaZZoc in that it stores zero in all the array elements. The function xtcalloc is implemented by the Toolkit independently of the particular envi- ronment, so programs ported to a system not supporting caZloc will still work. xtNew and xtNewSt ring provide slightly higher-level approaches to memory allocation. See Also XtErrorMsg, XtFree, XtMalloc, XtNew, XtNewSt ring, XtRealloc. X Toolkit Intrinsics Reference Manual 105 XtCheckSubclass Xt - Widget Information Name XtCheckSubclass m in DEBUG mode, verify a widget's class. Synopsis void XtCheckSubclass(w, widget_class, message) Widget w; WidgetClass widget_class; String message; Arguments w wi dget_class message Specifies the widget. Specifies the widget class to test against. Specifies the message to be used. Description XtCheckSubclass determines if widget w belongs to a subclass of the specified widget_class. (Note that two widgets of the same class belong to mutual subclasses.) The widget can be any number of subclasses removed and need not be an immediate subclass of the specified widget class. If the w is not a subclass, XtCheckSubclass constructs an error message from the supplied message, the widget's actual class, and the expected class, and it calls XtErrorMsg. XtCheckSubclass should be used at the entry point of exported routines to ensure that the client has passed in a valid widget class for the exported operation. XtCheckSubclass is a macro. It is only executed when the widget has been compiled with the compiler symbol DEBUG defined; otherwise, it is defined as the empty string and generates no code. XtCheckSubclass uses the Core widget data structures to perform its checking. See Also XtClass, Xt IsSubclass, XtSuperclass, Core(3). 106 X Toolkit Intrinsics Reference Manual XtConflgureWldget (continued) Xt - Geometry Management If a class need not recalculate anything when a widget is resized, it can specify NULL for the resize field in its class record. This is an unusual case and should occur only for widgets with very trivial display semantics. The resize method takes a widget as its only argument. See Also Stion 1.8, 'Geometry Management," XtMakeGeometryRequest, XtMakeResizeRequest, XtMoveWidget, XtResize- Widget, XtTranslateCoords. 110 X Toolkit Intn'nsics Reference Manual XtConvertCase Xt- Keyboard Handling m Name XtConvertCase m determine upper-case and lower-case versions of a keysym. Synopsis void XtConvertCase (display, keysym, Display *display; KeySym keysym; KeySym *lower_return; KeySym * upper_return; lower return, upper_re t urn ) Arguments di spl ay keysym lower return -- upper_re t u rn Specifies the display that the keysym came from. Specifies the keysym to convert. Returns the lower-case equivalent of the keysym. Returns the upper-case equivalent of the keysym. Description XtConvertCase is used to determine upper-case and lower-case equivalents for a keysym. It calls the case converter that is currently registered to convert those keysyms and returns the results. This procedure can perform application-specific shifting of characters A user-supplied XtKeyProc may need to use this function. XtRegisterCaseConverter can be used to register a new case converter. For a more detailed discussion of processing keyboard input, see Chapter 13, Miscellaneous Toolkit Programming Techniques, in Volume Four, X Toolkit lntrinsics Programming Manual. See Chapter 9, The Keyboard and the Pointer, in Volume One, Xlib Programming Manual, for more information on keysyms. See Also XtRegisterCaseConverter, XtSetKeyTranslator, XtTranslateKey, Xt- TranslateKeycode, XtCaseProc(2),XtKeyProc(2). 114 X Toolkit Intrinsics Reference Manual  Xt - Application Contexts XtCreateApplicationContext Name XtCreateApplicationContext m create an application context. Synopsis XtAppContext XtCreateApplicationContext() Description XtCreateApplicationContext returns an application context, which is an opaque type. Every application must have at least one application context. XtInitialize creates a default application context. XtInitialize is a simplified interface to XtToolkitInitialize, XtCreate- ApplicationContext, XtDisplayInitialize, and XtAppCreateShell; if it is not used, all four of these routines must be called. Routines that use an implicit context (like XtMainLoop and XtAddTimeOut) depend on the default context created by XtTnitialize. You cannot use these routines if you initialize a specific application context. Structures /. * Data structure for setting window attributes. ./ typedef struct { Pixmap background_pixmap; unsigned long background_pixel; Pixmap border_pixmap; unsigned long border_pixel; int bit_gravity; int win_gravity; int backing_store; unsigned long backing_planes; unsigned long backing_pixel; Bool save under; -- long event mask; -- long do_not_propagate_mask; Bool override redirect; -- Colormap colormap; Cursor cursor; } XSetWindowAttributes; /* pixmap, None, or ParentRelative */ /* background pixel */ /* pixmap, None, or CopyFromParent */ /* border pixel value */ /* one of bit gravity values */ /* one of the window gravity values */ /* NotUseful, WhenMapped, Always */ /* planes to be preseved if possible */ /* value to use in restoring planes */ /* should bits under be saved (pop ups) */ /* set of events that should be saved */ /* set of events that should not propagate */ /* override redirected config request */ /* colormap to be associated with window */ /* cursor to be displayed (or None) */ /* Definitions for valuemask argument of CreateWindow and ChangeWindowAttributes */ #define CWBackPixmap #define CWBackPixel #define CWBorderPixmap #define CWBorderPixel #define CWBitGravity #define CWWinGravity #define CWBackingStore #define CWBackingPlanes #define CWBackingPixel (IL<<0) (IL< #include #include #include #include /* * fields to be filled in from resources * Note that instance variables must be defined as a pointer... -- */ typedef struct instance variables { -- -- String label; XFontStruct *font struct; -- long foreground; } instance variable rec, *instance variables; -- _ -- instance variables InstanceVariables; -- static XtResource resources[] = { { XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel), XtOffset(instance variables, foreground), -- XtRString, "XtDefaultForeground" ), { XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct *), XtOffset(instance variables, font struct), XtRString, "XtDe faultFont" ), { XtNlabel, XtCLabel, XtRString, sizeof(String), XtOffset(instance variables, label), -- XtRString, "Default Label" ), ); Arg args[] = { XtNlabel, (XtArgVal) "Stuff", ); main(ac, av) int ac; char **av; { Widget toplevel; 142 X Toolkit Intrinsics Reference Manual XtGetErrorDatabase Xt- Error Handling-- Name XtGetErrorDatabase m obtain the error database. Synopsis XrmDatabase *XtGetErrorDatabase () Description Xt's high-level error and warning message handlers use a resource-like database for storing error messages. On UNIX-based systems, the database is usually stored in the file lusrlliblX111XtErrorDb. The XtGotErrorDatabaso function returns the address of the error database. The Intrinsics do a lazy binding of the error database and do not read in the database file until the first call to XtGetErrorDatabaseText. For a complete listing of all errors and warnings that can be generated by the Intrinsics, see Appendix D. Structures The type XrmDatabase is opaque and should not be manipulated directly. The return value can be manipulated with the Xlib functions XrmPutResource, XrmQPutResource, Xrm- GetResource, XrmQGetResource. See Also XtAppGetErrorDatabase, XtAppGetErrorDatabaseText, XtDatabase, XtGetErrorDatabaseText, XtErrorMsgHandler(2). 144 X Toolkit Intrinsics Reference Manual XtGetGC Xt- Graphics Context-- Name XtGetGC D obtain a read-only, shamble GC. Synopsis GC XtGetGC(w, value_mask, values) Widget w; XtGCMask value mask; -- XGCValues *values; Arguments value mask values Specifies the widget with which the GC is to be associated. Specifies which fields of the GC are to be filled in with widget data. Returns the actual values for this GC. Description The Inlrinsics provide a mechanism whereby cooperating clients can share a graphics context (GC), thereby reducing both the number of GCs created and the total number of server calls in any given application. The mechanism is a simple caching scheme, and all GCs obtained by means of this mechanism must be treated as read-only. If a changeable GC is needed, the Xlib XCreateGC function should be used instead. The XtGetGC function returns a shamble, read-only GC. The parameters to this function are the same as those for XCreateGC except that a widget is passed instead of a display. XtGetGC shares only GCs in which all values in the GC are the same. In particular, it does not use the value mask provided to determine which fields of the GC a widget considers rele- -- vant. val ue_mask is used only to tell the server which fields should be filled in with widget data and which it should fill in with default values. For a more rigorous account of GCs, see Volume One, Xlib Programming Manual. Structures typedef unsigned long XGCMask; /* Mask of values that are used by widget*/ typedef struct { int function; /* logical operation */ unsigned long plane_mask; /* plane mask */ unsigned long foreground; /* foreground pixel */ unsigned long background; /* background pixel */ int line width; /* line width */ -- int line_style; /* LneSolid, LineOnOffDash, LineDoubleDash */ int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */ int join_style; /* JoinMiter, JoinRound, JoinBevel */ int fill_style; /* FillSolid, FillTiled, FillStippled, FillOpaqueStippled */ int fill rule; /* EvenOddRule, WindingRule */ -- int arc mode; /* ArcChord, ArcPieSlice */ -- 146 X Toolkit Intrinsics Reference Manual Xt - Graphics Context (continued) XtGetGC Pixmap tile; Pixmap stipple; int ts x origin; int ts_y_origin; Font font; int subwindow_mode; Bool graphics_exposures; int clip_x_origin; int clip_y_origin; Pixmap clip_mask; int dash offset; char dashes; } XGCValues; /* tile pixmap for tiling operations */ /* stipple 1 plane pixmap for stipping */ /* offset for tile or * stipple operations */ /* default text font for text operations */ /* ClipByChildren, IncludeInferiors */ /* should exposures be generated? */ /* origin for clipping */ /* bitmap clipping; other calls for rects */ /* patterned/dashed line information */ See Also XtReleaseGC X Toolkit Intrinsics Reference Manual 14 7 XtGetSelectionTimeout Xt - Selectlons  Name XtGetSelectionTimeout m get the current selection timeout value. Synopsis unsigned int XtGetSelectionTimeout() Description XtGetSelectionTimeout returns the current value of the selection timeout in mil- liseconds. The default value is 5000 milliseconds (five seconds). The selection timeout is the time within which the two communicating applications must respond to one another. If one of them does not respond within this interval, the Intrinsics abort the selection request. Chapter 10, Inter-Client Communications, in Volume Four, X Toolkit Intrinsics Programming Manual, presents a complete example widget that both sends and receives data using selection. See Also Xt Set Select ionTimeout 150 X Toolkit Intrinsics Reference Manual Xt - Selections (continued) XtGetSelectionValues Chapter 10, Inter-Client Communications, in Volume Four, X Toolkit lntrinsics Programming Manual, presents a complete example widget that both sends and receives data using selection. See AIso XtGetSelectionValue, XtOwnSelection, XtSelectionCallbackProc(2). X Toolkit Intrinsics Reference Manual 153 XtG etSu b resou rces Xt- Resource Management Name XtGetSubresources -- update base-offset resource list (by name or class). Synopsis void XtGetSubresources(w, base, name, class, num_resources, args, num_args) Widget w; caddr t base; -- String name; String class; XtResourceList resources; Cardinal num resources; ArgList args ; Cardinal num_args; resources, Arguments base name class resources Specifies the widget that wants resources for a subpart. Specifies the base address of the subpart data structure where the resources should be written. Specifies the name of the subpart. Specifies the class of the subpart. Specifies the resource list for the subpart. num resources -- Specifies the number of resources in the resource list. a rgs Specifies the argument list tO override resources obtained from the resource database. num._args Specifies the number of arguments in the argument list. Description A widget does not do anything to get its own resources; instead, XtCreateWidget does this automatically before calling the class initialize procedure. However, some widgets have subparts that are not widgets but for which the widget would like to fetch resources. For example, the Athena Text widget fetches resources for its source and sink. Such widgets call XtGetSubresources to accomplish this. XtGetSubresources constructs a name or class list from the application name or class, the names or classes of all its ancestors, and the widget itself. Then, it appends to this list the name or class pair passed in. resources is fetched from the argument list, the resource database, or the default values in the resource list. Then, resources is copied into the subpart record. If args is NULL, num_args must be zero. However, if num__args is zero, the argument list is not referenced. 154 X Toolkit Intrinsics Reference Manual Xt - Resource Management (continued) XtGetSubvalues An krg is defined as foows: typedef struct { String name; XtArgVal value; } Arg, *ArgList; See Also Section 1.7, "Resources," XtSetArg, XtArgsP roc(2). X Toolkit Intrinsics Reference Manual 157 Xt - Resource Management (continued) XtGetValues See Also Section 1.7, "Resources," Xt SetArg, Xt SetValues, XtArgsProc(). X Toolkit Intrin$ics Reference Manual 159 XtlnstallAccelerators Xt- Translatlons and Actlons-- Name XtlnstallAccelerators m install a widget's accelerators on another widget. Synopsis void XtInstallAccelerators(destination, Widget destination; Widget source; source) Arguments destination Specifies the widget whose translations are to be augmented. source Specifies the widget whose actions are to be executed. Description It is often convenient to be able to bind events in one widget to actions in another. In particu- lar, it is often useful to be able to invoke menu actions from the keyboard. The Intdnsics pro- vide a facility, called accelerators, that let you accomplish this. Accelerators are simply trans- lation tables that map event sequences in one widget into actions in another. Every widget includes an XtNaccelerators resource, which is defined by the Core widget class. The actual value of this resource can be hardcoded by the application or set in a resource file, just like any other resource. However, in order for the XtNaccelerators resource to actually be used, the application must call XtInstallAccelerators (or XtInstallAllAccelerators). This call specifies two arguments. The test inat ion widget is the widget whose translation table will be augmented with the accelerator table from the Source widget. In other terms, you could think of the source as "source of actions" and the destination as "source of events." That is, events occurring in the destination widget will trigger actions in the source. (From the event point of view, the terminology seems backwards! However, the terms source and destination do make sense in terms of what is actually happening to the translation table of the destinaition widget.) For example, assume an application whose top-level shell widget was named topLevel, and which contained a Command widget instance named quit. Further assume that the quit widget had the following XtNaccelerators resource defined for it: *quit. accelerators: \n\ q: Quit() The call: XtInitialize (topLevel, quit) ; would allow a "q" typed in the application's top-level window to invoke the quit widget's Quit action. If the display_accelerator method in the Core part of the source widget class is non- NULL, XtInstallAccelerators calls it with the source widget and a string representa- tion of the accelerator table. (The string representation of the accelerator table is a canonical translation table representation, not an exact replica of what was registered.) The method is 166 X Toolkit Intrinsics Reference Manual XtlnstallAIIAccelerators '- Xt - Translations and Actions-- Name XtlnstallAllAccelerators m install all accelerators from a widget and its descendants onto a destination. Synopsis void XtInstallAllAccelerators(destination, Widget destination; Widget source; source) Arguments de s t i n a t i on Specifies the widget whose translations are to be augmented. source Specifies the widget from which the accelerators are to come. Description XtInstallAllAccelerators is a convenience function for installing all accelerators from a widget and all its descendants onto one destination widget It recursively traverses the widget tree rooted at source and installs the accelerators of each widget onto destination. A common use is to call XtInstallAllAccelerators and pass the application main window as the source. This will allow the events occurring anywhere in the application to be sent to a particular destination widget. Assuming the example shown under xt TnstallAccelerators, the difference between: XtInstallAccelerators (topLevel, quit) ; and xt InstallAl iAccelerators (topLevel, quit) ; is that in the second case, the quit widget's accelerator table will actually be merged with the translation table of every widget in the application, while in the first case, it will only be merged with the translation table for topLevel. Because of event propagation, the effect may be indistinguishable to the user in many cases. (By default, an event that is not selected in a widget will propagate through that widget to the widget's parent) However, it may make a difference if there are conflicting translations in a given widget, and you want the accelerator to override the existing translations (using the #Override directive in the accelerator table resource specification). See Also Section 1.5, 'l'ranslations and Actions," Xt InstallAccelerators. 168 X Toolkit Intrinsics Reference Manual B Xt - Widget Information XtlsComposite Name XtlsComposite -- test whether a widget is a subclass of the Composite widget class. Synopsis Boolean XtIsComposite (w) Widget w; Arguments Specifies the widget whose class is to be tested. Description xtIscomposite tests whether a widget is a subclass of the Composite widget class. This is really just a convenience function equivalent to calling XtIsSubclass with composite- WidgetClass as the class argument. XtIsCornposite is defined as a macro in : #define XtIsComposite(widget) XtIsSubclass(widget, (WidgetClass) \ compo s it eWidget C i a s s ) See Also Composite(3), Core(3). X Toolkit Intn'nsics Reference Manual 169 XtlsConstraint Xt - Widget Information Name XtIsConstraint m test whether a widget is a subclass of the Consla'aint widget class. Synopsis Boolean XtIsConstraint(w) Widget w; Arguments Specifies the widget whose class is to be tested. Description Xt IsConstraint tests whether a widget is a subclass of the Consla'aint widget class. This is really just a convenience function equivalent to calling xt x s Subclass with constraint- WidgetClass as the class argument. XtIsConstraint is defined as a macro in : #define XtIsConstraint (widget) XtIsSubclass(widget, (WidgetClass) \ constraintWidgetClass) See Also Consla'aint(3), Core(3). 170 X Toolkit Intnsics Reference Manual m Xt - Widget Information XtlsManaged Name XtlsManaged m determine whether a widget is managed by its parenL Synopsis Boolean XtIsManaged(w) Widget w; Arguments Specifies the widget whose state is to be tested. Description XtlsManaged returns TRUE if the specified child widget is currently being managed and FALSE if it is not. XtlsManaged is a macro for programs that include . It is a function for application programs that do not have access to the Core widget field names. xt IsManaged simply accesses the Core widget's managed field. See Also XtManageChi idren, XtUnmanageChi idren, Core(3). X Toolkit Intrinsics Reference Manual 171 XtlsRealized Xt - Widget Information-- Name XtlsRealized b determine whether a widget has been realized. Synopsis Boolean XtIsRealized (w) Widget w; Arguments Specifies the widget whose state is to be tested. Description XtIsRealized returns TRUE if the widget has been realized, and FALSE otherwise. A widget is realized if it has a nonzero X window ID in its Core field window. Xt I s Rea li z ed is a macro for programs that include . It is a function for application programs that do not have access to the Core widget field names, xt T s Rea lized accesses the window field from the Core widget structure, whose field definition is opaque from the point of view of application programmers. (Since the Core fields are opaque, they cannot be accessed by a macro.) Some widget methods (for example, set_values) might wish to operate differently depend- ing on whether or not the widget has been realized. See Also Section 1.1, "Widget Lifecycle" 172 X Toolkit Innsics Reference Manual D Xt - Widget Information XtlsSubclass Name XtlsSubclass -- determine whether a widget is a subclass of a class. Synopsis Boolean XtIsSubclass(w, widget_class) Widget w; WidgetClass widget_class; Arguments Specifies the widget whose class is to be tested. widget_class Specifies the widget class to test against. Description If w belongs to a derived class of widget_class, then it is a subclass. XtIsSubclass returns TRUE if the specified widget is a subclass of the given class. A widget is trivially a subclass of its own widget class, or it can be any number of subclasses removed. XtTsSubclass starts with the widget_class field in the Core class part of w's widget structure and follows the superclass pointer until it reaches the top of the class hier- archy. Composite widgets that restrict the class of widgets they will adopt as children can use xt I s- S ubc l a s s to find out if a widget belongs to the desired widget class. See Also XtCheckSubclass, XtClass, XtSuperclass, Composite(3), Core(3). X Toolkit Intrinsics Reference Manual 175 XtMakeGeometryRequest (continued) Xt - Geometry Management Otherwise, XtMakeGeometryRequest returns the resulting value from the parent's geometry manager. Children of primitive widgets are always unmanaged; thus, XtMakeGeometryRequest always returns XtGeometryYes when called by a child of a primitive widget. Structures The return codes from geometry managers are: typedef enum _XtGeometryResult { XtGeometryYes, /* Request accepted */ XtGeometryNo, /* Request denied */ XtGeometryAlmost,/* Request denied but willing to take reply */ XtGeometryDone /* Request accepted and done */ } XtGeometryResult; The XtWidgetGeometry structure is similar to but not identical to the corresponding Xlib structure: typedef unsigned long XtGeometryMask; typedef struct { XtGeometryMask request_mode; Position x, y; Dimension width, height; Dimension border width; -- Widget sibling; int stack mode; -- } XtWidgetGeometry; The request_mode definitions are from : #define CWX (i<<0) #define CWY (i<: typedef struct { String name; XtArgVal value; } Arg, *ArgList; See Also XtFree, XtMalloc, XtSetArg. 186 X Toolkit Intrinsics Reference Manual XtNameToWidget Xt - Widget Information-- Name XtNameToWidget -- translate a widget name to a widget instance. Synopsis Widget XtNameToWidget(reference, name); Widget reference; String name; Arguments reference n ame Specifies the widget from which the search is to start. Specifies the fully qualified name of the desired widget Description XtNameToWidget searches for a widget instance by name. name can refer to a child (either pop-up or normal) of the reference widget, or it can refer to a distant descendant To look up a distant descendant, separate the names of ancestors with periods. There are no wildcard searches. The search for a fully specified name proceeds as follows. The first (leftmost) component of the name string is searched for as a direct descendant of the reference widget If a widget with the given name is found, it is used as the reference widget and the search repeats for the next component A widget's name is given to it when it is created. If XtNameToWidget cannot find the speci- fied widget, it returns NULL. The Intrinsics do not require widgets to have unique names. If more than one child of the refer- ence widget matches a name, XtNameToWidget may select any of the matching widgets. If the specified names contain more than one component and if more than one child matches the first component, XtNameToWidget can return NULL if the single branch that it follows does not contain the named widget That is, XtNameToWidget does not back up and follow other matching branches of the widget tree. A search involving an ambiguous component name is not guaranteed to succeed, even if a widget of the specified name exists. Chapter 12, Menus, Gadgets, and Cascaded Pop Ups, in Volume Four, X Toolkit Intrinsics Pro- gramming Manual, presents a discussion and an example of XtNameToWidget. See Also Section 1.5, "Translations and Actions," Section 1.6, "Pop Ups," XtCreateManagedWidget, XtCreatePopupShell, XtCreateWidget. 188 X Toolkit Intrinsics Reference Manual XtOffset (continued) Xt - Argument Lists XtOffset is a macro defined in as follows: #define Xt0ffset (type, field) ((unsigned int) (((char *) \ (&(((type)NULL)->field)))--((char *) NULL))) See Also Section 1.7, "Resources," XtGetResources. 194 X Toolkit Intrinsics Reference Manual XtOpenDisplay (continued) Xt - Application Contexts XtOpenDisplay then calls the Xlib function XOpenDisplay tO open the display. If display_string was NULL, and no display was specified in argv, it uses the default display (on UNIX-based systems, this is the value of the DISPLAY environment variable). If XOpenDisplay succccds, XtOpenDisplay then calls XtDisplayInitialize with the opened display. If there was no -name option specified in argv and application_name is NULL, it uses the last component of argv [ 0 ]. XtOpenDi splay returns the newly opened display or NULL on failure. See Section 1.1, "Widget Lifecycle," for more general discussion, xtInitialize is a con- venience function that can be used if only one display is to be opened. Application contexts are constructed with XtAppCreateContext. Parsing the command line is discussed in Section 1.7, "Resources," and in XtDisplayInitialize. There is example code in Chapter 9, Resource Management and Type Conversion, in Volume Four, X Toolkit Intrinsics Program- ming Manual. See Also XtDisplayInitialize, Xt Initialize. 196 X Toolkit Intrinsics Reference Manual XtOwnSelection Xt - Selectlons Name XtOwnSelection -- indicate that selection data is available. Synopsis Boolean XtOwnSelection(w, selection, time, 1 ose_lgroc , done_lgroc ) Widget w; Atom selection; Time time; XtConvert Select ionP roc convert_lgroc; XtLoseSelectionProc 1 ose_lgroc; XtSelectionDoneProc done_lgroc; convert_lgroc, Arguments Specifies the widget that wishes to become the owner. selection Specifies an atom that describes the type of the selection (for example, XA_PRIMARY, XA_SECONDARY; these two are declared beforehand in ). time Specifies the times when selection ownership should commence. This should be the timestamp of the event that triggered ownership. It should be the time field taken directly from an XEvent structure. The value Current- T ime is not acceptable. c on vert_lgro c Specifies the procedure to call whenever someone requests the current value of the selection. 1 ose_proc Specifies the procedure to call whenever the widget has lost selection owner- ship, or specifies NULL if the owner is not interested in being called back. done_proc Specifies the procedure to call after the transfer completes, or specifies NULL if the owner is not interested in being called back. Description Calling XtOwnSelection is a precursor to sending data through the selection mechanism. xtOwnSelection informs the Intrinsics of its claim on the selection, and its readiness to send data on request, xtOwnSelection returns TRUE if the widget has successfully become the owner and FALSE otherwise. The widget may fail to become the owner if some other widget has asserted ownership after this widget, as indicated by time. Widgets can lose selection ownership either because another client more recently asserted ownership of the selection, or because the widget voluntarily gave up ownership of the selection with XtDisownSelect ion. The 1 ose_proc procedure is invoked when another widget successfully claims the selection after w. The 1 ose_proc procedure is not called if the widget fails to obtain selection owner- ship in the first place. 198 X Toolkit Intrinsics Reference Manual Xt - Selections (continued) XtOwnSelection If the widget successfully obtains the selection ownership, subsequent requests for data will be directed to convert_proc. XtConve rt Select ionP roc(2) describes the responsibilities of the widget or application sending data and its conversion duties. Chapter 10, Inter-CHent Communications, in Volume Four, X Toolkit Intrinsics Programming Manual, presents a complete example widget that both sends and receives data using selection. See Also XtDisownSelect ion, XtGet Select ionValue, Xt Select ionDone, XtConvert Select ionP roc(2), Xt LoseSelect ionP roc(2). X Toolkit Intrinsics Reference Manual 199 Xt - Translations and Actions (continued) XtParseTranslatlonTable The Intrinsics use the compiled form of the translation table to register the necessary events with the Event Manager. Widgets need do nothing other than specify the action and translation tables for events to be processed by the Resource Manager. The facility to parse translation tables can also be accessed by converting a string resource into a resource of type XtRTranslationTable. If an empty translation table is required for any purpose, one can be obtained by calling XtParseTranslationTable and passing an empty sng. XtAugmentTranslations and XtOverrideTranslations both expect translations in this compiled form. See Also Section 1.5, "Translations and Actions," Volume Four, X Toolkit Intrinsics Programming Manual, Chapter 7, Events, Translations, and Accelerators. X Toollut InlTinsics Reference Manual 203 XtPopup (continued) Xt- Pop Ups See Also Section 1.6, "Pop Ups," XtCheckSubclass, XtCreateManagedWidget, XtRealizeWidget. Volume Four, X Toolkit lntrinsics Programming Manual, Chapter 12, Menus, Gadgets, and Cascaded Pop Ups. 208 X Toolkit Intrinsics Reference Manual XtQueryGeometry Xt - Geometry Management-- Name XtQueryGeometry B query a child widget's preferred geometry. Synopsis XtGeometryResult XtQueryGeometry(w, intended, preferred_return) Widget w; XtWidgetGeometry *intended; XtWidgetGeometry *preferred_return; Arguments w Specifies the widget whose geometry preferences are being queried. intended Specifies any changes the parent plans to make to the child's geometry, or NULL. preferred_return Returns the child widget's preferred geometry. Description Some parents may be willing to adjust their layouts to accommodate the preferred geometries of their children. They can use XtQueryGeometry to obtain the preferred geometry and, as they see fit, can use or ignore any portion of the response. To discover a child's preferred geometry, the child's parent sets any changes that it intends to make to the child's geometry in the corresponding fields of the intended structure, sets the corresponding bits in intended, request_mode, and calls XtQueryGeomet ry. XtQueryGeometry clears all bits in the preferred_return->request_mode and checks the query_geometry field of the specified widget's class record. If the widget's query_geometry method is not NULL, XtQueryGeometry calls the query_geometry method and passes w, intended, and preferred_return as arguments. If intended is NULL, XtQueryGeometry replaces it with a pointer to an XtWidgetGeometry structure with request_mode=0 before calling query_geometry. The query_geomet ry procedure pointer is of type XtGeomet ryHandler(2): The que ry_geomet ry procedure is expected to examine the bits set in request->request_mode, evaluate the preferred geometry of the widget, and store the result in geometry_return (setting the bits in geometry_return->request_mode corresponding to those geometry fields that it cares abouO. If the proposed geometry change is acceptable without modification, the query_geometry procedure should return Xt- GeometryYes. If at least one field in geometry_return is different from the correspond- ing field in request or if a bit was set in geometry_return that was not set in request, the query_geometry procedure should return XtGeometryAlmost. If the preferred geometry is identical to the current geometry, the query_geometry procedure should return XtGeomet ryNo. After calling the query_geometry procedure or if the query_geometry field is NULL, XtQue ryGeomet ry examines all the unset bits in geomet ry_retu rn-> request_mode 210 X Toolkit Intn'nsics Reference Manual Xt - Geometry Management (continued) XtQueryGeometry and sets the corresponding fields in geometry_return to the current values from the widget instance. If the request_mode field is not set to CWStackMode, the stack_mode field is set to XtSMDontChange. XtQueryGeometry returns the value returned by the que ry_geomet ry procedure or XtGeomet ryYe s if the que ry_geomet ry field is NULL. Therefore, the caller can interpret a return of XtGeometryYes as not needing to evaluate the contents of the reply and, more importantly, not needing to modify its layout plans. A return of XtGeomet ryAlmost means either that both the parent and the child expressed interest in at least one common field and the child's preference does not match the parent's intentions or that the child expressed interest in a field that the parent might need to consider. A return value of XtGeometryNo means that both the parent and the child expressed interest in a field and that the child suggests that the field's current value is its preferred value. In addition, whether or not the caller ignores the return value or the reply mask, it is guaranteed that the reply structure contains complete geometry information for the child. Parents are expected to call XtQueryGeometry in their layout routine and wherever other information is significant after change_managed has been called. The change_managed method may assume that the child's current geometry is its preferred geometry. Thus, the child is still responsible for storing values into its own geometry during its initialize method. Structures The return codes from geometry managers are: typedef enum { XtGeometryYes, /* Request accepted */ XtGeometryNo, /* Request denied */ XtGeometryAlmost,/* Request denied but willing to take reply */ XtGeometryDone /* Request accepted and done */ } XtGeometryResult ; The XtWidgetGeometry structure is similar to but not identical to the corresponding Xlib structure: typedef unsigned long XtGeometryMask; typedef struct { XtGeometryMask request_mode; Position x, y; Dimension width, height; Dimension border width; -- Widget sibling; int stack mode; -- } XtWidgetGeometry; The request_mode definitions are from : #define CWX (i<<0) #define CWY (i<: -- #define Above 0 #define Below 1 #define TopIf 2 #define BottomIf 3 #define Opposite 4 The Intdnsics also support the following value: #define XtSMDontChange 5 For precise definitions of Above, Below, TopIf, BottomIf, and Opposite, see Volume Two, Xlib Reference Manual. XtSMDontChange indicates that the widget wants its current stacking order preserved. See Also Section 1.8, "Geometry Management," XtMakeGeomet ryRequest, Core(3), Composite(3). 212 X Toolkit intrinsics Reference Manual XtRegisterCaseConverter Xt- Keyboard Handllngm Name XtRegisterCaseConverter m register a case converter. Synopsis void XtRegisterCaseConverter (display, proc, Display *display; XtCaseProc proc; KeySym start; KeySym stop; start, stop) Arguments di spl ay proc start stop Specifies the display from which the key events are to come. Specifies the XtCaseProc that is to do the conversions. Specifies the first keysym for which this converter is valid. Specifies the last keysym for which this converter is valid. Description XtRegisterCaseConverter registers the spified case converter ( XtCase- Proc(2)). start and stop provide the inclusive range of keysyms for which this converter is to be called. The new converter overrides any previous converters for keysyms in that range. The only way to remove a converter is to register a new one. For example, the default key translator (_xtConvertCase) can be explicidy reinstalled. The default converter understands case conversion for all keysyms defined in the X11 protocol. The keysyms defining a keysym range are defined in . A related keyboard example is presented in Chapter 13, Miscellaneous Toolkit Programming Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual. Structures typedef XID KeySym; See Also XtSetKeyTranslator, XtTrans lateKeycode, XtCaseProc(2), XtKeyProc(2). 216 X Toolkit Intrinsics Reference Manual XtRemoveAllCallbacks Xt - Callbacks-- Name XtRemoveAllCallbacks m delete all procedures from a callback list. Synopsis void XtRemoveAllCallbacks(w, callback name) Widget w; String callback name; Arguments Specifies the widget whose callbacks are to be deleted. callback_name Specifies the callback list to be removed. Description XtRemoveAllCallbacks removes all the widget's callback procedures identified by ca22back_name, regardless of the value of its c2ient_data. This is in contrast to Xt- RemoveCa 1 lbac k and XtRemoveCa 1 lbac ks, which remove the specified callback only if a specified cli en t_data argument also matches. Calling any of these routines implicitly frees all storage associated with the Inlrinsics' internal representation of the callback list. See Also Secfionl.3,"Applicafionlnfface," XtAddCallbacks, XtCallCallbacks, XtRemoveCallback, XtRemove- Callbacks. 218 X Toolkit InlTinsics Reference Manual XtRemoveCallbacks Xt - Callbacks Name XtRemoveCallbacks m delete a list of procedures from a callback list. Synopsis void XtRemoveCallbacks(w, callback_name, callbacks) Widget w; String callback name; XtCallbackList callbacks; Arguments W Specifies the widget. callback name Specifies the callback list from which the procedure is to be deleted. callbacks Specifies the NULL-terminated list of callback procedures and corresponding client data to be deleted. Description XtRemoveCallbacks removes a list of procedures from the callback list identified by the rcsourcc callback name. The procedure is removed only if both the procedure callback and client data match a callback on the list. No warning message is generated if a procedure to be removed fails to match a callback on the list. Use XtRemoveAllCallbacks if you want to remove a partic- ular callback regardless of the value of its cliene.._data. Structures typedef struct XtCallbackRec* XtCallbackList; See Also Sfionl.3,"Applicationlntefface," XtAddCallbacks, XtCallCallbacks, XtRemoveAllCallbacks, XtRemove- Callback. 220 X Toolkit Intrinsics Reference Manual XtRemoveEventHandler (continued) Xt- Event Handling Event Mask Symbol NoEventMask KeyPressMask KeyReleaseMask ButtonPressMask ButtonReleaseMask EnterWindowMask LeaveWindowMask PointerMotionMask PointerMotionHintMask ButtonlMotionMask Button2MotionMask Button3MotionMask Button4MotionMask Button5MotionMask ButtonMotionMask KeymapStateMask ExposureMask VisibilityChangeMask StructureNotifyMask ResizeRedirectMask SubstructureNotifyMask SubstructureRedirectMask FocusChangeMask PropertyChangeMask ColormapChangeMask OwnerGrabButtonMask Circumstances No events Keyboard down events Keyboard up events Pointer button down events Pointer button up events Pointer window entry events Pointer window leave events All pointer motion events Fewer pointer motion events Pointer motion while button 1 down Pointer motion while button 2 down Pointer motion while button 3 down Pointer motion while button 4 down Pointer motion while button 5 down Pointer motion while any button down Any keyboard state change on EnterNotify, LeaveNotify, Focus In or FocusOut Any exposure (except GraphicsExpose and NoExpose) Any change in visibility Any change in window configuration. Redirect resize of this window Notify about reconfiguration of children Redirect reconfiguration of children Any change in keyboard focus Any change in property Any change in colormap Modifies handling of pointer events See Also Section 1.4, "Events," Xt AddEvent Handle r, Xt Remove RawE vent Handle r, XtEventHandler(2). 222 X Toolkit Intrinsics Reference Manual Xt - Pop Ups XtRemoveGrab Name XtRemoveGrab m redirect user input from modal widget back to normal destination. Synopsis void XtRemoveGrab(w) Widget w; Arguments Specifies the widget to remove from the modal cascade. XtRemoveGrab does not terminate a grab requested through the server; it simply changes Xt's event dispatching. Description XtRemoveGrab removes widgets from the modal cascade (a set of widgets that lock out user input to the application except through themselves). It issues an error if the specified widget was not in the modal cascade. The modal cascade is a data structure used by XtDispatchEvent when it tries to dispatch a user event. It is a list of widgets which have issued a request, from the Intrinsics, for events that would ordinarily be outside their jurisdiction. When the modal cascade is not empty, XtDispatchEvent delivers the event to the most recent modal cascade entry, with the exclusive parameter TRUE. XtPopup UseS XtAddGrab and XtRemoveGrab to constrain user events to a modal cas- cade. It is unusual to call XtAddGrab or XtRemoveGrab explicitly. See Also XtAddGrab, XtDispatchEvent, XtPopup. X Toolkit Intrinsics Reference Manual 223 XtRemovelnput Xt- Event Handllngm Name XtRemovelnput m cancel source of alternate input events. Synopsis void XtRemoveInput (id) Xt Input Id id; Arguments id Specifies the ID returned from the corresponding XtAddInput call. Description XtRemoveInput causes the Intrinsics to stop watching for events from an alternate input source registered with XtAddInput. Alternate input events are usually operating system reads, but they can be any I/O operation supported by the operating system. For more general discussion of alternate input events, see Chapter 13, Miscellaneous Toolkit Programming Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual. See Also XtAddInput, XtAppAddInput. 224 X Toolkit Intrinsics Reference Manual --Xt- Event Handllng XtRemoveRawEventHandler Name XtRemoveRawEventHandler -- remove a raw event handler. Synopsis void XtRemoveRawEventHandler (w, event_mask, client data) Widget w; EventMask event mask; Boolean nonmaskable; XtEventHandler proc; caddr t client data; nonmaskable, proc, Arguments event mask n onma skabl e proc client data Specifies the widget for which this handler is registered. Specifies the events for which to unregister this handler. Specifies a Boolean value that indicates whether this procedure should be unregistered for the nonmaskable events (Graphicsgxpose, Nogxpose, SelectionClear, SelectionRequest, SelectionNotify, ClientMessage, and MappingNotify). Specifies the procedure to be registered. Specifies the client data to match on the registered event handler. Description XtRemoveRawEventHandler stops the Rcified pcedure from receiving any more of the specified events. A handler is removed only if both the procedure proc and client data match a previously registered handler. If a handler to be removed fails to match a procedure, or if it has been regis- tered with a different value of client_data, XtRemoveEventHandler returns without reporting an error. Because the procedure is a raw event handler, it does not affect the widget's mask and never calls the Xlib xSelect Tnput function. Structures The event_mask is formed by combining the event mask symbols listed in the first column of the table below using the bitwise OR operator (I). Each mask symbol sets a bit in the event mask. The table also describes briefly the circumstances under which you would want to specify each symbol. X Toolkit Intrinsics Reference Manual 225 XtRemoveRawEventHandler (continued) Xt- Event Handling Event Mask Symbol NoEventMask KeyPressMask KeyReleaseMask ButtonPressMask ButtonReleaseMask EnterWindowMask LeaveWindowMask PointerMotionMask PointerMotionHintMask ButtonlMotionMask Button2MotionMask Button3MotionMask Button4MotionMask Button5MotionMask ButtonMotionMask KeymapStateMask ExposureMask VisibilityChangeMask StructureNotifyMask ResizeRedirectMask SubstructureNotifyMask SubstructureRedirectMask FocusChangeMask PropertyChangeMask ColormapChangeMask OwnerGrabButtonMask Circumstances No events Keyboard down events Keyboard up events Pointer button down events Pointer button up events Pointer window entry events Pointer window leave events All pointer motion events Fewer pointer motion events Pointer motion while button 1 down Pointer motion while button 2 down Pointer motion while button 3 down Pointer motion while button 4 down Pointer motion while button 5 down Pointer motion while any button down Any keyboard state change on EnterNotify, LeaveNotify, FocusIn or FocusOut Any exposure (except GraphicsExpose and NoExpose) Any change in visibility Any change in window configuration. Redirect resize of this window Notify about reconfiguration of children Redirect reconfiguration of children Any change in keyboard focus Any change in property Any change in colormap Modifies handling of pointer events See Also Stionl.4,"Events,'" XtRemoveEventHandler. XtEventHandler(2). 226 X Toolkit Intn'nsics Reference Manual XtRemoveWorkProc Xt- Event Handllngm Name XtRemoveWorkProc m remove a work procedure. Synopsis void XtRemoveWorkProc (id) XtWorkProcId id; Arguments id Specifies which work procedure to remove. Description XtRemoveWorkP roc explicitly removes the specified background work procedure. The Xt- WorkP roc I d is returned from a corresponding XtAddWorkP roc call. AJ1 XtWorkP roc is removed automatically once it returns TRUE. See Also Xt AddWo rkP roc, XtAppAddWorkP roc, XtWorkP roc(2). 228 X Toolkit Intrinsics Reference Manual XtResizeWindow Xt - Window Manipulation Name XtResizeWindow m resize a widget according to the values of its core dimensions. Synopsis void XtResizeWindow(w) Widget w; Arguments W Specifies the widget. Description XtRes i zeWindow calls the XConfigureWindow Xlib function to make the window of the specified widget match its Core width, height, and border width. The call to XConfigureWindow is done unconditionally because there is no way to tell if these values match the current values. XtResJ.zeWS.ndow does not cause the widget's resize method to be called. There are very few occasions when you need to use XtRes i zeWindow; it is more diplomatic to use XtRes i zeWidget. See Also Section 1.8, "Geometry Management," XtRes i zeWidge t. 230 X Toolkit Intn'nsics Reference Manual XtSetArg Xt - Argument Llsts Name XtSetArg m construct or modify an argument list dynamically. Synopsis void XtSetArg(arg, resource_name, value) Arg arg; String resource name; XtArgVal value; Arguments arg Specifies the argument to seL resource name Specifies the name of the resource. value Specifies the value of the resource, or else its address. (If the size of the resource is less than or equal to the size of an XtArgVal, the resource value is stored directly in val ue; otherwise, a pointer to it is stored in val ue.) Description Many Intdnsics functions need to be passed pairs of resource names and values. These are passed as an ArgList (see the Structures section below). To dynamically change values in an existing ArgList. use XtSetArg. XtSetArg sets the value of the arg structure. Arg structures are passed to widgets and resource routines setting or overriding resource values. Note that XtSetArg is a macro. Expressions involving autoincrement and autodecrement operations are unsafe in its argument list, since XtSetArg evaluates its first argument twice. XtSetArg is usually used in a highly stylized manner to minimize the probability of making a mistake; for example: Arg args [20] ; int n; n = 0; XtSetArg(args[n], XtNheight, i00); n++; XtSetArg(args[n], XtNwidth, 200); n++; XtSetValues(widget, args, n); Volume Four, X Toolkit lntrinsics Programming Manual, presents several examples using Args, setting them both with values initialized at compile time and using XtSetArg. Structures Arg is defined as foows in : typedef struct { String name; XtArgVal value; } Arg, *ArgList; 232 X Toolkit Innsics Reference Manual XtSetErrorHandler Xt - Error Handling--- Name XtSetErrorHandler m register a procedure to be called on fatal error conditions. Synopsis void XtSetErrorHandler (handler) XtErrorHandler handler; Arguments handler Specifies the new low-level fatal error procedure, which should not return. Description The Intrinsics let a client register procedures that are to be called whenever a fatal or nonfatal error occurs. These facilities are intended for both error reporting and logging and for error correction or recovery. Two levels of interface are provided: A high-level interface that takes an error name and class and looks the error up in an error resource database. The high-level fatal error handler is invoked by a call to Xt- ErrorMsg or XtAppErrorMsg; the high-level nonfatal error handler is invoked by a call to XtWarningMsg or XtAppWarningMsg. A new handler can be registered by calling Xt SetErrorMsgHandler or Xt SetWarningMsgHandler. A low-level interface that takes a simple string, which is printed out as the error message. The low-level fatal error handler is invoked by a call to Xt.rror or XtAppError; the low-level nonfatal error handler is invoked by a call to Xtwarning or XtApp- Warning. A new handler can be registered by calling XtSetErrorHandler or Xt- SetWarningHandler. The high-level functions construct a string to pass to the lower-level interface. On UNIX-based systems, the error database is usually lusrlliblXlllXtErrorDB. To obtain the error database (for example, to merge with an application or widget-specific data- base), use XtAppGetErrorDatabase. Application-context-specific error handling is not implemented on many systems. Most imple- mentations will have just one set of error handlers. If they are set for different application con- texts, the one performed last will prevail. The default low-level fatal error handler provided by the Intrinsics is _XtError. On UNIX- based systems, it prints the message to standard error and terminates the application. Using XtSetErrorHandler, you can replace this default error handler with one of your own. Fatal error message handlers should not return. If one does, subsequent Toolkit behavior is indeterminate. See xt Set Er ro rHandle r(2) for more details. See Also XtSetErrorMsgHandler, XtSetWarningHandler, XtErrorHandler(2). 234 X Toolkit Intrinsics Reference Manual Xt- Keyboard Handling (continued) XtSetKeyboardFocus parent can give the focus to another widget. Widgets that need to know when they lose the keyboard focus must use the Xlib focus notification mechanism explicitly (typically by specify- ing translations for Focus In and FocusOut events). Widgets that need the keyboard focus can call xSet InputFocus explicitly. Widgets that never want the keyboard focus should set their accept_focus procedure pointer to NULL. See Also XtAcceptFocusProc, XtAddGrab, XtCallAcceptFocus, XtDispatchEvent, Composite(3). X Toolkit Intrinsics Reference Manual 237 XtSetSelectionTimeout Xt - Selections-- Name XtSetSelectionTimeout -- set value of selection timeout. Synopsis void XtSetSelectionTimeout(timeout) unsigned long timeout; Arguments timeout Specifies the selection timeout in milliseconds. Description timeout is the time within which the two communicating applications must respond to one another. If one of them does not respond within this interval, Xt aborts the selection request. The default value of t./meout is 5000 milliseconds (five seconds). Chapter 10, Inter-Client Communications, in Volume Four, X Toolkit Intrinsics Programming Manual, presents a complete example widget that both sends and receives data using selections. See Also XtGet SelectionTimeout 240 X Toolkit Innsics Reference Manual m Xt - Resource Management XtSetSensitive Name XtSetSensitive -- set the sensitivity state of a widgeL Synopsls void XtSetSensitive(w, Widget w; Boolean sensitive; sensi ti ve) Arguments sensi ti ve Specifies the widget. Specifies a Boolean value that indicates whether the widget should receive keyboard and pointer events. Description Many widgets have a mode in which they assume a different appearance (for example, grayed out or stippled), do not respond to user events, and become dormant. When dormant, a widget is insensive. This means the Event Manager does not dispatch any events to the widget with an event type of KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify, EnterNotify, LeaveNotify, FocusIn, or FocusOut. Widget sensitivity is controlled by the sensitive and ancestor_sensitive fields in the Core class record. A widget can be insensitive because its sensitive field is FALSE or because one of its ancestors is insensitive; therefore, the widget's ancestor sensitive -- field is also FALSE (sensitive is always set to FALSE if ancestor sensitive is FALSE). A widget can, but does not need to, distinguish these two cases visually. xtSetSensitive first calls xtSetValues on the current widget with an argument list specifying that the sensitive field should change to the new value. It then recursively propa- gates the new value down the managed children tree by calling xtsetvalues on each child to set ancestor sensitive to the new value if the new values for sensitive and the child's ancestor sensitive are not the same. XtSetSensitive calls XtSetValues to change the sensitive and ancestor_sen- sitive fields in Core. Therefore, when one of these changes, the widget's set_values procedure should take whatever display actions are needed (for example, graying or stippling the widget). xtSetSensitive ensures that if a parent has either sensitive or ancestor_sensi- tive set to FALSE, then all children have ancestor_sensitive set to FALSE. Both sensitive and the ancestor sensitive field are maintained as Booleans in the Core instance record, defined in . See Also Xt GetVa lue s, Xt I s Sens it ive, Xt SetVa lue s. X Toolkit Intnnsics Reference Manual 241 Xt- Resource Management (continued) XtSetSubvalues Arg is defined as follows in : typedef struct { String name; XtArgVal value; } Arg, *ArgList; See Also Secfionl.7,'esoces," XtSetArg, XtArgsFunc(2). X Toolkit Intrinsics Reference Manual 243 XtSetValues Xt - Resource Management Name XtSetValues -- copy resources from ArgList tO widget Synopsis void XtSetValues(w, args, num_args) Widget w; ArgList args; Cardinal num_args; Arguments a rgs num_args Specifies the widget whose values are to be written and their new values. Specifies the argument list of name/value pairs that contain the resources to be modified. The resources and values passed are dependent on the widget being modified. Specifies the number of arguments in the argument list. Description XtSetValues modifies the current state of resources associated with a widget instance. (Actually, the widget decides what changes it will actually allow and updates all derived fields appropriately.) The name fields in args contain the names of resources. The value fields in args contain the new values of resources. xtSetValues starts with the resources specified for the Core widget fields and descends the subclass chain to the widget At each stage, it writes the new value (if specified by one of the arguments) or the existing value (if no new value is specified) to a new widget data record. xtSetValues then calls the set_values methods for the widget in superclass-to-subclass order. If the widget has any nOn-NULL set_values_hook fields, these methods are called immediately after the corresponding set_values method. This permits access to nonwidget resource data from xtSetValues. If the widget's parent is a subclass of constraintWidgetClass, XtSetValues also updates the widget's constraints. It starts with the constraint resources specified for constraintWidgetClass and proceeds down the subclass chain to the parent's class. At each stage, it writes the new value or the existing value to a new constraint record. It then calls the constraint set values methods from constraintWidgetClass down to the par- ent's class. The constraint set_values methods are called with widget arguments, as for all set_values methods, not just the constraint record arguments, so that they can make adjust- ments to the desired values based on full information about the widget xtSetValues determines if a geometry request is needed by comparing the current widget to the new widget If any geometry changes are required, it makes the request, and the geometry manager returns XtGeometryYes, XtGeometryAlmost, or XtGeometryNo. If Xt- GeometryYes is returned, XtSetValues calls the widget's resize method. If Xt- GeometryNo is returned, xtSetValues resets the geometry fields to their original values. If XtGeometryAlmost is rettlmed, XtSetValues calls the set_values_almost 244 X Toolkit Intrinsics Reference Manual Xt - Resource Management (continued) XtSetValues method, which determines what should be done and writes new values for the geometry fields into the new widget, xtSetValues then repeats this process, deciding once more whether the geometry manager should be called. Finally, if any of the set_values methods returned TRUE, XtSetValues causes the widget's expose procedure to be invoked by calling the Xlib XClearArea function on the widget's window. The conjugate function XtGetValues retrieves a widget's values. Structures Arg is defined as follows in : typedef struct { String name; XtArgVal value; } Arg, *ArgList; See Also Section 1.7, "Resources," XtSetArg, XtargsFunc(2). X Toolkit Intrinsics Reference Manual 245 XtSetWarningHandler Xt- Error Handling m Name XtSetWarningHandler m register a procedure to be called on nonfatal error conditions. Synopsis void XtSetWarningHandler (handler) XtErrorHandler handler; Arguments handler Specifies the new low-level nonfatal error procedure, which usually returns. Description The Intrinsics let a client register procedures that are to be called whenever a fatal or nonfatal error occurs. These facilities are intended for both error reporting and logging and for error correction or recovery. Two levels of interface are provided: A high-level interface that takes an error name and class and looks the error up in an error resource database. The high-level fatal error handler is invoked by a call to Xt- ErrorMsg or XtAppErrorMsg; the high-level nonfatal error handler is invoked by a call to XtWarningMsg or XtAppWarningMsg. A new handler can be registered by calling XtSetErrorMsgHandler or XtSetWarningMsgHandler. A low-level interface that takes a simple string, which is printed out as the error message. The low-level fatal error handler is invoked by a call to XtError or XtAppError; the low-level nonfatal error handler is invoked by a call to XtWarning or XtApp- Warning. A new handler can be registered by calling XtSetErrorHandler or Xt- SetWarningHandler. The high-level functions construct a string to pass to the lower-level interface. On UNIX-based systems, the error database is usually lusrlliblX111XtErrorDB. To obtain the error database (for example, to merge with an application or widget-specific data- base), use XtAppGetErrorDatabase. Application-context-specific error handling is not implemented on many systems. Most imple- mentations will have just one set of error handlers. If they are set for different application con- texts, the one performed last will prevail. The default warning handler provided by the Intrinsics is _XtWarning. On UNIX-based sys- tems, it prints the message to standard error and returns to the caller. Using XtSetWarning- Handler, you can replace this handler with one of your own. Warning message handlers should return. If an error is non-recoverable, an application should generate a fatal error. See Also XtErrorMsgHandler, XtSetErrorHandler, XtSetWarningMsgHandler, Xt- Warning, XtWarningHandler(2). 246 X Toolkit Intrinsics Reference Manual Xt - Keyboard Handling (continued) XtTranslateKey ModlMask Key defined as Modl was depressed. Mod5Mask StandardMask Keydefined as Mod5 wasdepssed. (ShiftMask I LockMask). See Also XtRegiste rCa seConverte r, XtSetKeyTranslator, XtKeyP roc(2). X Toolkit Intrinsics Reference Manual 253 Xt - Keyboard Handling (continued) XtTranslateKeycode Mod5Mask StandardMask Keydefined  Mod5 wasdepssed. (ShiftMask I LockMask). See Also XtRegisterCaseConverter, XtSetKeyTranslator, XtTranslateKey, XtKeyP roe(2). X Toolkit Intrinsics Reference Manual 255 m Xt - Geometry Management XtUnmanageChild Name XtUnmanageChild m remove a widget from its parent's managed list. Synopsis void XtUnmanageChild(w) Widget w; Arguments Specifies the child widget to be unmanaged. Description XtUnmanageChild constructs UnmanageChildren. a widget list containing one element and calls Xt- No that XtManageChild, XtManageChildren, XtUnmanageChild, and Xt- UnmanageChi idren are low-level routines that are used by generic composite widget build- ing routines. In addition, composite widgets can provide widget-specific, high-level conve- nience procedures to let applications create and manage children more easily. See Also Section l.l,"WMgetLicycle," XtDestroyWidget, XtIsManaged, XtManageChild, XtManageChildren, Xt- UnmanageChildren. X Toolkit Intrinsics Reference Manual 257 XtUnmanageChildren Xt - Geometry Management m Name XtUnmanageChildren n remove a l.ist of children from a parent widget's managed list. Synopsis void XtUnmanageChildren(children, num children) WidgetList children; Cardinal num children; Arguments chil dren Specifies a list of child widgets. num_children Specifies the number of children. Description XtUnmanageChildren removes a list of widgets from a parent widget's geometry manage- ment list. It performs the following: Issues an error if children do not all have the same parent or if the parent is not a sub- class of compos iteWidgetClas s. Returns immediately if the common parent is being destroyed; otherwise, for each unique child on the list, XtUnmanageChildren performs the following: Marks children viable if they are not being destroyed and are currently man- aged. For each viable child, if the child is realized, it makes it invisible by unmap- ping it. If the parent is realized, it calls the change__managed routine of the widgets' parent. XtUnmanageChildren does not destroy children. Removing widgets from a parent's man- aged set is often a temporary banishmentmsome time later, they may be managed again. To destroy widgets entirely, see XtDest royWidget. Note dmt XtManageChild, XtManageChildren, XtUnmanageChild, and Xt- UnmanageChildren are low-level routines that are used by generic composite widget build- ing routines. In addition, composite widgets can provide widget-specific, high-level conve- nience procedures to let applications create and manage children more easily. Structures typedef widget *WidgetList ; See Also Secfionl.l,"WidgetLifycle," XtDestroyWidget, XtIsManaged, XtManageChild, XtManageChildren, Xt- UnmanageChild. 258 X Toolkit Intrinsics Reference Manual B Xt - Widget Information XtWi d g etTo App I icatio n Co nte xt Name XtWidgetToApplicationContext B get the application context for a given widgeL Synopsis XtAppContext XtWidgetToApplicationContext(w) Widget w; Arguments Specifies the widget for which you want the application context. Description XtWidgetToApplicationContext returns the application context for the specified widget It locates the application context by following the chain of Core widget Parent structures until it finds one that is a subclass of the fundamental widget class windowObjClass. Then it accesses the application context associated with the display for that widget See Also XtCreateApplicat ionContext X Toolkit Intrinsics Reference Manual 263 -- Xt - Widget Information XtWindowToWidget Name XtWindowToWidget -- translate a window and display pointer into a widget instance. Synopsis Widget XtWindowToWidget (display, window) Display *display; Window window; Arguments di spl ay window Specifies the display on which the window is defined. Specify the window for which you want the widget. Description XtWindowToWidget takes a display pointer and a window and returns the associated widgeL The widget must be within the same application as the caller. On fzilme, XtWindowToWidget returns NULL. See Also XtNameToWidget, XtWindow. X Toolkit Intrinsics Reference Manual 265 Prototype Procedures This section contains alphabetically-organized reference pages for function proto- types (typedefs) used for widget methods and other handlers. Each page contains a synopsis of the routine's calling sequence, its arguments, a description of its function, and a reference to related routines. m Xt - Keyboard Handling XtAcceptFocusProc Name XtAcceptFocusProc B prototype procedure to accept or reject keyboard focus. Synopsis typedef Boolean Widget w; Time *time; (*XtAcceptFocusProc) (Widget, Time) ; Arguments time Specifies the widget. Specifies the X time of the event causing the accept focus. Description When the keyboard focus is given to a widget, Xt invokes the widget's accept_focus pro- cedure. The procedure should return a Boolean to indicate whether or not it will accept the focus, so that the parent can give the focus to another widget if necessary. The accept_focus procedure is part of the Core class structure. A widget that never wants the keyboard focus should set its accept_focus procedure to NU,, when it initializes its class record. A widget can usurp the keyboard focus by calling the Xlib function :bitmapEdit.cur_y + ((XMotionEvent *)event)->y) / w->bitmapEdit.cell size in pixels; -- else XtWarning("BitmapEdit: ToggleCell called with wrong event type\n"); Notice that some code is repeated to cast the event structure to the two different event types. With the current MIT implementation of Xlib, the positions of the x and y fields in the XButtonEvent and XMotionEvent suctures are the me, and therefore this casting is unnecessary. However, it is improper to depend on any particular implementation of Xlib. The order of the fields in one of these events could be different in a vendor's implementation of Xlib. 272 X Toolkit Intrinsics Reference Manual XtAImostProc (continued) Xt- Geometry Management Position x, y; Dimension width, height; Dimension border width; -- Widget sibling; int stack mode; -- } XtWidgetGeometry; The request_mode definitions are from : #define CWX (i<<0) #define CWY (i<: #define Above 0 #define Below 1 #define TopIf 2 #define BottomIf 3 #define Opposite 4 The Intrinsics also support the following value: #define XtSMDontChange 5 For precise definitions of Above, Be low, Top I f, BottomI f, and Oppos it e, see the refer- ence page for Configurewindow in Volume Two, Xlib Reference Manual. XtSMDont- Change indicates that the widget wants its current stacking order preserved. See Also Co(3) 274 X Toolkit Intrinsics Reference Manual -- Xt - Resource Management XtArgsFunc Name XUgsFunc -- prototype set values hook method. Synopsis typedef Boolean (*XtArgsFunc) (Widget, ArgList, Cardinal *); Widget w; ArgList args; Cardinal *num_args; Arguments args n um_a rgs Specifies the widget whose nonwidget resource values are to be changed. Specifies the argument list that was passed to XtCreateWidget. Specifies the number of arguments in the argument list. Description An XtArgsFunc procedure returns a Boolean indicating whether, based on the values passed in a rgs, the widget needs to be redrawn. Widgets can set subpart resource values when the application calls xtSetValues by supplying an XtArgsFunc procedure in the core widget class set_values_hook method. To set the actual subvalues of the nonwidget data, the widget should call XtSetSubvalues and pass the appropriate resource list. The set__values_hook method is similar to the set_values method, except that it is passed only the current widget instance structure and the arglist, instead of the old and new copies of the widget instance structure which are passed to set_values. As a result, set values hook needs to use a different technique for comparing the current subresource values with the values set by xtSetValues. There are two ways to do this. One is to loop through the widget's resource list, using strcmp to compare each resource name in the argument list with the subresource names, and then com- paring each argument value with the current value of the subresource. The other way is to copy the instance structure passed in using bcopy (after allocating mem- ory for the new copy with XtNew, described in Chapter 13, Miscellaneous Toolkit Program- ming Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual). Then call Xt- SetSubvalues to set the actual values to those in the argument list. After this process, you can compare the old and new values the same way this is done in the set_values method. As of Release 4, the initialize_hook and set_values_hook methods are stl called for backwards compatibility but are obsolete because the same information (the argument lists) has been added as arguments to the initialize and set_values methods. Structures Arg is defined as follows in : typedef struct { String name; XtArgVal value; } Arg, *ArgList; X Toolkit Intrinsics Reference Manual 275 XtArgsFunc (continued) Xt - Resource Management See Also Section 1.7, "Resources," XtCreat eWidget, Xt Set Subva lues, Xt SetVa lues, Core(3). 276 X Toolkit Intrinsics Reference Manual --Xt- Resource Management XtArgsProc Name XtArgsProc- prototype procedure for get_values_hook method. Synopsis typedef void (*XtArgsProc) (Widget, ArgList, Cardinal *); Widget w; ArgList args; Cardinal *num_args; Arguments args num_args Specifies the widget whose nonwidget resource values are to be retrieved. Specifies the argument list that was passed to XtCreateWidget. Specifies the number of arguments in the argument list. Description Widgets can return resource values from subparts for XtGetValues by supplying a pointer to an XtArgsProc procedure in the Core widget class get_values_hook field. To obtain the actual subvalues of the nonwidget data, the widget should call XtGetSubvalues and pass the appropriate resource list. The initialize hook method is also of t)e XtArgsProc. The initialize hook -- -- method allows a widget instance to initialize nonwidget data using information from the speci- fied argument list. For example, the Text widget has subparts that are not widgets, yet these subparts have resources that can be specified by means of the resource file or an argument list. The hook methods are called with different arguments than their nonhook counterparts. They are passed a single copy of the widget instance structure (the new copy already modified in the nonhook methods), and the argument list passed to the Xt routine that triggered the method. The set_values_hook and get_values_hook methods simply take this widget ID and argument list and pass them to XtSetSubvalues or XtGetSubvalues respectively. The initialize_hook method uses the contents of the argument list to validate resource set- tings for subparts and set nonresource subpart data. As of Release 4, the initialize hook and set values hook methods are stl called for backwards compatibility but are obsolete because the same information (the argument lists) has been added as arguments to the initialize and set_values methods. However, get_values_hook is still necessary. The example below shows the get_values_hook method for the AsciiSrc subpart of the Text widget (somewhat simplified to show only the essential elements). static void GetValuesHook(src, args, num_args) XawTextSource src; ArgList args; Cardinal * num_args; { X Toolkit Intrinsics Reference Manual 277 XtArgsProc (continued) Xt - Resource Management XtGetSubvalues((caddr t) src, -- sourceResources, XtNumber(sourceResources), args, *num_args); See Also Section 1.7, "Resources," XtCreateWidget, XtGetSubvalues, XtGetValues, Core(3). 278 X Toolkit Intrinsics Reference Manual m Xt - Keyboard Handling XtCaseProc Name XtCaseProc m prototype procedure called to convert the case of keysyms. Synopsis typedef void (*XtCaseProc) (KeySym *, KeySym *keysym; KeySym *lower return; KeySym *upper_return; KeySym *, KeySym *); Arguments keysym lower return upper_ret urn Specifies the keysym to convert. Specifies the lower-case equivalent for the keysym. Specifies the upper-case equivalent for the keysym. Description To handle capitalization of nonstandard keysyms, the Intrinsics allow clients to register case conversion routines. Case converter procedure pointers are of type xtCaseProc. An xtCaseProc allows an application to specify its own upper-case and lower-case transla- tions for keyboard keys. If there is no case distinction, the procedure should store the input keysym into both return values. The case converter can be registered with XtRegisterCaseConverter. Here is the default case converter from the R3 Intrinsics: /* ARGSUSED */ void _XtConvertCase(dpy, keysym, lower_return, upper_return) Display *dpy; KeySym keysym; KeySym *lower return; KeySym *upper_return; if ((keysym >= XK_a && keysym <= XK_z) II (keysym >= XK_ssharp && keysym <= XK_odiaeresis) (keysym >= XK oslash && keysym <= XK_ydiaeresis)) -- *lower return = keysym; -- *upper_return = keysym-0x20; return; } if ((keysym >= XK_A && keysym <= XK_Z) II (keysym >= XK_Agrave && keysym <= XK_Odiaeresis) (keysym >= XK_Ooblique && keysym <= XK_Thorn)) { *upper_return = keysym; *lower return = keysym+0x20; -- return; } X Toolkit Intrinsics Reference Manual 281 XtCaseProc (continued) Xt- Keyboard Handling *lower return = keysym; -- *upper_return = keysym; A related keyboard example is presented in Chapter 13, Miscellaneous Toolkit Programming Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual. See Also XtRegisterCaseConverter, XtTranslateKeycode. 282 X Toolkit Intrinsics Reference Manual XtConvertSelectionProc (continued) Xt - Selections The Inlrinsics call the selection owner's XtConvertSelectionProc to obtain selection data when another client requests it. The XtConvertSelectionProc is registered when the selection owner asserts its ownership. The XtConvertSelectionProc should return TRUE if the owner successfully converted the selection to the target type or FALSE otherwise. If the procedure returns FALSE, the values of the return arguments are undefined. Each XtConvertSelectionProc should respond to larget value TARGETS by returning a value containing the list of the targets they are prepared to convert their selection into. This is used by the selection owner. The list of targets should be an array of interned Atoms, and return_type should be XA_ATOM. Most type Atoms are defined in . Those that are not (for example, TARGETS) must be interned explicitly as Atoms by calling the Xlib function XInternAtom. See Also XtFree, XtGetSelectionValue, XtOwnSelection, XtSelectionDoneProc. The example below shows code to handle standard selection targets. This code is taken from the BitmapEdit widget developed in Volume Four, X Toolkit lntrinsics Programming Manual; however, this portion of it is adapted from the standard client xclipboard, and can be copied almost directly into your widget. static Boolean convert_proc(w, selection, target, type_return, value_return, length_return, format_return) BitmapEditWidget w; Atom *selection; Atom *target; Atom *type_return; caddr t *value return; -- -- unsigned long *length_return; int *format return; -- int x, y; int width, height; /* handle TARGETS target */ if (*target == XA TARGETS(XtDisplay(w))) { -- Atom* targetP; Atom* std_targets; unsigned long std_length; XmuConvertStandardSelection(w, CurrentTime, selection, target, type_return, (caddr_t*)&std_targets, &std_length, format_return); *value return = XtMalloc(sizeof(Atom)*(std_length + I)); -- targetP = *(Atom**)value return; -- *length_return = std_length + I; *targetP++ = w->bitmapEdit.target_atom; 284 X Toolkit Intrinsics Reference Manual XtConverter (continued) Xt- Resource Management define a symbolic constant (for example, XtDefaultForeground, XtDefault- Background, orXtDefaultFont). The foHowg example shows a convener that takes a string and converts it to a pixel vue: static void CvtStringToPixel(args, num_args, fromVal, toVal) XrmValuePtr args; Cardinal *num_args; XrmValuePtr fromVal; XrmValuePtr toVal; static XColor screenColor; XColor exactColor; Screen *screen; Colormap colormap; Status status; char message[1000]; XrmQuark q; String params[l]; Cardinal num_params = i; if (*num_args != 2) XtErrorMsg("cvtStringToPixel","wrongParameters", "XtToolkitError", "String to pixel conversion needs screen and colormap arguments", (String *)NULL, (Cardinal *)NULL); screen = *((Screen **) args[0].addr); colormap = *((Colormap *) args[l].addr); LowerCase((char *) fromVal->addr, message); q = XrmStringToQuark(message); if (q == XtQExtdefaultbackground) { done(&screen->white_pixel, Pixel); return; } if (q == XtQExtdefaultforeground) { done(&screen->black_pixel, Pixel); return; } if ((char) fromVal->addr[0] == '#') { /* some color rgb definition */ status = XParseColor(DisplayOfScreen(screen), colormap, (String) fromVal->addr, &screenColor); if (status != 0) status = XAllocColor(DisplayOfScreen (screen), colormap, &screenColor); } else /* some color name */ status = XAllocNamedColor(DisplayOfScreen(screen), colormap, (String) fromVal->addr, &screenColor, &exactColor); if (status == 0) { params[0]=(String)fromVal->addr; XtWarningMsg("cvtStringToPixel","noColormap", "XtToolkitError", 288 X Toolkit Intrinsics Reference Manual Xt- Resource Management (continued) XtConverter "Cannot allocate colormap entry for \\"%s\\ .... , params, &num_params) ; else { done(&(screenColor.pixel), Pixel) See Also Section 1.7, "Resources," Xt AppAddConve rt e r, Xt Convert, XtD i rect Convert, Xt S t r ingCo nver s i on- Warning. X Toolkit Intrinsics Reference Manual 289 XtErrorHandler Xt- Error Handling m Name XtErrorHandler -- prototype for low-level error and warning handlers. Synopsis typedef void (*XtErrorHandler) (String) ; String message; Arguments message Specifies the error message. Description The error handler should display the message string in some appropriate fashion. Some appli- cations may wish to log errors to a file as well. The default handlers simply print a message to standard error, and exit (for errors) or return (for warnings), as shown below: static void XtDefaultError(message) String message; extern void exit(); (void)fprintf(stderr, "X Toolkit Error: %s\n", message); exit(l); } static void _XtDefaultWarning(message) String message; { (void)fprintf(stderr, "X Toolkit Warning: %s\n", message); return; } See Also XtError, XtSetErrorHandler, XtSetWarningHandler, XtWarning. 290 X Toolkit Intrinsics Reference Manual -- Xt - Error Handling XtErrorMsgHandler Name XtErrorMsgHandler m prototype for high-level error and warning handlers. Synopsis typedef void (*XtErrorMsgHandler)(String, String, String, String *, Cardinal *); String name; String type; String class; String defaultp; String *params; Cardinal *num_params; Arguments n ame type class defaultp params n um_pa rams String, Specifies the name that is concatenated with the specified type to form the resource name of the error message. Specifies the type that is concatenated with the name to form the resource name of the error message. Specifies the resource class of the error message. Specifies the default message to use if no error database entry is found. Specifies a pointer to a list of values to be substituted in the message. Specifies the number of values in the parameter list. Description Application-supplied error handling functions, for both warnings and fatal errors, are of type XtE r ro rMsgHandle r. The specified name can be a general nd of enr, le invalidParameters or invalid- Window, and the specified type gives exa information. Standard printf notation is used to substitute the parameters into the message. The default Toolkit-supplied XtErrorMsgHandler routines construct a string and pass the result to XtError and XtWarning, respectively. Low-level handlers are of type XtError- Handler(2). The error handler should make a call to XtGetErrorDatabase or XtAppGetError- Database to retrieve the address of the loaded error database (if a database other than the default is being used), and XtGetErrorDatabaseText or XtAppGetErrorDatabase- Text to actually retdeve the message from the database. The example below shows the default error message handler from the MIT R3 In/nsics. static void _XtDefaultErrorMsg (name,type,class,defaultp,params,num_params) String name, type, class,defaultp; String* params; Cardinal* num_params; X Toolkit Intfinsics Reference Manual 291 XtErrorMsgHandler (continued) Xt- Error Handling char buffer[1000],message[1000]; XtGetErrorDatabaseText(name,type,class,defaultp, buffer, I000); if (num_params == NULL) XtError(buffer); else { (void) sprintf(message, buffer, params[0], params[l], params[2], params[3], params[4], params[5], params[6], params[7], params[8], params[9]); XtError(message); See Also XtSetErrorHandler, XtSetMsgHandler. 292 X Toolkit Intnsics Reference Manual m Xt - Event Handling XtEventHandler Name XtEventHandler D prototype procedure to handle input events. Synopsis typedef void (*XtEventHandler) (Widget, Widget w; caddr t client data; XEvent *event; caddr t, XEvent *) ; Arguments w Specifies the widget for which to handle events. client data Specifies the client-specific information registered with the event handler, which is usually NULL if the event handler is registered by the widget itself. even t Specifies the triggering event for this handler. Description Event handlers are of type XtEventHandler. A widget expresses interest in an event by calling XtAddEventHandler, specifying as the handler argument a pointer to a proce- dure of this type. Most widgets need not use event handlers explicitly. Instead they use the Xt Resource Man- ager to accept events and invoke procedures based on the interpretation of multiple events. The example below shows the code from xterm that registers an event handler for Focus In and FocusOut events, and a gutted version of the event handler itself. extern void HandleFocusChange(); static void VTInitialize (request, new) XtermWidget request, new; { XtAddEventHandler(topLevel,/* widget */ FocusChangeMask, /* event mask */ FALSE,/* non-maskable events */ HandleFocusChange,/* event handler */ (Opaque)NULL);/* client_data */ /*ARGSUSED*/ void HandleFocusChange(w, unused, event) Widget w; register XFocusChangeEvent *event; X Toolkit Intrinsics Reference Manul 293 XtEventHandler (continued) Xt- Event Handling caddr t unused;/* client data */ _ -- if (event->type == FocusIn) /* process FocusIn */ else { /* process FocusOut */ } ) See Also Section 1.4, "Events," Section 1.5, "Translations and Actions," XtAddEventHandler. 294 X Toolkit Intrinsics Reference Manual XtExposeProc (continued) Xt - Methods BitmapEdit widgets take advantage of this, too. They manufacture an artificial event contain- ing the bounding box of the cell to be toggled, and pass it when they call expose. This causes the expose method to copy only that one cell that was just updated to the window. The example below shows the expose method from the BitmapEdit widget described in Vol- ume Four, X Toolkit lntrinsics Programming Manual. /* ARGSUSED */ static void Redisplay(cw, event) BitmapEditWidget cw; XExposeEvent *event; { register int x, y; unsigned int width, height; if (:XtIsRealized(cw)) return; if (event) { /* called from btn-event */ x = event->x; y = event->y; width = event->width; height = event->height ; } else { /* called because of expose */ x = O; y= O; width = cw->bitmapEdit .pixmap_width_in_pixels; height = cw->bitmapEdit.pixmap_height in pixels; } if (DefaultDepthOfScreen(XtScreen(cw)) == i) XCopyArea (XtDisplay (cw), cw->bitmapEdit.big_picture, XtWindow (cw), cw->bitmapEdit.copy_gc, x + cw->bitmapEdit.cur_x, y + cw->bitmapEdit.cur_y, width, height, x, y); else XCopyPlane (XtDisplay (cw), cw->bitmapEdit.big_picture, XtWindow (cw), cw->bitmapEdit.copy_gc, x + cw->bitmapEdit.cur_x, y + cw->bitmapEdit.cur_y, width, height, x, y, I); } Note that the expose method first checks to see that the widget is realized using Xt- IsRealized. This is a precaution against the unlikely event that an instance of this widget is suddenly destroyed or unrealized by an application while Expose events are still pending. If this did happen, drawing on the nonexistent window would cause an X protocol error. Next, BitmapEdit's expose method sets the rectangle it will redraw based on the event passed in by Xt. We also call this method directly from the action that processes button presses. That action routine creates a pseudo-event to pass to expose to describe the area to be drawn. 296 X Toolkit Intn'nsics Reference Manual XtExposeProc (continued) Xt - Methods typedef struct { short xl, x2, yl, y2; } Box, BOX, BoxRec, *BoxPtr; typedef struct _XRegion { long size; long numRects; BOX *rects; BOX extents; } REGION; See Also Core(3) 298 X Toolkit Intrinsics Reference Manual XtGeometryHandler (continued) Xt - Geometry Management typedef enum _XtGeometryResult { XtGeometryYes, /* Request accepted */ XtGeometryNo, /* Request denied */ XtGeometryAlmost,/* Request denied but willing to take reply */ XtGeometryDone /* Request accepted and done */ } XtGeometryResult; The XtWidgetGeometry structure is similar to but not identical m the coesponding Xlib structure: typedef unsigned long XtGeometryMask; typedef struct { XtGeometryMask request_mode; Position x, y; Dimension width, height; Dimension border width; -- Widget sibling; int stack mode; -- } XtWidgetGeomet ry; The request_mode definitions are from : #define CWX (i<<0) #define CWY (i<: #define Above 0 #define Below 1 #define TopIf 2 #define BottomIf 3 #define Opposite 4 The Intrinsics also support the following value: #define XtSMDontChange 5 300 X Toolkit Intrinsics Reference Manual Xt - Geometry Management (continued) XtGeometryHandler For precise definitions of Above, Below, TopIf, BottomIf, and Opposite, see the refer- ence page for XConfigureWindow in Volume Two, Xlib Reference Manual. XtSMDont- Change indicates that the widget wants its current stacking order preserved. See Also Section 1.8, "Geometry Management,'" Chapter 11, Geometry Management, in Volume 4, X Toolkit lntrinsics Programming Manual. X Toolkit Intrinsics Reference Manual 301 Xt - Methods (continued) XtlnitProc whatever size is explicitly given, but they should compute a reasonable size if no size is requested. The request and new arguments provide the necessary information for how a subclass knows the difference between a specified size and a size computed by a superclass. The request widget is the widget as originally requested. The new widget starts with the values in the request, but it has been updated by all superclass initialization procedures called so far. A subclass initialize procedure can compare these two to resolve any potential conflicts. In the above example, the subclass with the visual surround can see if the width and height in the request widget are zero. If so, it adds its surround size to the width and height fields in the new widget. If not, it must make do with the size originally specified. The new widget will become the actual widget instance record. Therefore, the initialization procedure should do all its work on the new widget (the request widget should never be modified), and if it needs to call any routines that operate on a widget, it should specify new as the widget instance. See Also Section 1.1, "Widget Lifecycle," Core(3). X Toolkit Intrinsics Reference Manual 303 XtlnputCallbackProc Xt- Event Handling Name XtlnputCallbackProc -- prototype procedure called to handle file events. Synopsis typedef void (*XtInputCallbackProc)(caddr_t, int *, XtInputId *); caddr t client data; int *source; Xt Input Id *id; Arguments client data Specifies the client data that was registered for this procedure in XtApp- AddI nput. source Specifies the source file descriptor generating the event. i d Specifies the ID returned from the corresponding XtAppAddInput call. Description An XtInputCallbackProc is registered by calling XtAddInput or XtAppAddInput. i d is the return value from the procedure that registered it. An Xt InputCallbackProc is called when there is activity in file source. A procedure of this type is called to handle the type of file activity (input, output) it was registered for. The example below shows an XtInputCallbackProc named get_file_input togeer with the application used to register it. /* header files */ /* ARGSUSED */ get_file_input(client_data, fid, id) caddr t client data;/* unused */ _ -- int *fid; XtInputId *id; ( char buf[BUFSIZ]; int nbytes; int i; if ((nbytes = read(*fid, buf, BUFSIZ)) == -I) perror("get_file_input"); if (nbytes) for (i = 0; i < nbytes; i++) putchar (buf [i] ) ; main(argc, argv) int argc; 304 X Toolkit Intrinsics Reference Manual Xt- Event Handling (continued) XtlnputCallbackProc char **argv; { Widget topLevel, goodbye; FILE *fid; String filename; topLevel = XtInitialize(argv[0], "XFileInput", NULL, 0, &argc, argv); if (argv[l] == NULL) { fprintf(stderr, "xfileinput: filename must be specified on\ command line.\n"); exit(l); } filename = argv[l]; /* open file */ if ((fid = fopen(filename, "r")) == NULL) fprintf(stderr, "xfileinput: couldn't open input file"); /* register function to handle that input, NULL arg is client data */ -- XtAddInput(fileno(fid), XtInputReadMask, get_file_input, NULL); XtRealizeWidget(topLevel); XtMainLoop(); See Also XtAddInput, XtAppAddInput. Xt Intrinsics Reference Manual 305 XtKeyProc Xt - Keyboard Handling Name XtKeyProc -- prototype procedure to translate a key. Synopsis typedef void (*XtKeyProc)(Display *, Modifiers *, KeySym *) ; Display *display; KeyCode *keycode; Modifiers *modifiers; Modifiers *modifiers return; -- KeySym *keysym_return; KeyCode *, Modifiers *, Arguments display keycode modifiers Specifies the display from which to translate the events. Specifies the keycode that is to be translated. Specifies the mask that indicates what modifier keys (Shift, Meta, Control, etc.) are pressed. modifiers return -- Specifies the mask of modifier keys that the function actually evaluated in making the conversion. keysym_return Specifies the resulting keysym. Description The Resource Manager provides support for automatically translating keycodes in incoming key events into keysyms. Keycode-to-keysym translator procedure pointers are of type Xt- KeyP roc. This procedure takes a keycode and modifiers and produces a keysym. For any given key trans- lator function, modifiers return will be a constant that indicates the subset of all modifi- ers that are examined by the key translator. The default wanslator is XtTranslateKey, an XtKeyProc that uses Shift and Lock modifi- ers with the interpretations defined by the core protocol. The MIT R3 code for Xt- TranslateKey and associated internal routines is shown below. void _XtBuildKeysymTable(dpy, pd) Display* dpy; XtPerDisplay pd; int count; KeySym lower_return, upper_return, nbd,*bd; count = dpy->max_keycode-dpy->min_keycode+l; pd->keysyms = XGetKeyboardMapping( dpy, dpy->min_keycode,count,&pd->keysyms_per_keycode); if (pd->keysyms_per_keycode > I) 306 Xt Inn'nsics Reference Manual Xt- Keyboard Handling (continued) XtKeyProc nbd = (dpy->max_keycode - dpy->min_keycode + i) * pd->keysyms_per_keycode; for (bd = pd->keysyms; bd < (pd->keysyms + nbd); bd += pd->keysyms_per_keycode) { if ((*(bd+l)) == NoSymbol) { XtConvertCase(dpy,*bd, &lower_return, &upper_return); *bd = lower return; -- *(bd+l) = upper_return; } } } KeySym _XtKeyCodeToKeySym(dpy, pd, keycode,col) Display* dpy; XtPerDisplay pd; KeyCode keycode; int col; /* copied from Xlib */ int ind; if (pd->keysyms == NULL) { _XtBuildKeysymTable(dpy,pd); /* pd->keysyms*/ } if (col < 0 II col >= pd->keysyms_per_keycode) return (NoSymbol); if (keycode < dpy->min_keycode I I keycode > dpy->max_keycode) return(NoSymbol); ind = (keycode - dpy->min_keycode) * pd->keysyms_per_keycode + col; return (pd->keysyms[ind]); ) void XtTranslateKey(dpy, keycode, modifiers, modifiers_return, keysym_return) Display *dpy; KeyCode keycode; Modifiers modifiers; Modifiers *modifiers return; -- KeySym *keysym_return; XtPerDisplay perDisplay; perDisplay = XtGetPerDisplay(dpy); -- *modifiers return = StandardMask; -- if ((modifiers & StandardMask) == O) *keysym_return =_XtKeyCodeToKeySym(dpy, perDisplay, keycode, 0); else if ((modifiers & (ShiftMask I LockMask)) != 0) *keysym_return =_XtKeyCodeToKeySym(dpy, perDisplay, keycode, l); else *keysym_return = NoSymbol; Xt Innsics Reference Manual 307 XtKeyProc (continued) Xt- Keyboard Handling The XtPerDisplay structure referenced in the example is an internal structure used to keep track of variables that may differ on a display-by-display basis. Structures typedef unsigned int Modifiers; Modifiers will be made up of the bitwise OR the following masks: ShiftMask LockMask ControlMask ModlMask Shift key was depressed. Caps Lock key was depressed. Control key was depressed. Key defined as Modl was depressed. Mod5Mask Key defined as Mod5 was depressed. StandardMask (ShiftMask I LockMask). For a more detailed discussion of processing keyboard input, see Chapter 13, Miscellaneous Toolkit Programming Techniques, in Volume Four, X Toolkit lntrinsics Programming Manual. See Also XtSetKeyTranslator, XtTranslateKeycode, XtTranslateKey. 308 Xt Intrinsics Reference Manual  Xt - Selectlons / XtLoseSelectionProc Name XtLoseSelectionProc m prototype procedure called by the Intrinsics when another client claims the selection. Synopsis typedef void (*XtLoseSelectionProc) (Widget, Atom *); Widget w; Atom *selection; Arguments sel ecti on Specifies the widget that has lost selection ownership. Specifies the atom that describes the selection type. Description This procedure is called by the Intrinsics when the specified widget loses the selection. The XtLoseSelectionProc is registered when a widget asserts selection ownership with Xt- OwnSelection. The Intrinsics use this procedure to inform the former selection owner after the selection changes hands. Note that this procedure does not ask the widget to lose the selection owner- ship. Chapter 10, Inter-Client Communications, in Volume Four, X Toolkit Intrinsics Programming Manual, presents a complete example widget that both sends and receives data using selections. See Also XtDisownSelection, XtGet SelectionValues, XtOwnSelection. X Toolkit Intdnsics Reference Manual 309 XtOrderProc Xt - Geometry Management m Name XtOrderProc b prototype procedure for ordering the children of composite widget instances. Synopsis typedef Cardinal (*XtOrderProc) (Widget) ; Widget w; Arguments Specifies the widget Description Instances of composite widgets need to specify about the order in which their children are kept. For example, an application may want a set of command buttons in some logical order grouped by function, and it may want buttons that represent file names to be kept in alphabetical order. The inse rt_po s it ion method in a composite widget instance is of type XtOrde rP roc. Composite widgets that allow clients to order their children (usually homogeneous boxes) can call their widget instance's insert_position method from the class' insert child method to determine where a new child should go in its children array. Thus, a client of a com- posite class can apply different sordng criteria to widget instances of the class, passing in a dif- ferent insert_position method when it creates each composite widget instance. The return value of the insert_position method indicates how many children should go before the widget Returning zero indicates that the widget should go before all other children, and returning hum children indicates that it should go after all other children. The default -- insert_position method returns num_children and can be overridden by a specific composite widget's resource list or by the argument list provided when the composite widget is created. 310 X Toolkit Intrinsics Reference Manual -- Xt - Methods ' XtProc Name XtProc -- prototype procedure to initialize data for a widget class. Synopsis typedef void (*XtProc) ; Description An XtProc is a procedure to initialize data at program startup time. One-time initialization can be performed here, such as parsing accelerator tables, registering type converters, run-time alterations to data structures, or other actions that cannot be performed at compile time. The Core class_init method is of this type. See Also Core(3) X Toolkit Innsics Reference Manual 311 Xt - Methods (continued) XtRealizeProc A widget class can inherit its realize method from its superclass during class initialization. The realize method defined for Core calls XtCreateWindow with the passed value mask and attributes and with windowClass and visual set to CopyFrom- -- Parent. Both CompositeWidgetClass and ConstraintWidgetClass inherit this realize method, and most new widget subclasses can do the same. The most common noninherited realize methods set bit_gravity in the mask and attri- butes to the appropriate vnlue and then create the window. For example, depending on its justi- fication, Label sets bit_gravity to WestGravity, CenterGravity, or East- Gravity. Consequently, shiJnking it just moves the bits appropriately, and no Expose event is needed for repainting. If a composite widget's children should be realized in a particular order (typically to control the stacking order), the widget should call XtRealizeWidget on its children itself in the appropriate order from within its own tea l i ze method. Widgets that have children and that are not a subclass of compositeWidgetClass are responsible for calling XtRealizeWidget on their children, usually from within the realize method. Structures /* Definitions for valuemask argument. These control which fields in * XSetWindowAttributes structure should be used. */ typedef struct { Pixmap background_pixmap; unsigned long background_pixel; Pixmap border_pixmap; unsigned long border_pixel; int bit_gravity; int win_gravity; int backing_store; unsigned long backing_planes; unsigned long backing_pixel; Bool save under; -- long event mask; -- long do_not_propagate_mask; Bool override redirect; -- Colormap colormap; Cursor cursor; } XSetWindowAttributes; /* background or None or ParentRelative * / /* background pixel */ /* border of the window */ /* border pixel value */ /* one of bit gravity values */ /* one of the window gravity values */ /* NotUseful, WhenMapped, Always */ /* planes to be preserved if possible */ /* value to use in restoring planes */ /* should bits under be saved (popups) */ /* set of events that should be saved */ /* set of events that should not propagate */ /* boolean value for override-redirect */ /* colormap to be associated with window */ /* cursor to be displayed (or None) */ See Also Section 1.1, "Widget Lifecycle," XtC tea t eWindow, Xt Rea i i zeWidget, Core(3). X Toolkit Intrinsics Reference Manual 313 Xt Resou rce Defau ItProc Xt- Resource Management Name XtResourceDefaultProc m prototype procedure passed as a resource converter of type Xt- RCalIProc. Synopsis typedef void (*XtResourceDefaultProc)(Widget, Widget w; int offset; XrmValue *value; int, XrmValue *) Arguments offset value Specifies the widget whose resource is to be obtained. Specifies the offset of the field in the widget record. Specifies the resource value to fill in. Description Every resource has a representation type. There are 26 types defined by the Intrinsics, and additional user types can be created by registering a type converter for them (see XtAdd- Converter). Two special representation types (XtRImmediate and XtRCallProc) are usable only as default resource types. XtRImmediate indicates that the value in the default address field of the XtResource structure is the actual value of the resource rather than the address of the value. The value must be in correct representation type for the resource. No conversion is possible since there is no source representation type. XtRCallProc indicates that the value in the default_address field of the XtResource structure is a procedure variable. This procedure is automatically invoked with the widget, resource offset, and a pointer to the XrmValue in which to store the result and is an XtResourceDefaultProc. The XtResourceDefaultProc procedure should fill in the addr field of the value with a pointer to the default data in its correct type. The default address field in the resource structure is declared as a caddr t. On some machine architectures, this may be insufficient to hold procedure variables. The example below shows an XtResourceDefaultProc used to obtain a pointer to the current screen at runtime. / *ARGSUSED* / void XtCopyScreen(widget, offset, value) Widget widget ; int offset ; XrmValue *value; { value->addr = (caddr t) (&widget->core.screen) ; 314 X Toolkit Intrinsics Reference Manual Xt- Resource Management (continued) XtResourceDefaultProc See Also Section 1.7, "Resources" X Toolkit Intrinsics Reference Manual 315 Xt - Selections (continued) XtSelectionCall backProc Chapter 10, Inter-Client Communications, in Volume Four, X Toolkit Intrinsics Programming Manual, presents a complete example widget that both sends and receives data using selections. See Also XtDisownSelection, XtGetSelectionValue, XtGetSelectionValues, XtOwn- Selection. X Toolkit Intrinsics Reference Manual 317 -- Xt - Methods XtSetValuesFunc Name XtSetValuesFunc n prototype procedure for various set va lue s methods. -- Synopsis typedef Boolean (*XtSetValuesFunc) (Widget, Widget, Widget); Widget current; Widget request; Widget new; Arguments current request new Specifies a copy of the widget as it was before the xt Setva lues call. Specifies a copy of the widget with all values changed as asked for by the xtSetValues call before any class set values procedures have been -- called. Specifies the widget with the new values that are actually allowed. Description The Core set values method and Constraint set values method are both of type xt- -- -- SetValuesFunc. The Constraint set values method operates in the context of the child. -- This means its widget arguments are instances of the child, not the parent, even though they are class fields of the (Constrain0 Parent. current, request, and new are widget instance records of the appropriate widget class. new reflects values that have been modified by superclass set values methods, request -- reflects changes made only by the xtSetValues call itself, current was the widget instance at the time of the call, reflecting no changes. A widget can refer to request, to resolve conflicts between current and new. Any changes that the widget needs to make should be made to new. An XtSetValuesFunc returns a Boolean indicating TRUE if the widget should be redisplayed and FALSE otherwise, set_values methods should not do any work in response to anticipated changes in geometry because xtSetValues will eventually perform a geome- try request. The request might be denied. If the widget actually changes size in response to a xtSetValues, its resize method is called. Widgets should make geometry-related changes there. An XtSetValuesFunc cannot assume that the widget is realized, since it is permissible for an application to call XtSetValues before a widget is realized. See Also XtSetValues, Constraint(3), Core(3). X Toolkit Intrinsics Reference Manual 319 XtStringProc Xt - Methods Name XtSJngproc  protype procedure for display_accelerator meod. Synopsis typedef void (*XtStringProc) (Widget, Widget w; String string; String) Arguments string Specifies the widget instance requiring redisplay. Provides the string representation of the accelerators currently registered for the widget. Description This is the type of the display_accelerator method in the Core class. The string may not be an exact replica of the event it was registered with. Instead, it represents a translation in canonical form. See Also XtD i sp i a yAc ce le rat o r 320 X Toolkit Intrinsics Reference Manual --Xt- Event Handling XtTimerCallbackProc Name XtTimerCallbackProc n prototype callback procedure invoked when timeouts expire. Synopsis typedef void (*XtTimerCallbackProc)(caddr_t, XtIntervalId *); caddr t client data; XtIntervalId *id; Arguments client data Specifies the client data that was registered for this procedure in XtApp- -- AddT imeOut. id Specifies the ID returned from the corresponding XtAppAddTimeOut call. Description An XtTimerCallbackProc is invoked in response to an expired timing interval, as set by XtAddT imeOut. For a periodic wakeup, the callback procedure must call XtAddTimeOut again from this pro- cedure. See Also Xt AddT imeOut, Xt AppAddT imeOut, Chapter 8, More Input Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual. X Toolkit Intrinsics Reference Manual 321 XtWorkProc (continued) Xt- Prototype Procedures "dialog",/* widget name */ dialogWidgetClass,/* widget class */ pshell,/* parent widget*/ NULL,/* argument list*/ 0/* arglist size */ ); dialogDone = XtCreateManagedWidget( "dialogDone",/* widget name */ commandWidgetClass,/* widget class */ dialog,/* parent widget*/ NULL,/* argument list*/ 0/* arglist size */ ); XtAddCallback(dialogDone, XtNcallback, DialogDone, dialog); return(TRUE);/* makes Xt remove this work proc automatically */ } Remember that Xt canna interrupt a work procedure while it is runng; e procedure must voluntarily give up conol by returning, and it must do so quicy to avoid slowg ur respond. See Also XtAppAddWorkProc 324 X Toolkit Intrinsics Reference Manual Intrinsics-mandated Widget Classes This section contains reference pages for the Intrinsics-mandated widget classes: Core, Composite, Constraint, and Shell. It describes the class and instance records for these widget classes, and provides a detailed description of each of their meth- ods. As an exception to the general rule that reference pages are organized alphabeti- cally, in this section they are presented in order of inheritance: Core, Composite, Constraint, and Shell. m Xt - Widget Types Core Name Core Widget Class -- fundamental, top-level widgeL Synopsis #include StringDefs.h #include Intrinsic.h Description The Core widget class is the most fundamental type of widgeL All other widgets are subclasses of it. Widgets consist of two data structures: a class record (CoreClassPart) and an instance record (CorePart). Both records are defined in . Volume Four, X Toolkit Intrinsics Programming Manual, discusses how Inlrinsics support object-oriented pro- gramming. The Core widget itself is described there also, as is a template widget. The Release 3 data structures are described here. They differ only in minor ways from the Release 2 structures. The class and instance structure are defined in . The ClassPart is defined below: typedef struct CoreClassPart { WidgetClass superclass; /* pointer to superclass ClassRec */ String class name; /* widget resource class name */ -- Cardinal widget_size; /* size in bytes of widget record */ XtProc class initialize; /* class initialization proc */ -- XtWidgetClassProc class_part_initialize; /* dynamic initialization */ Boolean class inited; -- XtInitProc initialize; XtArgsProc initialize hook; XtRealizeProc realize; XtActionList actions; Cardinal num actions; XtResourceList resources; Cardinal num resources; -- XrmClass xrm class; Boolean compress_motion; Boolean compress_exposure; Boolean compress_enterleave; Boolean visible interest; XtWidgetProc destroy; XtWidgetProc resize; XtExposeProc expose; XtSetValuesFunc set values; XtArgsFunc set_values_hook; XtAlmostProc set values almost; _ -- XtArgsProc get_values_hook; XtAcceptFocusProc accept_focus; XtVersionType version; /* has class been initialized? */ /* initialize subclass fields */ /* notify that initialize called */ /* XCreateWindow for widget */ /* widget semantics name to proc map */ /* number of entries in actions */ /* resources for subclass fields */ /* number of entries in resources */ /* resource class quarkified */ /* compress MotionNotify for widget */ /* compress Expose events for widget*/ /* compress enter and leave events */ /* select for VisibilityNotify */ /* free data for subclass pointers */ /* geom manager changed widget size */ /* redisplay window */ /* set subclass resource values */ /* notify that set values called */ -- /* set values got "Almost" geo reply */ -- /* notify that get_values called */ /* assign input focus to widget */ /* version of Intrinsics used */ X Toolkit Intrinsics Reference Manual 327 Core (continued) Xt - Widget Types struct _XtOffsetRec *callback_private; /* list of callback offsets */ String tm table; /* state machine */ -- XtGeometryHandler query_geometry; /* return preferred geometry */ XtStringProc display_accelerator; /* display your accelerator */ caddr t extension; /* pointer to extension record */ -- } CoreClassPart; The core instance record is defined as foows: typedef struct CorePart { -- Widget self; WidgetClass widget_class; Widget parent; XrmName xrm name; -- /* pointer to widget itself */ /* pointer to widget's ClassRec */ /* parent widget */ /* widget resource name quarkified */ Boolean being_destroyed; /* marked for destroy */ XtCallbackList destroy_callbacks;/* who to call when widget destroyed */ caddr t constraints; /* constraint record */ /* window position */ /* window dimensions */ /* window border width */ /* is widget geometry managed? */ /* is widget sensitive to user events */ /* are all ancestors sensitive? */ /* private to event dispatcher */ /* translation management */ /* accelerator translations */ /* window border pixel */ /* window border pixmap or NULL */ /* list of pop ups */ /* how many pop ups */ /* widget resource name */ /* window's screen */ /* colormap */ /* window ID */ /* number of planes in window */ /* window background pixel */ /* window background pixmap or NULL */ /* is window mapped and not occluded? */ /* map window if it is managed? */ Position x, y; Dimension width, height; Dimension border width; -- Boolean managed; Boolean sensitive; Boolean ancestor sensitive; -- XtEventTable event table; -- XtTMRec tm; XtTranslations accelerators; Pixel border_pixel; Pixmap border_pixmap; WidgetList popup_list; Cardinal num_popups; String name; Screen *screen; Colormap colormap; Window window; Cardinal depth; Pixel background_pixel; Pixmap background_pixmap; Boolean visible; Boolean mapped_when_managed; } CorePart; The default values for the core fields, which are filled in by the Core resource list and the Core initialize method, are: 328 X Toolkit Intdnsics Reference Manual Xt - Widget Types (continued) Core Field self widget_class parent xrm name -- being_destroyed destroy_callbacks constraints X Y width height border width -- managed sensitive ancestor sensitive -- event table -- tm accelerators border_pixel border_pixmap popup_list num_popups name screen colormap window depth background_pixel background_pixmap visible mapped_when_managed Default Value Address of the widget structure (may not be changed). widget_class argument to XtCreateWidget (may not be changed). parent argument to XtCreateWidget (may not be changed). Encoded name argument to XtCreateWidget (may not be changed). Parent's bein g_des t toyed value. NULL NULL 0 0 0 0 FALSE TRUE Bitwi AND of parent's sensitive and ances- tor sensitive. Initialized by the Event Manager. Initialized by the Resource Manager. NULL XtDe fau it Fo reground NULL NULL 0 name argument to XtCreateWidget (may not be changed). Parent's screen; top-level widget gets it from display specifier (may not be changed). Default colormap for the screen. NULL Parent's depth; top-level widget gets root window depth. XtDefaultBackground NULL TRUE TRUE X Toolkit Intrinsics Reference Manual 329 Xt - Widget Types (continued) Core all superclass data as well as its own. Sometimes it is possible to anticipate the display needs of several levels of subclass widgets. For example, rather than maintaining separate display procedures for the widgets Command, Label, and Toggle, they could share a single redisplay routine that uses display state informa- tion as follows: Boolean invert Boolean highlight Dimension highlight_width Label would have invert and highlight always FALSE and have highlight_width zero. Command would dynamically set highlight and highlight_width, but it would leave invert always FALSE. Finally, Toggle would dynamically set all three. In this case, the expose methods for Command and Toggle inherit their superclass' expose method. Some widgets may use substantial computing resources to display data. However, this effort is wasted if the widget is not actually visible on the screen and is obscured by another application or is iconified. The visible field in the Core widget instance structure provides a hint to the widget that it need not display data. This field is guaranteed TRUE by the time an Expose event is processed if the widget is visible but is usually FALSE if the widget is not visible. Widgets can use or ignore the visible hint. If they ignore it, they should have visi- ble interest in their widget class record set FALSE. In such cases, the visible field is -- initialized TRUE and never changes. If visible_interest is TRUE, the Event Manager asks for VisibilityNotify events for the widget and updates the visible field accord- ingly. resize The resize method is of type XtWidgetProc. It takes a widget as its only argumenL The x, y, width, height and border width fields of the widget contain the new values. The -- resize method should recalculate the layout of internal data as needed. If a widget simply draws itself from whatever size is placed in the core height and width instance variables, it does not need a resize method. If nothing needs to be recalculated, it can specify NULL for the resize field in its class record. Other widgets need to know when they have changed size so that they can change the layout of their displayed data to match the new size. (For example, a widget may choose a new smaller font, if its size has been diminished.) The widget must treat resize as a command, not as a request. Nor can a widget appeal by issuing an XtMakeGeometryRequest or XtMake- ResizeRequest from its resize method. When a-parent widget is resized, it should reconfigure its children. When a parent resizes a child, it updates the geometry fields in the widget, configures the window if the widget is real- ized, and calls the child's resize method to notify the child. (See XtConfigureWidget.) X Toolkit Intnsics Reference Manual 333 Core (continued) Xt - Widget Types initialize hook This method is of type XtArgsProc. It is passed the new created widget instance, the Arg- List passed to XtCreateWidget, and its size. If this method is not NULL, it is called immediately after the corresponding initialize method or in its place if the initialize method is NULL. The initialize_hook method allows a widget instance to initialize nonwidget data using information from the specified argument list. For example, the Text widget has subparts that are not widgets, yet these subparts have resources that can be specified by means of the resource file or an argument list. display_accelerator The display_accelerator method is of type XtSt ringProc. The display_accelerator method is used to notify the widget that the Inllinsics have aug- mented another widget's translations with its accelerators. The accelerators themselves are specified as a translation table in the class accelerators field. They must refer to actions that either are global or are valid in the context of the widget When the Intlinsics invoke the display_acclerator method, it is passed the accelerator table in an internal canonical form. This form is still text, but it differs.from the original source of the accelerator table itself. query_geometry The query_geometry procedure pointer is of type XtGeomet ryHandler: typedef XtGeometryResult (*XtGeometryHandler) (Widget, XtWidgetGeometry *, XtWidgetGeometry *) ; Widget w; XtWidgetGeometry *request; XtWidgetGeometry * geometry_ret urn; The query_geomet ry method is expected to examine the bits set in request->request_mode, evaluate the preferred geometry of the widget, and store the result in geometry_return (setting the bits in geometry_return->request_mode corresponding to those geometry fields that it cares about). If the proposed geometry change is acceptable without modification, the query_geometry method should return Xt- GeometryYes. If at least one field in geometry_return is different from the correspond- ing field in request or if a bit was set in geometry_return that was not set in request, the query_geometry method should return XtGeomet ryAlmost. If the preferred geometry is identical to the current geometry, the query_geometry method should return Xt- Geomet ryNo. After calling the query_geomet ry method or if the que ry_geomet ry field is NULL, Xt- QueryGeometry examines all the unset bits in geometry_return->request_mode and sets the corresponding fields in geomet ry_return to the current values from the widget instance. If CWStackMode is not set, the stack mode field is set to XtSMDontChange. -- XtQueryGeometry returns the value returned by the query_geometry method or Xt- Geomet ryYes if the query_geomet ry field is NULL. 336 X Toolkit Intrinsics Reference Manual Xt - Widget Types (continued) Core Therefore, the caller can interpret a return of XtGeomet ryYes as not needing to evaluate the contents of reply and, more importantly, not needing to modify its layout plans. A return of XtGeometryAlmost means either that both the parent and the child expressed interest in at least one common field and the child's preference does not match the parent's intentions or that the child expressed interest in a field that the parent might need to consider. A return value of XtGeometryNo means that both the parent and the child expressed interest in a field and that the child suggests that the field's current value is its preferred value. In addition, whether or not the caller ignores the return value or the reply mask, it is guaranteed that the geome- try_return structure contains complete geometry information for the child. Parents are expected to call XtQueryGeometry in their layout routine and wherever other information is significant after change_managed has been called. The change_managed method may assume that the child's current geometry is its preferred geometry. Thus, the child is still responsible for storing values into its own geometry during its in it iali z e method. X Toolkit Intrinsics Reference Manual 337 Composite Xt - Widget Types Name Composite Widget Class m defines methods for geometry management. Synopsis #include StringDefs.h #include Intrinsic.h Description The Composite widget defines methods for geometry management. Any widget that is capable of managing child widgets should be a subclass of the Composite widget. (See also Sec- tion 1.8, "Geometry Management.") The class and instance structures are defined in . The composite class part is defined as follows: typedef struct _CompositeClassPart { XtGeometryHandler geometry_manager;/* geometry manager for children */ XtWidgetProc change_managed; /* change managed state of child */ XtWidgetProc insert child; /* physically add child to parent */ -- XtWidgetProc delete child; /* physically remove child */ -- caddr t extension; /* pointer to extension record */ -- } CompositeClassPart,*CompositePartPtr; The composite instance record is defined as follows: typedef struct _CompositePart { WidgetList children; Cardinal num children; -- Cardinal num slots; -- XtOrderProc insert_position; } CompositePart,*CompositePtr; /* array of ALL widget children */ /* total number of widget children */ /* number of slots in children array */ /* compute position of new child */ Note that this instance record contains a method. (Methods are generally kept in the class record, but many different subclasses of Composite may need a private XtOrderProc, so it is kept in the instance record.) The predefined class record and pointer for CompositeClassRec are: extern CompositeClassRec compositeClassRec; extern WidgetClass compositeWidgetClass; The opaque types CompositeWidget and CompositeWidgetClass and the opaque variable compositeWidgetClass are defined for generic operations on widgets that are a subclass of Compo s it eWidget. 338 X Toolkit Intrinsics Reference Manual Xt - Widget Types (continued) Com posite inform XtMakeGeometryRequest that it does not need to do the configuration itself. Although XtMakeGeometryRequest resizes the widget's window, it does not call the widget class' resize procedure if the geometry manager returns XtGeometryYes. The requesting widget must perform whatever resizing calculations are needed explicitly. If the geometry manager chooses to disallow the request, the widget cannot change its geome- try. The value of the reply parameter is undefined, and the geometry manager returns Xt- Geomet ryNo. Sometimes the geometry manager cannot satisfy the request exactly, but it may be able to sat- isfy a similar request. That is, it could satisfy only a subset of the requests (for example, size but not position) or a lesser request (for example, it cannot make the child as big as the request but it can make the child bigger than its current size). In such cases, the geometry manager fills in reply with the actual changes it is willing to make, including an appropriate mask, and returns XtGeometryAlmost. If a bit in reply, request_mode is zero, the geometry manager does not change the corresponding value if the reply is used immediately in a new request. If a bit is one, the geometry manager does change that element to the corresponding value in geometry_return. More bits may be set in reply, request_mode than in the original request if the geometry manager intends to change other fields should the child accept the compromise. When XtGeomet ryAlmost is returned, the widget must decide if the compromise suggested in reply is acceptable. If it is, the widget must not change its geometry directly; rather, it must make another call to XtMakeGeomet ryRequest. If the next geometry request from this child uses the reply filled in by an XtGeometry- Almost return and if there have been no intervening geometry requests on either its parent or any of its other children, the geometry manager must grant the request, if possible. That is, if the child asks immediately with the returned geometry, it should get an answer of Xt- GeometryYes. However, the user's window manager may affect the final outcome. To return an XtGeometryYes, the geometry manager frequently rearranges the position of other managed children by calling XtMoveWidget. However, a few geometry managers may sometimes change the size of other managed children by calling XtResizeWidget or Xt- ConfigureWidget. If XtCWQueryOnly is specified, the geometry manager must return how it would react to this geometry request without actually moving or resizing any widgets. Geometry managers must not assume that the request and reply arguments point to inde- pendent storage. The caller is permitted to use the same field for both, and the geometry man- ager must allocate its own temporary storage, if necessary. insert_position Instances of composite widgets need to specify information about the order in which their chil- dren are kept. For example, an application may want a set of command buttons in some logical order grouped by function, and it may want buttons that represent file names to be kept in alphabetical order. X Toolkit Intrinsics Reference Manual 341 Com posite (continued) Xt - Widget Types The insert_position method pointer in a composite widget instance is of type Xt- Orde rP roc." typedef Cardinal (*XtOrderProc) (Widget) ; Widget w; w specifies the widget. Composite widgets that allow clients to order their children (usually homogeneous boxes) can call their widget instance's insert_position method from the class' insert_child method to determine where a new child should go in its children array. Thus, a client of a com- posite class can apply different sorting criteria to widget instances of the class, passing in a dif- ferent insert_position method when it creates each composite widget instance. The return value of the insert_position method indicates how many children should go before the widget. Returning zero indicates that the widget should go before all other children, and returning num._children indicates that it should go after all other children. The default insert_position method returns num__children and can be overridden by a specific composite widget's resource list or by the argument list provided when the composite widget is created. See Also Core(3) 342 X Toolkit Intrinsics Reference Manual m Xt - Widget Types Constraint Name Constraint Widget Class -- provides data structures for a widget's parent. Synopsis #include StringDefs.h #include Intrinsic.h Description Constraint widgets are a subclass of compositeWidgetClass. Their name is derived from the fact that they may manage the geometry of their children based on constraints associated with each child. These constraints can be as simple as the maximum width and height the par- ent will allow the child to occupy or as complicated as how other children should change if this child is moved or resized. Constraint widgets let a parent define resources that are supplied for their children. For example, if the Constraint parent defines the maximum sizes for its children, these new size resources are retrieved for each child as if they were resources that were defined by the child widget. Accordingly, constraint resources may be included in the argument list or resource file just like any other resource for the child. Constraint widgets have all the responsibilities of normal composite widgets and, in addition, must process and act upon the constraint information associated with each of their children. To make it easy for widgets and the Intrinsics to keep track of the constraints associated with a child, every widget has a constrains field, which is the address of a parent-specific structure that contains constraint information about the child. If a child's parent is not a subclass of constraintWidgetClass, then the child's constraints field is NULL. Note that the constraint data structures are transparent to the child; that is, when a child is man- aged by a parent that is a subclass of a constraint widget, there is no difference, as far as the child is concerned, from being managed by a normal composite widget. The values passed to the parent's constraint set_values method are the same as those pas- sed to the child's class set_values method. A class can specify NULL for the set_values field of the ConstraintPart if it need not compute anything. The constraint set_va lues method should recompute any constraint fields derived from con- straint resources that are changed. Further, it should modify the widget fields as appropriate. For example, if a constraint for the maximum height of a widget is changed to a value smaller than the widget's current height, the constraint set_values method should reset the height field in the widget. The class and instance structures are defined in . X Toolkit Intrinsics Reference Manual 343 Shell Xt - Wldget Types-- Name Shell Widget Class -- application resources linking window managers. Synopsis #include StringDefs.h #include Intrinsic.h Description Widgets negotiate their size and position with their parent widget, that is, the widget that directly contains them. Widgets at the top of the hierarchy do not have parent widgets. Instead, they must deal with the outside world. To provide for this, each top-level widget is encapsulated in a special widget, called a Shell. Shell widgets, a subclass of the Composite widget, encapsulate other widgets and can allow a widget to avoid the geometry clipping imposed by the parent/child window relationship. They also can provide a layer of communication with the window manager. Shells have been designed to be as nearly invisible as possible. Clients have to create them (the top-level widget returned by a call to XtInitialize or XtCreateApplication- Context is a Shell widget, as is a pop-up widget created with XtPopup), but they should never have to worry about their sizes. If a shell widget is resized from the outside (typically by a window manager), the shell widget also resizes its child widget automatically. Similarly, if the shell's child widget needs to change size, it can make a geometry request to the shell, and the shell negotiates the size change with the outer environment. Clients should never attempt to change the size of their shells directly. There are seven different types of shells. Only four of these are public (i.e., should be instan- tiated by applications): OverrideShell TransientShell TopLevelShell ApplicationShell Used for shell windows that completely bypass the window manager (for example, pop-up menu shells). A subclass of Shell (see below). Used for shell windows that can be manipulated by the window manager but are not allowed to be iconified separately (for example, Dialog boxes that make no sense without their associated applica- tion). They are iconified by the window manager only if the main application shell is iconified. A subclass of VendorShell (see below). Used for normal top-level windows (for example, any additional top- level widgets an application needs). A subclass of VendorShell (see below). Used by the window manager to define a separate application instance, which is the main top-level window of the application. A subclass of TopLevelShell. 346 X Toolkit Intrinsics Reference Manual Shell (continued) Xt - Widget Types int vendor_specific; } VendorShellPart; typedef struct { int empty; } TransientShellPart; typedef struct { String icon name; -- Boolean iconic; } TopLevelShellPart; typedef struct { char *class; XrmClass xrm class; -- int argc; char **argv; } ApplicationShellPart; The furl definitions of e various shell widge have shell fields foflowg composite fields: typedef struct { CorePart core; CompositePart composite; ShellPart shell; } ShellRec, *ShellWidget; typedef struct { CorePart core; CompositePart composite; ShellPart shell; OverrideShellPart override; } OverrideShellRec, *OverrideShellWidget; typedef struct { CorePart core; CompositePart composite; ShellPart shell; WMShellPart wm; } WMShellRec, *WMShellWidget; typedef struct { CorePart core; CompositePart composite; ShellPart shell; WMShellPart wm; VendorShellPart vendor; } VendorShellRec, *VendorShellWidget; typedef struct { CorePart core; CompositePart composite; ShellPart shell; WMShellPart wm; VendorShellPart vendor; TransientShellPart transient; 350 X Toolkit Intrinsics Reference Manual Xt - Widget Types (continued) Shell TopLevel shells have the the following additional resources: Field Default Value icon_name Shell widget's name iconic FALSE The icon_name field is the string to display in the shell's icon, and the iconic field is an alter- native way to set the initialState resource to indicate that a shell should be initially displayed as an icon. Application shells have the following additional resources: Field Default Value argc 0 argv NULL The a rgc and a rgv fields are used to initialize the standard property te COMMAND. -- X Toolkit Innsics Reference Manual 353 Athena Widgets This section contains alphabetically-organized reference pages for the Athena widgets. This widget set is not part of the Intrinsics but was developed by MIT's Project Athena to demonstrate their use. It is documented here, since the Athena Widgets are used in the examples for Volume Four. Each reference page provides a description of the widget class and documents the include files for the widget, its class hierarchy, resources, translations and actions, and its programmatic interface, including both the Intrinsics calls to create or man- age the widget and any functions the widget itself exports. --Xt - Athena Widgets Box Name boxWidgetClass -- geometry-managing box widgeL Synopsis #include #include #include /* in R2 */ #include widget = XtCreateWidget(widget, boxWidgetClass,... ); Class Hierarchy Core - Composite - Box Description The Box widget provides geometry management of arbiu'ary widgets in a box of a specified dimension. The children are rearranged when resizing events occur either on the Box or when children are added or deleted. The Box widget always attempts to pack its children as closely as possible within the geometry allowed by its parent. Box widgets are commonly used to manage a related set of Command widgets and are fre- quently called ButtonBox widgets, but the children are not limited to buttons. The children are arranged on a background that has its own specified dimensions and color. Resources When creating a Box widget instance, the following resources are retrieved from the argument list or from the resource database: NalTle XtNbackground XtNbackground- Pixmap XtNborderColor XtNborderPixmap XtNborderWidth XtNdestroy- Callback XtNhSpace XtNheight XtNmappedWhen- Managed XtNtranslations XtNvSpace Type Pixel Pixmap Pixel Pixmap Dimension XtCallbackList Dimension Dimension Boolean TranslationTable Dimension Default XtDefault- Background None XtDefault- Foreground None 1 NULL 4 See below TRUE None Description Window background color Window background pixmap Window border color Window border pixmap Border width on button box Callbacks for XtDe st royWi dget Pixel distance left and right of children Viewing height of inner window Whether XtMapWidget is automatic Event-to-action translations Pixel distance top and bottom of chil- dren X Toolkit Intrinsics Reference Manual 357 -- Xt - Athena Widgets Command Name commandWidgetClass -- command button activated by pointer click. Synopsis #include #include #include /* in R2 */ #include widget = XtCreateWidget(widget, commandWidgetClass,... ); Class Hierarchy Core -- Simple -- Label -- Command Description The Command widget is a rectangular button that contains a text or pixmap label. When the pointer cursor is on the button, the button border is highlighted to indicate that the button is available for selection. Then, when a pointer button is pressed and released, the button is selected, and the application's callback routine (specified by the XtNcallback resource) is invoked. Resources When creating a Command widget instance, the following resources are retrieved from the argument list or from the resource database: Name XtNbackground XtNbackground- Pixmap XtNbitmap XtNborderColor XtNborderPixmap XtNborderWidth XtNcallback XtNcursor XtNdestroy- Callback XtNfont XtNforeground XtNheight XtNhighlight- Thickness XtNinsensitive- Border Pixel Pixmap Pixmap Pixel Default XtDefault- Background None None XtDefault- Foreground Description Window background color Window background pixmap Pixmap to display in place of the label Window border color Pixmap Dimension XtCallbackList Cursor XtCallbackList None 1 NULL None NULL Window border pixmap Width of button border Callback for button select Pointer cursor Callbacks for XtDestroyWidget XFontStruct* Pixel Dimension Dimension Pixmap XtDefaultFont XtDefault- Foreground Text height 2 Gray Label font Foreground color Button height Width of border to be highlighted Border when not sensitive X Toolkit Intrinsics Reference Manual 359 Command (continued) Xt - Athena Widgets Na.nle XtNinternal- Height XtNinternalWidth XtNjustify XtNlabel XtNmappedWhen- Managed XtNresize XtNsensitive XtNtranslations XtNwidth XtNx XtNy Dimension Dimension XtJustify String Boolean Boolean Boolean Translation- Table Dimension Position Position Default 4 XtJustifyCenter Button name TRUE TRUE TRUE See below Text width 0 0 Descdpfion Internal border height for highlighting Internal border width for highlighting Type of text alignment Button label Whether XtMapWidget is automatic Whether to auto-resize in SetVa lue s Whether widget receives input Event-to-action translations Button width x coordinate y coordinate Note that the Command widget supports two callback lists: XtNdestroyCallback and XtNcallback. The notify action executes the callbacks on the XtNcallback list. The call data argument is unused. -- The new resources (not inherited from superclasses) associated with the Command widget are: XtNbitmap Specifies a bitmap to display in place of the text label. See the description of this resource in the Label widget for further details. XtNheight Specifies the height of the Command widget. The default value is the minimum height that will contain: XtNinternalheight + height ofXtNlabel + XtNinternalHeight If the specified height is larger than the minimum, the label string is cen- tered vertically. XtN Int erna iHe ight Represents the distance in pixels between the top and bottom of the label text or bitmap and the horizontal edges of the Command widget. HighlightThickness can be larger or smaller than this value. XtNInternalWidth XtNjustify Represents the distance in pixels between the ends of the label text or bit- map and the vertical edges of the Command widget. Highlight- Thickness can be larger or smaller than this value. Specifies left, center, or right alignment of the label string within the Command widget. If it is specified within an ArgList, one of the values XtJustifyLeft, XtJustifyCenter, or XtJustifyRight can be specified. In a resource of type string, one of the values left, center, or right can be specified. 360 X Toolkit Intrinsics Reference Manual m Xt - Athena Widgets Dialog Name dialogWidgetClass -- dialog box widget. Synopsis #include #include #include /* in R2 */ #include widget = XtCreatewidget(widget, dialogwidgetClass .... ); Class Hierarchy Core - Composite - Consla'aint - Form -o Dialog Description The Dialog widget implements a commonly used interaction semantic to prompt for auxiliary input from a user. For example, you can use a Dialog widget when an application requires a small piece of information, such as a filename, from the user. A Dialog widget is simply a spe- cial case of the Form widget that provides a convenient way to create a preconfiguredform. The typical Dialog widget contains three areas. The first line contains a description of the func- tion of the Dialog widget, for example, the string Filename:. The second line contains an area into which the user types input. The third line can contain buttons that let the user confirm or cancel the Dialog input. Resources When creating a Dialog widget instance, the following resources are retrieved from the argu- ment list or from the resource database: Nalnc XtNbackground XtNbackground- Pixmap XtNborderColor XtNborderPixmap XtNborderWidth XtNdestroy- Callback XtNheight XtNlabel- XtNmappedWhen- Managed XtNmaximumLength XtNsensitive XtNtranslations Pixel Pixmap Pixel Pixmap Dimension XtCallbackList Dimension String Boolean int Boolean TranslationTable Default XtDefault- Background None XtDefault- Foreground None 1 NULL Computed atcreate Label name TRUE 256 TRUE None Description Window background color Window background pixmap Window border color Window border pixmap Width of border in pixels Callbacks for XtDestroyWidget Height of dialog S-ing to be displayed Whether XtMapWidget  automatic Maximum number of input characters Whether widget receives input Event-to-action translations X ToolkR Intrinsics Reference Manual 363 mXt - Athena Widgets Form Name formWidgetClass m geometry-managing widget implementing constraints on children. Synopsis #include #include #include /* in R2 */ #include widget = XtCreateWidget(widget, formWidgetClass,... ); Class Hierarchy Core -- Composite -- Constraint - Form Description The Form widget can contain an arbitrary number of children or subwidgets. The Form pro- vides geometry management for its children, which allows individual control of the position of each child. Any combination of children can be added to a Form. The initial positions of the children may be computed relative to the positions of other children. When the Form is resized, it computes new positions and sizes for its children. This computation is based upon information provided when a child is added to the Form. Resources When creating a Form widget instance, the following resources are retrieved from the argument list or from the resource database: NalTle XtNbackground XtNbackground- Pixmap XtNborderColor XtNborderPixmap XtNborderWidth XtNdefault- Distance XtNdestroy- Callback XtNheight XtNmappedWhen- Managed XtNsensitive Type Pixel Pixmap Pixel Default XtDefault- Background None XtDefault- Foreground Description Window background color Window background pixmap Window border color Pixmap Dimension int XtCallbackList Dimension Boolean Boolean None 1 4 NULL Computed at realize TRUE TRUE Window border pixmap Width of border in pixels Default value for XtNho ri zDi stance and XtNvert Di stance Callbacks for XtDestroyWidget Height of form Whether XtMapWidget is automatic Whether widget receives input X Toolkit Intrinsics Reference Manual 365 Form (continued) Xt - Athena Widgets NaiTle XtNtranslations XtNwidth XtNx XtNy Type TranslationTable Dimension Position Position Default None Computed at realize NULL NULL Description Event-to-action translations Width of form x position of form y position of form Constraints When creating children to be added to a Form, the following additional resources are retrieved from the argument list or from the resource database. Note that these resources are maintained by the Form widget even though they are stored in the child. Nalne XtNbottom XtNfromHoriz XtNfromVert XtNhorizDistance XtNleft XtNresizable XtNright XtNtop XtNvertDistance Type XtEdgeType Widget Widget int XtEdgeType Boolean XtEdgeType XtEdgeType int Default XtRubber NULL NULL XtdefaultDistance XtRubber FALSE XtRubber XtRubber XtdefaultDistance Description See text See text See text See text See text TRUE if allowed to resize See text See text See text These resources are called constraints, and can be specified to the Form to indicate where the child should be positioned within the Form. The resources XtNhorizDistance and XtNfromHoriz let the widget position itself a specified number of pixels horizontally away from another widget in the form. As an example, XtNhorizDistance could equal 10 and XtNfromHoriz could be the widget ID of another widget in the Form. The new widget will be placed 10 pixels to the right of the widget defined in XtNfromHoriz. If XtNfromHoriz equals NULL, then XtNhorizDistance is measured from the left edge of the Form. Similarly, the resources XtNvertDistance and XtNfromVert let the widget position itself a specified number of pixels vertically away from another widget in the Form. If Xt- NfromVert equals NULL, then XtNvertDistance is measured from the top of the Form. Form provides a StringToWidget conversion procedure. Using this procedure, the resource database may be used to specify the XtNfromHoriz and XtNfromVert resources by widget name rather than widget ID. The string value must be the name of a child of the same Form widget parent. The XtNtop, XtNbottom, XtNleft, and XtNright resources tell the Form where to posi- tion the child when the Form is resized. XtEdgeType is defined in and is one of XtChainTop, XtChainBottom, XtChainLeft, XtChainRight, or XtRubber. 366 X Toolkit Intrinsics Reference Manual Grip Xt - Athena Widgets-- Name gripWidgetClass m attachment point for dragging other widgets. Synopsis #include #include #include #include widget = XtCreateWidget(widget, /* in R2 */ gripWidgetClass,... ); Class Hierarchy Core -- Simple -- Grip Description The Grip widget provides a small region in which user input events (such as ButtonPress or ButtonRelease) may be handled. The most common use for the grip is as an attachment point for visually repositioning an object, such as the pane border in a VPaned widget. Resources When creating a Grip widget instance, the following resources are retrieved from the argument list or from the resource database: Name Type Default Description XtNborderColor Pixel XtDefault- Window border color Foreground XtNborderPixmap XtNborderWidth XtNcallback XtNcursor XtNdestroy- Callback XtNforeground Pixmap Dimension XtCallbackList Cursor XtCallbackList None 0 None None NULL Pixel XtDefault- Foreground Window border pixmap Width of the border in pixels Action routine Cursor for the grip Callback for x t De s t r oyWi dge t Window background color XtNheight XtNmappedWhen- Managed XtNsensitive XtNtranslations XtNwidth XtNx XtNy Dimension Boolean Boolean TranslationTable Dimension Position Position 8 TRUE TRUE None 8 0 0 Height of the widget Whether XtMapWidget is automatic Whether widget should receive input Event-to-action translations Width of the widget x coordinate within parent y coordinate within parent Note that the Grip widget displays its region with the foreground pixel only. 368 X Toolkit Intrinsics Reference Manual Label Xt - Athena Widgets m Name labelWidgetClass -- widget to display a non-editable string. Synopsis #include #include #include #include widget = XtCreateWidget(widget, Class Hierarchy Core --> Simple --> Label /* in R2 */ labelWidgetClass,... ); Description A Label is an noneditable text string or pixmap that is displayed within a window. The string is limited to one line and can be aligned to the left, right, or center of its window. A Label can neither be selected nor directly edited by the user. Resources When creating a Label widget instance, the following resources are retrieved from the argu- ment list or from the resource database: Nalne XtNbackground XtNbackground- Pixmap XtNbitmap XtNborderColor Class Type Pixel Pixmap Pixmap Pixel Pixmap Dimension Cursor XtCallbackList XFontStruct* Pixel Dimension Pixmap Dimension Dimension XtJustify String Default XtDefault- Background None None XtDefault- Foreground None 1 None NULL XtDefaultFont XtDefault- Foreground Text height Gray XtJustifyCenter Label name Description Window background color Window background pixmap Pixmap to display in place of the label Window border color Window border pixmap Border width in pixels Pointer cursor Callbacks for x t De s t royWi dge t Label font Foreground color Height of widget Border when not sensitive See note See note Type of text alignment String to be displayed XtNborderPixmap XtNborderWidth XtNcursor XtNdestroy- Callback XtNfont XtNforeground XtNheight XtNinsensitive- Border XtNinternal- Height XtNinternalWidth XtNjustify XtNlabel 370 X Toolkit Intrinsics Reference Manual BXt - Athena Wldgets List Name listWidgetClass m widget for managing row-column geometry. Synopsis #include #include #include #include widget = XtCreatewidget(widget, listWidgetClass,... ); Class Hierarchy Core  Simple  Grip /* in R2 */ Description The List widget is a rectangle that contains a list of strings formatted into rows and columns. When one of the strings is selected, it is highlighted, and an application callback routine is invoked. Resources When creating a List widget instance, the following resources are retrieved from the argument list or from the resource database: NalTIC XtNbackground XtNbackground- Pixmap XtNborderColor XtNborderPixmap XtNborderWidth XtNcallback XtNcolumnSpacing XtNcursor XtNdefaultColumns XtNdestroy- Callback XtNfont XtNforceColumns XtNforeground XtNheight XtNinsensitive- Border Pixel Pixmap Pixel Pixmap Dimension XtCallbackList Dimension Cursor int XtCallbackList XFontStruct* Boolean Pixel Dimension Pixmap Default XtDefault- Background None XtDefault- Foreground None 1 NULL 6 left_ptr 2 NULL XtDefaultFont FALSE XtDefault- Foreground Contaslist exactly Gray Description Window background color Window background pixmap Window border color Window border pixmap Width of border Selection callback function Space between columns in the list Pointer cursor Number of columns to use Callbacks for xt De st royWidge t Font for list text Force the use of XtNdefault- Columns Foreground (text) color Height of widget Border when not sensitive X Toolkit Intrinsics Reference Manual 373 List (continued) Xt - Athena Widgets NaTne XtNinternalHeight XtNinternalWidth XtNlist XtNlongest XtNmappedWhen- Managed XtNnumberStrings XtNpasteBuffer XtNrowSpacing XtNsensitive XtNtranslations XtNverticalList XtNwidth XtNx XtNy Type Dimension Dimension String * int Boolean int Boolean Dimension Boolean Translation- Table Boolean Dimension Position Position Default List name Longest item TRUE Number of strings FALSE 4 TRUE None FALSE Contains list exactly 0 0 Description Spacing between list and widget edges Spacing between list and widget edges An array of swings that is the list Length of the longest list item in pixels Whether XtMapWidget is automatic Number of items in the list Copy the selected item to cut buffer 0 Space between rows in the list Whether widget receives input Event-to-action translations Specify the layout of list items Width of widget Widget x coordinate Widget y coordinate The new resources associated with the List widget are: XtNcolumnSpacLng Specify the amount of space between each of the rows and columns in XtNrowSpacing the list. XtNdefaultColumns Specifies the default number of columns, which is used when neither the width nor the height of the List widget is specified or when xt- NforceColumns is TRUE. XtNforceColumns Specifies that the default number of columns is to be used no matter what the current size of the List widget is. XtNheight Specifies the height of the List widget. The default value is the mini- mum height that will contain the entire list with the spacing values specified. If the specified height is larger than the minimum, the list is put in the upper left comer. XtNinternalHeight Represents a margin, in pixels, between the top and bottom of the list and the edges of the List widget. XtNinternalWidth Represents a margin, in pixels, between the left and right edges of the list and the edges of the List widget. XtNlist Specifies the array of text strings that is to displayed in the List widget. If the default for XtNnumberStrings is used, the list must 374 X Toolkit Intrinsics Reference Manual Xt - Athena Widgets (continued) List The XtListShowCurrent function returns a pointer to an XtListReturnStruct structure that contains the currently highlighted item. If the value of the index member is XT LIST_NONE, the string member is undefined, which indicates that no item is currently selected. X Toolkit Intrinsics Reference Manual 377 Scrollbar Xt - Athena Widgets-- Name scrollbarWidgetClass -- widget to control scrolling of viewing area in another widget. Synopsis #include #include #include /* in R2 */ #include widget = XtCreateWidget(widget, scrollbarWidgetClass,... ); Class Hierarchy Core --) Simple --) Scroll Description The Scrollbar widget is a rectangular area that contains a slide region and a thumb (slide bar). A Scrollbar can be uscd alone, as a valuator, or within a composite widget (for example, a Viewport). A Scrollbar can be aligned either vertically or horizontally. When a Scrollbar is created, it is drawn with the thumb in a contrasting color. The thumb is normally used to scroll client data and to give visual feedback on the percentage of the client data that is visible. Each pointer button invokes a specific scrollbar action. That is, given either a vertical or hori- zontal alignment, the pointer button actions will scroll or return data as appropriate for that alignment. Pointer buttons 1 and 3 do not perform scrolling operations by default. Instead, they return the pixel position of the cursor on the scroll region. When pointer button 2 is clicked, the thumb moves to the current pointer position. When pointer button 2 is held down and the pointer is moved, the thumb follows the pointer. The cursor in the scroll region changes depending on the current action. When no pointer but- ton is pressed, the cursor appears as an arrow that points in the direction that scrolling can occur. When pointer button 1 or 3 is pressed, the cursor appears as a single-headed arrow that points in the logical direction that the client will move the data. When pointer button 2 is pressed, the cursor appears as an arrow that points to the thumb. While scrolling is in progress, the application receives notification from callback procedures. For both scrolling actions, the callback returns the Scrollbar widget ID, client data, and -- the pixel position of the pointer when the button was released. For smooth scrolling, the call- back routine returns the scroll bar window, cl i ent_data, and the current relative position of the thumb. When the thumb is moved using pointer button 2, the callback procedure is invoked continuously. When either button 1 or 3 is pressed, the callback procedure is invoked only when the button is released and the client callback procedure is responsible for moving the thumb. Resources When creating a Scrollbar widget instance, the following resources are retrieved from the argu- ment list or from the resource database: 378 X TooAkit Intrinsics Reference Manual Xt - Athena Widgets (continued) Scrollbar Name XtNbackground XtNbackground- Pixmap XtNborderColor XtNborderPixmap XtNborderWidth XtNdestroy- Callback XtNforeground XtNheight XtNjumpProc XtNlength XtNmappedWhen- Managed XtNorientation XtNscrollDCursor XtNscrollHCursor XtNscrollLCursor XtNscrollProc XtNscrollRCursor XtNscrollUCursor XtNscrollVCursor XtNsensitive XtNshown XtNthickness XtNthumb XtNtop XtNtranslations XtNwidth XtNx XtNy Pixel Pixmap Pixel Pixmap Dimension XtCallbackList Pixel Dimension XtCallbackList Dimension Boolean XtOrientation Cursor Cursor Cursor XtCallbackList Cursor Cursor Cursor Boolean float Dimension Pixmap float Translation- Table Dimension Position Position Default White None XtDefault- Foreground None NULL Black See below NULL None TRUE XtorientVertical XC sb down arrow _ XC sb h double _ arrow XC sb left arrow _ NULL XC sb right_arrow XC_sb_up_arrow XC sb v double _ arrow TRUE NULL 14 Gray NULL See below See below NULL NULL Description Window background color Window background pixmap Window border color Window border pixmap Width of button border Callbacks for xt De s t royWi dge t Thumb color Height of scroll bar Callback for thumb select Major dimension (height of XtorientVertical) V/hether XtMapWidget is auto- matic Orientation (vertical or horizon- tal) Cursor for scrolling down Idle horizontal cursor Cursor for scrolling left Callback for the slide region Cursor for scrolling right Cursor for scrolling up Idle vertical cursor Whether widget receives input Percentage the thumb covers Minor dimension (height if XtorientHorizontal) Thump pixmap Position on scroll bar Event-to-action translations Width of scroll bar x position of scroll bar y position of scroll bar The class for all cursor resources is xtCCursor. You can set the dimensions of the Scrollbar two ways. As for all widgets, you can use the Xt- Nwidth and XtNheight resources. In addition, you can use an alternative method that is independent of the vertical or horizontal orientation: X Toolkit Intrinsics Reference Manual 379 Scrollbar (continued) Xt - Athena Widgets w Specifies the Scrollbar widget ID. t o/9 Specifies the position of the top of the thumb as a fraction of the length of the Scrollbar. shown Specifies the length of the thumb as a fraction of the total length of the Scrollbar. XtScrollbarThumb moves the visible thumb to position (0.0- 1.0)and length (0.0- 1.0). Either top or shown can be specified as -1.0, in which case the current value is left unchanged. Values greater than 1.0 are truncated to 1.0. If called from XtNjumpProc, XtScrollbarSetThumb has no effect. 382 X Toolkit Intrinsics Reference Manual Tem plate (continued) Xt - Athena Widgets #define XtNdrawingColorl #define XtNdrawingColor2 #define XtNexposeCallback "drawingColorl" "drawingColor2" "exposeCallback" extern Pixel WindowColorl(/* Widget */); extern Pixel WindowColor2(/* Widget */); extern Font WindowFont(/* Widget */); Note that we have chosen to call the input callback list by the generic name, XtNcallback, rather than a specific name. If widgets that define a single user-input action all choose the same resource name then there is greater possibility for an application to switch between widgets of different types. Private Header File The private header file contains the complete declaration of the class and instance structures for the widget and any additional private dam that will be requid by anticipated subclasses of the widget. Information in the private header file is normally hidden om the application and is designed to be accessed only through oer public procedures, such as xt S e tva l ue s. The contents of the Template private header file, , are: #include /* XConsortium: TemplateP.h,v 1.2 88/10/25 17:31:47 swick Exp $ */ /* Copyright Massachusetts Institute of Technology 1987, 1988 */ #ifndef _TemplateP_h #define _TemplateP_h #include "Template.h" /* include superclass private header file */ #include /* define unique representation types not found in */ #define XtRTemplateResource typedef struct { int empty; } TemplateClassPart; typedef struct _TemplateClassRec { CoreClassPart core class; -- TemplateClassParttemplate_class; } TemplateClassRec; extern TemplateClassRec templateClassRec; typedef struct { /* resources */ char* resource; /* private state */ } TemplatePart; "TemplateResource" typedef struct _TemplateRec { 386 X Toolkit Intrinsics Reference Manual Xt - Athena Widgets (continued) Tern plate CorePart core; TemplatePart template; } TemplateRec; #endif _TemplateP_h The private header file includes the priva header file of i superclass, theby exposing the entke internal sucture of the widget. It may not ways be advantageous to do this; your own prect development style will dictate the appropria level of detl to expose in each module. The Window widget needs to declare two fields in i instance sucture to hold the drawing colors, a source field for the font and a field for the expose and user input callback lists: typedef struct { /* resources */ Pixel color I; -- Pixel color 2; -- XFontStruct* font; XtCallbackList expose_callback; XtCallbackList input_callback; /* private state */ /* (none) */ } WindowPart; Widget Source File The source code file implemen the widget class ielf. The unique put of this file is the decla- ration and initialization of the widget class record sucture and the declaration of all resources and action routines added by the widget class. The contents of the Templa implementation file, , are: #include /* XConsortium: Template.c,v 1.2 88/10/25 17:40:25 swick Exp $ */ /* Copyright Massachusetts Institute of Technology 1987, 1988 */ #include #include #include "TemplateP.h" static XtResource resources[] = { #define offset(field) XtOffset(TemplateWidget, template.field) /* {name, class, type, size, offset, default_type, default_addr}, */ { XtNtemplateResource, XtCTemplateResource, XtRTemplateResource, \\e sizeof(char*), offset(resource), XtRString, "default" }, #undef offset }; static void TemplateAction(/* Widget, XEvent*, String*, Cardinal* */); static XtActionsRec actions[] = ( /* (name, procedure}, */ X Toolkit Intrinsics Reference Manual 387 Tem plate (continued) Xt - Athena Widgets {"template", TemplateAction}, }; static char translations[] = " : template() \\en\\e " ; TemplateClassRec templateClassRec = { { /* core fields */ /* superclass */ /* class name */ -- /* widget_size */ /* class initialize */ -- /* class_part_initialize */ /* class inited */ -- /* initialize */ /* initialize hook */ -- /* realize */ /* actions */ /* num actions */ -- /* resources */ /* num resources */ -- /* xrm class */ -- /* compress_motion */ /* compress_exposure */ /* compress_enterleave */ /* visible interest */ -- /* destroy */ /* resize */ /* expose */ /* set values */ -- /* set values hook */ -- -- /* set values almost */ -- -- /* get_values_hook */ /* accept_focus */ /* version */ /* callback_private */ /* tm table */ -- /* query_geometry */ /* display_accelerator */ /* extension */ }, { /* template fields */ /* empty */ } }; (WidgetClass) &widgetClassRec, "Template", sizeof(TemplateRec), NULL, NULL, FALSE, NULL, NULL, XtInheritRealize, actions, XtNumber(actions), resources, XtNumber(resources), NULLQUARK, TRUE, TRUE, TRUE, FALSE, NULL, NULL, NULL, NULL, NULL, XtInheritSetValuesAlmost, NULL, NULL, XtVersion, NULL, translations, XtInheritQueryGeometry, XtInheritDisplayAccelerator, NULL WidgetClass templateWidgetClass = (WidgetClass)&templateClassRec; 388 X Toolkit Intrinsics Reference Manual Xt - Athena Widgets (continued) Tem plate The resource list for the Window widget might look le the following: static XtResource resources[] = { #define offset(field) XtOffset(WindowWidget, window.field) /* {name, class, type, size, offset, default_type, default addr}, */ -- { XtNdrawingColorl, XtCColor, XtRPixel, sizeof(Pixel), offset(color_l), XtRString, XtDefaultForeground }, { XtNdrawingColor2, XtCColor, XtRPixel, sizeof(Pixel), offset(color_2), XtRString, XtDefaultForeground }, { XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*), offset(font), XtRString, XtDefaultFont }, { XtNexposeCallback, XtCCallback, XtRCallback, sizeof(XtCallbackList), offset(expose_callback), XtRCallback, NULL }, { XtNcallback, XtCCallback, XtRCallback, sizeof(XtCallbackList), offset(input_callback), XtRCallback, NULL }, #undef offset }; The user input callback will be implemend by an action procedure that passes the event pointer as ca22_data. The action procedu is declared as: /* ARGSUSED */ static void InputAction(w, event, params, num_params) Widget w; XEvent *event; String *params;/* unused */ Cardinal *num_params;/* unused */ XtCallCallbacks(w, XtNcallback, (caddr t)event) ; -- } static XtActionsRec actions[] = { /* {name, procedure}, */ {"input", InputAction}, }; and the default input binding will be to execute the input callbacks on KeyPress and ButtonPress: static char translations[] = " :input() \\en\\e :input ( ) \\e In the class record declaration and initialization, the only field that is different from the Tem- plate is the expose procedure: /* ARGSUSED */ static void Redisplay(w, event, region) Widget w; XEvent *event; /* unused */ Region region; X Toolkit Intrinsics Reference Manual 389 Text (continued) Xt - Athena Widgets XtselectParagraph XtselectPosition XtselectWord Selects the entire paragraph (delimited by newline characters). Selects the current pointer position. Selects whole words (delimited by Whitespace) as the pointer moves onto them. The deult selectType array is: {XtselectPosition, XtselectWord, XtselectLine, XtselectParagraph, XtselectAll, XtselectNull} For the default case, two rapid pointer clicks highlight the current word, three clicks highlight the current line, four clicks highlight the current paragraph, and five clicks highlight the entire text. If the timeout value is exceeded, the next pointer click returns to the first entry in the selection array. The selection array is not copied by the Text widget. The client must allocate space for the array and cannot deallocate or change it until the Text widget is destroyed or until a new selection array is set. Translations and Actions Many standard keyboard editing facilities are supported by the event bindings. The following actions are supported: Cursor Movement forward-character backward-character forward-word backward-word forward-paragraph backward-paragraph beginning-of-line end-of-line next-line previous-line next-page previous-page beginning-of-file end-of-file scroll-one-line-up scroll-one-line-down New Line newline-and-indent newline-and-backup newline Kill kill-word backward-kill-word kill-selection Delete delete-next-character delete-previous-character delete-next-word delete-previous-word delete-selection Selection select-word select-all select-start select-adjust select-end extend-start extend-adjust extend-end Miscellaneous redraw-display insert-file do-nothing Unkill unkill stuff insert-selection 394 X Toolkit Intrinsics Reference Manual Xt - Athena Widgets (continued) Text Cursor Movement kill-to-end-of-line kill -to-end-of-paragraph Delete A page corresponds to the size of the Text window. For example, if the Text window is 50 lines in length, scrolling forward one page is the same as scrolling forward 50 lines. The delete action deletes a text item. The kill action deletes a text item and puts the item in the kill buffer (X cut buffer 1). The unkill action inserts the contents of the kill buffer into the text at the current position. The stuff action inserts the contents of the paste buffer (X cut buffer 0) into the text at the current position. The insert-selection action retrieves the value of a specified X selection or cut buffer, with fall-back to alternative selections or cut buffers. The default event bindings for the Text widget are: char defaultTextTranslations[] = ''\ CtrlF: 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\ CtrlB: CtrlD: CtrlA: CtrlE: CtrlH: CtrlJ: CtrlK: CtrlL: CtrlM: CtrlN: CtrlO: CtrlP: CtrlV: CtrlW: CtrlY: CtrlZ: MetaF: MetaB: MetaI: MetaK: MetaV: MetaY: MetaZ: :Metad: :MetaD: :Metah: :MetaH: :Meta\<: :Meta\>: :Meta]: X Toolkit Intrinsics Reference Manual 395 Text (conhnued) Xt - Athena Widgets typedef long XtTextPosition; void XtTextSetSelection(w, left, right) Widget w; XtTextPosition left, right; where: left ri gh t Specifies the window ID. Specifies the character position at which the selection begins. Specifies the character position at which the selection ends. If redisplay is not disabled, this function highlights the text and makes it the PRIMARY selection. To unhighlight previously highlighted text in a window, use XtTextUnset Select ion. void XtTextUnsetSelection(w) Widget w; To enable the application to get the character positions of the selected text, use XtText- GetSelectionPos. void XtTextGetSelectionPos(w, posl, pos2) Widget w; XtTextPosition *posl, *pos2; where: posl Specifies the window ID. Specifies a pointer to the location to which the beginning character position of the selection is returned. pos2 Specifies a pointer to the location to which the ending character position of the selection is returned. If the returned values are equal, there is no current selection. To enable an application to replace text, use XtTextReplace. int XtTextReplace(w, start_pos, end_pos, text) Widget w; XtTextPosition start_pos, end_pos; XtTextBlock *text; where: W start_pos end_pos text Specifies the window ID. Specifies the starting character position of the text replacement. Specifies the ending character position of the text replacement. Specifies the text to be inserted into the file. 398 X Toolkit Intrinsics Reference Manual Text (continued) Xt - Athena Widgets ArgList args; Cardinal num__args; The resources required by the source are qualified by the name and class of the parent and the sub-part name XtNtextSource and class XtCTextSource. TO deal|ocate s text stng source, use Xt St ringSourceDest roy. void XtStringSourceDestroy (source) XtTextSource source; The source must not be in use by any widget or an error will result. 402 X Toolkit Intrinsics Reference Manual  Xt - Athena Widgets VPaned Name vPanedWidgetClass -- geometry-managing widget for vertical tiles. Synopsis #include #include #include /* in R2 */ #include widget = XtCreateWidget(widget, vPanedWidgetClass,... ); Class Hierarchy Core --> Composite --> Constraint --> VPaned Description The VPaned widget manages children in a vertically tiled fashion. A region, called a grip, appears on the border between each child. When the pointer is positioned on a grip and pressed, an arrow is displayed that indicates the significant pane that is being resized. While keeping the pointer button down, the user can move the pointer up or down. This, in turn, changes the window borders, causing one pane to shrink and some other pane to grow. The cursor indicates the pane that is of interest to the user;, some other pane in the opposite direction will be chosen to grow or shrink an equal amount. The choice of alternate pane is a function of the XtNmin, XtNmax and XtNskipAdjust constraJn on the other panes. With the default bindings, button I reshes the pane above the selected grip, button 3 resizes the pane below the selected grip and button 2 reposifions the border between two panes only. Resources When creating a VPaned widget instance, the following resources are retrieved from the argu- ment list or from the resource database: NalTle XtNbackground XtNbackground- Pixmap XtNbetweenCursor XtNborderColor Type Pixel Default XtDefault- Background None Pixmap Cursor Pixel Pixmap Dimension XtCallbackList Pixel XC sb left arrow -- XtDefault- Foreground None NULL Black XtNborderPixmap XtNborderWidth XtNdestroy- Callback XtNforeground Description Window background color Window background pixmap Cursor for changing the bound- ary between two panes Window border color Window border pixmap Border width (pixels) Callbacks for XtDestroy- Widget Pixel value for the foreground color X Toolkit Intrinsics Reference Manual 405 VPaned (continued) Xt - Athena Widgets To delete an entire VPaned widget and all associated data structures, use XtDestroy- Widget and specify the widget ID of the VPaned widget. All the children of the VPaned widget are automatically destroyed at the same time. 408 X Toolkit Intrinsics Reference Manual Table A-1. Alphabetical Listing of Functions (continued) Function XtApp ... AddActions AddConverter AddInput AddTimeOut AddWorkProc CreateShell Error ErrorMsg GetErrorDatabase GetErrorDatabaseText GetSelectionTimeout MainLoop NextEvent PeekEvent Pending ProcessEvent SetErrorHandler SetErrorMsgHandler SetSelectionTimeout SetWarningHandler SetWarningMsgHandler Warning WarningMsg XtArgsFunc XtArgsProc XtAugmentTranslations XtBuildEventMask XtCallAcceptFocus XtCallbackExclusive XtCallbackNone XtCallbackNonexclusive XtCallbackPopdown XtCallbackProc XtCallCallbacks XtCalloc XtCaseProc XtCheckSubclass XtClass XtCloseDisplay XtConfigureWidget XtConvert XtConvertCase XtConverter Description Declare an action table and register it with the Resource Manager. Register a new resource convener for an application. Register a new file as an input source for a given application. Invoke a procedure after a specified timeout. Register a work procedure for a given application. Create additional top-level widget. Call the installed fatal error procedure. Call the high-level fatal error handler. Obtain the error database. Obtain the error database text for an error or a warning. Get the current selection timeout value. Process input from a given application. Return next event from an application's input queue. Nondestructively examine the head of an application's input queue. Determine if there are any events in an application's input queue. Process one input event. Register a procedure to be Register a procedure to be Set the Intnsics selection Register a procedure to be called on fatal error conditions. called on fatal error conditions. timeout. called on nonfatal error conditions. Register a procedure to be called on nonfatal error conditions. Call the installed nonfatal error procedure. Call the installed high-level warning handler. Protopc set values hook method. Protopc procedure for get_values_hook method. Nondestructively merge new translations with widget's existing ones. Retrieve a widget's event mask. Call a widget's accept_focus procedure. Callback function to pop up a widget. Callback function to pop up a widget. Callback function to pop up a widget. Pop down a widget from a callback routine. Prototype callback procedure. Execute the procedures in a widget's callback list. Allocate an array and initialize elements to zero. Prototype procedure called to convert the case of keysyms. In DEBUG mode, verify a widget's class. Obtain a widget's class. Close a display and remove it from an application context. Move and/or resize widget. Convert resource type. Determine upper-case and lower-case versions of a keysym. Prototype of a resource convener procedure. 412 X Toolkit Intrinsics Reference Manual Table A- 1. Alphabetical Listing of Functions (continued) Funcdon XtConvertSelectionProc XtCreate . . . ApplicationContext ApplicationShell ManagedWidget PopupShell Widget Window XtDatabase XtDestroy . . . ApplicationContext GC Widget XtDirectConvert XtDisownSelection XtDispatchEvent XtDisplay XtDisplayInitialize XtError XtErrorHandler XtErrorMsg XtErrorMsgHandler XtEventHandler XtExposeProc XtFree XtGeometryHandler XtGet ... ApplicationResources ErrorDatabase ErrorDatabaseText GC ResourceList SelectionTimeout SelectionValue SelectionValues Subresources Subvalues Values XtHasCallbacks XtInitialize XtInitProc XtInputCallbackProc Description Prototype procedure to return selection data Create an application context. Create an additional top-level widget. Create and manage a child widget. Create a pop-up shell. Create an instance of a widget. Create widget's working window. Obtain the resource database for a particular display. Destroy an application context and close its displays. Release 2 compatible function to free up read-only GCs. Destroy a widget instance. Perform resource conversion and cache result. Indicate that selection data is no longer available. Dispatch registered handlers for an event. Return the display pointer for the specified widget. Initialize a display and add it to an application context. Call the low-level fatal error handler. Prototype for low-level error and warning handlers. Call the high-level fatal error handler. Prototype for high-level error and warning handlers. Prototype procedure to handle input events. Prototype expose method used in Core widget class. Free an allocated block of storage. Prototype procedure to handle geometry requests. Update base-offset resource list (by application). Obtain the error database. Obtain the error database text for an error or a warning. Obtain a read-only, sharable GC. Retrieve default values for a resource list. Get the current selection timeout value. Obtain the complete selection data. Obtain selection data in multiple formats. Update base-offset resource list (by name or class). Copy from base-offset resource list to the argument list. Copy resources from a widget to the argument list. Determine the status of a widget's callback list. Initialize toolkit and display. Prototype initialize procedure for a widget class. Prototype procedure called to handle file events. Appendix A: Alphabetical and Group Summaries 413 Table A- 1. Alphabetical Listing of Functions (continued) Function XtInstall . . . Accelerators AllAccelerators XtIsComposite XtIsConstraint XtIsManaged XtIsRealized XtIsSensitive XtIsShell XtIsSubclass XtKeyProc XtLoseSelectionProc XtMainLoop XtMakeGeometryRequest XtMakeResizeRequest XtMalloc XtManageChild XtManageChildren XtMapWidget XtMergeArgLists XtMoveWidget XtNameToWidget XtNew XtNewString XtNextEvent XtNumber XtOffset XtOpenDisplay XtOrderProc XtOverrideTranslations XtOwnSelection XtParent XtParse . . . AcceleratorTable TranslationTable XtPeekEvent XtPending XtPopdown XtPopup XtProc XtProcessEvent Description Install a widget's accelerators on another widget. Install all accelerators from a widget and its descendants onto a desti- nation. Test whether a widget is a subclass of the Composite widget class. Test whether a widget is a subclass of the Constraint widget class. Determine whether a widget is managed by its parent. Determine whether a widget has been realized. Check the current sensitivity state of a widget. Test whether a widget is a subclass of the Shell widget class. Determine whether a widget is a subclass of a class. Prototype procedure to translate a key. Prototype procedure called by the Intrinsics when another client claims the selection. Continuously process events. Request parent to change child's geometry. Request parent to change child's size. Allocate storage. Add a widget to its parent's list of managed children. Add widgets to their parent's list of managed children. Map a widget to its display. Merge two ArgList structures. Move a widget on the display. Translate a widget name to a widget instance. Allocate storage for one instance of a data type. Copy an instance of a string. Return next event from input queue. Determine the number of elements in a fixed-size array. Determine the byte offset of a field within a structure. Open, initialize, and add a display to an application context. Prototype procedure for ordering the children of composite widget instances. Merge new translations, overwriting widget's existing ones. Indicate that selection data is available. Return the parent widget for the specified widget. Compile an accelerator table into its internal representation. Compile a translation table into its internal representation. Nondestructively examine the head of an application's input queue. Determine if there are any events in an application's input queue. Unmap a pop-up shell. Map a pop-up shell. Prototype procedure to initialize data for a widget class. Process one input event. 414 X Toolkit Intrinsics Reference Manual Boolean A typedef from used to indicate TRUE (1) or FALSE (0). Use either the symbols TRUE or FALSE, defined in or TRUE or FALSE, defined in . Cardinal A typedef from used to specify any unsigned numeric value. Dimension A typedef from 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 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 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 : Event Mask Symbol NoEventMask KeyPressMask KeyReleaseMask ButtonPressMask ButtonReleaseMask EnterWindowMask LeaveWindowMask PointerMotionMask PointerMotionHintMask ButtonlMotionMask Button2MotionMask Button3MotionMask Button4MotionMask Button5MotionMask ButtonMotionMask KeymapStateMask ExposureMask VisibilityChangeMask StructureNotifyMask ResizeRedirectMask SubstructureNotifyMask Circumstances No events Keyboard down events Keyboard up events Pointer button down events Pointer button up events Pointer window entry events Pointer window leave events All pointer motion events Fewer pointer motion events Pointer motion while button 1 down Pointer motion while button 2 down Pointer motion while button 3 down Pointer motion while button 4 down Pointer motion while button 5 down Pointer motion while any button down Any keyboard state change on EnterNotify, LeaveNotify, Focus In, or FocusOut Any exposure (except GraphicsExpose and NoExpose) Any change in visibility Any change in window configuration Redirect resize of this window Notify about reconfiguration of children 424 X Toolkit Intrinsics Reference Manual struct XDlsplay *display;l* Window root; /* int width, height; /* int mwidth, mheight; /* int ndepths; /* Depth *depths; /* int root_depth; /* Visual *root visual; /* GC default_gc; /* Colormap cmap; /* unsigned long white_pixel; unsigned long black_pixel;/* int max_maps, min_maps; /* int backing_store; /* Bool save unders; long root_input_mask; /* Screen; back pointer to display structure */ root window ID */ width and height of screen */ width and height of in millimeters */ number of depths possible */ llst of allowable depths on the screen */ bits per pixel */ root visual */ GC for the root root visual */ default colormap */ white and black pixel values */ max and min colormaps */ Never, WhenMapped, Always */ initial root input mask */ The xtScreen macro can be used in Xt to return the current screen. String A typedef for c h a r * An unsigned long value containing a time value in milliseconds. The constant CurrentTime is interpreted as the time in milliseconds since the server was started. The Time data type is used in event structures and as an argument to XtAddTimeOut. Widget A sucture returned by calls to create a widget such as xtInitialize, XtCreate- widget, XtCreateManagedwidget, and XtCreatePopupShell. The mem- bers of this structure should not be accessed dkecdy from applications; they should regard it as an opaque pointer. Type widget is actually a pointer to a widget instance structure. Widget code accesses instance variables from this structure. Window A structure mazined by the server, and known on the client side only by an integer ID. In Xt, a widget's window can be returned by the XtWindow macro. Given the window, the corresponding widget can be returned by XtWindowToWidget. XEvent A union of all flrly event structures. The fst member is always the type, so it is pos- sible to branch on the type, and do event-specific processing in each branch. For more information on the individual event structures, see Appendix C, Event Reference. XGCValues A structure defined in that is used to set the values in a Graphics Context using the XtGetGC function, or the Xlib functions XCreateGC, XChangeGC, or XGetGCValues. typedef struct { int function; /* logical operation */ unsigned long plane_mask; /* plane mask */ unsigned long foreground; /* foreground pixel */ unsigned long background; /* background pixel */ 426 X Toolkit Intfinsics Reference Manual int line width; -- int line_style; int cap_style; int join_style; int fill_style; int fill rule; -- int arc mode; -- Pixmap tile; Pixmap stipple; int ts x origin; int ts y origin; Font font; int subwindow mode; -- /* line width / /* LineSolld, LineOnOffDash, LineDoubleDash */ /* CapNotLast, CapButt, CapRound, CapProjecting */ /* JoinMiter, JoinRound, JoinBevel */ /* FillSolid, FillTiled, FillStippled, FillOpaqueStippled */ /* EvenOddRule, WindingRule */ /* ArcChord, ArcPieSllce */ /* pixmap for tiling operations */ /* 1 plane plxmap for stippling */ /* offset for tile or stipple operations */ /* default text font for text operations */ /* ClipByChildren, IncludeInferiors */ Bool graphics_exposures; /* should exposures be generated? */ int clip x origin; /* origin for clipping */ int clip y origin; Pixmap clip_mask; /* bitmap clipping; other calls for rects */ int dash offset; /* patterned/dashed line information */ -- char dashes; } XGCValues; For more information on e meaning and use of each of e members, see Chapter 5, The Grapcs Conte, in Volume One, Xlib Programmg Manual. The second gument of XgGegGC is a mask that specifies whh members of e structure e being t. See XgGCMask below for details. XrmDatabase A poter to an inrnal resource manager damtype. Members of is structure should not be cesd dkecdy. An XrmDatabase can be returned by e Xt c XtDatabase (a resoce damba) or XtGetE rro rDat abase (an eor mesge database). XrmOptionDescRec A sucture ud to define command le opfiom, pd to XtInitialize, Xt- DisplayInitialize, or XtOpenDisplay. The structure is defined  follows in : typedef struct { char *option; /* Option abbreviation in argv */ char *specifier;/* Resource specifier */ XrmOptionKind argKind; /* Which style of option it is */ caddr t value; /* Val to provide if XrmoptionNoArg */ } XrmOptionDescRec, *XrmOptionDescList; The vMue for e argKind element is specified by one of e foHowg enum vMues, defined in e me fde: typedef enum { XrmoptionNoArg, /* Value specified in OptionDescRec.value */ XrmoptionIsArg, /* Value is the option string itself */ XrmoptionStickyArg,/* Value immediately follows option */ XrmoptionSepArg, /* Value is next argument in argv */ XrmoptionResArg, /* Resource and value in next arg in argv */ XrmoptionSkipArg, /* Ignore this opt and next arg in argv */ Appendix B: X TooAkit Data Types 427 XrmoptionSkipLine /* Ignore this opt and rest of argv */ } XrmOptionKind; XrmOptionKind SeeXrmOptionDescRec. XrmValue A structure defined in , used in XtConvert and other resource con- version routines. typedef struct { unsigned int size; caddr t addr; } XrmValue, *XrmValuePtr; XrmValuePt r See XrmVa lue. XtAccelerators A pointer to an opaque internal type, a compiled accelerator table. A pointer to an Xt- Accelerators sUmcture is returned by a cl to XtParseAcceleratorTable. Usually, the compiled accelerator table is produced automatically by resource conversion of a string accelerator table stored in a resource file. XtActionList A typedef for _XtActionsRec, defined as follows in : typedef struct XtActionsRec *XtActionList; -- typede f struct XtActionsRec { -- char *string; XtActionProc proc; } XtActionsRec; Actions are added by cIs to XtAddActions or XtAppAddActions. By conven- tion, the string and the function name are identical, except that the function name begins with an upper-case letter, as in the example: static XtActionsRec two_quits [] = { {"confirm", Confirm}, {"quit", Quit}, }; This mapping from strings to function pointers is necessary to allow translation tables to be specified in resource t-des, which are made up entirely of strings. XtActionProc The typedef for an action procedure. See XtActionProc(2) for defils. XtAddressMode An enumerated type that specifies the possible values for the address mode field of an XtConvertArgRec. See XtConvertArgRec below for details. XtAppContext A pointer  an internal structure used to hold data specific to a particular application context. An XtAppContext can be returned by a call to 428 X rooR Intnsics Reference Manual XtCreateApplicationContext. The application Context being used by a widget can be returned by XtWidgetToApplicationContext. All standard Xt routines use a default application context; routines for handling explicit application contexts almost all have names containing the string App. XtCallbackLi st A structure defined as follows in : typedef struct XtCallbackRec* XtCallbackList ; typedef struct XtCallbackRec { -- XtCallbackProc callback; caddr t closure; } XtCallbackRec; An XtCallbackList is statically defined just after the callback function itself is declared or defined. Then the callback list is used to set a callback resource with any of the calls lhat set resources, including XtCreateWidget. In most documentation, the closure member is refecd to as client_data. In application code, when Xt- AddCallback and XtRemoveCallback are used, an XtCallbackList is not required. XtCallbackProc The typedef for callback functions. See XtCallbackProc(2) for details. XtCallbackStatus An enumerated type that defines the return values from XtHasCallbacks: typedef enum { XtCallbackNoList, /* Callback resource doesn't exist */ XtCallbackHasNone, /* Resource exists, but no callbacks on it */ XtCallbackHasSome /* Resource exists, and callbacks are registered for it */ } XtCallbackStatus; XtConvertArgList A structure ud in calls to XtAddConverter  speci how the convener will access the values m be convened. The structure is defined as llows in : typedef struct ' XtAddressMode address mode; caddr t address id; Cardinal size; } XtConvertArgRec, *XtConvertArgList; The enumered type XtAddressMode specifies the possible vues r the address mode field, which consols how the address id field should be inter- preted. typedef enum { XtAddress, /* address */ XtBaseOffset, /* offset */ XtImmediate, /* constant */ XtResourceString, /* resource name string */ XtResourceQuark /* resource name quark */ } XtAddressMode; Appendix B: X Toolkit Data Types 429 By specifying the address mode as XtBaaeOffaet, you can use xtoffset to find the appropriate widget resource, much as you do in a resource list. XtConvertArgRec See XtConvertArgList. XtConverter The typedef for resource converters. See XtConverter(2) for details. XtConvert SelectionProc The typedef for the selection conversion procedure registered by a call to xtown- Selection. See xtConvertSelectionproc(2) for derails. XtErrorHandler The typedef for low-level error or warning handle/s. See XtErrorHandler(2) for details. XtErrorMsgHandler The typedef for high-level error or warning message handlers. See XtErrorMsg- Handler(2) for details. XtEventHandler The typedef for event handlers. See XtEventHandler(2) for details. XtGCMask A mask used in calls to XtGetGC that indicates which fields in the XGCValues struc- ture are to be used. The mask consists of a bitwise OR of the following symbols: Member function plane_mask foreground background line width line_style cap_style Join_style fill_style fill rule tile stipple ts x origin ts_y_origin font subwindow mode graphlcs_exposures cllp x origin clip_y_origin cllp_mask Nhsk GCFunction GCPlaneMask GCForeground GCBackground GCLineWidth GCLineStyle GCCapStyle GCJoinStyle GCFillStyle GCFilIRule GCTile GCStipple GCTileStipXOrigin GCTileStipYOrigin GCFont GCSubwindowMode GCGraphicsExposures GCClipXOrigin GCClipYOrigin GCCllpMask Default GXcopy all l's o 1 o LineSolid CapButt JoinMiter FillSolid EvenOddRule pixmap f'dled with foreground pixel pixmap f'dled with l's 0 0 (implementation dependent) ClipByChildren TRUE 0 0 None 430 X Toolkit Intrinsics Reference Manual XtWorkProc The typedef for the work procedure registered by a call to XtAddWorkProc. See xt- wo rkP roc(2) for details. XtWorkProcId The unique identifier returned by a call to XtAddWorkProc and used as an argument in XtRemoveWorkProc. 434 X Toolkit Intrinsics Reference Manual C Event Reference This appendix describes each event in detail. It covers how the event is selected, what trans- lation table symbols are valid for each event type, when each event occurs, the information contained in each event structure, and the side effects of the event, if any. Each event is described on a separate reference page. Table C-1 lists each event mask, its associated event types, and the associated structure defi- nition. See Chapter 7, Events, in Volume One, Xlib Programming Manual, for more informa- tion on events. See also Chapter 7, Events, Translations, and Accelerators, in Volume Four, X Toolkit Intrinsics Programming Manual. Table C-1. Event masks, event types, and event structures Event Mask KeyPressMask KeyReleaseMask ButtonPressMask ButtonReleaseMask OwnerGrabButtonMask KeymapStateMask PointerMotionMask PointerMotionHintMask ButtonMotionMask ButtonlMotionMask Button2MotionMask Button3MotionMask Button4MotionMask Button5MotionMask EnterWindowMask LeaveWindowMask FocusChangeMask Event Type KeyPress KeyRelease ButtonPress ButtonRelease a KeymapNotify MotionNotify EnterNotify LeaveNotify FocusIn Structure XKeyPressedEvent XKeyReleasedEvent XButtonPressedEvent XButtonReleasedEvent a XKeymapEvent XPointerMovedEvent XEnterWindowEvent XLeaveWindowEvent XFocusInEvent Appendix C: Event Reference 435 Table C- 1. Event Masks, Event Types, and Event Structures (continued) Event Mask ExposureMask (selected in GC by graphics_expose membeO ColormapChangeMask PropertyChangeMask VisibilityChangeMask ResizeRedirectMask StructureNotifyMask SubstructureNotifyMask SubstructureRedirectMask Event Type FocusOut Expose GraphicsExpose NoExpose ColormapNotify PropertyNotify VisibilityNotify ResizeRequest CirculateNotify ConfigureNotify DestroyNotify GravityNotify MapNotify ReparentNotify UnmapNotify CirculateNotify ConfigureNotify CreateNotify DestroyNotify GravityNotify MapNotify ReparentNotify UnmapNotify CirculateRequest Structure XFocusOutEvent XExposeEvent XGraphicsExposeEvent XNoExposeEvent XColormapEvent XPropertyEvent XVisibilityEvent XResizeRequestEvent XCirculateEvent XConfigureEvent XDestroyWindowEvent XGravityEvent XMapEvent XReparentEvent XUnmapEvent XCirculateEvent XConfigureEvent XCreateWindowEvent XDestroyWindowEvent XGravityEvent XMapEvent XReparentEvent XUnmapEvent XCirculateRequestEvent (always selected) (always selected) (always selected) (always selected) (always selected) ConfigureRequest MapRequest MappingNotify ClientMessage SelectionClear SelectionNotify SelectionRequest XConfigureRequestEvent XMapRequestEvent XMappingEvent XClientMessageEvent XSetSelectClearEvent XSelectionEvent XSelectionRequestEvent 436 X Toolkit Intrnsics Reference Manual Meaning of Common Structure Elements Example C-1 shows the XEvent union and a simple event structure that is one member of the union. Several of the members of this structure are present in nearly every event struc- ture. They are described here before we go into the event-specific members (see also Section 8.2.2 in Volume One, Xlib Programming Manual). Examp C- 1. XEvent unn and XAnyEvent structure typedef union XEvent { int type; /* must not be changed; first member */ XAnyEvent xany; XButtonEvent xbutton; XCirculateEvent xcirculate; XCirculateRequestEvent xcirculaterequest; XCllentMessageEvent xclient; XColormapEvent xcolormap; XConfigureEvent xconfigure; XConflgureRequestEvent xconfigurerequest; XCreateWindowEvent xcreatewindow; XDestroyWindowEvent xdestroywindow; XCrossingEvent xcrossing; XExposeEvent xexpose; XFocusChangeEvent xfocus; XNoExposeEvent xnoexpose; XGraphicsExposeEvent xgraphicsexpose; XGravityEvent xgravity; XKeymapEvent xkeymap; XKeyEvent xkey; XMapEvent xmap; XUnmapEvent xunmap; XMappingEvent xmapping; XMapRequestEvent xmaprequest; XMotionEvent xmotion; XPropertyEvent xproperty; XReparentEvent xreparent; XResizeRequestEvent xresizerequest; XSelectlonClearEvent xselectionclear; XSelectionEvent xselection; XSelectionRequestEvent xselectionrequest; XVisibilityEvent xvisibility; } XEvent; typedef struct { int type; unsigned long serial;/* # of last request processed by server */ Bool send event; /* TRUE if this came from SendEvent request */ Display *display; /* display the event was read from */ Window window; /* window on which event was requested in * event mask */ } XAnyEvent; Appendix C: Event Reference 437 xcllent (continued) ClientMessage format Specifies the format of the property specified by rues sage_type. This will be on of the values 8, 16, or 3 2. X Toolkit Intrinsics Reference Manual 445 ConflgureNotlfy (continued) xconfigure above If this member is None, then the window is on the bottom of the stack with respect to its siblings. Otherwise, the window is immediately on top of the specified sib- ling window. override redirect The override_redirect a[L6bute of the reconfigured window. If TRUE, it instates at the c|ient wants ds window to be immune to interception by the window manager of configuration requests. Window managers nonn1|y shou|d inore hs event if override_redirect is TRUE. 448 X Toolkit Intrinsics Reference Manual ConfigureRequest (continued) xconfigurerequest width, height The requested width and height in pixels for the window. border width The requested border width for the window. above None, Above, Below, TopIf, BottomIf, or Opposite. Spifies the sibHng window on top of which the specified window should be placed. If this member has the constant None, then the specified window should be placed on the bottom. Notes The geometry is derived from the XConfigureWindow request that triggered the event. 450 X Toolkit Intrinsics Reference Manual CreateNotify (continued) xcreatewindow Notes For descriptions of these members, see the XCreateWindow function and the XSet- WindowAtt ributes sucture. 452 X Toolkit Intrinsics Reference Manual xfocus (continued) Focusln, FocusOut detail The det a il member identifies the relationship between the window that receives the event and the origin and destination windows. It will be described in detail after the description of which windows get what types of events. Notes The keyboard focus is a window that has been designated as the one to receive all keyboard input irrespective of the pointer position. Only the keyboard focus window and its descendants receive keyboard events. By default, the focus window is the root window. Since all windows are descendants of the root, the pointer controls the window that receives input. Most window managers allow the user to set a focus window, to avoid the problem where the pointer sometimes gets bumped into the wrong window and your typing doesn't go to the intended window. If the pointer is pointing at the root window, all typing is usually lost since there is no application for this input to propagate to. Some applications may set the keyboard focus so that they can get all keyboard input for a given period of time, but this practice is not encouraged. Focus events are used when an application wants to act differently when the keyboard focus is set to another window or to itself. FocusChangeMask is used to select FocusIn and FocusOut events. When a focus change occurs, A FocusOut event is delivered to the old focus window and a Focus In event is delivered to the window which receives the focus. Windows in between in the hierarchy are virtually crossed and receive one focus change event each depending on the relationship and direction of transfer between the origin and destination windows. Some or all of the windows between the window containing the pointer at the time of the focus change and that window's root window can also receive focus change events. By checking the detail member of Focus Tn and FocusOut events, an application can tell which of its windows can receive input. The detail member gives clues about the relationship of the event receiving window to the origin and destination of the focus. The detail member of FocusOut and Focus In events is analogous to the detail member of LeaveNotify and EnterNotify events, but with even more permutations to make life complicatexl. Virtual Focus Crossing and the detail Member We will now embark on specifying the types of events sent to each window and the detail member in each event, depending on the relative position in the hierarchy of the origin window (old focus), destination window (new focus), and the pointer window (window containing pointer at time of focus change). Don't even try to figure this out unless you have to. X Toolkif Intrinsics Reference Manual 463 Focusln, FocusOut (continued) xfocus Table C-4 shows the event types generated by a focus transition from window A to window B when window C is the least common ancestor of A and B, and P is the window containing the pointer. This table includes most of the events generated, but not all of them. It is quite pos- sible for a single window to receive more than one focus change event from a single focus change. Table C-4. Focusln and FocusOut Events and Window Relationship FocusOut Origin window (A) Windows between A and B exclusive if A is inferior Windows between A and C exclusive Root window on screen of origin if dif- ferent from screen of destination Pointer window up to but not including origin window if pointer window is descendant of origin Pointer window up to and including pointer window's root if transfer was from PointerRoot FocusIn Destination window (B) Windows between A and B exclusive if B is inferior Windows between B and C exclusive Root window on screen of destination if different from screen of origin Pointer window up to but not including destination window if pointer window is descendant of destination Pointer window up to and including pointer window's root if transfer was to PointerRoot Table C-5 lists the detail members in events generated by a focus transition from window A to window B, with P being the window containing the pointer. Table C-5. Event detail Member and Window Relationship detail]ag NotifyAncestor NotifyInferior NotifyVirtual NotifyNonlinear NotifyNonlinearVirtual Window Delivered To Origin or destination when either is descendant. Origin or destination when either is ancestor. Windows between A and B exclusive if either is descendant. Origin and destination when A and B are two or more windows distant from least common ancestor C. Windows between A and C exclusive and between B and C exclusive when A and B have least common ancestor C. Also on both root windows if A and B are on different screens. 464 X Toolkit Intrinsics Reference Manual KeyPress, KeyRelease (continued) xkey Keyboard events are analogous to button events, though of course there are many more keys than buttons, and the keyboard is not automatically grabbed between press and release. All the structure members have the same meaning as described for ButtonPress and ButtonRelease events except that button is replaced by keycode. 474 X Toolkit Intn'nsics Reference Manual VlslbllltyNotlfy (continued) xvislbility Table C-6. The State Element of the XVisibilityEvent Structure Visibility Status Before Partially obscured, fully obscured, or not view- able Viewable and com- pletely unobscured, or not viewable Viewable and com- pletely unobscured, or viewable and partially obscured, or not view- able Visibility Status After Viewable and com- pletely unobscured Viewable and partially obscured Viewable and partially obscured State Member VisibilityUnobscured VisibilityPartially- Obscured VisibilityPartially- Obscured 490 X Toolkit Intn'nsics Reference Manual translationParseError showLine parseError parseString typeConversionError noConverter versionMmatch widget wrongParameters cvtIntToBool cvtIntToBoolean cvtIntToFont cvtIntToPixel cvtIntToPixmap cvtIntToShort cvtStringToBool cvtStringToBoolean cvtStringToDisplay cvtStringToFile cvtStringToInt cvtStringToShort cvtStringToUnsignedChar cvtXColorToPixel ... found while parsing "'%s" Translation table syntax error:. %s Missing "'.LP No type converter registered for "%s'" to "%s" conversion Widget class %s version mismatch: widget %d vs. inu'insics %d Integer-to-Bool conversion needs no extra arguments Integer-m-Boolean conversion needs no extra arguments Integer-to-Font conversion needs no extra arguments Integer-to-Pixel conversion needs no extra arguments Integer-to-Pixmap conversion needs no extra arguments Integer-m-Short conversion needs no extra arguments String-to-Bool conversion needs no extra arguments String-to-Boolean conversion needs no extra arguments String-to-Display conversion needs no extra arguments String-to-File conversion needs no extra arguments Suing-m-Integer conversion needs no extra arguments String-to-Integer conversion needs no extra arguments Suing-m-Integer conversion needs no extra arguments Color-to-Pixel conversion needs no extra arguments Appendix D: Standard Errors and Warnings 495 F Translation Table Syntax Notation Syntax is specified in EBNF notation with the following conventions: [ a ] Means either nothing or "a" { a } Means zero or more occurrences of "a" All terminals are enclosed in double quotation masks ( .... ). Informal descriptions are enclosed in angle brackets (< >). Syntax The translation table file has the following syntax: translationTable = [directive ] { production } directive = { "#replace" I "#override" I "#augment" } 'Nn" production = lhs ":" rhs 'Nn" lhs = (event I keyseq ) { "," (event I keyseq) } keyseq =' ..... keychar {keychar} ...... keychar = [ ..... I "$" I '" ] event = [modifier_list] "<"event_type">" [ "(" count["+"] ")" ] {detail} modifier_list = (["!" I ":"] {modifier} )] "None" modifier = [ ..... ] modifier_name count = ("1" I "2" 1"3" I "4" ] ...) modifier_name = "@" I event_type = detail = rhs = { name "(" [params] ")" } name = namechar { namechar } namechar = { "a"-"z" I "A"-"Z" I "0"-"9" I "$" I "_" } params = string {"," string}. string = quoted_string I unquoted_string Appendix F: Translation Table Syntax 499 The supported abbreviations are listed in Table F-3. Table F-3. Modifier Key Abbreviations Abbreviation Ctrl Meta Shift BtnlDown BtnlUp Btn2Down Btn2Up Btn3Down Btn3Up Btn4Down Btn4Up Btn5Down Btn5Up BtnMotion BtnlMotion Btn2Motion Btn3Motion Btn4Motion Btn5Motion Meaning KeyPress with conol modifier KeyPress with meta modifier KeyPress with shift modifier ButtonPress with Btnl detail ButtonRelease with Btnl detail ButtonPress with Btn2 detail ButtonRelease with Btn2 detail ButtonPress with Btn3 detail ButtonRelease with Btn3 detail ButtonPress with Btn4 detail ButtonRelease with Btn4 detail ButtonPress with Btn5 detail ButtonRelease with Btn5 detail MotionNotify with any button modifier MotionNotify with Buttonl modifier MotionNotify with Button2 modifier MotionNotify with Button3 modifier MotionNotify with Buon4 m0fier MotionNotify with Buon5 m0fier The detail field is event-specific and normally corresponds to the detail field of an XEvent, for example, A. If no deta il field is specified, then ANY is assumed. A keysym can be specified as any of the standard keysym names, a hexadecimal number pre- fixed with Ox or OX, an octal number prefixed with 0, or a decimal number. A keysym expressed as a single digit is interpreted as the corresponding Latin 1 keysym. For example, 0 is the keysym XK_0. Other single character keysyms are treated as literal constants from Latin 1, for example, ! is treated as 0x21. Standard keysym names are as defined in with the XK_ prefix removed. (See Appendix H, Keysyms, in Volume Two, Xlib Reference Manual.) Appendix F: Translation Table Syntax 503 Canonical Representation Every translation table has a unique, canonical text representation. This representation is pas- sed to a widget's displa._aceelerat:or method to describe the accelerators installed on that widget. The table below shows the canonical representation of a translation table file. (See also the section on "Syntax" earlier in this appendix.) translationTable production lhs event = modifier_list = modifier = count = modifier_name = event_type = detail = rhs = name = namechar -- params -- string - quoted_string The canonical modifier names are: = { production } = lhs ":" rhs event { "," event } [modifier__st] "<"evenUtype">" ["C count["+"] ")" ] {detail} ["!" I ":"] {modifier} [ ..... ] modifier_name C1" 1"2" I "3" I "4" I ...) "@" ] { name "C [params] ")" } namechar { namechar } { "a"-"z" I "A"-"Z" I "0"-"9" I "$" I "_" } string {"," string}. quoted_string ...... {} ...... Buttonl Modl Button2 Mod2 Button3 Mod3 Button4 Mod4 Button5 Mod5 The canonical event types are: DestroyNotify EnterNotify Expose FocusIn FocusOut GraphicsExpose GravityNotify KeymapNotify ButtonPress ButtonRelease CirculateNotify CirculateRequest ClientMessage ColormapNotify ConfigureNotify ConfigureRequest CreateNotify Ctrl Shift Lock KeyPress KeyRelease LeaveNotify MapNotify MappingNotify MapRequest MotionNotify NoExpose PropertyNotify ReparentNotify ResizeRequest SelectionClear SelectionNotify SelectionRequest UnmapNotify VisibilityNotify 504 X Toolkit Inttnsics Reference Manual G StringDefs.h Header File This appendix lists the contents of the StringDefs.h header f'de. The contents are classified by resource names, class types, representation types, and constants. Table G-1. Resource Names Resource Name XtNaccelerators vXtNallowHoriz XtNallowVert XtNancestorSensitive XtNbackground XtNbackgroundPixmap Value "accelerators" "allowHoriz" "allowVert" "ancestorSensitive" "background" "backgroundPixmap" XtNborderColor XtNborder XtNborderPixmap XtNborderWidth XtNcallback XtNcolormap XtNdepth XtNdestroyCallback XtNeditType XtNfont XtNforceBars XtNforeground XtNfunction XtNheight XtNhSpace XtNindex XtNinnerHeight XtNinnerWidth XtNinnerWindow XtNinsertPosltion XtNinternalHelght "borderColor" "borderColor" "borderPixmap" "borderWidth" "callback" "colormap" "depth" "destroyCallback" "editType" "font" "forceBars" "foreground" "function" "height" "hSpace" "index" "innerHeight" "InnerWidth" "innerWindow" "InsertPosition" "InternalHelght" Appendix G: StringDefs.h Header File 507 Table G-1. Resource Names (continued) Resource Name XtNinternalWidth XtNJustlfy XtNknobHeight XtNknobIndent XtNknobPixel XtNknobWidth XtNlabel XtNlength XtNlowerRight XtNmappedWhenManaged XtNmenuEntry XtNname XtNnotify XtNorientation XtNparameter XtNpopupCallback XtNpopdownCallback XtNreverseVideo XtNscreen XtNscrollProc XtNscrollDCursor XtNscrollHCursor XtNscrollLCursor XtNscrollRCursor XtNscrollUCursor XtNscrollVCursor XtNselection XtNselectionArray XtNsensitive XtNshown XtNspace XtNstring XtNtextOptions XtNtextSink XtNtextSource XtNthickness XtNthumb XtNthumbProc XtNtop XtNtranslations XtNuseBottom XtNuseRight XtNvalue XtNvSpace Value "internalWidth" "Justify" "knobHeight" "knobIndent" "knobPixel" "knobWidth" "label" "length" "lowerRight" "mappedWhenManaged" "menuEntry" "name" "notify" "orientation" "parameter" "popupCallback" "popdownCallback" "reverseVideo" "screen" "scrollProc" "scrollDownCursor" "scrollHorizontalCursor" "scrollLeftCursor" "scrollRightCursor" "scrollUpCursor" "scrollVerticalCursor" "selection" "selectionArray" "sensitive" "shown" "space" "string" "textOptions" "textSink" "textSource" "thickness" "thumb" "thumbProc" "top" "translations" "useBottom" "useRight" "value" "vSpace" 508 X Too&# Intfinsics Reference Manual Table G-3. Representation Types (continued) Representation Type XtRFont XtRFontStruct XtRFunction XtRGeometry XtRImmedlate XtRInt XtRJustify XtRLongBoolean XtROrientation XtRPixel XtRPixmap XtRPointer XtRPosition XtRShort XtRString XtRStringTable XtRUnsignedChar XtRTranslationTable XtRWindow Value "Font" "FontStruct" "Function" "Geometry" "Immediate" "Int" "Justify" "LongBoolean" "Orientation" "Pixe1" "Pixmap" "Pointer" "Position" "Short" "String" "StringTable" "UnsignedChar" "TranslationTable" "Window" Table G-4. Constants Constant Boolean Enumeration: XtEoff XtEfalse XtEno XtEon XtEtrue XtEyes Orientation Enumeration: XtEvertical XtEhorizontal Text Edit Enumeration: XtEtextRead XtEtextAppend XtEtextEdit Value "off" "false" "no" " o n " "true" "yes" "vertical" "horizontal" "read" "append" "edit" Appendix G: StringDefs.h Header File 511 Table G-4. Constants (continued) Co.rant Color Enumeration: XtExtdefaultbackground XtExtdefaultforeground Fon XtExtdefaultfont Value "xtdefaultbackground" "xtdefaultforeground" "xtdefaultfont" 512 X Toolkit Inttnsics Reference Manual Master Index The Master Index combines Volumes Four and Five index entries, makino it easy to look up the appropriate references to a topic in either volume. PM refers to the X Toolkit Intrinsics Programming Manual. RM refers to the X Too/kit Intrinsics Reference Manual. Index The Master Index combines Volumes Four and Five index entries, making it easy to look up the appropriate references to a topic in either volume. PM refers to the X Toolkit Intrinsics Programming Manual. RM refers to the X Toolkit Intrinsics Reference Manual. The alphabetical sequence of the index is highlighted by the bolding of primary entries. # directive (see translations) ! (see modifiers) - options (see options) accelerators, about PM:53, 150, 189, 205-211, 253, 495 (see also display_accelerator) (see also XtInstallAccelerators) (see also XtInstallAllAccelerators) compiling accelerator table PM:210; RM:201 defining default table in code PM:210 display_accelerator method PM:211; RM:320 event propagation PM:207 for gadgets PM:371 for menus PM:367, 371 installing PM:205; RM:166-168; in multiple widgets PM:209 not usable in gadgets PM:373 parsing (see compiling) translations; conflicts with PM:209; transla- tion table limitations PM:206 accept_focus method, about PM:154, 389,391, 495 AcceptFocusProc RM:328 access control list PM:495 actions PM:30, 495 (see also XtAddActions, XtAppAddActions) actions, about PM:27, 39; RM:7, 428 action proc; format PM:46 actions table, PM:495; adding PM:43-45; RM:42-43, 60-61; declaring/registering with Resource Manager RM:60-61; example PM:45; format PM:45; XtAc- tionProc RM:270-272 adding; from application PM:43; in widget itself PM:184-186 arguments to PM:ll3 contrasted with callbacks PM:46, 112 defined in widget implementation file PM:145-147 gadget parent; example PM:380-381 in gadgets PM:373 naming conventions PM:42 passing arguments to PM:ll3 registering (see adding) using event data PM:222; example RM:271-272 widget instance pointer PM: 185 widget/application conflicts PM:146 (see also XtAddActions, XtAppAddActions) aliasing font names PM:443 AlmostProc RM:328 Alt key (see modifiers) ancestor PM:496 anonymous ttp PM:34 application contexts, about PM:97-99, 393-396, 496 Index 519 caching, old size PM:179 standard atoms PM:299 type conversions PM:260 Xmu; initializing PM:300 callbacks, about PM:26, 30, 39, 497; RM:6, 330, 429 adding PM:40, 42; more than one at a time PM:80; to callback list RM:46-47; to call- back resource RM:44-45 arguments to PM:42 callback list, about PM:79, RM:6; deleting method RM:219; deleting method list RM:220; determining status RM:160; executive methods RM:104; popping down widget RM:102-103; popping up widget RM:98-101; XtCallbackExclusive RM:98-99; XtCallbackNone RM:100; XtCallbackNonexclusive RM: 101; XtCallbackPopdown RM:102-103; XtCall- Callbacks RM:104; XtHasCallbacks RM:160; XtRemoveCallback RM:219; XtRemoveCallbacks RM:220 conta-asted with actions PM:46 format PM:42 naming conventions PM:42 passing data PM:77-79 pop-up functions PM:79 procedure RM:279-280 (see also XtAddCallback, XtCallbackoc) (see also XtTimerCallbackProc) Caption widget, about PM:409 cascading pop ups, about PM:345-347, 362-367 example PM:363-365 case converter PM:200 registering RM:216 (see also XtRegisterCaseConverter) chained methods (see inheritance) change_managed method PM:306-308, 319, 497; RM:340 in consta-alm widgets PM:338-339 ClrculateNotffy events RM:442 ClrculateRequest events RM:443 class, about PM:18, 498 class name; defined in Core class part PM:150 class part PM:137; combining into class record PM:138; lack of new fields PM:138 class record PM:136; allocating storage PM: 140; BitmapEdit widget PM:138-139; contents PM:136 class_initialize method PM:153, 258, 381, 498; RM:331 class_part_init method PM:153, 331; RM:331 hierarchy (see widget classes); Athena widgets PM:153; gadgets PM:375 sla-uctures PM:136-162 subclass; about RM:14 client, about PM:6, 498 ClientMessage events RM:444-445 client-server model PM:6 clipping region PM:498 color PM:53, 56, 120, 156-158, 253-254, 276 color names PM:433 colorcell, about PM:436, 498; read-only PM:438; read/write PM:438; shared PM:437 colormap, about PM:53,436, 498; installing PM:276; window attribute PM:156 ColormapNotify events RM:446 determining available PM:436 displaying PM:436 false PM:277 hexadecimal specification PM:434 RGB model PM:435 specifying PM:433 command buttons PM:404, 406, 417; RM:359-362 command line options (see options) compiling PM:34 Command widget PM:206-210, 353-359, 362, 366, 404-406, 417; RM:359-362 creating RM:362 desla'oying RM:362 resources RM:359-361 compiling Xt PM:34 composite widgets, as parent and child PM:320 change_rnanaged method RM:340 class, about PM:16, 21,137; XtNinsertPosi- tion resource PM:324 composite widget class; about PM:61 delete_child method RM:340 general purpose PM:409, 421 geometry_manager method RM:340-341 insert_child method RM:339-340 insert_position method RM:342 importance PM:408 initial size PM:309 inserting children PM:323 menus and control areas PM:418 ordering method; XtOrderProc RM:310 reasons for writing PM:305 resources (see resources) Index 521 due to set_values method changes PM:175 in expose method PM:166 into Core widget PM:117-119 window attributes PM:156-157 drop-down menu (see menus) elements (see array) encapsulation PM:29, 500 enter/leave compression PM:234 EnterNotffy events PM:195-196, 234, 353; RM:454-459 EnterWindow events PM:216 environment variables, DISPLAY PM:53 XAPPLRESDIR PM:245 XENVIRONMENT PM:245 errors, error database; obtaining RM:74, 75-77, 144; XtAppGetErrorDatabase RM:74, 145; XtAppGetErrorDatabaseText RM:75-77, 144 error handling PM:91.93; and application contexts PM:387; calling error resource database PM:386; calling fatal error han- dler RM:71-73, 85-86, 137-139. 234; .XF 2 listing RM:491 sfng conversion error message RM:248 events, event loop (see main loop) events, (see also exposure) (see also XtDispatchEvent) (see also XtMainLoop. XtNextEvent) about PM:10, 191,501; RM:7 accessing specific data RM:437 as argument of action PM:46 border crossing RM:454-459 ButtonPress RM:439-441 ButtonRelease RM:439-441 cancelling source RM:224 CirculateNotify RM:442 CirculateRequest RM:443 ClientMessage RM:444-445 ColormapNotify RM:446 ConfigureNotify RM:447-448 ConfigureRequest RM:449-450 CreateNotify RM:451-452 Desla'oyNotify RM:453 dispatching handlers RM: 133 EnterNotify PM:234; RM:454-459 EnterWindow PM:216 event compression PM:501 event data; using in an action PM:222 event filters PM:150, 234 event handelrs, about PM:28, 30, 215-220, 501; RM:7; adding PM:216; dispatching RM:133; for nonmaskable events PM:219-220; procedure RM:293-294, 304-305; raw PM:220; reasons to use PM:216; registering RM:49-50; register- ing raw RM:56-57; removing RM:221-222; removing raw RM:225-226; XtAddEventHandler RM:49-50; XtAd- dRawEventHandler RM:56-57; XtEventHandler RM:293-294; Xtln- putCallbackProc RM:304-305; XtRemo- veEventHandler RM:221-222; XtRemo- veRawEventHandler RM:225-226 event masks, about PM:216, 501; RM:424; retrieving RM:95-96; table PM:216; Xt]3uildEventMask RM:95-96 event members; common RM:438 event processing RM:84; XtAppProcessEvent RM:84 event propagation PM:501 event queue PM:234; peeking PM:234 event sequences; sharing initial events PM:204; sharing noninitial events PM:204 event source PM:501 event structure PM:221 event-driven programming, about PM: 10-11 event_mask window attribute PM: 157 expose PM:10 Expose PM:23, 153,235; RM:460-461 FocusIn PM:216; RM:462-467 FocusOut PM:216; RM:462-467 frozen event PM:502 GraphicsExpose PM:193,220; RM:468-469 GravityNotify RM:470 in action routines PM:124 in gadgets PM:373 input events; XtRemoveInput RM:224 KeymapNotify RM:471 KeyPress RM:472-474 KeyRelease RM:472-474 LeaveNotify PM:234; RM:454-459 LeaveWindow PM:216 list of types and structure names PM:223 MapNotify RM:475-476 MappingNotify RM:477-478 MapRequest RM:479 mocking up from action PM:171; RM:295 MotionNotify PM:216, 234; RM:480-482 next event; retuming RM:191 NoExpose PM:193; RM:468-469 nonmaskable PM:191o 207. 218 processing RM:176 524 X Toolkit Intdnsics Reference Manual processing one event; XtProcessEvent RM:209 propagation PM:207 PropertyNotify RM:483 ReparentNotffy RM:484 ResizeRequest RM:485 returning next event RM:80 selecting PM:207 SelectionClear PM:280, 289; RM:486 SelectionNotify PM:280, 290, 295; RM:487 SelectionRequest PM:280, 282, 290-291; RM:488 structures RM:438 translation table abbreviations PM:192-193 UnmapNotify RM:475-476 using inside actions or event handlers PM:221; RM:271 VisibilityNotify RM:489-490 XEvent; example PM:221; RM:271 (see also XtAppNextEvent, XtAppPending) examples, actions; actions table PM:45; adding actions PM:43-45; in gadget parent PM:380-381; using event datain PM:222; widget actions PM:184-185 adding; accelerators PM:206; event handler PM:218-219; RM:294; resource list to class structure PM:145; scrollbars to application PM:109, 111; work procedure PM:231-232 application resource data structure PM:81 BitmapEditClassRec PM:138-139, 138 BitmapEditRec PM: 139 calculating scrollbar thumb size PM: 113-116 cascading pop-up menu PM:3630 365 constraint resources PM:68-69 constraint widget change_rnanaged method PM:338-339 constraint widget; refiguring child locations PM:333-335 converting; default value of resource PM:254-255; selection PM:293-294; stan- dard selections PM:300-301; RM:284-285 creating; argument list PM:92; argument lists with XtSetArg PM:93, 94; GCs from ini- tialize method PM:169-170; icon pixmap PM:278-279 creating pop up; work procedure RM:323 creating; widget hierarchy PM:61-63 declaring; resource list PM:240; widget class record pointer PM:155 destroy method PM:183 drawing into Core widget PM:118-119 explicitly invoking converter PM:261 expose method PM:171-172; RM:296; in gad- get parent PM:378-379 gadget class structure PM:376 gadget instance structure PM:377 geometry_manager method in constraint widget PM:332-333 get_values_hook method PM:265; RM:277 hardcoding resources PM:92 highlighting selection PM:284-288 initialize method PM:166-168; in constraint widget PM:330 initializing; Core class part PM:148-149; Xmu atom caching PM:300 installing accelerators in multiple widgets PM:209 interactions between resources PM:55 laying out child widgets PM:317-319 main loop (custom) PM:233 menu using SimpleMenu widget PM:368-370 nonmaskable event handlers PM:219-220 obtaining; atom PM:291-292; source code availability PM:34 options table PM:88-89 passing arguments to converter PM:259 passing data PM:77-79 pasting selection PM:295-296 placing; drop-dowrtmenu PM:360,361; pop-up menu PM:354, 357 pop ups; work procedure to create PM:232 pop-up menu (spring-loaded); using Box widget PM:354-358 public function to get widget data PM:105 query_geometry method PM: 182; in compos- ite widget PM:316-317; in constraint widget PM:339 reading; from f'de PM:224-226; from pipe PM:226-227 registering resource converter PM:258 removing timeouts PM:229-230 resize method PM:177, 179; in composite widget PM:316; in constraint widget PM:336-337; in gadget parent PM:380 resource definition in widget PM: 143-145 resource list PM:82-83 resource value; getling PM:51 retrieving; application resources PM:85-86; resource default at run-time PM:256 settg; resources for widget hierarchy PM:64; resources with XtSetValues PM:50; win- dow attributes in realize method PM:157; XtNinput PM:276 set_values method PM:174-175; in composite widget PM:316 Index 525 timeouts PM:228-229 translation table PM:47 using; argument lists PM:92-93; event data in an action PM:222; RM:271-272; pop ups PM:71-74; timeouts PM:229 writing type converter PM:262-263 xbitrnapl PM:104-107 xbitrnap2 PM:107-116 xbitrnap3 PM:116-122 xbitrnap4 PM:123-132 XEvent RM:271 XEvent casting PM:221 xfarewell.c PM:43-45 xgoodbye.c PM:40 xhello.c PM:31-32 XrmOptionDescRec PM:88-89 (see also XtResourceDefaultProc) expo.lcs.mit.edu PM:34 Expose events PM:10, 23, 114, 122, 124, 150, 153, 165, 172, 230, 235,353; RM:51,297, 460-461 expose method PM:29, 153, 165-166, 170-174, 220, 501; RM:296-297, 332-333 in gadget parent PM:378-379 in gadgets PM:373,378 (see also XtExposeProc) exposure PM:501 (see also Expose events, XtAddExposureToRe- gion) compression PM: 172, 235; RM:297 exposure (see Expose events) extensions, about PM:12, 502 fatal error handllng (see errors) fatal error (see errors) file Input, registering file RM:65-66 files, f'rie events (see event handlers) f'rie input PM:224-226; registering f'rie RM:54-55; source masks PM:224; XtAd- dInput RM:54-55; XtAppAddInput RM:65-66 f'rienames; character limit PM:136 using names in resources PM:253 floating point numbers PM:253 Focusln events PM:195-196, 216, 390; RM:462-467 FocusOut events PM:195-196, 216, 390; RM:462-467 font conventions (in this book), bolding PM:xxviii; RM:viii italics PM:xxviii; RM:viii typewriter font PM:xxviii; RM:viii fonts PM:502 aliasing PM:442 creating databases (mldontdir) PM:44 directories PM:438 display (xfd) PM:438 families PM:438, 441 fonts.dir Fries PM:444 naming convention PM:439 printer PM:438 screen PM:438 specifying PM:433; as resources PM:253 using frie name as alias PM:443 wildcarding PM:441 foreground PM:502 Form widget, about PM:20, 67-70, 325-340, 409, 421; RM:365-367 adding children RM:367 child resources RM:366 creating RM:367 deleting children RM:367 destroying RM:367 example PM:421 layout method PM:329 resources RM:365-366 (see also resources) freeing storage block (see storage block) ftp PM:34 function typedefs, overlapping use PM:148 gadgets, about PM:155,345 accelerators PM:371; not usable PM:373 actions in PM:373 class hierarchy PM:374-375 class structure PM:376 composite parent PM:373,378-381 Core class structure PM:375 drawbacks PM:373 event handling in PM:373 expose method PM:378 implementation file PM:377 instance structure PM:377 internals PM:375-378 private header file PM:376-377 public header file PM:378 query_geometry method PM:378 reason for PM:372 set_values_almost method PM:378 Sme PM.'367-378 SmeBSB PM:367-378 526 X Toolkit Intrinsics Reference Manual SmeLine PM:367-378 superclass PM:377 unused Core fields in PM:377-378 games PM:227 GC (see graphics contexts) geometry management, about PM:33, 65-66, 177, 180-182, 273,305-341,502; RM:14, 338-342, 431 (see also XtDestroyWidget) (see also XtGeometryAlmost) (see also XtGeometryDone return value) (see also XtGeometryNo return value) (see also XtGeometryResult enum) (see also XtGeometryYes return value) (see also XtInheritDeleteChild constant) (see also XtInheritGeometryManager constant) (see also XtInheritInsertChild constant) (see also XtInheritSetValuesAlmost constant) (see also XtMakeGeometryRequest) (see also XtMakeResizeRequest) (see also XtMapWidget, XtMoveWidget) (see also XtNinsertPosition composite resource) (see also XtNmappedWhenManaged Core resource) (see also XtQueryGeometry) (see also XtResizeWidget) (see also XtUnmanageChild, XtUn- manageChildren) (see also XtUnmapWidget) (see also XtWidgetGeometry structure) almost right PM:323 border width PM:306 Box widget RM:357-358 change_managed method PM:306, 308, 319 changes PM:456; RM:177-179 changing; XtMakeGeometryRequest RM:177-179 compound widgets PM:340-341 conswaint class part PM:329 conswaint management PM:325 conswaints on children RM:365-367 delaying recalculation PM:340 delete_child method PM:306, 323-324 geometry handler; procedure RM:299-301 geometry manager RM:341 geometry_manager method PM:306, 311, 320-322; RM:340-341; in consaint widget PM:332-336 height PM:308 initial geometry negotiation PM:308, 310 initial size PM:308 initialize method PM:315 inserting children PM:323; insert_child method PM:306, 323-324 minimal useful size PM:317 querying RM:210-212; preferred geometry PM:320; query_geometry method PM:306, 321; XtQueryGeometry RM:210-212; XtQueryOnly constant PM:322 realize method PM:310, 315 resizing PM:305, 311; by application PM:312; by user PM:311; by widget request PM:311-312; resize method PM:306, 309 scope PM:306 scrollable widget RM:403-404 set_values method PM:311-312, 315 set_values_almost method PM:312, 322, 323 size preferences PM:320 stacking order PM:306, 341 clde-down PM:320 unmanaging widget PM:319 what if requests PM:322 widget for vertical tiles RM:405-408 width PM:308 get_values_hook method PM:154, 265-266, 502; RM:158, 275-278, 335 (see also XtArgsProc) global variables PM:75, 77 glyph PM:502 grabs PM:351,495, 502; RM:431 (see also XtAddGrab) (see also XtRemoveGrab) active vs. passive PM:352 adding or removing explicitly PM:372 exclusive vs. nonexclusive PM:352, 365 grab modes PM:365 in dialog boxes PM:371 keyboard PM:351 passive PM:507 pointer PM:351 reasons for in menus PM:353 graphics contexts PM:119, 140, 157, 502 (see also XtDestroyGC) (see also XtGetGC) (see also XtReleaseGC) caching PM:166, 168 changing PM:168, 176 creating PM: 166-170 deallocating RM:217 destroying RM:128 exclusive or logical function PM:287 freeing PM:176, 183 freeing (R2) RM:128 hardcoding values in PM: 170 Index 527 placing pop-up PM:357 pointer grabbing PM:351 popping down PM:351,359, 367; MenuPop- down RM:39 popping up PM:352, 358; MenuPopup RM:40-41 popping up with callbacks PM:360 pull down PM:347 SimpleMenu widget, example PM:368, 370 spring-loaded PM:347 messages, about PM:29, 505 OOP vs. Xt PM:29 Meta key (see modifiers) methods, about PM: 153-154, 505 accept_focus PM: 154, 389, 391 and instance structure PM:136 change_managed PM:306-308, 319; RM:340 class_initialize PM:153, 258, 381; RM:331 class_part_initialize PM: 153; RM:331 constraint widgets; destroying PM:329; geometry_manager PM:332; initializing PM:329; resizing PM:336 declarations in widget implementation file PM: 147-148 delete_child PM:306, 323-324; RM:340 destroy PM:154, 165, 183 display_accelerators PM:211 drawing; due to changes in set_values PM:175; in expose PM:166 expose PM:29, 153, 165-166, 170-174. 220; RM:296 Form layout PM:329 gadget; expose PM:378; query_geometry PM:378; set_values_almost PM:378 geometry_manager PM:306, 311,320-322; RM:340 get_values_hook PM: 154, 265-266; RM:275-277; example PM:265; example of RM:275, 277 in OOP PM:29 inheritance; adding to superclass PM:157; of superclass PM:155 initialize PM:153, 165-170, 315 initialize_hook PM:153, 265 insert_child PM:306, 323-324; RM:339 layout Form PM:329 not known to Xt PM:329 query_geometry PM:154, 165, 180-182, 306, 321 realize PM:153,274, 310, 315; RM:331 reconciliation PM: 157 resize PM:154, 165, 177-180, 306, 309 resources, and set_values PM: 174-176 set_values PM:154, 165-166, 174-176, 311-315 set_values_almost PM: 154, 312, 322-323 set_values_hook PM:154, 265-266; RM:275 minimal useful size PM:317 mkfontdir PM:444 Mod n key (see modifiers) modal cascade (see menus, cascading) modal pop ups (see pop ups) modifiers, ! PM:200 adding PM:198 and event sequences PM:202 case-specifics PM:200 colon PM:200-201 displaying list PM:198 for button events PM:202 keys, about PM:196-201,506;/klt key PM:197; Ctrl key PM:197; Hyper key PM: 197; key modifier RM:500-506; Meta key PM:197; Mod n key PM:197; Super key PM: 197 matching exactly PM:200 negating PM:199 None PM:200 tilde PM:199 monochrome PM:506 Motif PM:349, 399, 402 motion compression PM:234 MotionNotlfy events PM: 196, 202, 216, 234, 353; RM:480-482 multiple toplevel shells PM:395 naming conventions, (see also conventions) widgets PM:449 newllnes, in translations PM: 190 NoExpose events PM: 193; RM:468-469 nonfatal error (see errors) nonmaskable events PM: 191,207, 218-220, 506 example of handlers PM:219-220 notify modes (see translations) 0 object, about PM:28,506 Object class PM:374 object-oriented programming PM:28-29 530 X Toolkit Inttnsics Reference Manual single-line input field PM:280 sink, in Athena Text widget PM:264 size PM:305 hints PM:273 preferences PM:320 sizeof PM:150 Sme gadgets PM:367-378 SmeBSB gadgets PM:367-378 SmeLine gadget PM:367-378 software architecture, about PM:8 source code, obtaining; example PM:34 source files for widget PM:I35 source, in Athena Text widget PM:264 spring-loaded pop up (see pop ups) stacking order PM:306, 341,513 StatlcColor PM:513 StatlcGray PM:513 status PM:513 stdlo.h PM:I41 stipple PM:513 storage, storage block allocating RM:I81; for datatype RM:I89; XtNew RM:I89 freeing RM:I40; (see also XtFree) resizing RM:215 (see also XtMalloc) string, copying; XtNewStrlng RM:I90 StringDefs.h PM:83 StringDefs.h header file PM:30, 50, 141; RM:507 string, error message; XtStringConver- slonWarning RM:248 StrlngToWldget resource converter PM:69 structure, (see also XtOffset) determining field's byte offset RM:193-194 of Xt applications PM:30 subclass, about PM:I9, 513 submenus (menus, cascading) subparts PM:150, 154, 264-266 subresources PM:150, 154, 264-266 Super key (see modifiers) superclass, about PM:19, 149, 513 syntax functions PM:91 TCP/IP PM:280 templateWldgetCiass RM:383-390 Text widget, about PM:lg, 414, 424; RM:391-402 creating RM:397 default bindings RM:395-396 edit modes RM:392 resources RM:392-394 tight bindings PM:244, 513 tiling, about PM:53. 513 time PM:513 timeouts, about PM:227 adding PM:227 and visibility interest PM:230 callback method RM:321 example PM:228-229 invoking procedure after tirneout RM:67 removing PM:229-230 selection tirneout; setting RM:240; value RM:78, 87, 150 (see also XtAddTimeout, XtAppAddTimeOut) (see also XtAppSetSelectionTimeoul, XtGet- SelectionTimeout) (see also XtRemoveTimeOut, XtSetSelection- Timeout) (see also XtTimerCallbackProc) toolklts, initializing internals RM:250 initializing toolkit and display RM: 161-165 (see also XtIrLitialize, XtToolkitIrLitialize) top-level widget (see Shell widget) top-level window PM:514 topLevelShell widget class PM:270; RM:346-353 training In Xllb PM:489 TranslentShell widget class PM:70, 74, 270; RM:346-353 Translation Manager (see actions) translations, # augment directive PM:48 ! modifier symbol PM:200 # override directive PM:48 # replace directive PM:48 (see also accelerators) (see also actions) (see also XtOverrideTranslations) about PM:27, 39, 43, 47, 53, 514; RM:7 augmenting PM:48 colon modifier symbol PM:200-201 compiling; table RM:202-203; when widget class initialized PM: 147; XtParseTransla- tionTable RM:202-203 def'ming; default in Core class part PM:150; in source PM:49 details in PM:194-196 differences between directives PM: 191 directives PM:191 double-clicks PM:201 event abbreviations PM:192-193 event sequences PM:201-203 hardcoding PM:48 Inclox 535 child widget; about RM:15; creating/manag- ing PM:61,307;RM:118; layoutof PM:317 class; composite widget subclass PM: 16; determining subclass RM:175; name defined PM:150; obtaining RM:107; veri- fying RM:106; widgetClass class pointer PM:119; XtCheckSubclass RM:106; XtClass RM:107; XtlsComposite RM:169; XtlsConstraint RM:170; Xtls- Shell RM:174; XtlsSubclass RM:175 Command widget PM:19, 38-39, 40-42, 75, 104; RM:359-362 composite widget, about PM:21,305; RM:14, 169, 338-342; management PM:306; rea- sons forwriting PM:305; writing PM:312 compound PM:340-341 constraint widget, about PM:22, 305; RM: 16, 170, 343-345; management PM:325; writ- ing PM:325 converting (2 to 3) PM:453 Core widget PM:17, 116; RM:383 creating PM:30, 80; RM:122-123; additional top-level widget RM:69-70, 117; child widget RM:14; custom widget RM:383-390, 384; working window RM:124-125 declaring widget class record pointer; example PM:155 default size PM:180 defining conventions PM:136, 244; summary PM:162 destroying PM:26, 79, 183; RM:129-130; XtDestroyWidget RM: 129-130 Dialog widget PM:20, 75, 340; RM:363-364 display pointer RM: 134 displaying non-editable string RM:370-372 dragging PM:20; attachment point RM:368-369 Exclusive and Nonexclusive PM:407 Form widget PM:20, 104, 326, 421; RM:365-367 framework of code PM:135-162 geometry (see geometry management) getting data; example PM:105 getting widget data via public function PM:105 Grip widget PM:19; RM:368-369 implementation frie PM:135, 141-158; actions table PM:145-147; declaration of methods PM:147-148; resources PM:143-145; translation table PM:145-147 installing accelerators (see accelerators) instance structure PM:166 internals PM:135-162 Label widget PM:28, 116, 177, 258; RM:370-372 lifecycle RM:4 List widget PM:19; RM:373-377 macros for getting widget information PM:388 management PM:61,180-182; RM:171; row- column geometry RM:373-377; XtlsManaged RM:171 (see also XtManageChild, XtManageChildren) mapping PM:53; changing map_when_man- aged field RM:239; windows PM:33; XtMapWidget RM:185; XtSetMap- pedWhenManaged RM:239 merging translations RM:93-94 methods (see XtCreateWidge0 modal widget; redirecting input RM:52-53, 223; XtAddGrab RM:52-53; XtRemo- veGrab RM:223 moving/resizing PM:53; RM: 109-110; XtConfigureWidget RM: 109-110; XtMo- veWidget RM: 187 naming conventions PM:449 necessary include fries PM:136 parent widget PM:lll; returning RM:200; XtParent RM:200 popping down; Menupopdown RM:39 popping up PM:75-76; Menupopup RM:40-41 private header file PM:135, 136-140 procedure RM:322 public header file PM:135, 158-160 realizing PM:176; RM:172, 213-214; method RM:312-313; XtlsRealized RM:172; XtRealizeProc RM:312-313; XtReal- izeWidget RM:213-214 record size PM:150 removing PM:17; XtUnmanageChildren RM:258; XtUnmanageChild RM:257 resizing PM:65, 177-180, 306-314; RM:333; by application PM:312; by parent PM:311; per core dimensions RM:230; reasons for PM:322; resize method PM:336; XtMakeResizeRequest RM:180; XtResizeWidget RM:229; XtResizeWin- dow RM:230 retrieving event mask RM:95-96; XtBuil- dEventMask RM:95-96 returning screen pointer, XtScreen RM:231 Scroll widget PM:257 Scrollbar widget PM:19, 66, 108; RM:378-382 ScrollBox widget PM:314 Index 537 X Consortium address PM:490 X protocol PM:5,280 X source software PM:485 X Toolkit (see toolldts) X, about PM:3 XA CLIPBOARD (see selections) XA_MULTIPLE property (see selections) XA MULTIPLE property (see selections) XAPLRESDIR environment variable PM:245 XA_PRIMARY property (see selections) XA PRIMARY (see selections) XA SECONDARY (see selections) XA TARGETS atom (see selections) Xatom.h PM:288, 290 Xaw; PM:36 xbltmap application; PM:461 xbitmap I; example PM: 104-107 xbitmap2; example PM: I07-I 16 xbitmap3: example PM: I 16-122 xbitmaIM; example PM:123-132 XChangeGC Xllb function PM:I68 XChangeKeyboardMapplng RM:477 XClearArea Xllb function PM:I75 xcllpboard PM:300-302 XConflgureWlndow PM:341, RM:449-450, 485 XConvertSelectlon RM:487 XCopyArea Xllb function PM: 122, 174, 193; RM:297 XCopyColormapAndFree Xllb function PM:277 XCopyPlane Xllb function PM:I22, 174, 193; RM:297 XCreateGC Xllb function PM: 120, 166 XCreateWlndow Xlib function PM: 158 Xdefaults file PM:55, 245 xedlt PM:280 XENVIRONMENT envlronment varlable PM:245 xev PM:I98 XEvent unlon RM:437 xfarewell.c, example PM:43-45 xfd (font displayer) PM:441 XFlush Xllb function PM:394 XGCValues structure PM: 168 XGetIconSlzes Xllb function PM:279 XGetModlflerMapplng RM:478 XGetMotlonEvents RM:481 XGetPointerMapping RM:478 XGetStandardColormap Xllb function PM:277 xgoodbye.c, example PM:40 XGrabButton Xllb function PM:353 XGrabKey Xllb function PM:353 XGrabPointer Xllb function PM:352 xhello.c, example PM:31-32 XInternAtom Xlib function PM:290-291 Xlib PM:36, 170, 172, 176 Xlib Interface RM:17 xload PM:275 XLookupString Xllb function PM:391 XLowerWlndow Xlib function PM:341 XMapRalsed RM:479 XMapWindow RM:479 xmh PM:68,280 xmodmap PM:198 XMoveResizeWindow RM:485 Xmu PM:36, 259, 299 XmuConvertStandardSelection PM:300-301; RM:285 XmuConvertStandardSelection Xmu function PM:299 XmuInternAtom PM:299 XmuInternAtom Xmu function PM:299 Xmu, resource converters in PM:253 XNextEvent Xllb function PM:311 XParseGeometry Xllb function PM:274 XQueryPointer RM:481 XRaiseWindow Xllb function PM:341 xrdb PM:55, 243, 245 XRectlnRegion Xllb function PM: 172; RM:297 XRefreshKeyboardMapping RM:478 XResizeWindow RM:485 XRestackWindows Xllb function PM:341 XrmOptionDescRec RM:163 example PM:88-89 format PM:89 structure PM:88 XrmoptionlsArg argument style PM:90 XrmOptionKind enum values PM:90 XrmoptionNoArg argument style PM:90; RM: 165 XrmoptionResArg argument style PM:90 XrmoptionSepArg argument style PM:90 XrmoptionSklpArg argument style PM:90 XrmoptionSklpLine argument style PM:90 XrmoptionStickyArg argument style PM:90 XrmStringToQuark Xllb function PM:262 index 530 PM:253 XtRUnslgnedChar representation type PM:253 XtRWldget representation type PM:257 XtScreen RM:231 XtScrollbarSetThumb RM:381 XtSelectionCallbackProc PM:282; RM:316-317 XtSelectionDoneProc PM:282; RM:318 XtSetArg PM:50, 51, 93, 119; RM:232-233 XtSetErrorHandler PM:387, 393; RM:234 XtSetErrorMsgHandler PM:387, 393; RM:235 XtSetKeyboardFocus PM:391; RM:236-237 XtSetKeyTranslator RM:238 XtSetMappedWhenManaged RM:239 XtSetSelectionTlmeout PM:302, 393; RM:240 XtSetSensitive PM:75,371; RM:241 XtSetSubvalues PM:266; RM:242-243,275 XtSetValues PM:23, 49-51,136, 140, 154, 157, 165-166, 174-176, 319, 338; RM:244-245, 334-335,345 XtSetValuesFunc RM:319, 334 XtSetValuesFunc function prototype PM:175 XtSetWarningHandler PM:387, 393; RM:246 XtSetWarningMsgHandler PM:387, 393; RM:247 XtStringConverslonWarning PM:263, 387; RM:248 XtStringProc RM:320, 336 XtStringSourceCreate RM:401 XtStringSourceDestroy RM:402 XtSuperclass RM:249 XtTextBIock RM:399 XtTextChangeOptlons RM:400 XtTextDisableRedisplay RM:399 XtTextDisplay RM:400 XtTextEnableRedisplay RM:399 XtTextGetInsertionPoint RM:400 XtTextGetOptions RM:400 XtTextGetSelectionPos RM:398 XtTextGetSource RM:401 XtTextInvalldate RM:399 XtTextReplace RM:398 XtTextSetlnser tionPolnt RM:400 XtTextSetLastPos RM:400 XtTextSetSelection RM:397 XtTextSetSource RM:401 XtTextTopPosltion RM:400 XtTextUnsetSelection RM:398 XtTimeOut PM:393 XtTimerCallbackProc RM:321 XtToolkltInltiallze PM:30, 98, 243; RM:250 XtTranslateCoords PM:75,360-361; RM:25 XtTranslateKey PM:392; RM:252-253 XtTranslateKeycode PM:392; RM:254-255 XtUninstallTranslations RM:256 XtUnmanageChild PM:319; RM:257 XtUnmanageChildren PM:319; RM:258 XtUnmapWldget PM:319; RM:259 XtUnreallzeWldget RM:260 XtVaCreateArgsList PM:428 XtVaGetApplicationResources PM:260 XtVaGetSubresources PM:260 XtVerslon constant PM: 151 XtVerslonDontCheck constant PM: 151 XtWarnlng PM:386-387, 393; RM:261 XtWarningMsg PM:386-387, 393; RM:262 XtWidgetGeometry PM:320-323 XtWldgetGeometry structure PM: 180-182 XtWldgetProc PM:148; RM:322, 332-345 XtWldgetToAppllcationContext RM:263 XtWindow PM:176, 378; RM:264 XtWindowToWldget PM:389; RM:265 XtWorkProc PM:393; RM:323-324 XUnGrabPointer Xllb function PM:352 XVlew PM:10 XYPlxmap PM:515 Z zoomed window PM:515 ZPlxmap PM:515 Index 543 Please send me the information 1 have asked for on the reverse side of this card. PLACE STAMP HERE Name Company Address City _ State, ZIP (Fill out or tape business card here) Nutshell Handbooks NUtS.ELL O'Reilly & Associates. Inc. I t 632 Petaluma Avenue .A.DBOO,S Sebastopol CA 95472 Please send me the information I have asked for on the reverse side of this card. Name PLACE STAMP HERE Company Address City State, ZIP (Fill out or tape business card here) Nutshell Handbooks .UrSELL O'Reilly & Associates, Inc. ](1 632 Petaluma Avenue A.DBOOKS Sebastopol CA 95472 Overseas Distributors Effective January i. 1990, customers outside the U.S. and Canada will be able to order Nutshell Handbooks and the X Window System Series through distributors near them. These overseas locations offer international customers faster order processing, more local bookstores and local distributors, an increased representation at trade shows worldwide, as well as the high level, quality service our customers have always received. AUSTRALIA & NEW ZEALAND (orders and inquiries1 Addison-Wesley Publishers. Pty. Ltd. 6 Byfield Street North Ryde. N.S.W. 2113 AUSTRALIA Telephone: 61-2-888-2733 FAX: 6 I-2-888-94(14 ASIA inquiries (excluding Japan) Addison-Wesley Singapore Pte. Ltd. 15 Beach Road #05-09/10 Beach Centre Singapore 0718 SINGAPORE Telephone: 65-339-7503 FAX: 65-339-9709 UNITED KINGDOM & AFRICA (orders and inquiries) Addison-Wesley Publishers. Ltd. Finchampstead Road Wokin,,ham Berkshire RGI I 2NZ ENGLAND Telephone: 44-734-794-00(I FAX: 44-734-794-035 EUROPE & THE MIDDLE EAST (orders and inquiries) Addison-Wesley Publishers B.V. De Lairessestraat 9(I 1071 PJ Arnsterdan THE NETHERLANDS Telephone: 31-20-764-044 FAX: 3 I-2(I-664-5334 ASIA orders (excluding Japan Addison-Wesley Publishing Co.. Inc. International Order Department Route 128 Reading. Massachusetts ()1867 U.S.A. Telephone: 1-617-944-3700 FAX: 1-617-942-2829 JAPAN (orders and inquiries) Toppan Compan 3. Ltd. Ochanomizu Square B. I-6 Kanda Surugadai Chiyoda-ku. Tokyo I01 JAPAN Telephone: 81-3-295-3461 FAX: 81-3-293-5963