1mX Toolkit Intrinsics -- C Language Interface0m 1mX Window System0m 1mX Version 11, Release 6.40m First Revision - April, 1994 Joel McCormack Digital Equipment Corporation Western Software Laboratory Paul Asente Digital Equipment Corporation Western Software Laboratory Ralph R. Swick Digital Equipment Corporation External Research Group MIT X Consortium version 6 edited by Donna Converse X Consortium, Inc. X Window System is a trademark of X Consortium, Inc. Copyright © 1985, 1986, 1987, 1988, 1991, 1994 X Consortium Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documenta- tion files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PUR- POSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSOR- TIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Except as contained in this notice, the name of the X Con- sortium shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium. Copyright © 1985, 1986, 1987, 1988, 1991, 1994 Digital Equipment Corporation, Maynard, Massachusetts. Permission to use, copy, modify and distribute this documen- tation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permis- sion notice appear in supporting documentation, and that the name of Digital not be used in in advertising or publicity pertaining to distribution of the software without specific, written prior permission. Digital makes no representations about the suitability of the software described herein for any purpose. It is provided ``as is'' without express or implied warranty. 1mAcknowledgments0m The design of the X11 Intrinsics was done primarily by Joel McCormack of Digital WSL. Major contributions to the design and implementation also were done by Charles Haynes, Mike Chow, and Paul Asente of Digital WSL. Additional contribu- tors to the design and/or implementation were: Loretta Guarino-Reid (Digital WSL)Rich Hyde (Digital WSL) Susan Angebranndt (Digital WSL)Terry Weissman (Digital WSL) Mary Larson (Digital UEG) Mark Manasse (Digital SRC) Jim Gettys (Digital SRC) Leo Treggiari (Digital SDT) Ralph Swick (Project Athena and Digital ERP)Mark Ackerman (Project Athena) Ron Newman (Project Athena) Bob Scheifler (MIT LCS) The contributors to the X10 toolkit also deserve mention. Although the X11 Intrinsics present an entirely different programming style, they borrow heavily from the implicit and explicit concepts in the X10 toolkit. The design and implementation of the X10 Intrinsics were done by: Terry Weissman (Digital WSL) Smokey Wallace (Digital WSL) Phil Karlton (Digital WSL) Charles Haynes (Digital WSL) Frank Hall (HP) The design and implementation of the X10 toolkit's sample widgets were by the above, as well as by: Ram Rao (Digital UEG) Mary Larson (Digital UEG) Mike Gancarz (Digital UEG) Kathleen Langone (Digital UEG) These widgets provided a checklist of requirements that we had to address in the X11 Intrinsics. Thanks go to Al Mento of Digital's UEG Documentation Group for formatting and generally improving this document and to John Ousterhout of Berkeley for extensively reviewing early drafts of it. 1mxi0m Finally, a special thanks to Mike Chow, whose extensive per- formance analysis of the X10 toolkit provided the justifica- tion to redesign it entirely for X11. Joel McCormack Western Software Laboratory Digital Equipment Corporation March 1988 1mxii0m The current design of the Intrinsics has benefited greatly from the input of several dedicated reviewers in the member- ship of the X Consortium. In addition to those already men- tioned, the following individuals have dedicated significant time to suggesting improvements to the Intrinsics: Steve Pitschke (Stellar) C. Doug Blewett (AT&T) Bob Miller (HP) David Schiferl (Tektronix) Fred Taft (HP) Michael Squires (Sequent) Marcel Meth (AT&T) Jim Fulton (MIT) Mike Collins (Digital) Kerry Kimbrough (Texas Instruments) Scott McGregor (Digital) Phil Karlton (Digital) Julian Payne (ESS) Jacques Davy (Bull) Gabriel Beged-Dov (HP) Glenn Widener (Tektronix) Thanks go to each of them for the countless hours spent reviewing drafts and code. Ralph R. Swick External Research Group Digital Equipment Corporation MIT Project Athena June 1988 From Release 3 to Release 4, several new members joined the design team. We greatly appreciate the thoughtful comments, suggestions, lengthy discussions, and in some cases imple- mentation code contributed by each of the following: Don Alecci (AT&T) Ellis Cohen (OSF) Donna Converse (MIT) Clive Feather (IXI) Nayeem Islam (Sun) Dana Laursen (HP) Keith Packard (MIT) Chris Peterson (MIT) Richard Probst (Sun) Larry Cable (Sun) In Release 5, the effort to define the internationalization additions was headed by Bill McMahon of Hewlett Packard and Frank Rojas of IBM. This has been an educational process for many of us, and Bill and Frank's tutelage has carried us through. Vania Joloboff of the OSF also contributed to the internationalization additions. The implementation efforts of Bill, Gabe Beged-Dov, and especially Donna Converse for this release are also gratefully acknowledged. 1mxiii0m Ralph R. Swick December 1989 and July 1991 1mxiv0m The Release 6 Intrinsics is a result of the collaborative efforts of participants in the X Consortium's 1mintrinsics0m working group. A few individuals contributed substantial design proposals, participated in lengthy discussions, reviewed final specifications, and in most cases, were also responsible for sections of the implementation. They deserve recognition and thanks for their major contribu- tions: Paul Asente (Adobe) Larry Cable (SunSoft) Ellis Cohen (OSF) Daniel Dardailler (OSF) Vania Joloboff (OSF) Kaleb Keithley (X Consortium) Courtney Loomis (HP) Douglas Rand (OSF) Bob Scheifler (X Consortium) Ajay Vohra (SunSoft) Many others analyzed designs, offered useful comments and suggestions, and participated in a significant subset of the process. The following people deserve thanks for their con- tributions: Andy Bovingdon, Sam Chang, Chris Craig, George Erwin-Grotsky, Keith Edwards, Clive Feather, Stephen Gildea, Dan Heller, Steve Humphrey, David Kaelbling, Jaime Lau, Rob Lembree, Stuart Marks, Beth Mynatt, Tom Paquin, Chris Peter- son, Kamesh Ramakrishna, Tom Rodriguez, Jim VanGilder, Will Walker, and Mike Wexler. I am especially grateful to two of my colleagues: Ralph Swick for expert editorial guidance, and Kaleb Keithley for leadership in the implementation and the specification work. Donna Converse X Consortium April 1994 1mxv0m 1mAbout This Manual0m 4mX24m 4mToolkit24m 4mIntrinsics24m 4m--24m 4mC24m 4mLanguage24m 4mInterface24m is intended to be read by both application programmers who will use one or more of the many widget sets built with the Intrinsics and by widget programmers who will use the Intrinsics to build widgets for one of the widget sets. Not all the information in this manual, however, applies to both audiences. That is, because the application programmer is likely to use only a number of the Intrinsics functions in writing an applica- tion and because the widget programmer is likely to use many more, if not all, of the Intrinsics functions in building a widget, an attempt has been made to highlight those areas of information that are deemed to be of special interest for the application programmer. (It is assumed the widget pro- grammer will have to be familiar with all the information.) Therefore, all entries in the table of contents that are printed in 1mbold 22mindicate the information that should be of special interest to an application programmer. It is also assumed that, as application programmers become more familiar with the concepts discussed in this manual, they will find it more convenient to implement portions of their applications as special-purpose or custom widgets. It is possible, nonetheless, to use widgets without knowing how to build them. 1mConventions Used in this Manual0m This document uses the following conventions: · Global symbols are printed in 4mthis24m 4mspecial24m 4mfont24m. These can be either function names, symbols defined in include files, data types, or structure names. Argu- ments to functions, procedures, or macros are printed in 4mitalics24m. · Each function is introduced by a general discussion that distinguishes it from other functions. The func- tion declaration itself follows, and each argument is specifically explained. General discussion of the function, if any is required, follows the arguments. · To eliminate any ambiguity between those arguments that you pass and those that a function returns to you, the explanations for all arguments that you pass start with the word 4mspecifies24m or, in the case of multiple argu- ments, the word 4mspecify24m. The explanations for all arguments that are returned to you start with the word 4mreturns24m or, in the case of multiple arguments, the word 1mxvi0m 4mreturn24m. 1mxvii0m 1mChapter 10m 1mIntrinsics and Widgets0m The Intrinsics are a programming library tailored to the special requirements of user interface construction within a network window system, specifically the X Window System. The Intrinsics and a widget set make up an X Toolkit. 1m1.1. Intrinsics0m The Intrinsics provide the base mechanism necessary to build a wide variety of interoperating widget sets and application environments. The Intrinsics are a layer on top of Xlib, the C Library X Interface. They extend the fundamental abstractions provided by the X Window System while still remaining independent of any particular user interface pol- icy or style. The Intrinsics use object-oriented programming techniques to supply a consistent architecture for constructing and com- posing user interface components, known as widgets. This allows programmers to extend a widget set in new ways, either by deriving new widgets from existing ones (subclass- ing) or by writing entirely new widgets following the estab- lished conventions. When the Intrinsics were first conceived, the root of the object hierarchy was a widget class named Core. In Release 4 of the Intrinsics, three nonwidget superclasses were added above Core. These superclasses are described in Chapter 12. The name of the class now at the root of the Intrinsics class hierarchy is Object. The remainder of this specifica- tion refers uniformly to 4mwidgets24m and 4mCore24m as if they were the base class for all Intrinsics operations. The argument descriptions for each Intrinsics procedure and Chapter 12 describe which operations are defined for the nonwidget superclasses of Core. The reader may determine by context whether a specific reference to 4mwidget24m actually means ``wid- get'' or ``object.'' 1m1.2. Languages0m The Intrinsics are intended to be used for two programming purposes. Programmers writing widgets will be using most of the facilities provided by the Intrinsics to construct user interface components from the simple, such as buttons and scrollbars, to the complex, such as control panels and 1m10m 1mX Toolkit Intrinsics X11 Release 6.40m property sheets. Application programmers will use a much smaller subset of the Intrinsics procedures in combination with one or more sets of widgets to construct and present complete user interfaces on an X display. The Intrinsics programming interfaces primarily intended for application use are designed to be callable from most procedural pro- gramming languages. Therefore, most arguments are passed by reference rather than by value. The interfaces primarily intended for widget programmers are expected to be used principally from the C language. In these cases, the usual C programming conventions apply. In this specification, the term 4mclient24m refers to any module, widget, or application that calls an Intrinsics procedure. Applications that use the Intrinsics mechanisms must include the header files <4mX11/Intrinsic.h24m> and <4mX11/StringDefs.h24m>, or their equivalent, and they may also include <4mX11/Xatoms.h24m> and <4mX11/Shell.h24m>. In addition, widget implementations should include <4mX11/IntrinsicP.h24m> instead of <4mX11/Intrinsic.h24m>. The applications must also include the additional header files for each widget class that they are to use (for exam- ple, <4mX11/Xaw/Label.h24m> or <4mX11/Xaw/Scrollbar.h24m>). On a POSIX-based system, the Intrinsics object library file is named 4mlibXt.a24m and is usually referenced as -lXt when linking the application. 1m1.3. Procedures and Macros0m All functions defined in this specification except those specified below may be implemented as C macros with argu- ments. C applications may use ``#undef'' to remove a macro definition and ensure that the actual function is refer- enced. Any such macro will expand to a single expression that has the same precedence as a function call and that evaluates each of its arguments exactly once, fully pro- tected by parentheses, so that arbitrary expressions may be used as arguments. The following symbols are macros that do not have function equivalents and that may expand their arguments in a manner other than that described above: 4mXtCheckSubclass24m, 4mXtNew24m, 4mXtNumber24m, 4mXtOffsetOf24m, 4mXtOffset24m, and 4mXtSetArg24m. 1m1.4. Widgets0m The fundamental abstraction and data type of the X Toolkit is the widget, which is a combination of an X window and its associated input and display semantics and which is dynami- cally allocated and contains state information. Some 1m20m 1mX Toolkit Intrinsics X11 Release 6.40m widgets display information (for example, text or graphics), and others are merely containers for other widgets (for example, a menu box). Some widgets are output-only and do not react to pointer or keyboard input, and others change their display in response to input and can invoke functions that an application has attached to them. Every widget belongs to exactly one widget class, which is statically allocated and initialized and which contains the operations allowable on widgets of that class. Logically, a widget class is the procedures and data associated with all widgets belonging to that class. These procedures and data can be inherited by subclasses. Physically, a widget class is a pointer to a structure. The contents of this structure are constant for all widgets of the widget class but will vary from class to class. (Here, ``constant'' means the class structure is initialized at compile time and never changed, except for a one-time class initialization and in- place compilation of resource lists, which takes place when the first widget of the class or subclass is created.) For further information, see Section 2.5. The distribution of the declarations and code for a new wid- get class among a public .h file for application programmer use, a private .h file for widget programmer use, and the implementation .c file is described in Section 1.6. The predefined widget classes adhere to these conventions. A widget instance is composed of two parts: · A data structure which contains instance-specific val- ues. · A class structure which contains information that is applicable to all widgets of that class. Much of the input/output of a widget (for example, fonts, colors, sizes, or border widths) is customizable by users. This chapter discusses the base widget classes, Core, Com- posite, and Constraint, and ends with a discussion of widget classing. 1m1.4.1. Core Widgets0m The Core widget class contains the definitions of fields common to all widgets. All widgets classes are subclasses of the Core class, which is defined by the 4mCoreClassPart24m and 4mCorePart24m structures. 1m30m 1mX Toolkit Intrinsics X11 Release 6.40m 1m1.4.1.1. CoreClassPart Structure0m All widget classes contain the fields defined in the 4mCore-0m 4mClassPart24m structure. __ | typedef struct { WidgetClass superclass; See Section 1.6 String class_name; See Chapter 9 Cardinal widget_size; See Section 1.6 XtProc class_initialize; See Section 1.6 XtWidgetClassProc class_part_initialize;See Section 1.6 XtEnum class_inited; See Section 1.6 XtInitProc initialize; See Section 2.5 XtArgsProc initialize_hook; See Section 2.5 XtRealizeProc realize; See Section 2.6 XtActionList actions; See Chapter 10 Cardinal num_actions; See Chapter 10 XtResourceList resources; See Chapter 9 Cardinal num_resources; See Chapter 9 XrmClass xrm_class; Private to resource manager Boolean compress_motion; See Section 7.9 XtEnum compress_exposure; See Section 7.9 Boolean compress_enterleave; See Section 7.9 Boolean visible_interest; See Section 7.10 XtWidgetProc destroy; See Section 2.8 XtWidgetProc resize; See Chapter 6 XtExposeProc expose; See Section 7.10 XtSetValuesFunc set_values; See Section 9.7 XtArgsFunc set_values_hook; See Section 9.7 XtAlmostProc set_values_almost;See Section 9.7 XtArgsProc get_values_hook; See Section 9.7 XtAcceptFocusProc accept_focus;See Section 7.3 XtVersionType version; See Section 1.6 XtPointer callback_private; Private to callbacks String tm_table; See Chapter 10 XtGeometryHandler query_geometry;See Chapter 6 XtStringProc display_accelerator;See Chapter 10 XtPointer extension; See Section 1.6 } CoreClassPart; |__ All widget classes have the Core class fields as their first component. The prototypical 4mWidgetClass24m and 4mCoreWidgetClass0m are defined with only this set of fields. 1m40m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct { CoreClassPart core_class; } WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass; |__ Various routines can cast widget class pointers, as needed, to specific widget class types. The single occurrences of the class record and pointer for creating instances of Core are In 4mIntrinsicP.h24m: __ | extern WidgetClassRec widgetClassRec; #define coreClassRec widgetClassRec |__ In 4mIntrinsic.h24m: __ | extern WidgetClass widgetClass, coreWidgetClass; |__ The opaque types 4mWidget24m and 4mWidgetClass24m and the opaque vari- able 4mwidgetClass24m are defined for generic actions on widgets. In order to make these types opaque and ensure that the com- piler does not allow applications to access private data, the Intrinsics use incomplete structure definitions in 4mIntrinsic.h24m: __ | typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass; |__ 1m1.4.1.2. CorePart Structure0m All widget instances contain the fields defined in the 4mCorePart24m structure. 1m50m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct _CorePart { Widget self; Described below WidgetClass widget_class;See Section 1.6 Widget parent; See Section 2.5 Boolean being_destroyed; See Section 2.8 XtCallbackList destroy_callbacks;See Section 2.8 XtPointer constraints; See Section 3.6 Position x; See Chapter 6 Position y; See Chapter 6 Dimension width; See Chapter 6 Dimension height; See Chapter 6 Dimension border_width; See Chapter 6 Boolean managed; See Chapter 3 Boolean sensitive; See Section 7.7 Boolean ancestor_sensitive;See Section 7.7 XtTranslations accelerators;See Chapter 10 Pixel border_pixel; See Section 2.6 Pixmap border_pixmap; See Section 2.6 WidgetList popup_list; See Chapter 5 Cardinal num_popups; See Chapter 5 String name; See Chapter 9 Screen *screen; See Section 2.6 Colormap colormap; See Section 2.6 Window window; See Section 2.6 Cardinal depth; See Section 2.6 Pixel background_pixel; See Section 2.6 Pixmap background_pixmap;See Section 2.6 Boolean visible; See Section 7.10 Boolean mapped_when_managed;See Chapter 3 } CorePart; |__ All widget instances have the Core fields as their first component. The prototypical type 4mWidget24m is defined with only this set of fields. __ | typedef struct { CorePart core; } WidgetRec, *Widget, CoreRec, *CoreWidget; |__ Various routines can cast widget pointers, as needed, to specific widget types. In order to make these types opaque and ensure that the com- piler does not allow applications to access private data, the Intrinsics use incomplete structure definitions in 4mIntrinsic.h24m. 1m60m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct _WidgetRec *Widget, *CoreWidget; |__ 1m1.4.1.3. Core Resources0m The resource names, classes, and representation types speci- fied in the 4mcoreClassRec24m resource list are ------------------------------------------------------------------------ Name Class Representation ------------------------------------------------------------------------ XtNaccelerators XtCAccelerators XtRAcceleratorTable XtNbackground XtCBackground XtRPixel XtNbackgroundPixmap XtCPixmap XtRPixmap XtNborderColor XtCBorderColor XtRPixel XtNborderPixmap XtCPixmap XtRPixmap XtNcolormap XtCColormap XtRColormap XtNdepth XtCDepth XtRInt XtNmappedWhenManaged XtCMappedWhenManaged XtRBoolean XtNscreen XtCScreen XtRScreen XtNtranslations XtCTranslations XtRTranslationTable ------------------------------------------------------------------------ Additional resources are defined for all widgets via the 4mobjectClassRec24m and 4mrectObjClassRec24m resource lists; see Sec- tions 12.2 and 12.3 for details. 1m1.4.1.4. CorePart Default Values0m The default values for the Core fields, which are filled in by the Intrinsics, from the resource lists, and by the ini- tialize procedures, are ------------------------------------------------------------------------------ Field Default Value ------------------------------------------------------------------------------ self Address of the widget structure (may not be changed). widget_class 4mwidget_class24m argument to 4mXtCreateWidget24m (may not be changed). parent 4mparent24m argument to 4mXtCreateWidget24m (may not be changed). being_destroyed Parent's 4mbeing_destroyed24m value. destroy_callbacks NULL constraints NULL x 0 y 0 1m70m 1mX Toolkit Intrinsics X11 Release 6.40m width 0 height 0 border_width 1 managed 4mFalse0m sensitive 4mTrue0m ancestor_sensitive logical AND of parent's 4msensitive24m and 4mancestor_sensitive0m values. accelerators NULL border_pixel 4mXtDefaultForeground0m border_pixmap 4mXtUnspecifiedPixmap0m popup_list NULL num_popups 0 name 4mname24m argument to 4mXtCreateWidget24m (may not be changed). screen Parent's 4mscreen24m; top-level widget gets screen from dis- play specifier (may not be changed). colormap Parent's 4mcolormap24m value. window NULL depth Parent's 4mdepth24m; top-level widget gets root window depth. background_pixel 4mXtDefaultBackground0m background_pixmap 4mXtUnspecifiedPixmap0m visible 4mTrue0m mapped_when_man- 4mTrue0m aged ------------------------------------------------------------------------------ 4mXtUnspecifiedPixmap24m is a symbolic constant guaranteed to be unequal to any valid Pixmap id, 4mNone24m, and 4mParentRelative24m. 1m1.4.2. Composite Widgets0m The Composite widget class is a subclass of the Core widget class (see Chapter 3). Composite widgets are intended to be containers for other widgets. The additional data used by composite widgets are defined by the 4mCompositeClassPart24m and 4mCompositePart24m structures. 1m1.4.2.1. CompositeClassPart Structure0m In addition to the Core class fields, widgets of the Compos- ite class have the following class fields. 1m80m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct { XtGeometryHandler geometry_manager;See Chapter 6 XtWidgetProc change_managed; See Chapter 3 XtWidgetProc insert_child; See Chapter 3 XtWidgetProc delete_child; See Chapter 3 XtPointer extension; See Section 1.6 } CompositeClassPart; |__ The extension record defined for 4mCompositeClassPart24m with 4mrecord_type24m equal to 4mNULLQUARK24m is 4mCompositeClassExtension-0m 4mRec24m. __ | typedef struct { XtPointer next_extension; See Section 1.6.12 XrmQuark record_type; See Section 1.6.12 long version; See Section 1.6.12 Cardinal record_size; See Section 1.6.12 Boolean accepts_objects; See Section 2.5.2 Boolean allows_change_managed_set;See Section 3.4.3 } CompositeClassExtensionRec, *CompositeClassExtension; |__ Composite classes have the Composite class fields immedi- ately following the Core class fields. __ | typedef struct { CoreClassPart core_class; CompositeClassPart composite_class; } CompositeClassRec, *CompositeWidgetClass; |__ The single occurrences of the class record and pointer for creating instances of Composite are In 4mIntrinsicP.h24m: __ | extern CompositeClassRec compositeClassRec; |__ In 4mIntrinsic.h24m: 1m90m 1mX Toolkit Intrinsics X11 Release 6.40m __ | extern WidgetClass compositeWidgetClass; |__ The opaque types 4mCompositeWidget24m and 4mCompositeWidgetClass0m and the opaque variable 4mcompositeWidgetClass24m are defined for generic operations on widgets whose class is Composite or a subclass of Composite. The symbolic constant for the 4mCom-0m 4mpositeClassExtension24m version identifier is 4mXtCompositeExten-0m 4msionVersion24m (see Section 1.6.12). 4mIntrinsic.h24m uses an incomplete structure definition to ensure that the compiler catches attempts to access private data. __ | typedef struct _CompositeClassRec *CompositeWidgetClass; |__ 1m1.4.2.2. CompositePart Structure0m In addition to the Core instance fields, widgets of the Com- posite class have the following instance fields defined in the 4mCompositePart24m structure. __ | typedef struct { WidgetList children; See Chapter 3 Cardinal num_children; See Chapter 3 Cardinal num_slots; See Chapter 3 XtOrderProc insert_position;See Section 3.2 } CompositePart; |__ Composite widgets have the Composite instance fields immedi- ately following the Core instance fields. __ | typedef struct { CorePart core; CompositePart composite; } CompositeRec, *CompositeWidget; |__ 4mIntrinsic.h24m uses an incomplete structure definition to ensure that the compiler catches attempts to access private data. 1m100m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct _CompositeRec *CompositeWidget; |__ 1m1.4.2.3. Composite Resources0m The resource names, classes, and representation types that are specified in the 4mcompositeClassRec24m resource list are ------------------------------------------------------------- Name Class Representation ------------------------------------------------------------- XtNchildren XtCReadOnly XtRWidgetList XtNinsertPosition XtCInsertPosition XtRFunction XtNnumChildren XtCReadOnly XtRCardinal ------------------------------------------------------------- 1m1.4.2.4. CompositePart Default Values0m The default values for the Composite fields, which are filled in from the Composite resource list and by the Com- posite initialize procedure, are ----------------------------------------------------- Field Default Value ----------------------------------------------------- children NULL num_children 0 num_slots 0 insert_position Internal function to insert at end ----------------------------------------------------- The 4mchildren24m, 4mnum_children24m, and 4minsert_position24m fields are declared as resources; XtNinsertPosition is a settable resource, XtNchildren and XtNnumChildren may be read by any client but should only be modified by the composite widget class procedures. 1m1.4.3. Constraint Widgets0m The Constraint widget class is a subclass of the Composite widget class (see Section 3.6). Constraint widgets maintain additional state data for each child; for example, client- defined constraints on the child's geometry. The additional data used by constraint widgets are defined by the 4mCon-0m 4mstraintClassPart24m and 4mConstraintPart24m structures. 1m110m 1mX Toolkit Intrinsics X11 Release 6.40m 1m1.4.3.1. ConstraintClassPart Structure0m In addition to the Core and Composite class fields, widgets of the Constraint class have the following class fields. __ | typedef struct { XtResourceList resources;See Chapter 9 Cardinal num_resources; See Chapter 9 Cardinal constraint_size;See Section 3.6 XtInitProc initialize; See Section 3.6 XtWidgetProc destroy; See Section 3.6 XtSetValuesFunc set_values;See Section 9.7.2 XtPointer extension; See Section 1.6 } ConstraintClassPart; |__ The extension record defined for 4mConstraintClassPart24m with 4mrecord_type24m equal to 4mNULLQUARK24m is 4mConstraintClassExtension-0m 4mRec24m. __ | typedef struct { XtPointer next_extension;See Section 1.6.12 XrmQuark record_type; See Section 1.6.12 long version; See Section 1.6.12 Cardinal record_size; See Section 1.6.12 XtArgsProc get_values_hook;See Section 9.7.1 } ConstraintClassExtensionRec, *ConstraintClassExtension; |__ Constraint classes have the Constraint class fields immedi- ately following the Composite class fields. __ | typedef struct _ConstraintClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ConstraintClassPart constraint_class; } ConstraintClassRec, *ConstraintWidgetClass; |__ The single occurrences of the class record and pointer for creating instances of Constraint are In 4mIntrinsicP.h24m: 1m120m 1mX Toolkit Intrinsics X11 Release 6.40m __ | extern ConstraintClassRec constraintClassRec; |__ In 4mIntrinsic.h24m: __ | extern WidgetClass constraintWidgetClass; |__ The opaque types 4mConstraintWidget24m and 4mConstraintWidgetClass0m and the opaque variable 4mconstraintWidgetClass24m are defined for generic operations on widgets whose class is Constraint or a subclass of Constraint. The symbolic constant for the 4mConstraintClassExtension24m version identifier is 4mXtConstrain-0m 4mtExtensionVersion24m (see Section 1.6.12). 4mIntrinsic.h24m uses an incomplete structure definition to ensure that the compiler catches attempts to access private data. __ | typedef struct _ConstraintClassRec *ConstraintWidgetClass; |__ 1m1.4.3.2. ConstraintPart Structure0m In addition to the Core and Composite instance fields, wid- gets of the Constraint class have the following unused instance fields defined in the 4mConstraintPart24m structure __ | typedef struct { int empty; } ConstraintPart; |__ Constraint widgets have the Constraint instance fields imme- diately following the Composite instance fields. 1m130m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct { CorePart core; CompositePart composite; ConstraintPart constraint; } ConstraintRec, *ConstraintWidget; |__ 4mIntrinsic.h24m uses an incomplete structure definition to ensure that the compiler catches attempts to access private data. __ | typedef struct _ConstraintRec *ConstraintWidget; |__ 1m1.4.3.3. Constraint Resources0m The 4mconstraintClassRec24m 4mcore_class24m and 4mconstraint_class0m 4mresources24m fields are NULL, and the 4mnum_resources24m fields are zero; no additional resources beyond those declared by the superclasses are defined for Constraint. 1m1.5. Implementation-Specific Types0m To increase the portability of widget and application source code between different system environments, the Intrinsics define several types whose precise representation is explic- itly dependent upon, and chosen by, each individual imple- mentation of the Intrinsics. These implementation-defined types are 1mBoolean 22mA datum that contains a zero or nonzero value. Unless explicitly stated, clients should not assume that the nonzero value is equal to the symbolic value 4mTrue24m. 1mCardinal 22mAn unsigned integer datum with a minimum range of [0..2^16-1]. 1mDimension 22mAn unsigned integer datum with a minimum range of [0..2^16-1]. 1mPosition 22mA signed integer datum with a minimum range of [-2^15..2^15-1]. 1mXtPointer 22mA datum large enough to contain the largest of a char*, int*, function pointer, structure pointer, 1m140m 1mX Toolkit Intrinsics X11 Release 6.40m or long value. A pointer to any type or func- tion, or a long value may be converted to an 4mXtPointer24m and back again and the result will com- pare equal to the original value. In ANSI C environments it is expected that 4mXtPointer24m will be defined as void*. 1mXtArgVal 22mA datum large enough to contain an 4mXtPointer24m, 4mCardinal24m, 4mDimension24m, or 4mPosition24m value. 1mXtEnum 22mAn integer datum large enough to encode at least 128 distinct values, two of which are the sym- bolic values 4mTrue24m and 4mFalse24m. The symbolic values 4mTRUE24m and 4mFALSE24m are also defined to be equal to 4mTrue24m and 4mFalse24m, respectively. In addition to these specific types, the precise order of the fields within the structure declarations for any of the instance part records 4mObjectPart24m, 4mRectObjPart24m, 4mCorePart24m, 4mCompositePart24m, 4mShellPart24m, 4mWMShellPart24m, 4mTopLevelShellPart24m, and 4mApplicationShellPart24m is implementation-defined. These structures may also have additional private fields internal to the implementation. The 4mObjectPart24m, 4mRectObjPart24m, and 4mCorePart24m structures must be defined so that any member with the same name appears at the same offset in 4mObjectRec24m, 4mRect-0m 4mObjRec24m, and 4mCoreRec24m (4mWidgetRec24m). No other relations between the offsets of any two fields may be assumed. 1m1.6. Widget Classing0m The 4mwidget_class24m field of a widget points to its widget class structure, which contains information that is constant across all widgets of that class. As a consequence, widgets usually do not implement directly callable procedures; rather, they implement procedures, called methods, that are available through their widget class structure. These meth- ods are invoked by generic procedures that envelop common actions around the methods implemented by the widget class. Such procedures are applicable to all widgets of that class and also to widgets whose classes are subclasses of that class. All widget classes are a subclass of Core and can be sub- classed further. Subclassing reduces the amount of code and declarations necessary to make a new widget class that is similar to an existing class. For example, you do not have to describe every resource your widget uses in an 4mXtRe-0m 4msourceList24m. Instead, you describe only the resources your widget has that its superclass does not. Subclasses usually inherit many of their superclasses' procedures (for example, the expose procedure or geometry handler). 1m150m 1mX Toolkit Intrinsics X11 Release 6.40m Subclassing, however, can be taken too far. If you create a subclass that inherits none of the procedures of its super- class, you should consider whether you have chosen the most appropriate superclass. To make good use of subclassing, widget declarations and naming conventions are highly stylized. A widget consists of three files: · A public .h file, used by client widgets or applica- tions. · A private .h file, used by widgets whose classes are subclasses of the widget class. · A .c file, which implements the widget. 1m1.6.1. Widget Naming Conventions0m The Intrinsics provide a vehicle by which programmers can create new widgets and organize a collection of widgets into an application. To ensure that applications need not deal with as many styles of capitalization and spelling as the number of widget classes it uses, the following guidelines should be followed when writing new widgets: · Use the X library naming conventions that are applica- ble. For example, a record component name is all low- ercase and uses underscores (_) for compound words (for example, background_pixmap). Type and procedure names start with uppercase and use capitalization for com- pound words (for example, 4mArgList24m or 4mXtSetValues24m). · A resource name is spelled identically to the field name except that compound names use capitalization rather than underscore. To let the compiler catch spelling errors, each resource name should have a sym- bolic identifier prefixed with ``XtN''. For example, the 4mbackground_pixmap24m field has the corresponding iden- tifier XtNbackgroundPixmap, which is defined as the string ``backgroundPixmap''. Many predefined names are listed in <4mX11/StringDefs.h24m>. Before you invent a new name, you should make sure there is not already a name that you can use. · A resource class string starts with a capital letter and uses capitalization for compound names (for exam- ple,``BorderWidth''). Each resource class string should have a symbolic identifier prefixed with ``XtC'' (for example, XtCBorderWidth). Many predefined classes are listed in <4mX11/StringDefs.h24m>. 1m160m 1mX Toolkit Intrinsics X11 Release 6.40m · A resource representation string is spelled identically to the type name (for example, ``TranslationTable''). Each representation string should have a symbolic iden- tifier prefixed with ``XtR'' (for example, XtRTransla- tionTable). Many predefined representation types are listed in <4mX11/StringDefs.h24m>. · New widget classes start with a capital and use upper- case for compound words. Given a new class name AbcXyz, you should derive several names: - Additional widget instance structure part name AbcXyzPart. - Complete widget instance structure names AbcXyzRec and _AbcXyzRec. - Widget instance structure pointer type name AbcXyzWidget. - Additional class structure part name AbcXyzClass- Part. - Complete class structure names AbcXyzClassRec and _AbcXyzClassRec. - Class structure pointer type name AbcXyzWidget- Class. - Class structure variable abcXyzClassRec. - Class structure pointer variable abcXyzWidget- Class. · Action procedures available to translation specifica- tions should follow the same naming conventions as pro- cedures. That is, they start with a capital letter, and compound names use uppercase (for example, ``High- light'' and ``NotifyClient''). The symbolic identifiers XtN..., XtC..., and XtR... may be implemented as macros, as global symbols, or as a mixture of the two. The (implicit) type of the identifier is 4mString24m. The pointer value itself is not significant; clients must not assume that inequality of two identifiers implies inequality of the resource name, class, or representation string. Clients should also note that although global sym- bols permit savings in literal storage in some environments, they also introduce the possibility of multiple definition conflicts when applications attempt to use independently developed widgets simultaneously. 1m170m 1mX Toolkit Intrinsics X11 Release 6.40m 1m1.6.2. Widget Subclassing in Public .h Files0m The public .h file for a widget class is imported by clients and contains · A reference to the public .h file for the superclass. · Symbolic identifiers for the names and classes of the new resources that this widget adds to its superclass. The definitions should have a single space between the definition name and the value and no trailing space or comment in order to reduce the possibility of compiler warnings from similar declarations in multiple classes. · Type declarations for any new resource data types defined by the class. · The class record pointer variable used to create widget instances. · The C type that corresponds to widget instances of this class. · Entry points for new class methods. For example, the following is the public .h file for a pos- sible implementation of a Label widget: #ifndef LABEL_H #define LABEL_H /* New resources */ #define XtNjustify "justify" #define XtNforeground "foreground" #define XtNlabel "label" #define XtNfont "font" #define XtNinternalWidth "internalWidth" #define XtNinternalHeight "internalHeight" /* Class record pointer */ extern WidgetClass labelWidgetClass; /* C Widget type definition */ typedef struct _LabelRec *LabelWidget; /* New class method entry points */ extern void LabelSetText(); /* Widget w */ /* String text */ extern String LabelGetText(); /* Widget w */ 1m180m 1mX Toolkit Intrinsics X11 Release 6.40m #endif LABEL_H The conditional inclusion of the text allows the application to include header files for different widgets without being concerned that they already may be included as a superclass of another widget. To accommodate operating systems with file name length restrictions, the name of the public .h file is the first ten characters of the widget class. For example, the public .h file for the Constraint widget class is 4mConstraint.h24m. 1m1.6.3. Widget Subclassing in Private .h Files0m The private .h file for a widget is imported by widget classes that are subclasses of the widget and contains · A reference to the public .h file for the class. · A reference to the private .h file for the superclass. · Symbolic identifiers for any new resource representa- tion types defined by the class. The definitions should have a single space between the definition name and the value and no trailing space or comment. · A structure part definition for the new fields that the widget instance adds to its superclass's widget struc- ture. · The complete widget instance structure definition for this widget. · A structure part definition for the new fields that this widget class adds to its superclass's constraint structure if the widget class is a subclass of Con- straint. · The complete constraint structure definition if the widget class is a subclass of Constraint. · Type definitions for any new procedure types used by class methods declared in the widget class part. · A structure part definition for the new fields that this widget class adds to its superclass's widget class structure. · The complete widget class structure definition for this widget. 1m190m 1mX Toolkit Intrinsics X11 Release 6.40m · The complete widget class extension structure defini- tion for this widget, if any. · The symbolic constant identifying the class extension version, if any. · The name of the global class structure variable con- taining the generic class structure for this class. · An inherit constant for each new procedure in the wid- get class part structure. For example, the following is the private .h file for a pos- sible Label widget: #ifndef LABELP_H #define LABELP_H #include /* New representation types used by the Label widget */ #define XtRJustify "Justify" /* New fields for the Label widget record */ typedef struct { /* Settable resources */ Pixel foreground; XFontStruct *font; String label; /* text to display */ XtJustify justify; Dimension internal_width;/* # pixels horizontal border */ Dimension internal_height;/* # pixels vertical border */ /* Data derived from resources */ GC normal_GC; GC gray_GC; Pixmap gray_pixmap; Position label_x; Position label_y; Dimension label_width; Dimension label_height; Cardinal label_len; Boolean display_sensitive; } LabelPart; /* Full instance record declaration */ typedef struct _LabelRec { CorePart core; LabelPart label; } LabelRec; 1m200m 1mX Toolkit Intrinsics X11 Release 6.40m /* Types for Label class methods */ typedef void (*LabelSetTextProc)(); /* Widget w */ /* String text */ typedef String (*LabelGetTextProc)(); /* Widget w */ /* New fields for the Label widget class record */ typedef struct { LabelSetTextProc set_text; LabelGetTextProc get_text; XtPointer extension; } LabelClassPart; /* Full class record declaration */ typedef struct _LabelClassRec { CoreClassPart core_class; LabelClassPart label_class; } LabelClassRec; /* Class record variable */ extern LabelClassRec labelClassRec; #define LabelInheritSetText((LabelSetTextProc)_XtInherit) #define LabelInheritGetText((LabelGetTextProc)_XtInherit) #endif LABELP_H To accommodate operating systems with file name length restrictions, the name of the private .h file is the first nine characters of the widget class followed by a capital P. For example, the private .h file for the Constraint widget class is 4mConstrainP.h24m. 1m1.6.4. Widget Subclassing in .c Files0m The .c file for a widget contains the structure initializer for the class record variable, which contains the following parts: · Class information (for example, 4msuperclass24m, 4mclass_name24m, 4mwidget_size24m, 4mclass_initialize24m, and 4mclass_inited24m). · Data constants (for example, 4mresources24m and 4mnum_resources24m, 4mactions24m and 4mnum_actions24m, 4mvisible_inter-0m 4mest24m, 4mcompress_motion24m, 4mcompress_exposure24m, and 4mversion24m). · Widget operations (for example, 4minitialize24m, 4mrealize24m, 4mdestroy24m, 4mresize24m, 4mexpose24m, 4mset_values24m, 4maccept_focus24m, and any new operations specific to the widget). 1m210m 1mX Toolkit Intrinsics X11 Release 6.40m The 4msuperclass24m field points to the superclass global class record, declared in the superclass private .h file. For direct subclasses of the generic core widget, 4msuperclass0m should be initialized to the address of the 4mwidgetClassRec0m structure. The superclass is used for class chaining opera- tions and for inheriting or enveloping a superclass's opera- tions (see Sections 1.6.7, 1.6.9, and 1.6.10). The 4mclass_name24m field contains the text name for this class, which is used by the resource manager. For example, the Label widget has the string ``Label''. More than one widget class can share the same text class name. This string must be permanently allocated prior to or during the execution of the class initialization procedure and must not be subse- quently deallocated. The 4mwidget_size24m field is the size of the corresponding wid- get instance structure (not the size of the class struc- ture). The 4mversion24m field indicates the toolkit implementation ver- sion number and is used for runtime consistency checking of the X Toolkit and widgets in an application. Widget writers must set it to the implementation-defined symbolic value 4mXtVersion24m in the widget class structure initialization. Those widget writers who believe that their widget binaries are compatible with other implementations of the Intrinsics can put the special value 4mXtVersionDontCheck24m in the 4mversion0m field to disable version checking for those widgets. If a widget needs to compile alternative code for different revi- sions of the Intrinsics interface definition, it may use the symbol 4mXtSpecificationRelease24m, as described in Chapter 13. Use of 4mXtVersion24m allows the Intrinsics implementation to recognize widget binaries that were compiled with older implementations. The 4mextension24m field is for future upward compatibility. If the widget programmer adds fields to class parts, all sub- class structure layouts change, requiring complete recompi- lation. To allow clients to avoid recompilation, an exten- sion field at the end of each class part can point to a record that contains any additional class information required. All other fields are described in their respective sections. The .c file also contains the declaration of the global class structure pointer variable used to create instances of the class. The following is an abbreviated version of the .c file for a Label widget. The resources table is described in Chapter 9. 1m220m 1mX Toolkit Intrinsics X11 Release 6.40m /* Resources specific to Label */ static XtResource resources[] = { {XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel), XtOffset(LabelWidget, label.foreground), XtRString, XtDefaultForeground}, {XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct *), XtOffset(LabelWidget, label.font),XtRString, XtDefaultFont}, {XtNlabel, XtCLabel, XtRString, sizeof(String), XtOffset(LabelWidget, label.label), XtRString, NULL}, . . . } /* Forward declarations of procedures */ static void ClassInitialize(); static void Initialize(); static void Realize(); static void SetText(); static void GetText(); . . . /* Class record constant */ LabelClassRec labelClassRec = { { /* core_class fields */ /* superclass */ (WidgetClass)&coreClassRec, /* class_name */ "Label", /* widget_size */ sizeof(LabelRec), /* class_initialize */ClassInitialize, /* class_part_initialize */NULL, /* class_inited */False, /* initialize */ Initialize, /* initialize_hook */NULL, /* realize */ Realize, /* actions */ NULL, /* num_actions */ 0, /* resources */ resources, /* num_resources */XtNumber(resources), /* xrm_class */ NULLQUARK, /* compress_motion */True, /* compress_exposure */True, /* compress_enterleave */True, /* visible_interest */False, /* destroy */ NULL, /* resize */ Resize, /* expose */ Redisplay, /* set_values */ SetValues, /* set_values_hook */NULL, 1m230m 1mX Toolkit Intrinsics X11 Release 6.40m /* set_values_almost */XtInheritSetValuesAlmost, /* get_values_hook */NULL, /* accept_focus */NULL, /* version */ XtVersion, /* callback_offsets */NULL, /* tm_table */ NULL, /* query_geometry */XtInheritQueryGeometry, /* display_accelerator */NULL, /* extension */ NULL }, { /* Label_class fields */ /* get_text */ GetText, /* set_text */ SetText, /* extension */ NULL } }; /* Class record pointer */ WidgetClass labelWidgetClass = (WidgetClass) &labelClassRec; /* New method access routines */ void LabelSetText(w, text) Widget w; String text; { Label WidgetClass lwc = (Label WidgetClass)XtClass(w); XtCheckSubclass(w, labelWidgetClass, NULL); *(lwc->label_class.set_text)(w, text) } /* Private procedures */ . . . 1m1.6.5. Widget Class and Superclass Look Up0m To obtain the class of a widget, use 4mXtClass24m. __ | WidgetClass XtClass(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. |__ The 4mXtClass24m function returns a pointer to the widget's class structure. 1m240m 1mX Toolkit Intrinsics X11 Release 6.40m To obtain the superclass of a widget, use 4mXtSuperclass24m. __ | WidgetClass XtSuperclass(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. |__ The 4mXtSuperclass24m function returns a pointer to the widget's superclass class structure. 1m1.6.6. Widget Subclass Verification0m To check the subclass to which a widget belongs, use 4mXtIs-0m 4mSubclass24m. __ | Boolean XtIsSubclass(4mw24m, 4mwidget_class24m) Widget 4mw24m; WidgetClass 4mwidget_class24m; 4mw24m Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof. 4mwidget_class0m Specifies the widget class for which to test. Must be 1mobjectClass 22mor any subclass thereof. |__ The 4mXtIsSubclass24m function returns 4mTrue24m if the class of the specified widget is equal to or is a subclass of the speci- fied class. The widget's class can be any number of sub- classes down the chain and need not be an immediate subclass of the specified class. Composite widgets that need to restrict the class of the items they contain can use 4mXtIs-0m 4mSubclass24m to find out if a widget belongs to the desired class of objects. To test if a given widget belongs to a subclass of an Intrinsics-defined class, the Intrinsics define macros or functions equivalent to 4mXtIsSubclass24m for each of the built- in classes. These procedures are 4mXtIsObject24m, 4mXtIsRectObj24m, 4mXtIsWidget24m, 4mXtIsComposite24m, 4mXtIsConstraint24m, 4mXtIsShell24m, 4mXtIsOverrideShell24m, 4mXtIsWMShell24m, 4mXtIsVendorShell24m, 4mXtIsTran-0m 4msientShell24m, 4mXtIsTopLevelShell24m, 4mXtIsApplicationShell24m, and 1m250m 1mX Toolkit Intrinsics X11 Release 6.40m 4mXtIsSessionShell24m. All these macros and functions have the same argument description. __ | Boolean XtIs4m24m (4mw24m) Widget 4mw24m; 4mw24m Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof. |__ These procedures may be faster than calling 4mXtIsSubclass0m directly for the built-in classes. To check a widget's class and to generate a debugging error message, use 4mXtCheckSubclass24m, defined in <4mX11/IntrinsicP.h24m>: __ | void XtCheckSubclass(4mw24m, 4mwidget_class24m, 4mmessage24m) Widget 4mw24m; WidgetClass 4mwidget_class24m; String 4mmessage24m; 4mw24m Specifies the widget or object whose class is to be checked. Must be of class Object or any sub- class thereof. 4mwidget_class0m Specifies the widget class for which to test. Must be 1mobjectClass 22mor any subclass thereof. 4mmessage24m Specifies the message to be used. |__ The 4mXtCheckSubclass24m macro determines if the class of the specified widget is equal to or is a subclass of the speci- fied class. The widget's class can be any number of sub- classes down the chain and need not be an immediate subclass of the specified class. If the specified widget's class is not a subclass, 4mXtCheckSubclass24m constructs an error message from the supplied message, the widget's actual class, and the expected class and calls 4mXtErrorMsg24m. 4mXtCheckSubclass0m 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. 1m260m 1mX Toolkit Intrinsics X11 Release 6.40m 4mXtCheckSubclass24m is only executed when the module has been compiled with the compiler symbol DEBUG defined; otherwise, it is defined as the empty string and generates no code. 1m1.6.7. Superclass Chaining0m While most fields in a widget class structure are self-con- tained, some fields are linked to their corresponding fields in their superclass structures. With a linked field, the Intrinsics access the field's value only after accessing its corresponding superclass value (called downward superclass chaining) or before accessing its corresponding superclass value (called upward superclass chaining). The self-con- tained fields are In all widget classes:4mclass_name0m 4mclass_initialize0m 4mwidget_size0m 4mrealize0m 4mvisible_interest0m 4mresize0m 4mexpose0m 4maccept_focus0m 4mcompress_motion0m 4mcompress_exposure0m 4mcompress_enterleave0m 4mset_values_almost0m 4mtm_table0m 4mversion0m 4mallocate0m 4mdeallocate0m In Composite widget classes:4mgeometry_manager0m 4mchange_managed0m 4minsert_child0m 4mdelete_child0m 4maccepts_objects0m 4mallows_change_managed_set0m In Constraint widget classes:4mconstraint_size0m In Shell widget classes:4mroot_geometry_manager0m With downward superclass chaining, the invocation of an operation first accesses the field from the Object, RectObj, and Core class structures, then from the subclass structure, and so on down the class chain to that widget's class struc- ture. These superclass-to-subclass fields are 4mclass_part_initialize0m 4mget_values_hook0m 4minitialize0m 1m270m 1mX Toolkit Intrinsics X11 Release 6.40m 4minitialize_hook0m 4mset_values0m 4mset_values_hook0m 4mresources0m In addition, for subclasses of Constraint, the following fields of the 4mConstraintClassPart24m and 4mConstraintClassExten-0m 4msionRec24m structures are chained from the Constraint class down to the subclass: 4mresources0m 4minitialize0m 4mset_values0m 4mget_values_hook0m With upward superclass chaining, the invocation of an opera- tion first accesses the field from the widget class struc- ture, then from the superclass structure, and so on up the class chain to the Core, RectObj, and Object class struc- tures. The subclass-to-superclass fields are 4mdestroy0m 4mactions0m For subclasses of Constraint, the following field of 4mCon-0m 4mstraintClassPart24m is chained from the subclass up to the Con- straint class: 4mdestroy0m 1m1.6.8. Class Initialization: class_initialize and0m 1mclass_part_initialize Procedures0m Many class records can be initialized completely at compile or link time. In some cases, however, a class may need to register type converters or perform other sorts of once-only runtime initialization. Because the C language does not have initialization proce- dures that are invoked automatically when a program starts up, a widget class can declare a class_initialize procedure that will be automatically called exactly once by the Intrinsics. A class initialization procedure pointer is of type 4mXtProc24m: 1m280m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtProc)(void); |__ A widget class indicates that it has no class initialization procedure by specifying NULL in the 4mclass_initialize24m field. In addition to the class initialization that is done exactly once, some classes perform initialization for fields in their parts of the class record. These are performed not just for the particular class, but for subclasses as well, and are done in the class's class part initialization proce- dure, a pointer to which is stored in the 4mclass_part_ini-0m 4mtialize24m field. The class_part_initialize procedure pointer is of type 4mXtWidgetClassProc24m. __ | typedef void (*XtWidgetClassProc)(WidgetClass); WidgetClass 4mwidget_class24m; 4mwidget_class0m Points to the class structure for the class being initialized. |__ During class initialization, the class part initialization procedures for the class and all its superclasses are called in superclass-to-subclass order on the class record. These procedures have the responsibility of doing any dynamic ini- tializations necessary to their class's part of the record. The most common is the resolution of any inherited methods defined in the class. For example, if a widget class C has superclasses Core, Composite, A, and B, the class record for C first is passed to Core 's class_part_initialize proce- dure. This resolves any inherited Core methods and compiles the textual representations of the resource list and action table that are defined in the class record. Next, Compos- ite's class_part_initialize procedure is called to initial- ize the composite part of C's class record. Finally, the class_part_initialize procedures for A, B, and C, in that order, are called. For further information, see Section 1.6.9. Classes that do not define any new class fields or that need no extra processing for them can specify NULL in the 4mclass_part_initialize24m field. All widget classes, whether they have a class initialization procedure or not, must start with their 4mclass_inited24m field 4mFalse24m. The first time a widget of a class is created, 4mXtCreateWid-0m 4mget24m ensures that the widget class and all superclasses are 1m290m 1mX Toolkit Intrinsics X11 Release 6.40m initialized, in superclass-to-subclass order, by checking each 4mclass_inited24m field and, if it is 4mFalse24m, by calling the class_initialize and the class_part_initialize procedures for the class and all its superclasses. The Intrinsics then set the 4mclass_inited24m field to a nonzero value. After the one-time initialization, a class structure is constant. The following example provides the class initialization pro- cedure for a Label class. static void ClassInitialize() { XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify, NULL, 0, XtCacheNone, NULL); } 1m1.6.9. Initializing a Widget Class0m A class is initialized when the first widget of that class or any subclass is created. To initialize a widget class without creating any widgets, use 4mXtInitializeWidgetClass24m. __ | void XtInitializeWidgetClass(4mobject_class24m) WidgetClass 4mobject_class24m; 4mobject_class0m Specifies the object class to initialize. May be 4mobjectClass24m or any subclass thereof. |__ If the specified widget class is already initialized, 4mXtIni-0m 4mtializeWidgetClass24m returns immediately. If the class initialization procedure registers type con- verters, these type converters are not available until the first object of the class or subclass is created or 4mXtIni-0m 4mtializeWidgetClass24m is called (see Section 9.6). 1m1.6.10. Inheritance of Superclass Operations0m A widget class is free to use any of its superclass's self- contained operations rather than implementing its own code. The most frequently inherited operations are expose 1m300m 1mX Toolkit Intrinsics X11 Release 6.40m realize insert_child delete_child geometry_manager set_values_almost To inherit an operation 4mxyz24m, specify the constant 4mXtIn-0m 4mheritXyz24m in your class record. Every class that declares a new procedure in its widget class part must provide for inheriting the procedure in its class_part_initialize procedure. The chained operations declared in Core and Constraint records are never inherited. Widget classes that do nothing beyond what their superclass does specify NULL for chained procedures in their class records. Inheriting works by comparing the value of the field with a known, special value and by copying in the superclass's value for that field if a match occurs. This special value, called the inheritance constant, is usually the Intrinsics internal value 4m_XtInherit24m cast to the appropriate type. 4m_XtInherit24m is a procedure that issues an error message if it is actually called. For example, 4mCompositeP.h24m contains these definitions: #define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit) #define XtInheritChangeManaged ((XtWidgetProc) _XtInherit) #define XtInheritInsertChild ((XtArgsProc) _XtInherit) #define XtInheritDeleteChild ((XtWidgetProc) _XtInherit) Composite's class_part_initialize procedure begins as fol- lows: static void CompositeClassPartInitialize(widgetClass) WidgetClass widgetClass; { CompositeWidgetClass wc = (CompositeWidgetClass)widgetClass; CompositeWidgetClass super = (CompositeWidgetClass)wc->core_class.superclass; if (wc->composite_class.geometry_manager == XtInheritGeometryManager) { wc->composite_class.geometry_manager = super->composite_class.geometry_manager; } if (wc->composite_class.change_managed == XtInheritChangeManaged) { wc->composite_class.change_managed = super->composite_class.change_managed; 1m310m 1mX Toolkit Intrinsics X11 Release 6.40m } . . . Nonprocedure fields may be inherited in the same manner as procedure fields. The class may declare any reserved value it wishes for the inheritance constant for its new fields. The following inheritance constants are defined: For Object: 4mXtInheritAllocate0m 4mXtInheritDeallocate0m For Core: 4mXtInheritRealize0m 4mXtInheritResize0m 4mXtInheritExpose0m 4mXtInheritSetValuesAlmost0m 4mXtInheritAcceptFocus0m 4mXtInheritQueryGeometry0m 4mXtInheritTranslations0m 4mXtInheritDisplayAccelerator0m For Composite: 4mXtInheritGeometryManager0m 4mXtInheritChangeManaged0m 4mXtInheritInsertChild0m 4mXtInheritDeleteChild0m For Shell: 4mXtInheritRootGeometryManager0m 1m1.6.11. Invocation of Superclass Operations0m A widget sometimes needs to call a superclass operation that is not chained. For example, a widget's expose procedure 1m320m 1mX Toolkit Intrinsics X11 Release 6.40m might call its superclass's 4mexpose24m and then perform a little more work on its own. For example, a Composite class with predefined managed children can implement insert_child by first calling its superclass's 4minsert_child24m and then calling 4mXtManageChild24m to add the child to the managed set. Note A class method should not use 4mXtSuperclass24m but should instead call the class method of its own specific superclass directly through the super- class record. That is, it should use its own class pointers only, not the widget's class point- ers, as the widget's class may be a subclass of the class whose implementation is being refer- enced. This technique is referred to as 4menveloping24m the superclass's operation. 1m1.6.12. Class Extension Records0m It may be necessary at times to add new fields to already existing widget class structures. To permit this to be done without requiring recompilation of all subclasses, the last field in a class part structure should be an extension pointer. If no extension fields for a class have yet been defined, subclasses should initialize the value of the extension pointer to NULL. If extension fields exist, as is the case with the Compos- ite, Constraint, and Shell classes, subclasses can provide values for these fields by setting the 4mextension24m pointer for the appropriate part in their class structure to point to a statically declared extension record containing the addi- tional fields. Setting the 4mextension24m field is never manda- tory; code that uses fields in the extension record must always check the 4mextension24m field and take some appropriate default action if it is NULL. In order to permit multiple subclasses and libraries to chain extension records from a single 4mextension24m field, extension records should be declared as a linked list, and each extension record definition should contain the follow- ing four fields at the beginning of the structure declara- tion: 1m330m 1mX Toolkit Intrinsics X11 Release 6.40m __ | struct { XtPointer next_extension; XrmQuark record_type; long version; Cardinal record_size; }; 4mnext_extension0m Specifies the next record in the list, or NULL. 4mrecord_type24m Specifies the particular structure declaration to which each extension record instance con- forms. 4mversion24m Specifies a version id symbolic constant sup- plied by the definer of the structure. 4mrecord_size24m Specifies the total number of bytes allocated for the extension record. |__ The 4mrecord_type24m field identifies the contents of the exten- sion record and is used by the definer of the record to locate its particular extension record in the list. The 4mrecord_type24m field is normally assigned the result of 4mXrm-0m 4mStringToQuark24m for a registered string constant. The Intrin- sics reserve all record type strings beginning with the two characters ``XT'' for future standard uses. The value 4mNUL-0m 4mLQUARK24m may also be used by the class part owner in extension records attached to its own class part extension field to identify the extension record unique to that particular class. The 4mversion24m field is an owner-defined constant that may be used to identify binary files that have been compiled with alternate definitions of the remainder of the extension record data structure. The private header file for a widget class should provide a symbolic constant for subclasses to use to initialize this field. The 4mrecord_size24m field value includes the four common header fields and should normally be initialized with 4msizeof24m(). Any value stored in the class part extension fields of 4mCom-0m 4mpositeClassPart24m, 4mConstraintClassPart24m, or 4mShellClassPart24m must point to an extension record conforming to this definition. The Intrinsics provide a utility function for widget writers to locate a particular class extension record in a linked list, given a widget class and the offset of the 4mextension0m field in the class record. 1m340m 1mX Toolkit Intrinsics X11 Release 6.40m To locate a class extension record, use 4mXtGetClassExtension24m. __ | XtPointer XtGetClassExtension(4mobject_class24m, 4mbyte_offset24m, 4mtype24m, 4mversion24m, 4mrecord_size24m) WidgetClass 4mobject_class24m; Cardinal 4mbyte_offset24m; XrmQuark 4mtype24m; long 4mversion24m; Cardinal 4mrecord_size24m; 4mobject_class0m Specifies the object class containing the exten- sion list to be searched. 4mbyte_offset0m Specifies the offset in bytes from the base of the class record of the extension field to be searched. 4mtype24m Specifies the record_type of the class extension to be located. 4mversion24m Specifies the minimum acceptable version of the class extension required for a match. 4mrecord_size0m Specifies the minimum acceptable length of the class extension record required for a match, or 0. |__ The list of extension records at the specified offset in the specified object class will be searched for a match on the specified type, a version greater than or equal to the spec- ified version, and a record size greater than or equal the specified record_size if it is nonzero. 4mXtGetClassExtension0m returns a pointer to a matching extension record or NULL if no match is found. The returned extension record must not be modified or freed by the caller if the caller is not the extension owner. 1m350m 1mX Toolkit Intrinsics X11 Release 6.40m 1mChapter 20m 1mWidget Instantiation0m A hierarchy of widget instances constitutes a widget tree. The shell widget returned by 4mXtAppCreateShell24m is the root of the widget tree instance. The widgets with one or more children are the intermediate nodes of that tree, and the widgets with no children of any kind are the leaves of the widget tree. With the exception of pop-up children (see Chapter 5), this widget tree instance defines the associated X Window tree. Widgets can be either composite or primitive. Both kinds of widgets can contain children, but the Intrinsics provide a set of management mechanisms for constructing and interfac- ing between composite widgets, their children, and other clients. Composite widgets, that is, members of the class 4mcompos-0m 4miteWidgetClass24m, are containers for an arbitrary, but widget implementation-defined, collection of children, which may be instantiated by the composite widget itself, by other clients, or by a combination of the two. Composite widgets also contain methods for managing the geometry (layout) of any child widget. Under unusual circumstances, a composite widget may have zero children, but it usually has at least one. By contrast, primitive widgets that contain children typically instantiate specific children of known classes themselves and do not expect external clients to do so. Primitive widgets also do not have general geometry manage- ment methods. In addition, the Intrinsics recursively perform many opera- tions (for example, realization and destruction) on compos- ite widgets and all their children. Primitive widgets that have children must be prepared to perform the recursive operations themselves on behalf of their children. A widget tree is manipulated by several Intrinsics func- tions. For example, 4mXtRealizeWidget24m traverses the tree downward and recursively realizes all pop-up widgets and children of composite widgets. 4mXtDestroyWidget24m traverses the tree downward and destroys all pop-up widgets and chil- dren of composite widgets. The functions that fetch and modify resources traverse the tree upward and determine the inheritance of resources from a widget's ancestors. 4mXtMake-0m 4mGeometryRequest24m traverses the tree up one level and calls the geometry manager that is responsible for a widget child's geometry. 1m360m 1mX Toolkit Intrinsics X11 Release 6.40m To facilitate upward traversal of the widget tree, each wid- get has a pointer to its parent widget. The Shell widget that 4mXtAppCreateShell24m returns has a 4mparent24m pointer of NULL. To facilitate downward traversal of the widget tree, the 4mchildren24m field of each composite widget is a pointer to an array of child widgets, which includes all normal children created, not just the subset of children that are managed by the composite widget's geometry manager. Primitive widgets that instantiate children are entirely responsible for all operations that require downward traversal below themselves. In addition, every widget has a pointer to an array of pop- up children. 1m2.1. Initializing the X Toolkit0m Before an application can call any Intrinsics function other than 4mXtSetLanguageProc24m and 4mXtToolkitThreadInitialize24m, it must initialize the Intrinsics by using · 4mXtToolkitInitialize24m, which initializes the Intrinsics internals · 4mXtCreateApplicationContext24m, which initializes the per- application state · 4mXtDisplayInitialize24m or 4mXtOpenDisplay24m, which initializes the per-display state · 4mXtAppCreateShell24m, which creates the root of a widget tree Or an application can call the convenience procedure 4mXtOpe-0m 4mnApplication24m, which combines the functions of the preceding procedures. An application wishing to use the ANSI C locale mechanism should call 4mXtSetLanguageProc24m prior to calling 4mXtDisplayInitialize24m, 4mXtOpenDisplay24m, 4mXtOpenApplication24m, or 4mXtAppInitialize24m. Multiple instances of X Toolkit applications may be imple- mented in a single address space. Each instance needs to be able to read input and dispatch events independently of any other instance. Further, an application instance may need multiple display connections to have widgets on multiple displays. From the application's point of view, multiple display connections usually are treated together as a single unit for purposes of event dispatching. To accommodate both requirements, the Intrinsics define application contexts, each of which provides the information needed to distinguish one application instance from another. The major component of an application context is a list of one or more X 4mDisplay0m pointers for that application. The Intrinsics handle all display connections within a single application context 1m370m 1mX Toolkit Intrinsics X11 Release 6.40m simultaneously, handling input in a round-robin fashion. The application context type 4mXtAppContext24m is opaque to clients. To initialize the Intrinsics internals, use 4mXtToolkitIni-0m 4mtialize24m. __ | void XtToolkitInitialize() |__ If 4mXtToolkitInitialize24m was previously called, it returns immediately. When 4mXtToolkitThreadInitialize24m is called before 4mXtToolkitInitialize24m, the latter is protected against simultaneous activation by multiple threads. To create an application context, use 4mXtCreateApplication-0m 4mContext24m. __ | XtAppContext XtCreateApplicationContext() |__ The 4mXtCreateApplicationContext24m function returns an applica- tion context, which is an opaque type. Every application must have at least one application context. To destroy an application context and close any remaining display connections in it, use 4mXtDestroyApplicationContext24m. __ | void XtDestroyApplicationContext(4mapp_context24m) XtAppContext 4mapp_context24m; 4mapp_context0m Specifies the application context. |__ The 4mXtDestroyApplicationContext24m function destroys the speci- fied application context. If called from within an event dispatch (for example, in a callback procedure), 4mXtDestroy-0m 4mApplicationContext24m does not destroy the application context until the dispatch is complete. 1m380m 1mX Toolkit Intrinsics X11 Release 6.40m To get the application context in which a given widget was created, use 4mXtWidgetToApplicationContext24m. __ | XtAppContext XtWidgetToApplicationContext(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget for which you want the appli- cation context. Must be of class Object or any subclass thereof. |__ The 4mXtWidgetToApplicationContext24m function returns the appli- cation context for the specified widget. To initialize a display and add it to an application con- text, use 4mXtDisplayInitialize24m. 1m390m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtDisplayInitialize(4mapp_context24m, 4mdisplay24m, 4mapplication_name24m, 4mapplication_class24m, 4moptions24m, 4mnum_options24m, 4margc24m, 4margv24m) XtAppContext 4mapp_context24m; Display *4mdisplay24m; String 4mapplication_name24m; String 4mapplication_class24m; XrmOptionDescRec *4moptions24m; Cardinal 4mnum_options24m; int *4margc24m; String *4margv24m; 4mapp_context24m Specifies the application context. 4mdisplay24m Specifies a previously opened display connec- tion. Note that a single display connection can be in at most one application context. 4mapplication_name0m Specifies the name of the application instance. 4mapplication_class0m Specifies the class name of this application, which is usually the generic name for all instances of this application. 4moptions24m Specifies how to parse the command line for any application-specific resources. The 4moptions24m argument is passed as a parameter to 4mXrmParseCommand24m. For further information, see Section 15.9 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface0m and Section 2.4 of this specification. 4mnum_options24m Specifies the number of entries in the options list. 4margc24m Specifies a pointer to the number of command line parameters. 4margv24m Specifies the list of command line parameters. |__ The 4mXtDisplayInitialize24m function retrieves the language string to be used for the specified display (see Section 11.11), calls the language procedure (if set) with that lan- guage string, builds the resource database for the default screen, calls the Xlib 4mXrmParseCommand24m function to parse the command line, and performs other per-display initialization. After 4mXrmParseCommand24m has been called, 4margc24m and 4margv24m contain only those parameters that were not in the standard option table or in the table specified by the 4moptions24m argument. If the modified 4margc24m is not zero, most applications simply 1m400m 1mX Toolkit Intrinsics X11 Release 6.40m print out the modified 4margv24m along with a message listing the allowable options. On POSIX-based systems, the application name is usually the final component of 4margv24m[0]. If the syn- chronous resource is 4mTrue24m, 4mXtDisplayInitialize24m calls the Xlib 4mXSynchronize24m function to put Xlib into synchronous mode for this display connection and any others currently open in the application context. See Sections 2.3 and 2.4 for details on the 4mapplication_name24m, 4mapplication_class24m, 4moptions24m, and 4mnum_options24m arguments. 4mXtDisplayInitialize24m calls 4mXrmSetDatabase24m to associate the resource database of the default screen with the display before returning. 1m410m 1mX Toolkit Intrinsics X11 Release 6.40m To open a display, initialize it, and then add it to an application context, use 4mXtOpenDisplay24m. __ | Display *XtOpenDisplay(4mapp_context24m, 4mdisplay_string24m, 4mapplication_name24m, 4mapplication_class24m, 4moptions24m, 4mnum_options24m, 4margc24m, 4margv24m) XtAppContext 4mapp_context24m; String 4mdisplay_string24m; String 4mapplication_name24m; String 4mapplication_class24m; XrmOptionDescRec *4moptions24m; Cardinal 4mnum_options24m; int *4margc24m; String *4margv24m; 4mapp_context24m Specifies the application context. 4mdisplay_string0m Specifies the display string, or NULL. 4mapplication_name0m Specifies the name of the application instance, or NULL. 4mapplication_class0m Specifies the class name of this application, which is usually the generic name for all instances of this application. 4moptions24m Specifies how to parse the command line for any application-specific resources. The options argument is passed as a parameter to 4mXrmParseCommand24m. 4mnum_options24m Specifies the number of entries in the options list. 4margc24m Specifies a pointer to the number of command line parameters. 4margv24m Specifies the list of command line parameters. |__ The 4mXtOpenDisplay24m function calls 4mXOpenDisplay24m with the spec- ified 4mdisplay_string24m. If 4mdisplay_string24m is NULL, 4mXtOpenDis-0m 4mplay24m uses the current value of the -display option specified in 4margv24m. If no display is specified in 4margv24m, the user's default display is retrieved from the environment. On POSIX-based systems, this is the value of the 4mDISPLAY24m envi- ronment variable. 1m420m 1mX Toolkit Intrinsics X11 Release 6.40m If this succeeds, 4mXtOpenDisplay24m then calls 4mXtDisplayInitial-0m 4mize24m and passes it the opened display and the value of the -name option specified in 4margv24m as the application name. If no -name option is specified and 4mapplication_name24m is non- NULL, 4mapplication_name24m is passed to 4mXtDisplayInitialize24m. If 4mapplication_name24m is NULL and if the environment variable 4mRESOURCE_NAME24m is set, the value of 4mRESOURCE_NAME24m is used. Otherwise, the application name is the name used to invoke the program. On implementations that conform to ANSI C Hosted Environment support, the application name will be 4margv24m[0] less any directory and file type components, that is, the final component of 4margv24m[0], if specified. If 4margv24m[0] does not exist or is the empty string, the applica- tion name is ``main''. 4mXtOpenDisplay24m returns the newly opened display or NULL if it failed. See Section 7.12 for information regarding the use of 4mXtOpenDisplay24m in multiple threads. To close a display and remove it from an application con- text, use 4mXtCloseDisplay24m. __ | void XtCloseDisplay(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the display. |__ The 4mXtCloseDisplay24m function calls 4mXCloseDisplay24m with the specified 4mdisplay24m as soon as it is safe to do so. If called from within an event dispatch (for example, a callback pro- cedure), 4mXtCloseDisplay24m does not close the display until the dispatch is complete. Note that applications need only call 4mXtCloseDisplay24m if they are to continue executing after clos- ing the display; otherwise, they should call 4mXtDestroyAppli-0m 4mcationContext24m. See Section 7.12 for information regarding the use of 4mXtCloseDisplay24m in multiple threads. 1m2.2. Establishing the Locale0m Resource databases are specified to be created in the cur- rent process locale. During display initialization prior to creating the per-screen resource database, the Intrinsics will call out to a specified application procedure to set the locale according to options found on the command line or in the per-display resource specifications. 1m430m 1mX Toolkit Intrinsics X11 Release 6.40m The callout procedure provided by the application is of type 4mXtLanguageProc24m. __ | typedef String (*XtLanguageProc)(Display*, String, XtPointer); Display *4mdisplay24m; String 4mlanguage24m; XtPointer 4mclient_data24m; 4mdisplay24m Passes the display. 4mlanguage24m Passes the initial language value obtained from the command line or server per-display resource specifications. 4mclient_data0m Passes the additional client data specified in the call to 4mXtSetLanguageProc24m. |__ The language procedure allows an application to set the locale to the value of the language resource determined by 4mXtDisplayInitialize24m. The function returns a new language string that will be subsequently used by 4mXtDisplayInitialize0m to establish the path for loading resource files. The returned string will be copied by the Intrinsics into new memory. Initially, no language procedure is set by the Intrinsics. To set the language procedure for use by 4mXtDisplayInitial-0m 4mize24m, use 4mXtSetLanguageProc24m. __ | XtLanguageProc XtSetLanguageProc(4mapp_context24m, 4mproc24m, 4mclient_data24m) XtAppContext 4mapp_context24m; XtLanguageProc 4mproc24m; XtPointer 4mclient_data24m; 4mapp_context0m Specifies the application context in which the language procedure is to be used, or NULL. 4mproc24m Specifies the language procedure. 4mclient_data0m Specifies additional client data to be passed to the language procedure when it is called. |__ 4mXtSetLanguageProc24m sets the language procedure that will be 1m440m 1mX Toolkit Intrinsics X11 Release 6.40m called from 4mXtDisplayInitialize24m for all subsequent Displays initialized in the specified application context. If 4mapp_context24m is NULL, the specified language procedure is registered in all application contexts created by the call- ing process, including any future application contexts that may be created. If 4mproc24m is NULL, a default language proce- dure is registered. 4mXtSetLanguageProc24m returns the previ- ously registered language procedure. If a language proce- dure has not yet been registered, the return value is unspecified, but if this return value is used in a subse- quent call to 4mXtSetLanguageProc24m, it will cause the default language procedure to be registered. The default language procedure does the following: · Sets the locale according to the environment. On ANSI C-based systems this is done by calling 4msetlocale24m( 4mLC_ALL24m, 4mlanguage24m ). If an error is encountered, a warning message is issued with 4mXtWarning24m. · Calls 4mXSupportsLocale24m to verify that the current locale is supported. If the locale is not supported, a warn- ing message is issued with 4mXtWarning24m and the locale is set to ``C''. · Calls 4mXSetLocaleModifiers24m specifying the empty string. · Returns the value of the current locale. On ANSI C- based systems this is the return value from a final call to 4msetlocale24m( 4mLC_ALL24m, NULL ). A client wishing to use this mechanism to establish locale can do so by calling 4mXtSetLanguageProc24m prior to 4mXtDis-0m 4mplayInitialize24m, as in the following example. Widget top; XtSetLanguageProc(NULL, NULL, NULL); top = XtOpenApplication(...); ... 1m2.3. Loading the Resource Database0m The 4mXtDisplayInitialize24m function first determines the lan- guage string to be used for the specified display. It then creates a resource database for the default screen of the display by combining the following sources in order, with the entries in the first named source having highest prece- dence: 1m450m 1mX Toolkit Intrinsics X11 Release 6.40m · Application command line (4margc24m, 4margv24m). · Per-host user environment resource file on the local host. · Per-screen resource specifications from the server. · Per-display resource specifications from the server or from the user preference file on the local host. · Application-specific user resource file on the local host. · Application-specific class resource file on the local host. When the resource database for a particular screen on the display is needed (either internally, or when 4mXtScreen-0m 4mDatabase24m is called), it is created in the following manner using the sources listed above in the same order: · A temporary database, the ``server resource database'', is created from the string returned by 4mXResourceMan-0m 4magerString24m or, if 4mXResourceManagerString24m returns NULL, the contents of a resource file in the user's home directory. On POSIX-based systems, the usual name for this user preference resource file is $HOME/1m.Xdefaults22m. · If a language procedure has been set, 4mXtDisplayInitial-0m 4mize24m first searches the command line for the option ``-xnlLanguage'', or for a -xrm option that specifies the xnlLanguage/XnlLanguage resource, as specified by Section 2.4. If such a resource is found, the value is assumed to be entirely in XPCS, the X Portable Charac- ter Set. If neither option is specified on the command line, 4mXtDisplayInitialize24m queries the server resource database (which is assumed to be entirely in XPCS) for the resource 4mname24m1m.xnlLanguage22m, class 4mClass24m1m.XnlLanguage0m where 4mname24m and 4mClass24m are the 4mapplication_name24m and 4mapplication_class24m specified to 4mXtDisplayInitialize24m. The language procedure is then invoked with the resource value if found, else the empty string. The string returned from the language procedure is saved for all future references in the Intrinsics that require the per-display language string. · The screen resource database is initialized by parsing the command line in the manner specified by Section 2.4. 1m460m 1mX Toolkit Intrinsics X11 Release 6.40m · If a language procedure has not been set, the initial database is then queried for the resource 4mname24m1m.xnlLan-0m 1mguage22m, class 4mClass24m1m.XnlLanguage 22mas specified above. If this database query fails, the server resource database is queried; if this query also fails, the language is determined from the environment; on POSIX-based sys- tems, this is done by retrieving the value of the 4mLANG0m environment variable. If no language string is found, the empty string is used. This language string is saved for all future references in the Intrinsics that require the per-display language string. · After determining the language string, the user's envi- ronment resource file is then merged into the initial resource database if the file exists. This file is user-, host-, and process-specific and is expected to contain user preferences that are to override those specifications in the per-display and per-screen resources. On POSIX-based systems, the user's environ- ment resource file name is specified by the value of the 4mXENVIRONMENT24m environment variable. If this envi- ronment variable does not exist, the user's home direc- tory is searched for a file named 4m.Xdefaults-host,0m 4mwhere24m 4mhost24m 4mis24m 4mthe24m 4mhost24m 4mname24m 4mof24m 4mthe24m 4mmachine24m 4mon24m 4mwhich24m 4mthe0m 4mapplication24m 4mis24m 4mrunning.0m · The per-screen resource specifications are then merged into the screen resource database, if they exist. These specifications are the string returned by 4mXScreenResourceString24m for the respective screen and are owned entirely by the user. · Next, the server resource database created earlier is merged into the screen resource database. The server property, and corresponding user preference file, are owned and constructed entirely by the user. · The application-specific user resource file from the local host is then merged into the screen resource database. This file contains user customizations and is stored in a directory owned by the user. Either the user or the application or both can store resource specifications in the file. Each should be prepared to find and respect entries made by the other. The file name is found by calling 4mXrmSetDatabase24m with the cur- rent screen resource database, after preserving the original display-associated database, then calling 4mXtResolvePathname24m with the parameters (4mdisplay24m, NULL, NULL, NULL, 4mpath24m, NULL, 0, NULL), where 4mpath24m is defined in an operating-system-specific way. On POSIX-based 1m470m 1mX Toolkit Intrinsics X11 Release 6.40m systems, 4mpath24m is defined to be the value of the envi- ronment variable 4mXUSERFILESEARCHPATH24m if this is defined. If 4mXUSERFILESEARCHPATH24m is not defined, an implementation-dependent default value is used. This default value is constrained in the following manner: - If the environment variable 4mXAPPLRESDIR24m is not defined, the default 4mXUSERFILESEARCHPATH24m must con- tain at least six entries. These entries must con- tain $HOME as the directory prefix, plus the follow- ing substitutions: 1. %C, %N, %L or %C, %N, %l, %t, %c 2. %C, %N, %l 3. %C, %N 4. %N, %L or %N, %l, %t, %c 5. %N, %l 6. %N The order of these six entries within the path must be as given above. The order and use of substitu- tions within a given entry are implementation-depen- dent. - If 4mXAPPLRESDIR24m is defined, the default 4mXUSERFILE-0m 4mSEARCHPATH24m must contain at least seven entries. These entries must contain the following directory prefixes and substitutions: 1. $XAPPLRESDIR with %C, %N, %L or %C, %N, %l, %t, %c 2. $XAPPLRESDIR with %C, %N, %l 3. $XAPPLRESDIR with %C, %N 4. $XAPPLRESDIR with %N, %L or %N, %l, %t, %c 5. $XAPPLRESDIR with %N, %l 6. $XAPPLRESDIR with %N 7. $HOME with %N The order of these seven entries within the path must be as given above. The order and use of sub- stitutions within a given entry are implementation- dependent. · Last, the application-specific class resource file from the local host is merged into the screen resource data- base. This file is owned by the application and is usually installed in a system directory when the appli- cation is installed. It may contain sitewide cus- tomizations specified by the system manager. The name of the application class resource file is found by calling 4mXtResolvePathname24m with the parameters (4mdisplay24m, ``app-defaults'', NULL, NULL, NULL, NULL, 0, NULL). 1m480m 1mX Toolkit Intrinsics X11 Release 6.40m This file is expected to be provided by the developer of the application and may be required for the applica- tion to function properly. A simple application that wants to be assured of having a minimal set of resources in the absence of its class resource file can declare fallback resource specifications with 4mXtAppSet-0m 4mFallbackResources24m. Note that the customization substi- tution string is retrieved dynamically by 4mXtRe-0m 4msolvePathname24m so that the resolved file name of the application class resource file can be affected by any of the earlier sources for the screen resource data- base, even though the contents of the class resource file have lowest precedence. After calling 4mXtRe-0m 4msolvePathname24m, the original display-associated database is restored. To obtain the resource database for a particular screen, use 4mXtScreenDatabase24m. __ | XrmDatabase XtScreenDatabase(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the screen whose resource database is to be returned. |__ The 4mXtScreenDatabase24m function returns the fully merged resource database as specified above, associated with the specified screen. If the specified 4mscreen24m does not belong to a 4mDisplay24m initialized by 4mXtDisplayInitialize24m, the results are undefined. To obtain the default resource database associated with a particular display, use 4mXtDatabase24m. __ | XrmDatabase XtDatabase(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the display. |__ The 4mXtDatabase24m function is equivalent to 4mXrmGetDatabase24m. It returns the database associated with the specified display, or NULL if a database has not been set. 1m490m 1mX Toolkit Intrinsics X11 Release 6.40m To specify a default set of resource values that will be used to initialize the resource database if no application- specific class resource file is found (the last of the six sources listed above), use 4mXtAppSetFallbackResources24m. __ | void XtAppSetFallbackResources(4mapp_context24m, 4mspecification_list24m) XtAppContext 4mapp_context24m; String *4mspecification_list24m; 4mapp_context24m Specifies the application context in which the fallback specifications will be used. 4mspecification_list0m Specifies a NULL-terminated list of resource specifications to preload the database, or NULL. |__ Each entry in 4mspecification_list24m points to a string in the format of 4mXrmPutLineResource24m. Following a call to 4mXtAppSet-0m 4mFallbackResources24m, when a resource database is being created for a particular screen and the Intrinsics are not able to find or read an application-specific class resource file according to the rules given above and if 4mspecification_list0m is not NULL, the resource specifications in 4mspecifica-0m 4mtion_list24m will be merged into the screen resource database in place of the application-specific class resource file. 4mXtAppSetFallbackResources24m is not required to copy 4mspecifica-0m 4mtion_list24m; the caller must ensure that the contents of the list and of the strings addressed by the list remain valid until all displays are initialized or until 4mXtAppSetFall-0m 4mbackResources24m is called again. The value NULL for 4mspecifi-0m 4mcation_list24m removes any previous fallback resource specifi- cation for the application context. The intended use for fallback resources is to provide a minimal number of resources that will make the application usable (or at least terminate with helpful diagnostic messages) when some prob- lem exists in finding and loading the application defaults file. 1m2.4. Parsing the Command Line0m The 4mXtOpenDisplay24m function first parses the command line for the following options: -display Specifies the display name for 4mXOpenDisplay24m. -name Sets the resource name prefix, which overrides the application name passed to 4mXtOpenDisplay24m. 1m500m 1mX Toolkit Intrinsics X11 Release 6.40m -xnllanguage Specifies the initial language string for estab- lishing locale and for finding application class resource files. 4mXtDisplayInitialize24m has a table of standard command line options that are passed to 4mXrmParseCommand24m for adding resources to the resource database, and it takes as a param- eter additional application-specific resource abbreviations. The format of this table is described in Section 15.9 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m. __ | typedef enum { XrmoptionNoArg, /* Value is specified in OptionDescRec.value */ XrmoptionIsArg, /* Value is the option string itself */ XrmoptionStickyArg, /* Value is characters immediately following option */ XrmoptionSepArg, /* Value is next argument in argv */ XrmoptionResArg, /* Use the next argument as input to XrmPutLineResource*/ XrmoptionSkipArg, /* Ignore this option and the next argument in argv */ XrmoptionSkipNArgs, /* Ignore this option and the next */ /* OptionDescRec.value arguments in argv */ XrmoptionSkipLine /* Ignore this option and the rest of argv */ } XrmOptionKind; typedef struct { char *option; /* Option name in argv */ char *specifier; /* Resource name (without application name) */ XrmOptionKind argKind;/* Location of the resource value */ XPointer value; /* Value to provide if XrmoptionNoArg */ } XrmOptionDescRec, *XrmOptionDescList; |__ The standard table contains the following entries: ----------------------------------------------------------------------- Option String Resource Name Argument Kind Resource Value ----------------------------------------------------------------------- -background *background SepArg next argument -bd *borderColor SepArg next argument -bg *background SepArg next argument -borderwidth .borderWidth SepArg next argument -bordercolor *borderColor SepArg next argument -bw .borderWidth SepArg next argument -display .display SepArg next argument -fg *foreground SepArg next argument -fn *font SepArg next argument -font *font SepArg next argument -foreground *foreground SepArg next argument -geometry .geometry SepArg next argument 1m510m 1mX Toolkit Intrinsics X11 Release 6.40m ----------------------------------------------------------------------- -iconic .iconic NoArg ``true'' -name .name SepArg next argument -reverse .reverseVideo NoArg ``on'' -rv .reverseVideo NoArg ``on'' +rv .reverseVideo NoArg ``off'' -selectionTimeout .selectionTimeout SepArg next argument -synchronous .synchronous NoArg ``on'' +synchronous .synchronous NoArg ``off'' -title .title SepArg next argument -xnllanguage .xnlLanguage SepArg next argument -xrm next argument ResArg next argument -xtsessionID .sessionID SepArg next argument ----------------------------------------------------------------------- Note that any unique abbreviation for an option name in the standard table or in the application table is accepted. If reverseVideo is 4mTrue24m, the values of 4mXtDefaultForeground0m and 4mXtDefaultBackground24m are exchanged for all screens on the Display. The value of the synchronous resource specifies whether or not Xlib is put into synchronous mode. If a value is found in the resource database during display initialization, 4mXtDisplayInitialize24m makes a call to 4mXSynchronize24m for all display connections currently open in the application con- text. Therefore, when multiple displays are initialized in the same application context, the most recent value speci- fied for the synchronous resource is used for all displays in the application context. The value of the selectionTimeout resource applies to all displays opened in the same application context. When mul- tiple displays are initialized in the same application con- text, the most recent value specified is used for all dis- plays in the application context. The -xrm option provides a method of setting any resource in an application. The next argument should be a quoted string identical in format to a line in the user resource file. For example, to give a red background to all command buttons in an application named 4mxmh24m, you can start it up as xmh -xrm 'xmh*Command.background: red' When it parses the command line, 4mXtDisplayInitialize24m merges the application option table with the standard option table before calling the Xlib 4mXrmParseCommand24m function. An entry in the application table with the same name as an entry in the standard table overrides the standard table entry. If 1m520m 1mX Toolkit Intrinsics X11 Release 6.40m an option name is a prefix of another option name, both names are kept in the merged table. The Intrinsics reserve all option names beginning with the characters ``-xt'' for future standard uses. 1m2.5. Creating Widgets0m The creation of widget instances is a three-phase process: 1. The widgets are allocated and initialized with resources and are optionally added to the managed sub- set of their parent. 2. All composite widgets are notified of their managed children in a bottom-up traversal of the widget tree. 3. The widgets create X windows, which then are mapped. To start the first phase, the application calls 4mXtCreateWid-0m 4mget24m for all its widgets and adds some (usually, most or all) of its widgets to their respective parents' managed set by calling 4mXtManageChild24m. To avoid an 4mO24m(4mn24m2) creation process where each composite widget lays itself out each time a wid- get is created and managed, parent widgets are not notified of changes in their managed set during this phase. After all widgets have been created, the application calls 4mXtRealizeWidget24m with the top-level widget to execute the second and third phases. 4mXtRealizeWidget24m first recursively traverses the widget tree in a postorder (bottom-up) traver- sal and then notifies each composite widget with one or more managed children by means of its change_managed procedure. Notifying a parent about its managed set involves geometry layout and possibly geometry negotiation. A parent deals with constraints on its size imposed from above (for exam- ple, when a user specifies the application window size) and suggestions made from below (for example, when a primitive child computes its preferred size). One difference between the two can cause geometry changes to ripple in both direc- tions through the widget tree. The parent may force some of its children to change size and position and may issue geom- etry requests to its own parent in order to better accommo- date all its children. You cannot predict where anything will go on the screen until this process finishes. Consequently, in the first and second phases, no X windows are actually created, because it is likely that they will get moved around after creation. This avoids unnecessary requests to the X server. 1m530m 1mX Toolkit Intrinsics X11 Release 6.40m Finally, 4mXtRealizeWidget24m starts the third phase by making a preorder (top-down) traversal of the widget tree, allocates an X window to each widget by means of its realize proce- dure, and finally maps the widgets that are managed. 1m2.5.1. Creating and Merging Argument Lists0m Many Intrinsics functions may be passed pairs of resource names and values. These are passed as an arglist, a pointer to an array of 4mArg24m structures, which contains __ | typedef struct { String name; XtArgVal value; } Arg, *ArgList; |__ where 4mXtArgVal24m is as defined in Section 1.5. If the size of the resource is less than or equal to the size of an 4mXtArgVal24m, the resource value is stored directly in 4mvalue24m; otherwise, a pointer to it is stored in 4mvalue24m. To set values in an 4mArgList24m, use 4mXtSetArg24m. __ | void XtSetArg(4marg24m, 4mname24m, 4mvalue24m) Arg 4marg24m; String 4mname24m; XtArgVal 4mvalue24m; 4marg24m Specifies the 4mname/value24m pair to set. 4mname24m Specifies the name of the resource. 4mvalue24m Specifies the value of the resource if it will fit in an 4mXtArgVal24m, else the address. |__ The 4mXtSetArg24m function 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; 1m540m 1mX Toolkit Intrinsics X11 Release 6.40m XtSetArg(args[n], XtNheight, 100);n++; XtSetArg(args[n], XtNwidth, 200);n++; XtSetValues(widget, args, n); Alternatively, an application can statically declare the argument list and use 4mXtNumber24m: static Args args[] = { {XtNheight, (XtArgVal) 100}, {XtNwidth, (XtArgVal) 200}, }; XtSetValues(Widget, args, XtNumber(args)); Note that you should not use expressions with side effects such as auto-increment or auto-decrement within the first argument to 4mXtSetArg24m. 4mXtSetArg24m can be implemented as a macro that evaluates the first argument twice. To merge two arglist arrays, use 4mXtMergeArgLists24m. __ | ArgList XtMergeArgLists(4margs124m, 4mnum_args124m, 4margs224m, 4mnum_args224m) ArgList 4margs124m; Cardinal 4mnum_args124m; ArgList 4margs224m; Cardinal 4mnum_args224m; 4margs124m Specifies the first argument list. 4mnum_args124m Specifies the number of entries in the first argu- ment list. 4margs224m Specifies the second argument list. 4mnum_args224m Specifies the number of entries in the second argument list. |__ The 4mXtMergeArgLists24m function allocates enough storage to hold the combined arglist arrays and copies them into it. Note that it does not check for duplicate entries. The length of the returned list is the sum of the lengths of the specified lists. When it is no longer needed, free the returned storage by using 4mXtFree24m. All Intrinsics interfaces that require 4mArgList24m arguments have analogs conforming to the ANSI C variable argument list 1m550m 1mX Toolkit Intrinsics X11 Release 6.40m (traditionally called ``varargs'') calling convention. The name of the analog is formed by prefixing ``Va'' to the name of the corresponding 4mArgList24m procedure; e.g., 4mXtVaCreateWid-0m 4mget24m. Each procedure named 1mXtVa4m22msomething24m takes as its last arguments, in place of the corresponding 4mArgList24m/ 4mCardinal0m parameters, a variable parameter list of resource name and value pairs where each name is of type 4mString24m and each value is of type 4mXtArgVal24m. The end of the list is identified by a 4mname24m entry containing NULL. Developers writing in the C language wishing to pass resource name and value pairs to any of these interfaces may use the 4mArgList24m and varargs forms interchangeably. Two special names are defined for use only in varargs lists: 4mXtVaTypedArg24m and 4mXtVaNestedList24m. __ | #define XtVaTypedArg "XtVaTypedArg" |__ If the name 4mXtVaTypedArg24m is specified in place of a resource name, then the following four arguments are interpreted as a 4mname/type/value/size24m tuple 4mwhere24m name is of type 4mString24m, 4mtype24m is of type 4mString24m, 4mvalue24m is of type 4mXtArgVal24m, and 4msize0m is of type int. When a varargs list containing 4mXtVaTypedArg0m is processed, a resource type conversion (see Section 9.6) is performed if necessary to convert the value into the for- mat required by the associated resource. If 4mtype24m is XtRString, then 4mvalue24m contains a pointer to the string and 4msize24m contains the number of bytes allocated, including the trailing null byte. If 4mtype24m is not XtRString, then 4mif24m size is less than or equal to 1msizeof22m(1mXtArgVal22m), the value should be the data cast to the type 4mXtArgVal24m, otherwise 4mvalue24m is a pointer to the data. If the type conversion fails for any reason, a warning message is issued and the list entry is skipped. __ | #define XtVaNestedList "XtVaNestedList" |__ If the name 4mXtVaNestedList24m is specified in place of a resource name, then the following argument is interpreted as an 4mXtVarArgsList24m value, which specifies another varargs list that is logically inserted into the original list at the point of declaration. The end of the nested list is identi- fied with a name entry containing NULL. Varargs lists may nest to any depth. 1m560m 1mX Toolkit Intrinsics X11 Release 6.40m To dynamically allocate a varargs list for use with 4mXtVaNestedList24m in multiple calls, use 4mXtVaCreateArgsList24m. __ | typedef XtPointer XtVarArgsList; XtVarArgsList XtVaCreateArgsList(4munused24m, ...) XtPointer 4munused24m; 4munused24m This argument is not currently used and must be specified as NULL. ... Specifies a variable parameter list of resource name and value pairs. |__ The 4mXtVaCreateArgsList24m function allocates memory and copies its arguments into a single list pointer, which may be used with 4mXtVaNestedList24m. The end of both lists is identified by a 4mname24m entry containing NULL. Any entries of type 4mXtVaType-0m 4mdArg24m are copied as specified without applying conversions. Data passed by reference (including Strings) are not copied, only the pointers themselves; the caller must ensure that the data remain valid for the lifetime of the created varargs list. The list should be freed using 4mXtFree24m when no longer needed. Use of resource files and of the resource database is gener- ally encouraged over lengthy arglist or varargs lists when- ever possible in order to permit modification without recom- pilation. 1m2.5.2. Creating a Widget Instance0m To create an instance of a widget, use 4mXtCreateWidget24m. 1m570m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtCreateWidget(4mname24m, 4mobject_class24m, 4mparent24m, 4margs24m, 4mnum_args24m) String 4mname24m; WidgetClass 4mobject_class24m; Widget 4mparent24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mname24m Specifies the resource instance name for the cre- ated widget, which is used for retrieving resources and, for that reason, should not be the same as any other widget that is a child of the same parent. 4mobject_class0m Specifies the widget class pointer for the created object. Must be 1mobjectClass 22mor any subclass thereof. 4mparent24m Specifies the parent widget. Must be of class Object or any subclass thereof. 4margs24m Specifies the argument list to override any other resource specifications. 4mnum_args24m Specifies the number of entries in the argument list. |__ The 4mXtCreateWidget24m function performs all the boilerplate operations of widget creation, doing the following in order: · Checks to see if the class_initialize procedure has been called for this class and for all superclasses and, if not, calls those necessary in a superclass-to- subclass order. · If the specified class is not 4mcoreWidgetClass24m or a sub- class thereof, and the parent's class is a subclass of 4mcompositeWidgetClass24m and either no extension record in the parent's composite class part extension field exists with the 4mrecord_type24m 4mNULLQUARK24m or the 4maccepts_objects24m field in the extension record is 4mFalse24m, 4mXtCreateWidget24m issues a fatal error; see Section 3.1 and Chapter 12. · If the specified class contains an extension record in the object class part 4mextension24m field with 4mrecord_type0m 4mNULLQUARK24m and the 4mallocate24m field is not NULL, the pro- cedure is invoked to allocate memory for the widget instance. If the parent is a member of the class 4mcon-0m 4mstraintWidgetClass24m, the procedure also allocates memory for the parent's constraints and stores the address of 1m580m 1mX Toolkit Intrinsics X11 Release 6.40m this memory into the 4mconstraints24m field. If no allocate procedure is found, the Intrinsics allocate memory for the widget and, when applicable, the constraints, and initializes the 4mconstraints24m field. · Initializes the Core nonresource data fields 4mself24m, 4mpar-0m 4ment24m, 4mwidget_class24m, 4mbeing_destroyed24m, 4mname24m, 4mmanaged24m, 4mwin-0m 4mdow24m, 4mvisible24m, 4mpopup_list24m, and 4mnum_popups24m. · Initializes the resource fields (for example, 4mback-0m 4mground_pixel24m) by using the 4mCoreClassPart24m resource lists specified for this class and all superclasses. · If the parent is a member of the class 4mconstraintWid-0m 4mgetClass24m, initializes the resource fields of the con- straints record by using the 4mConstraintClassPart0m resource lists specified for the parent's class and all superclasses up to 4mconstraintWidgetClass24m. · Calls the initialize procedures for the widget starting at the Object initialize procedure on down to the wid- get's initialize procedure. · If the parent is a member of the class 4mconstraintWid-0m 4mgetClass24m, calls the 4mConstraintClassPart24m initialize pro- cedures, starting at 4mconstraintWidgetClass24m on down to the parent's 4mConstraintClassPart24m initialize procedure. · If the parent is a member of the class 4mcompositeWidget-0m 4mClass24m, puts the widget into its parent's children list by calling its parent's insert_child procedure. For further information, see Section 3.1. To create an instance of a widget using varargs lists, use 4mXtVaCreateWidget24m. 1m590m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtVaCreateWidget(4mname24m, 4mobject_class24m, 4mparent24m, ...) String 4mname24m; WidgetClass 4mobject_class24m; Widget 4mparent24m; 4mname24m Specifies the resource name for the created wid- get. 4mobject_class0m Specifies the widget class pointer for the created object. Must be 1mobjectClass 22mor any subclass thereof. 4mparent24m Specifies the parent widget. Must be of class Object or any subclass thereof. ... Specifies the variable argument list to override any other resource specifications. |__ The 4mXtVaCreateWidget24m procedure is identical in function to 4mXtCreateWidget24m with the 4margs24m and 4mnum_args24m parameters replaced by a varargs list, as described in Section 2.5.1. 1m2.5.3. Creating an Application Shell Instance0m An application can have multiple top-level widgets, each of which specifies a unique widget tree that can potentially be on different screens or displays. An application uses 4mXtAp-0m 4mpCreateShell24m to create independent widget trees. 1m600m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtAppCreateShell(4mname24m, 4mapplication_class24m, 4mwidget_class24m, 4mdisplay24m, 4margs24m, 4mnum_args24m) String 4mname24m; String 4mapplication_class24m; WidgetClass 4mwidget_class24m; Display *4mdisplay24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mname24m Specifies the instance name of the shell widget. If 4mname24m is NULL, the application name passed to 4mXtDisplayInitialize24m is used. 4mapplication_class0m Specifies the resource class string to be used in place of the widget 4mclass_name24m string when 4mwidget_class24m is 4mapplicationShellWidgetClass24m or a subclass thereof. 4mwidget_class0m Specifies the widget class for the top-level widget (e.g., 4mapplicationShellWidgetClass24m). 4mdisplay24m Specifies the display for the default screen and for the resource database used to retrieve the shell widget resources. 4margs24m Specifies the argument list to override any other resource specifications. 4mnum_args24m Specifies the number of entries in the argument list. |__ The 4mXtAppCreateShell24m function creates a new shell widget instance as the root of a widget tree. The screen resource for this widget is determined by first scanning 4margs24m for the XtNscreen argument. If no XtNscreen argument is found, the resource database associated with the default screen of the specified display is queried for the resource 4mname24m.screen, class 4mClass24m.Screen where 4mClass24m is the specified 4mapplica-0m 4mtion_class24m if 4mwidget_class24m is 4mapplicationShellWidgetClass24m or a subclass thereof. If 4mwidget_class24m is not 4mapplication-0m 4mShellWidgetClass24m or a subclass, 4mClass24m is the 4mclass_name0m field from the 4mCoreClassPart24m of the specified 4mwidget_class24m. If this query fails, the default screen of the specified display is used. Once the screen is determined, the resource database associated with that screen is used to retrieve all remaining resources for the shell widget not specified in 4margs24m. The widget name and 4mClass24m as determined above are used as the leftmost (i.e., root) components in all fully qualified resource names for objects within this widget tree. 1m610m 1mX Toolkit Intrinsics X11 Release 6.40m If the specified widget class is a subclass of WMShell, the name and 4mClass24m as determined above will be stored into the 4mWM_CLASS24m property on the widget's window when it becomes realized. If the specified 4mwidget_class24m is 4mapplication-0m 4mShellWidgetClass24m or a subclass thereof, the 4mWM_COMMAND24m prop- erty will also be set from the values of the XtNargv and XtNargc resources. To create multiple top-level shells within a single (logi- cal) application, you can use one of two methods: · Designate one shell as the real top-level shell and create the others as pop-up children of it by using 4mXtCreatePopupShell24m. · Have all shells as pop-up children of an unrealized top-level shell. The first method, which is best used when there is a clear choice for what is the main window, leads to resource speci- fications like the following: xmail.geometry:... (the main window) xmail.read.geometry:...(the read window) xmail.compose.geometry:...(the compose window) The second method, which is best if there is no main window, leads to resource specifications like the following: xmail.headers.geometry:...(the headers window) xmail.read.geometry:...(the read window) xmail.compose.geometry:...(the compose window) To create a top-level widget that is the root of a widget tree using varargs lists, use 4mXtVaAppCreateShell24m. 1m620m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtVaAppCreateShell(4mname24m, 4mapplication_class24m, 4mwidget_class24m, 4mdisplay24m, ...) String 4mname24m; String 4mapplication_class24m; WidgetClass 4mwidget_class24m; Display *4mdisplay24m; 4mname24m Specifies the instance name of the shell wid- get. If 4mname24m is NULL, the application name passed to 4mXtDisplayInitialize24m is used. 4mapplication_class0m Specifies the resource class string to be used in place of the widget 4mclass_name24m string when 4mwidget_class24m is 4mapplicationShellWidget-0m 4mClass24m or a subclass thereof. 4mwidget_class24m Specifies the widget class for the top-level widget. 4mdisplay24m Specifies the display for the default screen and for the resource database used to retrieve the shell widget resources. ... Specifies the variable argument list to over- ride any other resource specifications. |__ The 4mXtVaAppCreateShell24m procedure is identical in function to 4mXtAppCreateShell24m with the 4margs24m and 4mnum_args24m parameters replaced by a varargs list, as described in Section 2.5.1. 1m2.5.4. Convenience Procedure to Initialize an Application0m To initialize the Intrinsics internals, create an applica- tion context, open and initialize a display, and create the initial root shell instance, an application may use 4mXtOpe-0m 4mnApplication24m or 4mXtVaOpenApplication24m. 1m630m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtOpenApplication(4mapp_context_return24m, 4mapplication_class24m, 4moptions24m, 4mnum_options24m, 4margc_in_out24m, 4margv_in_out24m, 4mfallback_resources24m, 4mwidget_class24m, 4margs24m, 4mnum_args24m) XtAppContext *4mapp_context_return24m; String 4mapplication_class24m; XrmOptionDescList 4moptions24m; Cardinal 4mnum_options24m; int *4margc_in_out24m; String *4margv_in_out24m; String *4mfallback_resources24m; WidgetClass 4mwidget_class24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mapp_context_return0m Returns the application context, if non-NULL. 4mapplication_class0m Specifies the class name of the application. 4moptions24m Specifies the command line options table. 4mnum_options24m Specifies the number of entries in 4moptions24m. 4margc_in_out24m Specifies a pointer to the number of command line arguments. 4margv_in_out24m Specifies a pointer to the command line argu- ments. 4mfallback_resources0m Specifies resource values to be used if the application class resource file cannot be opened or read, or NULL. 4mwidget_class24m Specifies the class of the widget to be cre- ated. Must be shellWidgetClass or a sub- class. 4margs24m Specifies the argument list to override any other resource specifications for the created shell widget. 4mnum_args24m Specifies the number of entries in the argu- ment list. |__ The 4mXtOpenApplication24m function calls 4mXtToolkitInitialize0m followed by 4mXtCreateApplicationContext24m, then calls 4mXtOpenDisplay24m with 4mdisplay_string24m NULL and 4mapplication_name0m NULL, and finally calls 4mXtAppCreateShell24m with 4mname24m NULL, the specified 4mwidget_class24m, an argument list and count, and returns the created shell. The recommended 4mwidget_class24m is 1m640m 1mX Toolkit Intrinsics X11 Release 6.40m 4msessionShellWidgetClass24m. The argument list and count are created by merging the specified 4margs24m and 4mnum_args24m with a list containing the specified 4margc24m and 4margv24m. The modified 4margc24m and 4margv24m returned by 4mXtDisplayInitialize24m are returned in 4margc_in_out24m and 4margv_in_out24m. If 4mapp_context_return24m is not NULL, the created application context is also returned. If the display specified by the command line cannot be opened, an error message is issued and 4mXtOpenApplication0m terminates the application. If 4mfallback_resources24m is non- NULL, 4mXtAppSetFallbackResources24m is called with the value prior to calling 4mXtOpenDisplay24m. 1m650m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtVaOpenApplication(4mapp_context_return24m, 4mapplication_class24m, 4moptions24m, 4mnum_options24m, 4margc_in_out24m, 4margv_in_out24m, 4mfallback_resources24m, 4mwidget_class24m, ...) XtAppContext *4mapp_context_return24m; String 4mapplication_class24m; XrmOptionDescList 4moptions24m; Cardinal 4mnum_options24m; int *4margc_in_out24m; String *4margv_in_out24m; String *4mfallback_resources24m; WidgetClass 4mwidget_class24m; 4mapp_context_return0m Returns the application context, if non-NULL. 4mapplication_class0m Specifies the class name of the application. 4moptions24m Specifies the command line options table. 4mnum_options24m Specifies the number of entries in 4moptions24m. 4margc_in_out24m Specifies a pointer to the number of command line arguments. 4margv_in_out24m Specifies the command line arguments array. 4mfallback_resources0m Specifies resource values to be used if the application class resource file cannot be opened, or NULL. 4mwidget_class24m Specifies the class of the widget to be cre- ated. Must be shellWidgetClass or a sub- class. ... Specifies the variable argument list to over- ride any other resource specifications for the created shell. |__ The 4mXtVaOpenApplication24m procedure is identical in function to 4mXtOpenApplication24m with the 4margs24m and 4mnum_args24m parameters replaced by a varargs list, as described in Section 2.5.1. 1m2.5.5. Widget Instance Allocation: The allocate Procedure0m A widget class may optionally provide an instance allocation procedure in the 4mObjectClassExtension24m record. When the call to create a widget includes a varargs list containing 4mXtVaTypedArg24m, these arguments will be passed to 1m660m 1mX Toolkit Intrinsics X11 Release 6.40m the allocation procedure in an 4mXtTypedArgList24m. __ | typedef struct { String name; String type; XtArgVal value; int size; } XtTypedArg, *XtTypedArgList; |__ The allocate procedure pointer in the 4mObjectClassExtension0m record is of type 4mXtAllocateProc24m. 1m670m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtAllocateProc)(WidgetClass, Cardinal*, Cardinal*, ArgList, Cardinal*, XtTypedArgList, Cardinal*, Widget*, XtPointer*); WidgetClass 4mwidget_class24m; Cardinal* 4mconstraint_size24m; Cardinal* 4mmore_bytes24m; ArgList 4margs24m; Cardinal* 4mnum_args24m; XtTypedArgList 4mtyped_args24m, Cardinal* 4mnum_typed_args24m; Widget* 4mnew_return24m; XtPointer* 4mmore_bytes_return24m; 4mwidget_class24m Specifies the widget class of the instance to allocate. 4mconstraint_size0m Specifies the size of the constraint record to allocate, or 0. 4mmore_bytes24m Specifies the number of auxiliary bytes of memory to allocate. 4margs24m Specifies the argument list as given in the call to create the widget. 4mnum_args24m Specifies the number of arguments. 4mtyped_args24m Specifies the list of typed arguments given in the call to create the widget. 4mnum_typed_args24m Specifies the number of typed arguments. 4mnew_return24m Returns a pointer to the newly allocated instance, or NULL in case of error. 4mmore_bytes_return0m Returns the auxiliary memory if it was requested, or NULL if requested and an error occurred; otherwise, unchanged. |__ At widget allocation time, if an extension record with 4mrecord_type24m equal to 4mNULLQUARK24m is located through the object class part 4mextension24m field and the 4mallocate24m field is not NULL, the 4mXtAllocateProc24m will be invoked to allocate memory for the widget. If no ObjectClassPart extension record is declared with 4mrecord_type24m 4mequal24m to 4mNULLQUARK24m, then 4mXtInheri-0m 4mtAllocate24m and 4mXtInheritDeallocate24m are assumed. If no 4mXtAl-0m 4mlocateProc24m is found, the Intrinsics will allocate memory for the widget. 1m680m 1mX Toolkit Intrinsics X11 Release 6.40m An 4mXtAllocateProc24m must perform the following: · Allocate memory for the widget instance and return it in 4mnew_return24m. The memory must be at least 4mwc->core_class.widget_size24m bytes in length, double-word aligned. · Initialize the 4mcore.constraints24m field in the instance record to NULL or to point to a constraint record. If 4mconstraint_size24m is not 0, the procedure must allocate memory for the constraint record. The memory must be double-word aligned. · If 4mmore_bytes24m is not 0, then the address of a block of memory at least 4mmore_bytes24m in size, double-word aligned, must be returned in the 4mmore_bytes_return0m parameter, or NULL to indicate an error. A class allocation procedure that envelops the allocation procedure of a superclass must rely on the enveloped proce- dure to perform the instance and constraint allocation. Allocation procedures should refrain from initializing fields in the widget record except to store pointers to newly allocated additional memory. Under no circumstances should an allocation procedure that envelopes its superclass allocation procedure modify fields in the instance part of any superclass. 1m2.5.6. Widget Instance Initialization: The initialize Pro-0m 1mcedure0m The initialize procedure pointer in a widget class is of type 4mXtInitProc24m. 1m690m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtInitProc)(Widget, Widget, ArgList, Cardinal*); Widget 4mrequest24m; Widget 4mnew24m; ArgList 4margs24m; Cardinal *4mnum_args24m; 4mrequest24m Specifies a copy of the widget with resource val- ues as requested by the argument list, the resource database, and the widget defaults. 4mnew24m Specifies the widget with the new values, both resource and nonresource, that are actually allowed. 4margs24m Specifies the argument list passed by the client, for computing derived resource values. If the client created the widget using a varargs form, any resources specified via 4mXtVaTypedArg24m are con- verted to the widget representation and the list is transformed into the 4mArgList24m format. 4mnum_args24m Specifies the number of entries in the argument list. |__ An initialization procedure performs the following: · Allocates space for and copies any resources referenced by address that the client is allowed to free or modify after the widget has been created. For example, if a widget has a field that is a 4mString24m, it may choose not to depend on the characters at that address remaining constant but dynamically allocate space for the string and copy it to the new space. Widgets that do not copy one or more resources referenced by address should clearly so state in their user documentation. Note It is not necessary to allocate space for or to copy callback lists. · Computes values for unspecified resource fields. For example, if 4mwidth24m and 4mheight24m are zero, the widget should compute an appropriate width and height based on its other resources. 1m700m 1mX Toolkit Intrinsics X11 Release 6.40m Note A widget may directly assign only its own 4mwidth24m and 4mheight24m within the initialize, ini- tialize_hook, set_values, and set_values_hook procedures; see Chapter 6. · Computes values for uninitialized nonresource fields that are derived from resource fields. For example, graphics contexts (GCs) that the widget uses are derived from resources like background, foreground, and font. An initialization procedure also can check certain fields for internal consistency. For example, it makes no sense to specify a colormap for a depth that does not support that colormap. Initialization procedures are called in superclass-to-sub- class order after all fields specified in the resource lists have been initialized. The initialize procedure does not need to examine 4margs24m and 4mnum_args24m if all public resources are declared in the resource list. Most of the initializa- tion code for a specific widget class deals with fields defined in that class and not with fields defined in its superclasses. If a subclass does not need an initialization procedure because it does not need to perform any of the above opera- tions, it can specify NULL for the 4minitialize24m field in the class record. Sometimes a subclass may want to overwrite values filled in by its superclass. In particular, size calculations of a superclass often are incorrect for a subclass, and in this case, the subclass must modify or recalculate fields declared and computed by its superclass. As an example, a subclass can visually surround its super- class display. In this case, the width and height calcu- lated by the superclass initialize procedure are too small and need to be incremented by the size of the surround. The subclass needs to know if its superclass's size was calcu- lated by the superclass or was specified explicitly. All widgets must place themselves into whatever size is explic- itly given, but they should compute a reasonable size if no size is requested. The 4mrequest24m and 4mnew24m arguments provide the necessary informa- tion for a subclass to determine the difference between an explicitly specified field and a field computed by a super- class. The 4mrequest24m widget is a copy of the widget as ini- tialized by the arglist and resource database. The 4mnew0m 1m710m 1mX Toolkit Intrinsics X11 Release 6.40m 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 4mwidth24m and 4mheight24m in the 4mrequest24m widget are zero. If so, it adds its surround size to the 4mwidth24m and 4mheight24m fields in the 4mnew24m widget. If not, it must make do with the size originally specified. The 4mnew24m widget will become the actual widget instance record. Therefore, the initialization procedure should do all its work on the 4mnew24m widget; the 4mrequest24m widget should never be modified. If the initialize procedure needs to call any routines that operate on a widget, it should spec- ify 4mnew24m as the widget instance. 1m2.5.7. Constraint Instance Initialization: The Constraint-0m 1mClassPart initialize Procedure0m The constraint initialization procedure pointer, found in the 4mConstraintClassPart24m 4minitialize24m field of the widget class record, is of type 4mXtInitProc24m. The values passed to the parent constraint initialization procedures are the same as those passed to the child's class widget initialization pro- cedures. The 4mconstraints24m field of the 4mrequest24m widget points to a copy of the constraints record as initialized by the arglist and resource database. The constraint initialization procedure should compute any constraint fields derived from constraint resources. It can make further changes to the 4mnew24m widget to make the widget and any other constraint fields conform to the specified constraints, for example, changing the widget's size or position. If a constraint class does not need a constraint initializa- tion procedure, it can specify NULL for the 4minitialize24m field of the 4mConstraintClassPart24m in the class record. 1m2.5.8. Nonwidget Data Initialization: The initialize_hook0m 1mProcedure0m 1m720m 1mX Toolkit Intrinsics X11 Release 6.40m Note The initialize_hook procedure is obsolete, as the same information is now available to the initial- ize procedure. The procedure has been retained for those widgets that used it in previous releases. The initialize_hook procedure pointer is of type 4mXtArgsProc24m: __ | typedef void (*XtArgsProc)(Widget, ArgList, Cardinal*); Widget 4mw24m; ArgList 4margs24m; Cardinal *4mnum_args24m; 4mw24m Specifies the widget. 4margs24m Specifies the argument list passed by the client. If the client created the widget using a varargs form, any resources specified via 4mXtVaTypedArg24m are converted to the widget representation and the list is transformed into the 4mArgList24m format. 4mnum_args24m Specifies the number of entries in the argument list. |__ If this procedure is not NULL, it is called immediately after the corresponding initialize procedure or in its place if the 4minitialize24m field is NULL. The initialize_hook procedure allows a widget instance to initialize nonresource data using information from the spec- ified argument list as if it were a resource. 1m2.6. Realizing Widgets0m To realize a widget instance, use 4mXtRealizeWidget24m. __ | void XtRealizeWidget(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Core or |__ any subclass thereof. 1m730m 1mX Toolkit Intrinsics X11 Release 6.40m If the widget is already realized, 4mXtRealizeWidget24m simply returns. Otherwise it performs the following: · Binds all action names in the widget's translation ta- ble to procedures (see Section 10.1.2). · Makes a postorder traversal of the widget tree rooted at the specified widget and calls each non-NULL change_managed procedure of all composite widgets that have one or more managed children. · Constructs an 4mXSetWindowAttributes24m structure filled in with information derived from the Core widget fields and calls the realize procedure for the widget, which adds any widget-specific attributes and creates the X window. · If the widget is not a subclass of 4mcompositeWidget-0m 4mClass24m, 4mXtRealizeWidget24m returns; otherwise it continues and performs the following: - Descends recursively to each of the widget's man- aged children and calls the realize procedures. Primitive widgets that instantiate children are responsible for realizing those children them- selves. - Maps all of the managed children windows that have 4mmapped_when_managed24m 4mTrue24m. If a widget is managed but 4mmapped_when_managed24m is 4mFalse24m, the widget is allocated visual space but is not displayed. If the widget is a top-level shell widget (that is, it has no parent), and 4mmapped_when_managed24m is 4mTrue24m, 4mXtRealizeWidget0m maps the widget window. 4mXtCreateWidget24m, 4mXtVaCreateWidget24m, 4mXtRealizeWidget24m, 4mXtMan-0m 4mageChildren24m, 4mXtUnmanageChildren24m, 4mXtUnrealizeWidget24m, 4mXtSetMappedWhenManaged24m, and 4mXtDestroyWidget24m maintain the following invariants: · If a composite widget is realized, then all its managed children are realized. · If a composite widget is realized, then all its managed children that have 4mmapped_when_managed24m 4mTrue24m are mapped. All Intrinsics functions and all widget routines should accept either realized or unrealized widgets. When calling the realize or change_managed procedures for children of a composite widget, 4mXtRealizeWidget24m calls the procedures in reverse order of appearance in the 4mCompositePart24m 4mchildren0m list. By default, this ordering of the realize procedures will result in the stacking order of any newly created 1m740m 1mX Toolkit Intrinsics X11 Release 6.40m subwindows being top-to-bottom in the order of appearance on the list, and the most recently created child will be at the bottom. To check whether or not a widget has been realized, use 4mXtIsRealized24m. __ | Boolean XtIsRealized(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. |__ The 4mXtIsRealized24m function returns 4mTrue24m if the widget has been realized, that is, if the widget has a nonzero window ID. If the specified object is not a widget, the state of the nearest widget ancestor is returned. Some widget procedures (for example, set_values) might wish to operate differently after the widget has been realized. 1m2.6.1. Widget Instance Window Creation: The realize Proce-0m 1mdure0m The realize procedure pointer in a widget class is of type 4mXtRealizeProc24m. __ | typedef void (*XtRealizeProc)(Widget, XtValueMask*, XSetWindowAttributes*); Widget 4mw24m; XtValueMask *4mvalue_mask24m; XSetWindowAttributes *4mattributes24m; 4mw24m Specifies the widget. 4mvalue_mask0m Specifies which fields in the 4mattributes24m structure are used. 4mattributes0m Specifies the window attributes to use in the 4mXCreateWindow24m call. |__ The realize procedure must create the widget's window. 1m750m 1mX Toolkit Intrinsics X11 Release 6.40m Before calling the class realize procedure, the generic 4mXtRealizeWidget24m function fills in a mask and a corresponding 4mXSetWindowAttributes24m structure. It sets the following fields in 4mattributes24m and corresponding bits in 4mvalue_mask0m based on information in the widget core structure: · The 4mbackground_pixmap24m (or 4mbackground_pixel24m if 4mback-0m 4mground_pixmap24m is 4mXtUnspecifiedPixmap24m) is filled in from the corresponding field. · The 4mborder_pixmap24m (or 4mborder_pixel24m if 4mborder_pixmap24m is 4mXtUnspecifiedPixmap24m) is filled in from the correspond- ing field. · The 4mcolormap24m is filled in from the corresponding field. · The 4mevent_mask24m is filled in based on the event handlers registered, the event translations specified, whether the 4mexpose24m field is non-NULL, and whether 4mvisi-0m 4mble_interest24m is 4mTrue24m. · The 4mbit_gravity24m is set to 4mNorthWestGravity24m if the 4mexpose24m field is NULL. These or any other fields in attributes and the correspond- ing bits in 4mvalue_mask24m can be set by the realize procedure. Note that because realize is not a chained operation, the widget class realize procedure must update the 4mXSetWindowAt-0m 4mtributes24m structure with all the appropriate fields from non- Core superclasses. A widget class can inherit its realize procedure from its superclass during class initialization. The realize proce- dure defined for 4mcoreWidgetClass24m calls 4mXtCreateWindow24m with the passed 4mvalue_mask24m and 4mattributes24m and with 4mwindow_class0m and 4mvisual24m set to 4mCopyFromParent24m. Both 4mcompositeWidgetClass0m and 4mconstraintWidgetClass24m inherit this realize procedure, and most new widget subclasses can do the same (see Section 1.6.10). The most common noninherited realize procedures set 4mbit_gravity24m in the mask and attributes to the appropriate value and then create the window. For example, depending on its justification, Label might set 4mbit_gravity24m to 4mWestGrav-0m 4mity24m, 4mCenterGravity24m, or 4mEastGravity24m. Consequently, shrinking it would just move the bits appropriately, and no exposure event is needed for repainting. If a composite widget's children should be realized in an order other than that specified (to control the stacking order, for example), it should call 4mXtRealizeWidget24m on its children itself in the appropriate order from within its own realize procedure. 1m760m 1mX Toolkit Intrinsics X11 Release 6.40m Widgets that have children and whose class is not a subclass of 4mcompositeWidgetClass24m are responsible for calling 4mXtReal-0m 4mizeWidget24m on their children, usually from within the realize procedure. Realize procedures cannot manage or unmanage their descen- dants. 1m2.6.2. Window Creation Convenience Routine0m Rather than call the Xlib 4mXCreateWindow24m function explicitly, a realize procedure should normally call the Intrinsics ana- log 4mXtCreateWindow24m, which simplifies the creation of windows for widgets. __ | void XtCreateWindow(4mw24m, 4mwindow_class24m, 4mvisual24m, 4mvalue_mask24m, 4mattributes24m) Widget 4mw24m; unsigned int 4mwindow_class24m; Visual *4mvisual24m; XtValueMask 4mvalue_mask24m; XSetWindowAttributes *4mattributes24m; 4mw24m Specifies the widget that defines the additional window attributed. Must be of class Core or any subclass thereof. 4mwindow_class0m Specifies the Xlib window class (for example, 4mInputOutput24m, 4mInputOnly24m, or 4mCopyFromParent24m). 4mvisual24m Specifies the visual type (usually 4mCopyFromPar-0m 4ment24m). 4mvalue_mask0m Specifies which fields in the 4mattributes24m structure are used. 4mattributes0m Specifies the window attributes to use in the 4mXCreateWindow24m call. |__ The 4mXtCreateWindow24m function calls the Xlib 4mXCreateWindow0m function with values from the widget structure and the passed parameters. Then, it assigns the created window to the widget's 4mwindow24m field. 4mXtCreateWindow24m evaluates the following fields of the widget core structure: 4mdepth24m, 4mscreen24m, 4mparent->core.window24m, 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, and 4mborder_width24m. 1m770m 1mX Toolkit Intrinsics X11 Release 6.40m 1m2.7. Obtaining Window Information from a Widget0m The Core widget class definition contains the screen and window ids. The 4mwindow24m field may be NULL for a while (see Sections 2.5 and 2.6). The display pointer, the parent widget, screen pointer, and window of a widget are available to the widget writer by means of macros and to the application writer by means of functions. __ | Display *XtDisplay(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Core or any subclass thereof. |__ 4mXtDisplay24m returns the display pointer for the specified wid- get. __ | Widget XtParent(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. |__ 4mXtParent24m returns the parent object for the specified widget. The returned object will be of class Object or a subclass. __ | Screen *XtScreen(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Core or any subclass thereof. |__ 4mXtScreen24m returns the screen pointer for the specified wid- get. 1m780m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Window XtWindow(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Core or any subclass thereof. |__ 4mXtWindow24m returns the window of the specified widget. The display pointer, screen pointer, and window of a widget or of the closest widget ancestor of a nonwidget object are available by means of 4mXtDisplayOfObject24m, 4mXtScreenOfObject24m, and 4mXtWindowOfObject24m. __ | Display *XtDisplayOfObject(4mobject24m) Widget 4mobject24m; 4mobject24m Specifies the object. Must be of class Object or any subclass thereof. |__ 4mXtDisplayOfObject24m is identical in function to 4mXtDisplay24m if the object is a widget; otherwise 4mXtDisplayOfObject24m returns the display pointer for the nearest ancestor of 4mobject24m that is of class Widget or a subclass thereof. __ | Screen *XtScreenOfObject(4mobject24m) Widget 4mobject24m; 4mobject24m Specifies the object. Must be of class Object or any subclass thereof. |__ 4mXtScreenOfObject24m is identical in function to 4mXtScreen24m if the object is a widget; otherwise 4mXtScreenOfObject24m returns the screen pointer for the nearest ancestor of 4mobject24m that is of class Widget or a subclass thereof. 1m790m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Window XtWindowOfObject(4mobject24m) Widget 4mobject24m; 4mobject24m Specifies the object. Must be of class Object or any subclass thereof. |__ 4mXtWindowOfObject24m is identical in function to 4mXtWindow24m if the object is a widget; otherwise 4mXtWindowOfObject24m returns the window for the nearest ancestor of 4mobject24m that is of class Widget or a subclass thereof. To retrieve the instance name of an object, use 4mXtName24m. __ | String XtName(4mobject24m) Widget 4mobject24m; 4mobject24m Specifies the object whose name is desired. Must be of class Object or any subclass thereof. |__ 4mXtName24m returns a pointer to the instance name of the speci- fied object. The storage is owned by the Intrinsics and must not be modified. The name is not qualified by the names of any of the object's ancestors. Several window attributes are locally cached in the widget instance. Thus, they can be set by the resource manager and 4mXtSetValues24m as well as used by routines that derive struc- tures from these values (for example, 4mdepth24m for deriving pixmaps, 4mbackground_pixel24m for deriving GCs, and so on) or in the 4mXtCreateWindow24m call. The 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, and 4mborder_width24m window attributes are available to geometry managers. These fields are main- tained synchronously inside the Intrinsics. When an 4mXCon-0m 4mfigureWindow24m is issued by the Intrinsics on the widget's window (on request of its parent), these values are updated immediately rather than some time later when the server gen- erates a 4mConfigureNotify24m event. (In fact, most widgets do not select 4mSubstructureNotify24m events.) This ensures that all geometry calculations are based on the internally con- sistent toolkit world rather than on either an inconsistent world updated by asynchronous 4mConfigureNotify24m events or a consistent, but slow, world in which geometry managers ask the server for window sizes whenever they need to lay out their managed children (see Chapter 6). 1m800m 1mX Toolkit Intrinsics X11 Release 6.40m 1m2.7.1. Unrealizing Widgets0m To destroy the windows associated with a widget and its non- pop-up descendants, use 4mXtUnrealizeWidget24m. __ | void XtUnrealizeWidget(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Core or any subclass thereof. |__ If the widget is currently unrealized, 4mXtUnrealizeWidget0m simply returns. Otherwise it performs the following: · Unmanages the widget if the widget is managed. · Makes a postorder (child-to-parent) traversal of the widget tree rooted at the specified widget and, for each widget that has declared a callback list resource named ``unrealizeCallback'', executes the procedures on the XtNunrealizeCallback list. · Destroys the widget's window and any subwindows by calling 4mXDestroyWindow24m with the specified widget's 4mwin-0m 4mdow24m field. Any events in the queue or which arrive following a call to 4mXtUnrealizeWidget24m will be dispatched as if the window(s) of the unrealized widget(s) had never existed. 1m2.8. Destroying Widgets0m The Intrinsics provide support · To destroy all the pop-up children of the widget being destroyed and destroy all children of composite wid- gets. · To remove (and unmap) the widget from its parent. · To call the callback procedures that have been regis- tered to trigger when the widget is destroyed. · To minimize the number of things a widget has to deal- locate when destroyed. · To minimize the number of 4mXDestroyWindow24m calls when destroying a widget tree. 1m810m 1mX Toolkit Intrinsics X11 Release 6.40m To destroy a widget instance, use 4mXtDestroyWidget24m. __ | void XtDestroyWidget(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. |__ The 4mXtDestroyWidget24m function provides the only method of destroying a widget, including widgets that need to destroy themselves. It can be called at any time, including from an application callback routine of the widget being destroyed. This requires a two-phase destroy process in order to avoid dangling references to destroyed widgets. In phase 1, 4mXtDestroyWidget24m performs the following: · If the 4mbeing_destroyed24m field of the widget is 4mTrue24m, it returns immediately. · Recursively descends the widget tree and sets the 4mbeing_destroyed24m field to 4mTrue24m for the widget and all normal and pop-up children. · Adds the widget to a list of widgets (the destroy list) that should be destroyed when it is safe to do so. Entries on the destroy list satisfy the invariant that if w2 occurs after w1 on the destroy list, then w2 is not a descendent, either normal or pop-up, of w1. Phase 2 occurs when all procedures that should execute as a result of the current event have been called, including all procedures registered with the event and translation man- agers, that is, when the current invocation of 4mXtDis-0m 4mpatchEvent24m is about to return, or immediately if not in 4mXtDispatchEvent24m. In phase 2, 4mXtDestroyWidget24m performs the following on each entry in the destroy list in the order specified: · If the widget is not a pop-up child and the widget's parent is a subclass of 4mcompositeWidgetClass24m, and if the parent is not being destroyed, it calls 4mXtUnman-0m 4mageChild24m on the widget and then calls the widget's par- ent's delete_child procedure (see Section 3.3). · Calls the destroy callback procedures registered on the widget and all normal and pop-up descendants in pos- torder (it calls child callbacks before parent 1m820m 1mX Toolkit Intrinsics X11 Release 6.40m callbacks). The 4mXtDestroyWidget24m function then makes second traversal of the widget and all normal and pop-up descendants to perform the following three items on each widget in postorder: · If the widget is not a pop-up child and the widget's parent is a subclass of 4mconstraintWidgetClass24m, it calls the 4mConstraintClassPart24m destroy procedure for the par- ent, then for the parent's superclass, until finally it calls the 4mConstraintClassPart24m destroy procedure for 4mconstraintWidgetClass24m. · Calls the 4mCoreClassPart24m destroy procedure declared in the widget class, then the destroy procedure declared in its superclass, until finally it calls the destroy procedure declared in the Object class record. Call- back lists are deallocated. · If the widget class object class part contains an 4mObjectClassExtension24m record with the record_type 4mNUL-0m 4mLQUARK24m and the 4mdeallocate24m field is not NULL, calls the deallocate procedure to deallocate the instance and if one exists, the constraint record. Otherwise, the Intrinsics will deallocate the widget instance record and if one exists, the constraint record. · Calls 4mXDestroyWindow24m if the specified widget is real- ized (that is, has an X window). The server recur- sively destroys all normal descendant windows. (Win- dows of realized pop-up Shell children, and their descendants, are destroyed by a shell class destroy procedure.) 1m2.8.1. Adding and Removing Destroy Callbacks0m When an application needs to perform additional processing during the destruction of a widget, it should register a destroy callback procedure for the widget. The destroy callback procedures use the mechanism described in Chapter 8. The destroy callback list is identified by the resource name XtNdestroyCallback. For example, the following adds an application-supplied destroy callback procedure 4mClientDestroy24m with client data to a widget by calling 4mXtAddCallback24m. XtAddCallback(4mw24m, XtNdestroyCallback, 4mClientDestroy24m, 4mclient_data24m) Similarly, the following removes the application-supplied destroy callback procedure 4mClientDestroy24m by calling 4mXtRemoveCallback24m. 1m830m 1mX Toolkit Intrinsics X11 Release 6.40m XtRemoveCallback(4mw24m, XtNdestroyCallback, 4mClientDestroy24m, 4mclient_data24m) The 4mClientDestroy24m argument is of type 4mXtCallbackProc24m; see Section 8.1. 1m2.8.2. Dynamic Data Deallocation: The destroy Procedure0m The destroy procedure pointers in the 4mObjectClassPart24m, 4mRec-0m 4mtObjClassPart24m, and 4mCoreClassPart24m structures are of type 4mXtWidgetProc24m. __ | typedef void (*XtWidgetProc)(Widget); Widget 4mw24m; 4mw24m Specifies the widget being destroyed. |__ The destroy procedures are called in subclass-to-superclass order. Therefore, a widget's destroy procedure should deal- locate only storage that is specific to the subclass and should ignore the storage allocated by any of its super- classes. The destroy procedure should deallocate only resources that have been explicitly created by the subclass. Any resource that was obtained from the resource database or passed in an argument list was not created by the widget and therefore should not be destroyed by it. If a widget does not need to deallocate any storage, the destroy procedure entry in its class record can be NULL. Deallocating storage includes, but is not limited to, the following steps: · Calling 4mXtFree24m on dynamic storage allocated with 4mXtMal-0m 4mloc24m, 4mXtCalloc24m, and so on. · Calling 4mXFreePixmap24m on pixmaps created with direct X calls. · Calling 4mXtReleaseGC24m on GCs allocated with 4mXtGetGC24m. · Calling 4mXFreeGC24m on GCs allocated with direct X calls. · Calling 4mXtRemoveEventHandler24m on event handlers added to other widgets. · Calling 4mXtRemoveTimeOut24m on timers created with 4mXtAppAd-0m 4mdTimeOut24m. 1m840m 1mX Toolkit Intrinsics X11 Release 6.40m · Calling 4mXtDestroyWidget24m for each child if the widget has children and is not a subclass of 4mcompositeWidget-0m 4mClass24m. During destroy phase 2 for each widget, the Intrinsics remove the widget from the modal cascade, unregister all event handlers, remove all key, keyboard, button, and pointer grabs and remove all callback procedures registered on the widget. Any outstanding selection transfers will time out. 1m2.8.3. Dynamic Constraint Data Deallocation: The Con-0m 1mstraintClassPart destroy Procedure0m The constraint destroy procedure identified in the 4mCon-0m 4mstraintClassPart24m structure is called for a widget whose par- ent is a subclass of 4mconstraintWidgetClass24m. This constraint destroy procedure pointer is of type 4mXtWidgetProc24m. The con- straint destroy procedures are called in subclass-to-super- class order, starting at the class of the widget's parent and ending at 4mconstraintWidgetClass24m. Therefore, a parent's constraint destroy procedure should deallocate only storage that is specific to the constraint subclass and not storage allocated by any of its superclasses. If a parent does not need to deallocate any constraint stor- age, the constraint destroy procedure entry in its class record can be NULL. 1m2.8.4. Widget Instance Deallocation: The deallocate Proce-0m 1mdure0m The deallocate procedure pointer in the 4mObjectClassExtension0m record is of type 4mXtDeallocateProc24m. __ | typedef void (*XtDeallocateProc)(Widget, XtPointer); Widget 4mwidget24m; XtPointer 4mmore_bytes24m; 4mwidget24m Specifies the widget being destroyed. 4mmore_bytes0m Specifies the auxiliary memory received from the corresponding allocator along with the widget, or NULL. |__ When a widget is destroyed, if an 4mObjectClassExtension0m record exists in the object class part 4mextension24m field with 1m850m 1mX Toolkit Intrinsics X11 Release 6.40m 4mrecord_type24m 4mNULLQUARK24m and the 4mdeallocate24m field is not NULL, the 4mXtDeallocateProc24m will be called. If no ObjectClassPart extension record is declared with 4mrecord_type24m equal to 4mNUL-0m 4mLQUARK24m, then 4mXtInheritAllocate24m and 4mXtInheritDeallocate24m are assumed. The responsibilities of the deallocate procedure are to deallocate the memory specified by 4mmore_bytes24m if it is not NULL, to deallocate the constraints record as speci- fied by the widget's 4mcore.constraints24m field if it is not NULL, and to deallocate the widget instance itself. If no 4mXtDeallocateProc24m is found, it is assumed that the Intrinsics originally allocated the memory and is responsi- ble for freeing it. 1m2.9. Exiting from an Application0m All X Toolkit applications should terminate by calling 4mXtDe-0m 4mstroyApplicationContext24m and then exiting using the standard method for their operating system (typically, by calling 4mexit24m for POSIX-based systems). The quickest way to make the windows disappear while exiting is to call 4mXtUnmapWidget24m on each top-level shell widget. The Intrinsics have no resources beyond those in the program image, and the X server will free its resources when its connection to the application is broken. Depending upon the widget set in use, it may be necessary to explicitly destroy individual widgets or widget trees with 4mXtDestroyWidget24m before calling 4mXtDestroyApplicationContext0m in order to ensure that any required widget cleanup is prop- erly executed. The application developer must refer to the widget documentation to learn if a widget needs to perform cleanup beyond that performed automatically by the operating system. If the client is a session participant (see Section 4.2), then the client may wish to resign from the session before exiting. See Section 4.2.4 for details. 1m860m 1mX Toolkit Intrinsics X11 Release 6.40m 1mChapter 30m 1mComposite Widgets and Their Children0m Composite widgets (widgets whose class is a subclass of 4mcom-0m 4mpositeWidgetClass24m) can have an arbitrary number of children. Consequently, they are responsible for much more than primi- tive widgets. Their responsibilities (either implemented directly by the widget class or indirectly by Intrinsics functions) include: · Overall management of children from creation to destruction. · Destruction of descendants when the composite widget is destroyed. · Physical arrangement (geometry management) of a dis- playable subset of children (that is, the managed chil- dren). · Mapping and unmapping of a subset of the managed chil- dren. Overall management is handled by the generic procedures 4mXtCreateWidget24m and 4mXtDestroyWidget24m. 4mXtCreateWidget24m adds children to their parent by calling the parent's insert_child procedure. 4mXtDestroyWidget24m removes children from their parent by calling the parent's delete_child pro- cedure and ensures that all children of a destroyed compos- ite widget also get destroyed. Only a subset of the total number of children is actually managed by the geometry manager and hence possibly visible. For example, a composite editor widget supporting multiple editing buffers might allocate one child widget for each file buffer, but it might display only a small number of the existing buffers. Widgets that are in this displayable sub- set are called managed widgets and enter into geometry man- ager calculations. The other children are called unmanaged widgets and, by definition, are not mapped by the Intrin- sics. Children are added to and removed from their parent's man- aged set by using 4mXtManageChild24m, 4mXtManageChildren24m, 4mXtUnman-0m 4mageChild24m, 4mXtUnmanageChildren24m, and 4mXtChangeManagedSet24m, which notify the parent to recalculate the physical layout of its children by calling the parent's change_managed procedure. The 4mXtCreateManagedWidget24m convenience function calls 4mXtCre-0m 4mateWidget24m and 4mXtManageChild24m on the result. 1m870m 1mX Toolkit Intrinsics X11 Release 6.40m Most managed children are mapped, but some widgets can be in a state where they take up physical space but do not show anything. Managed widgets are not mapped automatically if their 4mmap_when_managed24m field is 4mFalse24m. The default is 4mTrue0m and is changed by using 4mXtSetMappedWhenManaged24m. Each composite widget class declares a geometry manager, which is responsible for figuring out where the managed children should appear within the composite widget's window. Geometry management techniques fall into four classes: Fixed boxes Fixed boxes have a fixed number of children created by the parent. All these children are managed, and none ever makes geometry manager requests. Homogeneous boxes Homogeneous boxes treat all children equally and apply the same geometry constraints to each child. Many clients insert and delete widgets freely. Heterogeneous boxes Heterogeneous boxes have a specific location where each child is placed. This location usually is not specified in pixels, because the window may be resized, but is expressed rather in terms of the relationship between a child and the parent or between the child and other specific children. The class of heterogeneous boxes is usually a subclass of Constraint. Shell boxes Shell boxes typically have only one child, and the child's size is usually exactly the size of the shell. The geometry manager must communicate with the window manager, if it exists, and the box must also accept 4mCon-0m 4mfigureNotify24m events when the window size is changed by the window manager. 1m3.1. Addition of Children to a Composite Widget: The0m 1minsert_child Procedure0m To add a child to the parent's list of children, the 4mXtCre-0m 4mateWidget24m function calls the parent's class routine insert_child. The insert_child procedure pointer in a com- posite widget is of type 4mXtWidgetProc24m. 1m880m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtWidgetProc)(Widget); Widget 4mw24m; 4mw24m Passes the newly created child. |__ Most composite widgets inherit their superclass's operation. The insert_child routine in 4mCompositeWidgetClass24mcalls and inserts the child at the specified position in the 4mchildren0m list, expanding it if necessary. Some composite widgets define their own insert_child routine so that they can order their children in some convenient way, create companion controller widgets for a new widget, or limit the number or class of their child widgets. A com- posite widget class that wishes to allow nonwidget children (see Chapter 12) must specify a 4mCompositeClassExtension0m extension record as described in Section 1.4.2.1 and set the 4maccepts_objects24m field in this record to 4mTrue24m. If the 4mCom-0m 4mpositeClassExtension24m record is not specified or the 4maccepts_objects24m field is 4mFalse24m, the composite widget can assume that all its children are of a subclass of Core with- out an explicit subclass test in the insert_child procedure. If there is not enough room to insert a new child in the 4mchildren24m array (that is, 4mnum_children24m is equal to 4mnum_slots24m), the insert_child procedure must first reallocate the array and update 4mnum_slots24m. The insert_child procedure then places the child at the appropriate position in the array and increments the 4mnum_children24m field. 1m3.2. Insertion Order of Children: The insert_position Pro-0m 1mcedure0m Instances of composite widgets sometimes need to specify more 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 but- tons that represent file names to be kept in alphabetical order without constraining the order in which the buttons are created. An application controls the presentation order of a set of children by supplying an XtNinsertPosition resource. The insert_position procedure pointer in a composite widget instance is of type 4mXtOrderProc24m. 1m890m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef Cardinal (*XtOrderProc)(Widget); Widget 4mw24m; 4mw24m Passes the newly created widget. |__ Composite widgets that allow clients to order their children (usually homogeneous boxes) can call their widget instance's insert_position procedure from the class's insert_child pro- cedure to determine where a new child should go in its 4mchil-0m 4mdren24m array. Thus, a client using a composite class can apply different sorting criteria to widget instances of the class, passing in a different insert_position procedure resource when it creates each composite widget instance. The return value of the insert_position procedure indicates how many children should go before the widget. Returning zero indicates that the widget should go before all other children, and returning 4mnum_children24m indicates that it should go after all other children. The default insert_position function returns 4mnum_children24m and can be overridden by a specific composite widget's resource list or by the argument list provided when the composite widget is created. 1m3.3. Deletion of Children: The delete_child Procedure0m To remove the child from the parent's 4mchildren24m list, the 4mXtDestroyWidget24m function eventually causes a call to the Composite parent's class delete_child procedure. The delete_child procedure pointer is of type 4mXtWidgetProc24m. __ | typedef void (*XtWidgetProc)(Widget); Widget 4mw24m; 4mw24m Passes the child being deleted. |__ Most widgets inherit the delete_child procedure from their superclass. Composite widgets that create companion widgets define their own delete_child procedure to remove these com- panion widgets. 1m900m 1mX Toolkit Intrinsics X11 Release 6.40m 1m3.4. Adding and Removing Children from the Managed Set0m The Intrinsics provide a set of generic routines to permit the addition of widgets to or the removal of widgets from a composite widget's managed set. These generic routines eventually call the composite widget's change_managed proce- dure if the procedure pointer is non-NULL. The change_man- aged procedure pointer is of type 4mXtWidgetProc24m. The widget argument specifies the composite widget whose managed child set has been modified. 1m3.4.1. Managing Children0m To add a list of widgets to the geometry-managed (and hence displayable) subset of their Composite parent, use 4mXtMan-0m 4mageChildren24m. __ | typedef Widget *WidgetList; void XtManageChildren(4mchildren24m, 4mnum_children24m) WidgetList 4mchildren24m; Cardinal 4mnum_children24m; 4mchildren24m Specifies a list of child widgets. Each child must be of class RectObj or any subclass thereof. 4mnum_children0m Specifies the number of children in the list. |__ The 4mXtManageChildren24m function performs the following: · Issues an error if the children do not all have the same parent or if the parent's class is not a subclass of 4mcompositeWidgetClass24m. · Returns immediately if the common parent is being destroyed; otherwise, for each unique child on the list, 4mXtManageChildren24m ignores the child if it already is managed or is being destroyed, and marks it if not. · If the parent is realized and after all children have been marked, it makes some of the newly managed chil- dren viewable: - Calls the change_managed routine of the widgets' parent. - Calls 4mXtRealizeWidget24m on each previously unmanaged child that is unrealized. 1m910m 1mX Toolkit Intrinsics X11 Release 6.40m - Maps each previously unmanaged child that has 4mmap_when_managed24m 4mTrue24m. Managing children is independent of the ordering of children and independent of creating and deleting children. The lay- out routine of the parent should consider children whose 4mmanaged24m field is 4mTrue24m and should ignore all other children. Note that some composite widgets, especially fixed boxes, call 4mXtManageChild24m from their insert_child procedure. If the parent widget is realized, its change_managed proce- dure is called to notify it that its set of managed children has changed. The parent can reposition and resize any of its children. It moves each child as needed by calling 4mXtMoveWidget24m, which first updates the 4mx24m and 4my24m fields and which then calls 4mXMoveWindow24m. If the composite widget wishes to change the size or border width of any of its children, it calls 4mXtResizeWidget24m, which first updates the 4mwidth24m, 4mheight24m, and 4mborder_width24m fields and then calls 4mXConfigureWindow24m. Simultaneous repositioning and resizing may be done with 4mXtConfigureWidget24m; see Section 6.6. To add a single child to its parent widget's set of managed children, use 4mXtManageChild24m. __ | void XtManageChild(4mchild24m) Widget 4mchild24m; 4mchild24m Specifies the child. Must be of class RectObj or any subclass thereof. |__ The 4mXtManageChild24m function constructs a 4mWidgetList24m of length 1 and calls 4mXtManageChildren24m. To create and manage a child widget in a single procedure, use 4mXtCreateManagedWidget24m or 4mXtVaCreateManagedWidget24m. 1m920m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtCreateManagedWidget(4mname24m, 4mwidget_class24m, 4mparent24m, 4margs24m, 4mnum_args24m) String 4mname24m; WidgetClass 4mwidget_class24m; Widget 4mparent24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mname24m Specifies the resource instance name for the cre- ated widget. 4mwidget_class0m Specifies the widget class pointer for the created widget. Must be 1mrectObjClass 22mor any subclass thereof. 4mparent24m Specifies the parent widget. Must be of class Composite or any subclass thereof. 4margs24m Specifies the argument list to override any other resource specifications. 4mnum_args24m Specifies the number of entries in the argument list. |__ The 4mXtCreateManagedWidget24m function is a convenience routine that calls 4mXtCreateWidget24m and 4mXtManageChild24m. 1m930m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtVaCreateManagedWidget(4mname24m, 4mwidget_class24m, 4mparent24m, ...) String 4mname24m; WidgetClass 4mwidget_class24m; Widget 4mparent24m; 4mname24m Specifies the resource instance name for the cre- ated widget. 4mwidget_class0m Specifies the widget class pointer for the created widget. Must be 1mrectObjClass 22mor any subclass thereof. 4mparent24m Specifies the parent widget. Must be of class Composite or any subclass thereof. ... Specifies the variable argument list to override any other resource specifications. |__ 4mXtVaCreateManagedWidget24m is identical in function to 4mXtCre-0m 4mateManagedWidget24m with the 4margs24m and 4mnum_args24m parameters replaced by a varargs list, as described in Section 2.5.1. 1m3.4.2. Unmanaging Children0m To remove a list of children from a parent widget's managed list, use 4mXtUnmanageChildren24m. __ | void XtUnmanageChildren(4mchildren24m, 4mnum_children24m) WidgetList 4mchildren24m; Cardinal 4mnum_children24m; 4mchildren24m Specifies a list of child widgets. Each child must be of class RectObj or any subclass thereof. 4mnum_children0m Specifies the number of children. |__ The 4mXtUnmanageChildren24m function performs the following: · Returns immediately if the common parent is being destroyed. · Issues an error if the children do not all have the same parent or if the parent is not a subclass of 4mcom-0m 4mpositeWidgetClass24m. 1m940m 1mX Toolkit Intrinsics X11 Release 6.40m · For each unique child on the list, 4mXtUnmanageChildren0m ignores the child if it is unmanaged; otherwise it per- forms the following: - Marks the child as unmanaged. - If the child is realized and the 4mmap_when_managed0m field is 4mTrue24m, it is unmapped. · If the parent is realized and if any children have become unmanaged, calls the change_managed routine of the widgets' parent. 4mXtUnmanageChildren24m does not destroy the child widgets. Removing widgets from a parent's managed set is often a tem- porary banishment, and some time later the client may manage the children again. To destroy widgets entirely, 4mXtDestroy-0m 4mWidget24m should be called instead; see Section 2.9. To remove a single child from its parent widget's managed set, use 4mXtUnmanageChild24m. __ | void XtUnmanageChild(4mchild24m) Widget 4mchild24m; 4mchild24m Specifies the child. Must be of class RectObj or any subclass thereof. |__ The 4mXtUnmanageChild24m function constructs a widget list of length 1 and calls 4mXtUnmanageChildren24m. These functions are low-level routines that are used by generic composite widget building routines. In addition, composite widgets can provide widget-specific, high-level convenience procedures. 1m3.4.3. Bundling Changes to the Managed Set0m A client may simultaneously unmanage and manage children with a single call to the Intrinsics. In this same call the client may provide a callback procedure that can modify the geometries of one or more children. The composite widget class defines whether this single client call results in separate invocations of the change_managed method, one to unmanage and the other to manage, or in just a single invo- cation. 1m950m 1mX Toolkit Intrinsics X11 Release 6.40m To simultaneously remove from and add to the geometry-man- aged set of children of a composite parent, use 4mXtChangeMan-0m 4magedSet24m. __ | void XtChangeManagedSet(4munmanage_children24m, 4mnum_unmanage_children24m, 4mdo_change_proc24m, 4mclient_data24m, 4mmanage_children24m, 4mnum_manage_children24m) WidgetList 4munmanage_children24m; Cardinal 4mnum_unmanage_children24m; XtDoChangeProc 4mdo_change_proc24m; XtPointer 4mclient_data24m; WidgetList 4mmanage_children24m; Cardinal 4mnum_manage_children24m; 4munmanage_children24m Specifies the list of widget children to initially remove from the managed set. 4mnum_unmanage_children0m Specifies the number of entries in the 4munmanage_children24m list. 4mdo_change_proc24m Specifies a procedure to invoke between unmanaging and managing the children, or NULL. 4mclient_data24m Specifies client data to be passed to the do_change_proc. 4mmanage_children24m Specifies the list of widget children to finally add to the managed set. 4mnum_manage_children0m Specifies the number of entries in the 4mmanage_children24m list. |__ The 4mXtChangeManagedSet24m function performs the following: · Returns immediately if 4mnum_unmanage_children24m and 4mnum_manage_children24m are both 0. · Issues a warning and returns if the widgets specified in the 4mmanage_children24m and the 4munmanage_children24m lists do not all have the same parent or if that parent is not a subclass of 4mcompositeWidgetClass24m. · Returns immediately if the common parent is being destroyed. · If 4mdo_change_proc24m is not NULL and the parent's 4mCompos-0m 4miteClassExtension24m 4mallows_change_managed_set24m field is 1m960m 1mX Toolkit Intrinsics X11 Release 6.40m 4mFalse24m, then 4mXtChangeManagedSet24m performs the following: - Calls 4mXtUnmanageChildren24m (4munmanage_children24m, 4mnum_unmanage_children24m). - Calls the 4mdo_change_proc24m. - Calls 4mXtManageChildren24m (4mmanage_children24m, 4mnum_man-0m 4mage_children24m). · Otherwise, the following is performed: - For each child on the 4munmanage_children24m list; if the child is already unmanaged it is ignored, oth- erwise it is marked as unmanaged, and if it is realized and its 4mmap_when_managed24m field is 4mTrue24m, it is unmapped. - If 4mdo_change_proc24m is non-NULL, the procedure is invoked. - For each child on the 4mmanage_children24m list; if the child is already managed or is being destroyed, it is ignored; otherwise it is marked as managed. - If the parent is realized and after all children have been marked, the change_managed method of the parent is invoked, and subsequently some of the newly managed children are made viewable by call- ing 4mXtRealizeWidget24m on each previously unmanaged child that is unrealized and mapping each previ- ously unmanaged child that has 4mmap_when_managed0m 4mTrue24m. If no 4mCompositeClassExtension24m record is found in the par- ent's composite class part 4mextension24m field with record type 4mNULLQUARK24m and version greater than 1, and if 4mXtInher-0m 4mitChangeManaged24m was specified in the parent's class record during class initialization, the value of the 4mallows_change_managed_set24m field is inherited from the super- class. The value inherited from 4mcompositeWidgetClass24m for the 4mallows_change_managed_set24m field is 4mFalse24m. It is not an error to include a child in both the 4munman-0m 4mage_children24m and the 4mmanage_children24m lists. The effect of such a call is that the child remains managed following the call, but the 4mdo_change_proc24m is able to affect the child while it is in an unmanaged state. The 4mdo_change_proc24m is of type 4mXtDoChangeProc24m. 1m970m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtDoChangeProc)(Widget, WidgetList, Cardinal*, WidgetList, Cardinal*, XtPointer); Widget 4mcomposite_parent24m; WidgetList 4munmange_children24m; Cardinal *4mnum_unmanage_children24m; WidgetList 4mmanage_children24m; Cardinal *4mnum_manage_children24m; XtPointer 4mclient_data24m; 4mcomposite_parent24m Passes the composite parent whose managed set is being altered. 4munmanage_children24m Passes the list of children just removed from the managed set. 4mnum_unmanage_children0m Passes the number of entries in the 4munman-0m 4mage_children24m list. 4mmanage_children24m Passes the list of children about to be added to the managed set. 4mnum_manage_children0m Passes the number of entries in the 4mman-0m 4mage_children24m list. 4mclient_data24m Passes the client data passed to 4mXtChange-0m 4mManagedSet24m. |__ The 4mdo_change_proc24m procedure is used by the caller of 4mXtChangeManagedSet24m to make changes to one or more children at the point when the managed set contains the fewest entries. These changes may involve geometry requests, and in this case the caller of 4mXtChangeManagedSet24m may take advantage of the fact that the Intrinsics internally grant geometry requests made by unmanaged children without invok- ing the parent's geometry manager. To achieve this advan- tage, if the 4mdo_change_proc24m procedure changes the geometry of a child or of a descendant of a child, then that child should be included in the 4munmanage_children24m and 4mmanage_chil-0m 4mdren24m lists. 1m3.4.4. Determining if a Widget Is Managed0m To determine the managed state of a given child widget, use 4mXtIsManaged24m. 1m980m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Boolean XtIsManaged(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. |__ The 4mXtIsManaged24m function returns 4mTrue24m if the specified wid- get is of class RectObj or any subclass thereof and is man- aged, or 4mFalse24m otherwise. 1m3.5. Controlling When Widgets Get Mapped0m A widget is normally mapped if it is managed. However, this behavior can be overridden by setting the XtNmappedWhenMan- aged resource for the widget when it is created or by set- ting the 4mmap_when_managed24m field to 4mFalse24m. To change the value of a given widget's 4mmap_when_managed0m field, use 4mXtSetMappedWhenManaged24m. __ | void XtSetMappedWhenManaged(4mw24m, 4mmap_when_managed24m) Widget 4mw24m; Boolean 4mmap_when_managed24m; 4mw24m Specifies the widget. Must be of class Core or any subclass thereof. 4mmap_when_managed0m Specifies a Boolean value that indicates the new value that is stored into the widget's 4mmap_when_managed24m field. |__ If the widget is realized and managed, and if 4mmap_when_man-0m 4maged24m is 4mTrue24m, 4mXtSetMappedWhenManaged24m maps the window. If the widget is realized and managed, and if 4mmap_when_managed0m is 4mFalse24m, it unmaps the window. 4mXtSetMappedWhenManaged24m is a convenience function that is equivalent to (but slightly faster than) calling 4mXtSetValues24m and setting the new value for the XtNmappedWhenManaged resource then mapping the wid- get as appropriate. As an alternative to using 4mXtSetMapped-0m 4mWhenManaged24m to control mapping, a client may set 4mmapped_when_managed24m to 4mFalse24m and use 4mXtMapWidget24m and 4mXtUn-0m 4mmapWidget24m explicitly. 1m990m 1mX Toolkit Intrinsics X11 Release 6.40m To map a widget explicitly, use 4mXtMapWidget24m. __ | XtMapWidget(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Core or any subclass thereof. |__ To unmap a widget explicitly, use 4mXtUnmapWidget24m. __ | XtUnmapWidget(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Core or any subclass thereof. |__ 1m3.6. Constrained Composite Widgets0m The Constraint widget class is a subclass of 4mcompositeWid-0m 4mgetClass24m. The name is derived from the fact that constraint widgets 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 parent will allow the child to occupy or can be as complicated as how other children should change if this child is moved or resized. Constraint widgets let a parent define constraints as 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's class. 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 4mconstraints24m field, which is the address of a parent-spe- cific structure that contains constraint information about the child. If a child's parent does not belong to a 1m1000m 1mX Toolkit Intrinsics X11 Release 6.40m subclass of 4mconstraintWidgetClass24m, then the child's 4mcon-0m 4mstraints24m field is NULL. Subclasses of Constraint can add constraint data to the con- straint record defined by their superclass. To allow this, widget writers should define the constraint records in their private .h file by using the same conventions as used for widget records. For example, a widget class that needs to maintain a maximum width and height for each child might define its constraint record as follows: typedef struct { Dimension max_width, max_height; } MaxConstraintPart; typedef struct { MaxConstraintPart max; } MaxConstraintRecord, *MaxConstraint; A subclass of this widget class that also needs to maintain a minimum size would define its constraint record as fol- lows: typedef struct { Dimension min_width, min_height; } MinConstraintPart; typedef struct { MaxConstraintPart max; MinConstraintPart min; } MaxMinConstraintRecord, *MaxMinConstraint; Constraints are allocated, initialized, deallocated, and otherwise maintained insofar as possible by the Intrinsics. The Constraint class record part has several entries that facilitate this. All entries in 4mConstraintClassPart24m are fields and procedures that are defined and implemented by the parent, but they are called whenever actions are per- formed on the parent's children. The 4mXtCreateWidget24m function uses the 4mconstraint_size24m field in the parent's class record to allocate a constraint record when a child is created. 4mXtCreateWidget24m also uses the con- straint resources to fill in resource fields in the con- straint record associated with a child. It then calls the constraint initialize procedure so that the parent can com- pute constraint fields that are derived from constraint resources and can possibly move or resize the child to con- form to the given constraints. 1m1010m 1mX Toolkit Intrinsics X11 Release 6.40m When the 4mXtGetValues24m and 4mXtSetValues24m functions are executed on a child, they use the constraint resources to get the values or set the values of constraints associated with that child. 4mXtSetValues24m then calls the constraint set_values procedures so that the parent can recompute derived con- straint fields and move or resize the child as appropriate. If a Constraint widget class or any of its superclasses have declared a 4mConstraintClassExtension24m record in the 4mCon-0m 4mstraintClassPart24m 4mextension24m fields with a record type of 4mNUL-0m 4mLQUARK24m and the 4mget_values_hook24m field in the extension record is non-NULL, 4mXtGetValues24m calls the get_values_hook proce- dure(s) to allow the parent to return derived constraint fields. The 4mXtDestroyWidget24m function calls the constraint destroy procedure to deallocate any dynamic storage associated with a constraint record. The constraint record itself must not be deallocated by the constraint destroy procedure; 4mXtDe-0m 4mstroyWidget24m does this automatically. 1m1020m 1mX Toolkit Intrinsics X11 Release 6.40m 1mChapter 40m 1mShell Widgets0m Shell widgets hold an application's top-level widgets to allow them to communicate with the window manager and ses- sion manager. Shells have been designed to be as nearly invisible as possible. Clients have to create them, 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 managed 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. The five types of public shells are: 4mOverrideShell24m Used for shell windows that completely bypass the window manager (for example, pop-up menu shells). 4mTransientShell24m Used for shell windows that have the 4mWM_TRANSIENT_FOR24m property set. The effect of this property is dependent upon the window manager being used. 4mTopLevelShell24m Used for normal top-level windows (for example, any additional top-level widgets an application needs). 4mApplication-24m Formerly used for the single main top- 4mShell24m level window that the window manager iden- tifies as an application instance and made obsolete by SessionShell. 4mSessionShell24m Used for the single main top-level window that the window manager identifies as an application instance and that interacts with the session manager. 1m4.1. Shell Widget Definitions0m Widgets negotiate their size and position with their parent widget, that is, the widget that directly contains them. 1m1030m 1mX Toolkit Intrinsics X11 Release 6.40m Widgets at the top of the hierarchy do not have parent wid- gets. 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 widget. Shell widgets, whose class is a subclass of the Composite class, encapsulate other widgets and can allow a widget to avoid the geometry clipping imposed by the parent-child win- dow relationship. They also can provide a layer of communi- cation with the window manager. The eight different types of shells are: 4mShell24m The base class for shell widgets; provides the fields needed for all types of shells. Shell is a direct subclass of 4mcompositeWid-0m 4mgetClass24m. 4mOverrideShell24m A subclass of Shell; used for shell windows that completely bypass the window manager. 4mWMShell24m A subclass of Shell; contains fields needed by the common window manager protocol. 4mVendorShell24m A subclass of WMShell; contains fields used by vendor-specific window managers. 4mTransientShell24m A subclass of VendorShell; used for shell windows that desire the 4mWM_TRANSIENT_FOR0m property. 4mTopLevelShell24m A subclass of VendorShell; used for normal top-level windows. 4mApplication-24m A subclass of TopLevelShell; may be used for 4mShell24m an application's additional root windows. 4mSessionShell24m A subclass of ApplicationShell; used for an application's main root window. Note that the classes Shell, WMShell, and VendorShell are internal and should not be instantiated or subclassed. Only OverrrideShell, TransientShell, TopLevelShell, Application- Shell, and SessionShell are intended for public use. 1m4.1.1. ShellClassPart Definitions0m Only the Shell class has additional class fields, which are all contained in the 4mShellClassExtensionRec24m. None of the other Shell classes have any additional class fields: 1m1040m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct { XtPointer extension; } ShellClassPart, OverrideShellClassPart, WMShellClassPart, VendorShellClassPart, TransientShellClassPart, TopLevelShellClassPart, ApplicationShellClassPart, SessionShellClassPart; |__ The full Shell class record definitions are: 1m1050m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct _ShellClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ShellClassPart shell_class; } ShellClassRec; typedef struct { XtPointer next_extension; See Section 1.6.12 XrmQuark record_type; See Section 1.6.12 long version; See Section 1.6.12 Cardinal record_size; See Section 1.6.12 XtGeometryHandler root_geometry_manager;See below } ShellClassExtensionRec, *ShellClassExtension; typedef struct _OverrideShellClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ShellClassPart shell_class; OverrideShellClassPart override_shell_class; } OverrideShellClassRec; typedef struct _WMShellClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ShellClassPart shell_class; WMShellClassPart wm_shell_class; } WMShellClassRec; typedef struct _VendorShellClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ShellClassPart shell_class; WMShellClassPart wm_shell_class; VendorShellClassPart vendor_shell_class; } VendorShellClassRec; typedef struct _TransientShellClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ShellClassPart shell_class; WMShellClassPart wm_shell_class; VendorShellClassPart vendor_shell_class; TransientShellClassPart transient_shell_class; } TransientShellClassRec; 1m1060m 1mX Toolkit Intrinsics X11 Release 6.40m typedef struct _TopLevelShellClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ShellClassPart shell_class; WMShellClassPart wm_shell_class; VendorShellClassPart vendor_shell_class; TopLevelShellClassPart top_level_shell_class; } TopLevelShellClassRec; typedef struct _ApplicationShellClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ShellClassPart shell_class; WMShellClassPart wm_shell_class; VendorShellClassPart vendor_shell_class; TopLevelShellClassPart top_level_shell_class; ApplicationShellClassPart application_shell_class; } ApplicationShellClassRec; typedef struct _SessionShellClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ShellClassPart shell_class; WMShellClassPart wm_shell_class; VendorShellClassPart vendor_shell_class; TopLevelShellClassPart top_level_shell_class; ApplicationShellClassPart application_shell_class; SessionShellClassPart session_shell_class; } SessionShellClassRec; |__ 1m1070m 1mX Toolkit Intrinsics X11 Release 6.40m The single occurrences of the class records and pointers for creating instances of shells are: __ | extern ShellClassRec shellClassRec; extern OverrideShellClassRec overrideShellClassRec; extern WMShellClassRec wmShellClassRec; extern VendorShellClassRec vendorShellClassRec; extern TransientShellClassRec transientShellClassRec; extern TopLevelShellClassRec topLevelShellClassRec; extern ApplicationShellClassRec applicationShellClassRec; extern SessionShellClassRec sessionShellClassRec; extern WidgetClass shellWidgetClass; extern WidgetClass overrideShellWidgetClass; extern WidgetClass wmShellWidgetClass; extern WidgetClass vendorShellWidgetClass; extern WidgetClass transientShellWidgetClass; extern WidgetClass topLevelShellWidgetClass; extern WidgetClass applicationShellWidgetClass; extern WidgetClass sessionShellWidgetClass; |__ The following opaque types and opaque variables are defined for generic operations on widgets whose class is a subclass of Shell. ----------------------------------------------------------- Types Variables ----------------------------------------------------------- 4mShellWidget24m 4mshellWidgetClass0m 4mOverrideShellWidget24m 4moverrideShellWidgetClass0m 4mWMShellWidget24m 4mwmShellWidgetClass0m 4mVendorShellWidget24m 4mvendorShellWidgetClass0m 4mTransientShellWidget24m 4mtransientShellWidgetClass0m 4mTopLevelShellWidget24m 4mtopLevelShellWidgetClass0m 4mApplicationShellWidget24m 4mapplicationShellWidgetClass0m 4mSessionShellWidget24m 4msessionShellWidgetClass0m 4mShellWidgetClass0m 4mOverrideShellWidgetClass0m 4mWMShellWidgetClass0m 4mVendorShellWidgetClass0m 4mTransientShellWidgetClass0m 4mTopLevelShellWidgetClass0m 4mApplicationShellWidgetClass0m 4mSessionShellWidgetClass0m ----------------------------------------------------------- The declarations for all Intrinsics-defined shells except VendorShell appear in 4mShell.h24m and 4mShellP.h24m. VendorShell has separate public and private .h files which are included by 1m1080m 1mX Toolkit Intrinsics X11 Release 6.40m 4mShell.h24m and 4mShellP.h24m. 4mShell.h24m uses incomplete structure definitions to ensure that the compiler catches attempts to access private data in any of the Shell instance or class data structures. The symbolic constant for the 4mShellClassExtension24m version identifier is 4mXtShellExtensionVersion24m (see Section 1.6.12). The root_geometry_manager procedure acts as the parent geom- etry manager for geometry requests made by shell widgets. When a shell widget calls either 4mXtMakeGeometryRequest24m or 4mXtMakeResizeRequest24m, the root_geometry_manager procedure is invoked to negotiate the new geometry with the window man- ager. If the window manager permits the new geometry, the root_geometry_manager procedure should return 4mXtGeometryYes24m; if the window manager denies the geometry request or does not change the window geometry within some timeout interval (equal to 4mwm_timeout24m in the case of WMShells), the root_geometry_manager procedure should return 4mXtGeometryNo24m. If the window manager makes some alternative geometry change, the root_geometry_manager procedure may return either 4mXtGeometryNo24m and handle the new geometry as a resize or 4mXtGeometryAlmost24m in anticipation that the shell will accept the compromise. If the compromise is not accepted, the new size must then be handled as a resize. Subclasses of Shell that wish to provide their own root_geometry_man- ager procedures are strongly encouraged to use enveloping to invoke their superclass's root_geometry_manager procedure under most situations, as the window manager interaction may be very complex. If no 4mShellClassPart24m extension record is declared with 4mrecord_type24m equal to 4mNULLQUARK24m, then 4mXtInheritRootGeometry-0m 4mManager24m is assumed. 1m4.1.2. ShellPart Definition0m The various shell widgets have the following additional instance fields defined in their widget records: 1m1090m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct { String geometry; XtCreatePopupChildProc create_popup_child_proc; XtGrabKind grab_kind; Boolean spring_loaded; Boolean popped_up; Boolean allow_shell_resize; Boolean client_specified; Boolean save_under; Boolean override_redirect; XtCallbackList popup_callback; XtCallbackList popdown_callback; Visual * visual; } ShellPart; typedef struct { int empty; } OverrideShellPart; typedef struct { String title; int wm_timeout; Boolean wait_for_wm; Boolean transient; Boolean urgency; Widget client_leader; String window_role; struct _OldXSizeHints { long flags; int x, y; int width, height; int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; int y; } min_aspect, max_aspect; } size_hints; XWMHints wm_hints; int base_width, base_height, win_gravity; Atom title_encoding; } WMShellPart; typedef struct { int vendor_specific; } VendorShellPart; typedef struct { 1m1100m 1mX Toolkit Intrinsics X11 Release 6.40m Widget transient_for; } TransientShellPart; typedef struct { String icon_name; Boolean iconic; Atom icon_name_encoding; } TopLevelShellPart; typedef struct { char * class; XrmClass xrm_class; int argc; char ** argv; } ApplicationShellPart; typedef struct { SmcConn connection; String session_id; String * restart_command; String * clone_command; String * discard_command; String * resign_command; String * shutdown_command; String * environment; String current_dir; String program_path; unsigned char restart_style; Boolean join_session; XtCallbackList save_callbacks; XtCallbackList interact_callbacks; XtCallbackList cancel_callbacks; XtCallbackList save_complete_callbacks; XtCallbackList die_callbacks; XtCallbackList error_callbacks; } SessionShellPart; |__ 1m1110m 1mX Toolkit Intrinsics X11 Release 6.40m The full shell widget instance record definitions are: __ | 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; } TransientShellRec, *TransientShellWidget; 1m1120m 1mX Toolkit Intrinsics X11 Release 6.40m typedef struct { CorePart core; CompositePart composite; ShellPart shell; WMShellPart wm; VendorShellPart vendor; TopLevelShellPart topLevel; } TopLevelShellRec, *TopLevelShellWidget; typedef struct { CorePart core; CompositePart composite; ShellPart shell; WMShellPart wm; VendorShellPart vendor; TopLevelShellPart topLevel; ApplicationShellPart application; } ApplicationShellRec, *ApplicationShellWidget; typedef struct { CorePart core; CompositePart composite; ShellPart shell; WMShellPart wm; VendorShellPart vendor; TopLevelShellPart topLevel; ApplicationShellPart application; SessionShellPart session; } SessionShellRec, *SessionShellWidget; |__ 1m4.1.3. Shell Resources0m The resource names, classes, and representation types speci- fied in the 4mshellClassRec24m resource list are: ------------------------------------------------------------------- Name Class Representation ------------------------------------------------------------------- XtNallowShellResize XtCAllowShellResize XtRBoolean XtNcreatePopupChildProc XtCCreatePopupChildProc XtRFunction XtNgeometry XtCGeometry XtRString XtNoverrideRedirect XtCOverrideRedirect XtRBoolean XtNpopdownCallback XtCCallback XtRCallback XtNpopupCallback XtCCallback XtRCallback XtNsaveUnder XtCSaveUnder XtRBoolean 1m1130m 1mX Toolkit Intrinsics X11 Release 6.40m XtNvisual XtCVisual XtRVisual ------------------------------------------------------------------- OverrideShell declares no additional resources beyond those defined by Shell. The resource names, classes, and representation types speci- fied in the 4mwmShellClassRec24m resource list are: -------------------------------------------------------------------------- Name Class Representation -------------------------------------------------------------------------- XtNbaseHeight XtCBaseHeight XtRInt XtNbaseWidth XtCBaseWidth XtRInt XtNclientLeader XtCClientLeader XtRWidget XtNheightInc XtCHeightInc XtRInt XtNiconMask XtCIconMask XtRBitmap XtNiconPixmap XtCIconPixmap XtRBitmap XtNiconWindow XtCIconWindow XtRWindow XtNiconX XtCIconX XtRInt XtNiconY XtCIconY XtRInt XtNinitialState XtCInitialState XtRInitialState XtNinput XtCInput XtRBool XtNmaxAspectX XtCMaxAspectX XtRInt XtNmaxAspectY XtCMaxAspectY XtRInt XtNmaxHeight XtCMaxHeight XtRInt XtNmaxWidth XtCMaxWidth XtRInt XtNminAspectX XtCMinAspectX XtRInt XtNminAspectY XtCMinAspectY XtRInt XtNminHeight XtCMinHeight XtRInt XtNminWidth XtCMinWidth XtRInt XtNtitle XtCTitle XtRString XtNtitleEncoding XtCTitleEncoding XtRAtom XtNtransient XtCTransient XtRBoolean XtNwaitforwm, XtNwaitForWm XtCWaitforwm, XtCWaitForWm XtRBoolean XtNwidthInc XtCWidthInc XtRInt XtNwindowRole XtCWindowRole XtRString XtNwinGravity XtCWinGravity XtRGravity XtNwindowGroup XtCWindowGroup XtRWindow XtNwmTimeout XtCWmTimeout XtRInt XtNurgency XtCUrgency XtRBoolean -------------------------------------------------------------------------- The class resource list for VendorShell is implementation- defined. The resource names, classes, and representation types that are specified in the 4mtransientShellClassRec24m resource list are: 1m1140m 1mX Toolkit Intrinsics X11 Release 6.40m ------------------------------------------------------- Name Class Representation ------------------------------------------------------- XtNtransientFor XtCTransientFor XtRWidget ------------------------------------------------------- The resource names, classes, and representation types that are specified in the 4mtopLevelShellClassRec24m resource list are: ----------------------------------------------------------- Name Class Representation ----------------------------------------------------------- XtNiconName XtCIconName XtRString XtNiconNameEncoding XtCIconNameEncoding XtRAtom XtNiconic XtCIconic XtRBoolean ----------------------------------------------------------- The resource names, classes, and representation types that are specified in the 4mapplicationShellClassRec24m resource list are: ------------------------------------------------------- Name Class Representation ------------------------------------------------------- XtNargc XtCArgc XtRInt XtNargv XtCArgv XtRStringArray ------------------------------------------------------- 1m1150m 1mX Toolkit Intrinsics X11 Release 6.40m The resource names, classes, and representation types that are specified in the 4msessionShellClassRec24m resource list are: -------------------------------------------------------------------- Name Class Representation -------------------------------------------------------------------- XtNcancelCallback XtCCallback XtRCallback XtNcloneCommand XtCCloneCommand XtRCommandArgArray XtNconnection XtCConnection XtRSmcConn XtNcurrentDirectory XtCCurrentDirectory XtRDirectoryString XtNdieCallback XtCCallback XtRCallback XtNdiscardCommand XtCDiscardCommand XtRCommandArgArray XtNenvironment XtCEnvironment XtREnvironmentArray XtNerrorCallback XtCCallback XtRCallback XtNinteractCallback XtCCallback XtRCallback XtNjoinSession XtCJoinSession XtRBoolean XtNprogramPath XtCProgramPath XtRString XtNresignCommand XtCResignCommand XtRCommandArgArray XtNrestartCommand XtCRestartCommand XtRCommandArgArray XtNrestartStyle XtCRestartStyle XtRRestartStyle XtNsaveCallback XtCCallback XtRCallback XtNsaveCompleteCallback XtCCallback XtRCallback XtNsessionID XtCSessionID XtRString XtNshutdownCommand XtCShutdownCommand XtRCommandArgArray -------------------------------------------------------------------- 1m4.1.4. ShellPart Default Values0m The default values for fields common to all classes of pub- lic shells (filled in by the Shell resource lists and the Shell initialize procedures) are: --------------------------------------------------------- Field Default Value --------------------------------------------------------- geometry NULL create_popup_child_proc NULL grab_kind (none) spring_loaded (none) popped_up 4mFalse0m allow_shell_resize 4mFalse0m client_specified (internal) save_under 4mTrue24m for OverrideShell and TransientShell, 4mFalse24m other- wise override_redirect 4mTrue24m for OverrideShell, 4mFalse0m otherwise popup_callback NULL popdown_callback NULL visual 4mCopyFromParent0m --------------------------------------------------------- 1m1160m 1mX Toolkit Intrinsics X11 Release 6.40m The 4mgeometry24m field specifies the size and position and is usually given only on a command line or in a defaults file. If the 4mgeometry24m field is non-NULL when a widget of class WMShell is realized, the geometry specification is parsed using 4mXWMGeometry24m with a default geometry string constructed from the values of 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, 4mwidth_inc24m, and 4mheight_inc24m and the size and position flags in the window manager size hints are set. If the geometry specifies an x or y position, then 4mUSPosition24m is set. If the geometry specifies a width or height, then 4mUSSize24m is set. Any fields in the geometry specification override the corresponding values in the Core 4mx24m, 4my24m, 4mwidth24m, and 4mheight24m fields. If 4mgeom-0m 4metry24m is NULL or contains only a partial specification, then the Core 4mx24m, 4my24m, 4mwidth24m, and 4mheight24m fields are used and 4mPPosi-0m 4mtion24m and 4mPSize24m are set as appropriate. The geometry string is not copied by any of the Intrinsics Shell classes; a client specifying the string in an arglist or varargs list must ensure that the value remains valid until the shell widget is realized. For further information on the geometry string, see Section 16.4 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m. The 4mcreate_popup_child_proc24m procedure is called by the 4mXtPopup24m procedure and may remain NULL. The 4mgrab_kind24m, 4mspring_loaded24m, and 4mpopped_up24m fields maintain widget state information as described under 4mXtPopup24m, 4mXtMenuPopup24m, 4mXtPop-0m 4mdown24m, and 4mXtMenuPopdown24m. The 4mallow_shell_resize24m field con- trols whether the widget contained by the shell is allowed to try to resize itself. If allow_shell_resize is 4mFalse24m, any geometry requests made by the child will always return 4mXtGeometryNo24m without interacting with the window manager. Setting 4msave_under24m 4mTrue24m instructs the server to attempt to save the contents of windows obscured by the shell when it is mapped and to restore those contents automatically when the shell is unmapped. It is useful for pop-up menus. Set- ting 4moverride_redirect24m 4mTrue24m determines whether the window manager can intercede when the shell window is mapped. For further information on override_redirect, see Section 3.2 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m and Sections 4.1.10 and 4.2.2 in the 4mInter-Client24m 4mCommunication24m 4mConventions24m 4mManual24m. The pop-up and pop-down callbacks are called during 4mXtPopup24m and 4mXtPopdown24m. The default value of the 4mvisual24m resource is the symbolic value 4mCopyFromParent24m. The Intrinsics do not need to query the parent's visual type when the default value is used; if a client using 4mXtGetValues24m to examine the visual type receives the value 4mCopyFromParent24m, it must then use 4mXGetWindowAttributes24m if it needs the actual visual type. The default values for Shell fields in WMShell and its sub- classes are: 1m1170m 1mX Toolkit Intrinsics X11 Release 6.40m ---------------------------------------------------------- Field Default Value ---------------------------------------------------------- title Icon name, if specified, otherwise the application's name wm_timeout Five seconds, in units of milliseconds wait_for_wm 4mTrue0m transient 4mTrue24m for TransientShell, 4mFalse24m otherwise urgency 4mFalse0m client_leader NULL window_role NULL min_width 1mXtUnspecifiedShellInt0m min_height 1mXtUnspecifiedShellInt0m max_width 1mXtUnspecifiedShellInt0m max_height 1mXtUnspecifiedShellInt0m width_inc 1mXtUnspecifiedShellInt0m height_inc 1mXtUnspecifiedShellInt0m min_aspect_x 1mXtUnspecifiedShellInt0m min_aspect_y 1mXtUnspecifiedShellInt0m max_aspect_x 1mXtUnspecifiedShellInt0m max_aspect_y 1mXtUnspecifiedShellInt0m input 4mFalse0m initial_state Normal icon_pixmap None icon_window None icon_x 1mXtUnspecifiedShellInt0m icon_y 1mXtUnspecifiedShellInt0m icon_mask None window_group 1mXtUnspecifiedWindow0m base_width 1mXtUnspecifiedShellInt0m base_height 1mXtUnspecifiedShellInt0m win_gravity 1mXtUnspecifiedShellInt0m title_encoding See text ---------------------------------------------------------- The 4mtitle24m and 4mtitle_encoding24m fields are stored in the 4mWM_NAME24m property on the shell's window by the WMShell real- ize procedure. If the 4mtitle_encoding24m field is 4mNone24m, the 4mtitle24m string is assumed to be in the encoding of the current locale and the encoding of the 4mWM_NAME24m property is set to 4mXStdICCTextStyle24m. If a language procedure has not been set the default value of 4mtitle_encoding24m is 1mXA_STRING22m, otherwise the default value is 4mNone24m. The 4mwm_timeout24m field specifies, in milliseconds, the amount of time a shell is to wait for confirmation of a geometry request to the window manager. If none comes back within that time, the shell assumes the window manager is not functioning properly and sets 4mwait_for_wm24m to 4mFalse24m (later events may reset this value). When 4mwait_for_wm24m is 4mFalse24m, the shell does not wait for a response, but relies on asynchronous notification. If 4mtran-0m 4msient24m is 4mTrue24m, the 4mWM_TRANSIENT_FOR24m property will be stored on the shell window with a value as specified below. The interpretation of this property is specific to the window 1m1180m 1mX Toolkit Intrinsics X11 Release 6.40m manager under which the application is run; see the 4mInter-0m 4mClient24m 4mCommunication24m 4mConventions24m 4mManual24m for more details. The realize and set_values procedures of WMShell store the 4mWM_CLIENT_LEADER24m property on the shell window. When 4mclient_leader24m is not NULL and the client leader widget is realized, the property will be created with the value of the window of the client leader widget. When 4mclient_leader24m is NULL and the shell widget has a NULL parent, the widget's window is used as the value of the property. When 4mclient_leader24m is NULL and the shell widget has a non-NULL parent, a search is made for the closest shell ancestor with a non-NULL 4mclient_leader24m, and if none is found the shell ancestor with a NULL parent is the result. If the resulting widget is realized, the property is created with the value of the widget's window. When the value of 4mwindow_role24m is not NULL, the realize and set_values procedures store the 4mWM_WINDOW_ROLE24m property on the shell's window with the value of the resource. All other resources specify fields in the window manager hints and the window manager size hints. The realize and set_values procedures of WMShell set the corresponding flag bits in the hints if any of the fields contain nondefault values. In addition, if a flag bit is set that refers to a field with the value 4mXtUnspecifiedShellInt24m, the value of the field is modified as follows: ------------------------------------------------------------ Field Replacement ------------------------------------------------------------ base_width, base_height 0 width_inc, height_inc 1 max_width, max_height 32767 min_width, min_height 1 min_aspect_x, min_aspect_y -1 max_aspect_x, max_aspect_y -1 icon_x, icon_y -1 win_gravity Value returned by 4mXWMGeometry0m if called, else 1mNorthWestGrav-0m 1mity0m ------------------------------------------------------------ If the shell widget has a non-NULL parent, then the realize and set_values procedures replace the value 4mXtUnspecified-0m 4mWindow24m in the 4mwindow_group24m field with the window id of the root widget of the widget tree if the root widget is real- ized. The symbolic constant 4mXtUnspecifiedWindowGroup24m may be used to indicate that the 4mwindow_group24m hint flag bit is not to be set. If 4mtransient24m is 4mTrue24m, the shell's class is not a 1m1190m 1mX Toolkit Intrinsics X11 Release 6.40m subclass of TransientShell, and 4mwindow_group24m is not 4mXtUn-0m 4mspecifiedWindowGroup24m, the WMShell realize and set_values procedures then store the 4mWM_TRANSIENT_FOR24m property with the value of 4mwindow_group24m. Transient shells have the following additional resource: ------------------------------ Field Default Value ------------------------------ transient_for NULL ------------------------------ The realize and set_values procedures of TransientShell store the 4mWM_TRANSIENT_FOR24m property on the shell window if 4mtransient24m is 4mTrue24m. If 4mtransient_for24m is non-NULL and the widget specified by 4mtransient_for24m is realized, then its win- dow is used as the value of the 4mWM_TRANSIENT_FOR24m property; otherwise, the value of 4mwindow_group24m is used. 4mTopLevel24m shells have the the following additional resources: ----------------------------------------- Field Default Value ----------------------------------------- icon_name Shell widget's name iconic 4mFalse0m icon_name_encoding See text ----------------------------------------- The 4micon_name24m and 4micon_name_encoding24m fields are stored in the 4mWM_ICON_NAME24m property on the shell's window by the TopLevelShell realize procedure. If the 4micon_name_encoding0m field is 4mNone24m, the 4micon_name24m string is assumed to be in the encoding of the current locale and the encoding of the 4mWM_ICON_NAME24m property is set to 4mXStdICCTextStyle24m. If a lan- guage procedure has not been set, the default value of 4micon_name_encoding24m is 1mXA_STRING22m, otherwise the default value is 4mNone24m. The 4miconic24m field may be used by a client to request that the window manager iconify or deiconify the shell; the TopLevelShell set_values procedure will send the appropriate 4mWM_CHANGE_STATE24m message (as specified by the 4mInter-Client24m 4mCommunication24m 4mConventions24m 4mManual24m) if this resource is changed from 4mFalse24m to 4mTrue24m and will call 4mXtPopup0m specifying 4mgrab_kind24m as 4mXtGrabNone24m if 4miconic24m is changed from 4mTrue24m to 4mFalse24m. The XtNiconic resource is also an alterna- tive way to set the XtNinitialState resource to indicate that a shell should be initially displayed as an icon; the TopLevelShell initialize procedure will set 4minitial_state24m to 4mIconicState24m if 4miconic24m is 4mTrue24m. 1m1200m 1mX Toolkit Intrinsics X11 Release 6.40m Application shells have the following additional resources: ---------------------- Field Default Value ---------------------- argc 0 argv NULL ---------------------- The 4margc24m and 4margv24m fields are used to initialize the standard property 4mWM_COMMAND24m. See the 4mInter-Client24m 4mCommunication0m 4mConventions24m 4mManual24m for more information. The default values for the SessionShell instance fields, which are filled in from the resource lists and by the ini- tialize procedure, are --------------------------------------------- Field Default Value --------------------------------------------- cancel_callbacks NULL clone_command See text connection NULL current_dir NULL die_callbacks NULL discard_command NULL environment NULL error_callbacks NULL interact_callbacks NULL join_session 4mTrue0m program_path See text resign_command NULL restart_command See text restart_style 4mSmRestartIfRunning0m save_callbacks NULL save_complete_callbacks NULL session_id NULL shutdown_command NULL --------------------------------------------- The 4mconnection24m field contains the session connection object or NULL if a session connection is not being managed by this widget. The 4msession_id24m is an identification assigned to the session participant by the session manager. The 4msession_id24m will be passed to the session manager as the client identifier of the previous session. When a connection is established with the session manager, the client id assigned by the session manager is stored in the 4msession_id24m field. When not NULL, the 4msession_id24m of the Session shell widget that is at the root of the widget tree of the client leader widget will be 1m1210m 1mX Toolkit Intrinsics X11 Release 6.40m used to create the 4mSM_CLIENT_ID24m property on the client leader's window. If 4mjoin_session24m is 4mFalse24m, the widget will not attempt to establish a connection to the session manager at shell cre- ation time. See Sections 4.2.1 and 4.2.4 for more informa- tion on the functionality of this resource. The 4mrestart_command24m, 4mclone_command24m, 4mdiscard_command24m, 4mresign_command24m, 4mshutdown_command24m, 4menvironment24m, 4mcurrent_dir24m, 4mprogram_path24m, and 4mrestart_style24m fields contain standard ses- sion properties. When a session connection is established or newly managed by the shell, the shell initialize and set_values methods check the values of the 4mrestart_command24m, 4mclone_command24m, and 4mpro-0m 4mgram_path24m resources. At that time, if 4mrestart_command24m is NULL, the value of the 4margv24m resource will be copied to 4mrestart_command24m. Whether or not 4mrestart_command24m was NULL, if "-xtsessionID" "" does not already appear in the 4mrestart_command24m, it will be added by the initialize and set_values methods at the beginning of the command argu- ments; if the "-xtsessionID" argument already appears with an incorrect session id in the following argument, that argument will be replaced with the current session id. After this, the shell initialize and set_values procedures check the 4mclone_command24m. If 4mclone_command24m is NULL, 4mrestart_command24m will be copied to 4mclone_command24m, except the "-xtsessionID" and following argument will not be copied. Finally, the shell initialize and set_values procedures check the 4mprogram_path24m. If 4mprogram_path24m is NULL, the first element of 4mrestart_command24m is copied to 4mprogram_path24m. The possible values of 4mrestart_style24m are 4mSmRestartIfRunning24m, 4mSmRestartAnyway24m, 4mSmRestartImmediately24m, and 4mSmRestartNever24m. A resource converter is registered for this resource; for the strings that it recognizes, see Section 9.6.1. The resource type EnvironmentArray is a NULL-terminated array of pointers to strings; each string has the format "name=value". The `=' character may not appear in the name, and the string is terminated by a null character. 1m4.2. Session Participation0m Applications can participate in a user's session, exchanging messages with the session manager as described in the 4mX24m 4mSes-0m 4msion24m 4mManagement24m 4mProtocol24m and the 4mX24m 4mSession24m 4mManagement0m 4mLibrary24m. 1m1220m 1mX Toolkit Intrinsics X11 Release 6.40m When a widget of 4msessionShellWidgetClass24m or a subclass is created, the widget provides support for the application as a session participant and continues to provide support until the widget is destroyed. 1m4.2.1. Joining a Session0m When a Session shell is created, if 4mconnection24m is NULL, and if 4mjoin_session24m is 4mTrue24m, and if 4margv24m or 4mrestart_command24m is not NULL, and if in POSIX environments the 4mSESSION_MANAGER0m environment variable is defined, the shell will attempt to establish a new connection with the session manager. To transfer management of an existing session connection from an application to the shell at widget creation time, pass the existing session connection ID as the 4mconnection0m resource value when creating the Session shell, and if the other creation-time conditions on session participation are met, the widget will maintain the connection with the ses- sion manager. The application must ensure that only one Session shell manages the connection. In the Session shell set_values procedure, if 4mjoin_session0m changes from 4mFalse24m to 4mTrue24m and 4mconnection24m is NULL and when in POSIX environments the 4mSESSION_MANAGER24m environment vari- able is defined, the shell will attempt to open a connection to the session manager. If 4mconnection24m changes from NULL to non-NULL, the Session shell will take over management of that session connection and will set 4mjoin_session24m to 4mTrue24m. If 4mjoin_session24m changes from 4mFalse24m to 4mTrue24m and 4mconnection24m is not NULL, the Session shell will take over management of the session connection. When a successful connection has been established, 4mconnec-0m 4mtion24m contains the session connection ID for the session par- ticipant. When the shell begins to manage the connection, it will call 4mXtAppAddInput24m to register the handler which watches for protocol messages from the session manager. When the attempt to connect fails, a warning message is issued and 4mconnection24m is set to NULL. While the connection is being managed, if a 4mSaveYourself24m, 4mSaveYourselfPhase224m, 4mInteract24m, 4mShutdownCancelled24m, 4mSaveCom-0m 4mplete24m, or 4mDie24m message is received from the session manager, the Session shell will call out to application callback pro- cedures registered on the respective callback list of the Session shell and will send 4mSaveYourselfPhase2Request24m, 4mInteractRequest24m, 4mInteractDone24m, 4mSaveYourselfDone24m, and 4mConnec-0m 4mtionClosed24m messages as appropriate. Initially, all of the client's session properties are undefined. When any of the session property resource values are defined or change, the Session shell initialize and set_values procedures will update the client's session property value by a 1m1230m 1mX Toolkit Intrinsics X11 Release 6.40m 4mSetProperties24m or a 4mDeleteProperties24m message, as appropriate. The session ProcessID and UserID properties are always set by the shell when it is possible to determine the value of these properties. 1m4.2.2. Saving Application State0m The session manager instigates an application checkpoint by sending a 4mSaveYourself24m request. Applications are responsi- ble for saving their state in response to the request. When the 4mSaveYourself24m request arrives, the procedures regis- tered on the Session shell's save callback list are called. If the application does not register any save callback pro- cedures on the save callback list, the shell will report to the session manager that the application failed to save its state. Each procedure on the save callback list receives a token in the 4mcall_data24m parameter. The checkpoint token in the 4mcall_data24m parameter is of type 4mXtCheckpointToken24m. __ | typedef struct { int save_type; int interact_style; Boolean shutdown; Boolean fast; Boolean cancel_shutdown int phase; int interact_dialog_type;/* return */ Boolean request_cancel; /* return */ Boolean request_next_phase; /* return */ Boolean save_success; /* return */ } XtCheckpointTokenRec, *XtCheckpointToken; |__ The 4msave_type24m, 4minteract_style24m, 4mshutdown24m, and 4mfast24m fields of the token contain the parameters of the 4mSaveYourself24m mes- sage. The possible values of 4msave_type24m are 4mSmSaveLocal24m, 4mSmSaveGlobal24m, and 4mSmSaveBoth24m; these indicate the type of information to be saved. The possible values of 4minter-0m 4mact_style24m are 4mSmInteractStyleNone24m, 4mSmInteractStyleErrors24m, and 4mSmInteractStyleAny24m; these indicate whether user interac- tion would be permitted and, if so, what kind of interac- tion. If 4mshutdown24m is 4mTrue24m, the checkpoint is being per- formed in preparation for the end of the session. If 4mfast0m is 4mTrue24m, the client should perform the checkpoint as quickly as possible. If 4mcancel_shutdown24m is 4mTrue24m, a 4mShutdownCan-0m 4mcelled24m message has been received for the current save 1m1240m 1mX Toolkit Intrinsics X11 Release 6.40m operation. (See Section 4.4.4.) The 4mphase24m is used by man- ager clients, such as a window manager, to distinguish between the first and second phase of a save operation. The 4mphase24m will be either 1 or 2. The remaining fields in the checkpoint token structure are provided for the application to communicate with the shell. Upon entry to the first application save callback procedure, the return fields in the token have the following initial values: 4minteract_dialog_type24m is 4mSmDialogNormal24m; 4mrequest_can-0m 4mcel24m is 4mFalse24m; 4mrequest_next_phase24m is 4mFalse24m; and 4msave_success0m is 4mTrue24m. When a token is returned with any of the four return fields containing a noninitial value, and when the field is applicable, subsequent tokens passed to the appli- cation during the current save operation will always contain the noninitial value. The purpose of the token's 4msave_success24m field is to indicate the outcome of the entire operation to the session manager and ultimately, to the user. Returning 4mFalse24m indicates some portion of the application state could not be successfully saved. If any token is returned to the shell with 4msave_suc-0m 4mcess24m 4mFalse24m, tokens subsequently received by the application for the current save operation will show 4msave_success24m as 4mFalse24m. When the shell sends the final status of the check- point to the session manager, it will indicate failure to save application state if any token was returned with 4msave_success24m 4mFalse24m. Session participants that manage and save the state of other clients should structure their save or interact callbacks to set 4mrequest_next_phase24m to 4mTrue24m when phase is 1, which will cause the shell to send the 4mSaveYourselfPhase2Request24m when the first phase is complete. When the 4mSaveYourselfPhase20m message is received, the shell will invoke the save call- backs a second time with 4mphase24m equal to 2. Manager clients should save the state of other clients when the callbacks are invoked the second time and 4mphase24m equal to 2. The application may request additional tokens while a check- point is under way, and these additional tokens must be returned by an explicit call. 1m1250m 1mX Toolkit Intrinsics X11 Release 6.40m To request an additional token for a save callback response that has a deferred outcome, use 4mXtSessionGetToken24m. __ | XtCheckpointToken XtSessionGetToken(4mwidget24m) Widget 4mwidget24m; 4mwidget24m Specifies the Session shell widget which manages session participation. |__ The 4mXtSessionGetToken24m function will return NULL if no check- point operation is currently under way. To indicate the completion of checkpoint processing includ- ing user interaction, the application must signal the Ses- sion shell by returning all tokens. (See Sections 4.2.2.2 and 4.2.2.4). To return a token, use 4mXtSessionReturnToken24m. __ | void XtSessionReturnToken(4mtoken24m) XtCheckpointToken 4mtoken24m; 4mtoken24m Specifies a token that was received as the 4mcall_data24m by a procedure on the interact callback list or a token that was received by a call to 4mXtSessionGetToken24m. |__ Tokens passed as 4mcall_data24m to save callbacks are implicitly returned when the save callback procedure returns. A save callback procedure should not call 4mXtSessionReturnToken24m on the token passed in its 4mcall_data24m. 1m4.2.2.1. Requesting Interaction0m When the token 4minteract_style24m allows user interaction, the application may interact with the user during the check- point, but must wait for permission to interact. Applica- tions request permission to interact with the user during the checkpointing operation by registering a procedure on the Session shell's interact callback list. When all save callback procedures have returned, and each time a token that was granted by a call to 4mXtSessionGetToken24m is returned, the Session shell examines the interact callback list. If interaction is permitted and the interact callback list is not empty, the shell will send an 4mInteractRequest24m to the 1m1260m 1mX Toolkit Intrinsics X11 Release 6.40m session manager when an interact request is not already out- standing for the application. The type of interaction dialog that will be requested is specified by the 4minteract_dialog_type24m field in the check- point token. The possible values for 4minteract_dialog_type0m are 4mSmDialogError24m and 4mSmDialogNormal24m. If a token is returned with 4minteract_dialog_type24m containing 4mSmDialogError24m, the interact request and any subsequent interact requests will be for an error dialog; otherwise, the request will be for a normal dialog with the user. When a token is returned with 4msave_success24m 4mFalse24m or 4minter-0m 4mact_dialog_type24m 4mSmDialogError24m, tokens subsequently passed to callbacks during the same active 4mSaveYourself24m response will reflect these changed values, indicating that an error con- dition has occurred during the checkpoint. The 4mrequest_cancel24m field is a return value for interact callbacks only. Upon return from a procedure on the save callback list, the value of the token's 4mrequest_cancel24m field is not examined by the shell. This is also true of tokens received through a call to 4mXtSessionGetToken24m. 1m4.2.2.2. Interacting with the User during a Checkpoint0m When the session manager grants the application's request for user interaction, the Session shell receives an 4mInteract0m message. The procedures registered on the interact callback list are executed, but not as if executing a typical call- back list. These procedures are individually executed in sequence, with a checkpoint token functioning as the sequencing mechanism. Each step in the sequence begins by removing a procedure from the interact callback list and executing it with a token passed in the 4mcall_data24m. The interact callback will typically pop up a dialog box and return. When the user interaction and associated applica- tion checkpointing has completed, the application must return the token by calling 4mXtSessionReturnToken24m. Returning the token completes the current step and triggers the next step in the sequence. During interaction the client may request cancellation of a shutdown. When a token passed as 4mcall_data24m to an interact procedure is returned, if 4mshutdown24m is 4mTrue24m and 4mcancel_shut-0m 4mdown24m is 4mFalse24m, 4mrequest_cancel24m indicates whether the applica- tion requests that the pending shutdown be cancelled. If 4mrequest_cancel24m is 4mTrue24m, the field will also be 4mTrue24m in any tokens subsequently granted during the checkpoint operation. When a token is returned requesting cancellation of the ses- sion shutdown, pending interact procedures will still be called by the Session shell. When all interact procedures have been removed from the interact callback list, executed, 1m1270m 1mX Toolkit Intrinsics X11 Release 6.40m and the final interact token returned to the shell, an 4mInteractDone24m message is sent to the session manager, indi- cating whether a pending session shutdown is requested to be cancelled. 1m4.2.2.3. Responding to a Shutdown Cancellation0m Callbacks registered on the cancel callback list are invoked when the Session shell processes a 4mShutdownCancelled24m message from the session manager. This may occur during the pro- cessing of save callbacks, while waiting for interact per- mission, during user interaction, or after the save opera- tion is complete and the application is expecting a 4mSaveCom-0m 4mplete24m or a 4mDie24m message. The 4mcall_data24m for these callbacks is NULL. When the shell notices that a pending shutdown has been can- celled, the token 4mcancel_shutdown24m field will be 4mTrue24m in tokens subsequently given to the application. Receiving notice of a shutdown cancellation does not cancel the pending execution of save callbacks or interact call- backs. After the cancel callbacks execute, if 4minter-0m 4mact_style24m is not 4mSmInteractStyleNone24m and the interact list is not empty, the procedures on the interact callback list will be executed and passed a token with 4minteract_style0m 4mSmInteractStyleNone24m. The application should not interact with the user, and the Session shell will not send an 4mInter-0m 4mactDone24m message. 1m4.2.2.4. Completing a Save0m When there is no user interaction, the shell regards the application as having finished saving state when all call- back procedures on the save callback list have returned, and any additional tokens passed out by 4mXtSessionGetToken24m have been returned by corresponding calls to 4mXtSessionReturnTo-0m 4mken24m. If the save operation involved user interaction, the above completion conditions apply, and in addition, all requests for interaction have been granted or cancelled, and all tokens passed to interact callbacks have been returned through calls to 4mXtSessionReturnToken24m. If the save opera- tion involved a manager client that requested the second phase, the above conditions apply to both the first and sec- ond phase of the save operation. When the application has finished saving state, the Session shell will report the result to the session manager by send- ing the 4mSaveYourselfDone24m message. If the session is contin- uing, the shell will receive the 4mSaveComplete24m message when all applications have completed saving state. This message indicates that applications may again allow changes to their 1m1280m 1mX Toolkit Intrinsics X11 Release 6.40m state. The shell will execute the save_complete callbacks. The 4mcall_data24m for these callbacks is NULL. 1m4.2.3. Responding to a Shutdown0m Callbacks registered on the die callback list are invoked when the session manager sends a 4mDie24m message. The callbacks on this list should do whatever is appropriate to quit the application. Before executing procedures on the die call- back list, the Session shell will close the connection to the session manager and will remove the handler that watches for protocol messages. The 4mcall_data24m for these callbacks is NULL. 1m4.2.4. Resigning from a Session0m When the Session shell widget is destroyed, the destroy method will close the connection to the session manager by sending a 4mConnectionClosed24m protocol message and will remove the input callback that was watching for session protocol messages. When 4mXtSetValues24m is used to set 4mjoin_session24m to 4mFalse24m, the set_values method of the Session shell will close the con- nection to the session manager if one exists by sending a 4mConnectionClosed24m message, and 4mconnection24m will be set to NULL. Applications that exit in response to user actions and that do not wait for phase 2 destroy to complete on the Session shell should set 4mjoin_session24m to 4mFalse24m before exiting. When 4mXtSetValues24m is used to set 4mconnection24m to NULL, the Ses- sion shell will stop managing the connection, if one exists. However, that session connection will not be closed. Applications that wish to ensure continuation of a session connection beyond the destruction of the shell should first retrieve the 4mconnection24m resource value, then set the 4mconnec-0m 4mtion24m resource to NULL, and then they may safely destroy the widget without losing control of the session connection. The error callback list will be called if an unrecoverable communications error occurs while the shell is managing the connection. The shell will close the connection, set 4mcon-0m 4mnection24m to NULL, remove the input callback, and call the procedures registered on the error callback list. The 4mcall_data24m for these callbacks is NULL. 1m1290m 1mX Toolkit Intrinsics X11 Release 6.40m 1mChapter 50m 1mPop-Up Widgets0m Pop-up widgets are used to create windows outside of the window hierarchy defined by the widget tree. Each pop-up child has a window that is a descendant of the root window, so that the pop-up window is not clipped by the pop-up wid- get's parent window. Therefore, pop-ups are created and attached differently to their widget parent than normal wid- get children. A parent of a pop-up widget does not actively manage its pop-up children; in fact, it usually does not operate upon them in any way. The 4mpopup_list24m field in the 4mCorePart0m structure contains the list of its pop-up children. This pop-up list exists mainly to provide the proper place in the widget hierarchy for the pop-up to get resources and to pro- vide a place for 4mXtDestroyWidget24m to look for all extant children. A composite widget can have both normal and pop-up children. A pop-up can be popped up from almost anywhere, not just by its parent. The term 4mchild24m always refers to a normal, geom- etry-managed widget on the composite widget's list of chil- dren, and the term 4mpop-up24m 4mchild24m always refers to a widget on the pop-up list. 1m5.1. Pop-Up Widget Types0m There are three kinds of pop-up widgets: · Modeless pop-ups A modeless pop-up (for example, a dialog box that does not prevent continued interaction with the rest of the application) can usually be manipulated by the window manager and looks like any other application window from the user's point of view. The application main window itself is a special case of a modeless pop-up. · Modal pop-ups A modal pop-up (for example, a dialog box that requires user input to continue) can sometimes be manipulated by the window manager, and except for events that occur in the dialog box, it disables user-event distribution to the rest of the application. 1m1300m 1mX Toolkit Intrinsics X11 Release 6.40m · Spring-loaded pop-ups A spring-loaded pop-up (for example, a menu) can seldom be manipulated by the window manager, and except for events that occur in the pop-up or its descendants, it disables user-event distribution to all other applica- tions. Modal pop-ups and spring-loaded pop-ups are very similar and should be coded as if they were the same. In fact, the same widget (for example, a ButtonBox or Menu widget) can be used both as a modal pop-up and as a spring-loaded pop-up within the same application. The main difference is that spring- loaded pop-ups are brought up with the pointer and, because of the grab that the pointer button causes, require differ- ent processing by the Intrinsics. Furthermore, all user input remap events occurring outside the spring-loaded pop- up (e.g., in a descendant) are also delivered to the spring- loaded pop-up after they have been dispatched to the appro- priate descendant, so that, for example, button-up can take down a spring-loaded pop-up no matter where the button-up occurs. Any kind of pop-up, in turn, can pop up other widgets. Modal and spring-loaded pop-ups can constrain user events to the most recent such pop-up or allow user events to be dis- patched to any of the modal or spring-loaded pop-ups cur- rently mapped. Regardless of their type, all pop-up widget classes are responsible for communicating with the X window manager and therefore are subclasses of one of the Shell widget classes. 1m5.2. Creating a Pop-Up Shell0m For a widget to be popped up, it must be the child of a pop- up shell widget. None of the Intrinsics-supplied shells will simultaneously manage more than one child. Both the shell and child taken together are referred to as the pop- up. When you need to use a pop-up, you always refer to the pop-up by the pop-up shell, not the child. To create a pop-up shell, use 4mXtCreatePopupShell24m. 1m1310m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtCreatePopupShell(4mname24m, 4mwidget_class24m, 4mparent24m, 4margs24m, 4mnum_args24m) String 4mname24m; WidgetClass 4mwidget_class24m; Widget 4mparent24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mname24m Specifies the instance name for the created shell widget. 4mwidget_class0m Specifies the widget class pointer for the created shell widget. 4mparent24m Specifies the parent widget. Must be of class Core or any subclass thereof. 4margs24m Specifies the argument list to override any other resource specifications. 4mnum_args24m Specifies the number of entries in the argument list. |__ The 4mXtCreatePopupShell24m function ensures that the specified class is a subclass of Shell and, rather than using insert_child to attach the widget to the parent's 4mchildren0m list, attaches the shell to the parent's 4mpopup_list0m directly. The screen resource for this widget is determined by first scanning 4margs24m for the XtNscreen argument. If no XtNscreen argument is found, the resource database associated with the parent's screen is queried for the resource 4mname24m.screen, class 4mClass24m.Screen where 4mClass24m is the 4mclass_name24m field from the 4mCoreClassPart24m of the specified 4mwidget_class24m. If this query fails, the parent's screen is used. Once the screen is determined, the resource database associated with that screen is used to retrieve all remaining resources for the widget not specified in 4margs24m. A spring-loaded pop-up invoked from a translation table via 4mXtMenuPopup24m must already exist at the time that the transla- tion is invoked, so the translation manager can find the shell by name. Pop-ups invoked in other ways can be created when the pop-up actually is needed. This delayed creation of the shell is particularly useful when you pop up an unspecified number of pop-ups. You can look to see if an appropriate unused shell (that is, not currently popped up) exists and create a new shell if needed. 1m1320m 1mX Toolkit Intrinsics X11 Release 6.40m To create a pop-up shell using varargs lists, use 4mXtVaCre-0m 4matePopupShell24m. __ | Widget XtVaCreatePopupShell(4mname24m, 4mwidget_class24m, 4mparent24m, ...) String 4mname24m; WidgetClass 4mwidget_class24m; Widget 4mparent24m; 4mname24m Specifies the instance name for the created shell widget. 4mwidget_class0m Specifies the widget class pointer for the created shell widget. 4mparent24m Specifies the parent widget. Must be of class Core or any subclass thereof. ... Specifies the variable argument list to override any other resource specifications. |__ 4mXtVaCreatePopupShell24m is identical in function to 4mXtCre-0m 4matePopupShell24m with 4mthe24m args and 4mnum_args24m parameters replaced by a varargs list as described in Section 2.5.1. 1m5.3. Creating Pop-Up Children0m Once a pop-up shell is created, the single child of the pop- up shell can be created either statically or dynamically. At startup, an application can create the child of the pop- up shell, which is appropriate for pop-up children composed of a fixed set of widgets. The application can change the state of the subparts of the pop-up child as the application state changes. For example, if an application creates a static menu, it can call 4mXtSetSensitive24m (or, in general, 4mXtSetValues24m) on any of the buttons that make up the menu. Creating the pop-up child early means that pop-up time is minimized, especially if the application calls 4mXtRealizeWid-0m 4mget24m on the pop-up shell at startup. When the menu is needed, all the widgets that make up the menu already exist and need only be mapped. The menu should pop up as quickly as the X server can respond. Alternatively, an application can postpone the creation of the child until it is needed, which minimizes application startup time and allows the pop-up child to reconfigure itself each time it is popped up. In this case, the pop-up child creation routine might poll the application to find 1m1330m 1mX Toolkit Intrinsics X11 Release 6.40m out if it should change the sensitivity of any of its sub- parts. Pop-up child creation does not map the pop-up, even if you create the child and call 4mXtRealizeWidget24m on the pop-up shell. All shells have pop-up and pop-down callbacks, which provide the opportunity either to make last-minute changes to a pop- up child before it is popped up or to change it after it is popped down. Note that excessive use of pop-up callbacks can make popping up occur more slowly. 1m5.4. Mapping a Pop-Up Widget0m Pop-ups can be popped up through several mechanisms: · A call to 4mXtPopup24m or 4mXtPopupSpringLoaded24m. · One of the supplied callback procedures 4mXtCallbackNone24m, 4mXtCallbackNonexclusive24m, or 4mXtCallbackExclusive24m. · The standard translation action 4mXtMenuPopup24m. Some of these routines take an argument of type 4mXtGrabKind24m, which is defined as __ | typedef enum {XtGrabNone, XtGrabNonexclusive, XtGrabExclusive} XtGrabKind; |__ The create_popup_child_proc procedure pointer in the shell widget instance record is of type 4mXtCreatePopupChildProc24m. __ | typedef void (*XtCreatePopupChildProc)(Widget); Widget 4mw24m; 4mw24m Specifies the shell widget being popped up. |__ To map a pop-up from within an application, use 4mXtPopup24m. 1m1340m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtPopup(4mpopup_shell24m, 4mgrab_kind24m) Widget 4mpopup_shell24m; XtGrabKind 4mgrab_kind24m; 4mpopup_shell0m Specifies the shell widget. 4mgrab_kind24m Specifies the way in which user events should be constrained. |__ The 4mXtPopup24m function performs the following: · Calls 4mXtCheckSubclass24m to ensure 4mpopup_shell24m's class is a subclass of 4mshellWidgetClass24m. · Raises the window and returns if the shell's 4mpopped_up0m field is already 4mTrue24m. · Calls the callback procedures on the shell's 4mpopup_callback24m list, specifying a pointer to the value of 4mgrab_kind24m as the 4mcall_data24m argument. · Sets the shell 4mpopped_up24m field to 4mTrue24m, the shell 4mspring_loaded24m field to 4mFalse24m, and the shell 4mgrab_kind0m field from 4mgrab_kind24m. · If the shell's 4mcreate_popup_child_proc24m field is non- NULL, 4mXtPopup24m calls it with 4mpopup_shell24m as the parame- ter. · If 4mgrab_kind24m is either 4mXtGrabNonexclusive24m or 4mXtGrabEx-0m 4mclusive24m, it calls XtAddGrab(4mpopup_shell24m, (4mgrab_kind24m == XtGrabExclusive), False) · Calls 4mXtRealizeWidget24m with 4mpopup_shell24m specified. · Calls 4mXMapRaised24m with the window of 4mpopup_shell24m. To map a spring-loaded pop-up from within an application, use 4mXtPopupSpringLoaded24m. 1m1350m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtPopupSpringLoaded(4mpopup_shell24m) Widget 4mpopup_shell24m; 4mpopup_shell0m Specifies the shell widget to be popped up. |__ The 4mXtPopupSpringLoaded24m function performs exactly as 4mXtPopup0m except that it sets the shell 4mspring_loaded24m field to 4mTrue0m and always calls 4mXtAddGrab24m with 4mexclusive24m 4mTrue24m and 4mspring-0m 4mloaded24m 4mTrue24m. To map a pop-up from a given widget's callback list, you also can register one of the 4mXtCallbackNone24m, 4mXtCallbac-0m 4mkNonexclusive24m, or 4mXtCallbackExclusive24m convenience routines as callbacks, using the pop-up shell widget as the client data. 1m1360m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtCallbackNone(4mw24m, 4mclient_data24m, 4mcall_data24m) Widget 4mw24m; XtPointer 4mclient_data24m; XtPointer 4mcall_data24m; 4mw24m Specifies the widget. 4mclient_data0m Specifies the pop-up shell. 4mcall_data24m Specifies the callback data argument, which is not used by this procedure. void XtCallbackNonexclusive(4mw24m, 4mclient_data24m, 4mcall_data24m) Widget 4mw24m; XtPointer 4mclient_data24m; XtPointer 4mcall_data24m; 4mw24m Specifies the widget. 4mclient_data0m Specifies the pop-up shell. 4mcall_data24m Specifies the callback data argument, which is not used by this procedure. void XtCallbackExclusive(4mw24m, 4mclient_data24m, 4mcall_data24m) Widget 4mw24m; XtPointer 4mclient_data24m; XtPointer 4mcall_data24m; 4mw24m Specifies the widget. 4mclient_data0m Specifies the pop-up shell. 4mcall_data24m Specifies the callback data argument, which is not used by this procedure. |__ The 4mXtCallbackNone24m, 4mXtCallbackNonexclusive24m, and 4mXtCallback-0m 4mExclusive24m functions call 4mXtPopup24m with the shell specified by the 4mclient_data24m argument and 4mgrab_kind24m set as the name spec- ifies. 4mXtCallbackNone24m, 4mXtCallbackNonexclusive24m, and 4mXtCall-0m 4mbackExclusive24m specify 4mXtGrabNone24m, 4mXtGrabNonexclusive24m, and 4mXtGrabExclusive24m, respectively. Each function then sets the 1m1370m 1mX Toolkit Intrinsics X11 Release 6.40m widget that executed the callback list to be insensitive by calling 4mXtSetSensitive24m. Using these functions in callbacks is not required. In particular, an application must provide customized code for callbacks that create pop-up shells dynamically or that must do more than desensitizing the but- ton. Within a translation table, to pop up a menu when a key or pointer button is pressed or when the pointer is moved into a widget, use 4mXtMenuPopup24m, or its synonym, 4mMenuPopup24m. From a translation writer's point of view, the definition for this translation action is __ | void XtMenuPopup(4mshell_name24m) String 4mshell_name24m; 4mshell_name0m Specifies the name of the shell widget to pop up. |__ 4mXtMenuPopup24m is known to the translation manager, which reg- isters the corresponding built-in action procedure 4mXtMenuPopupAction24m using 4mXtRegisterGrabAction24m specifying 4mowner_events24m 4mTrue24m, 4mevent_mask24m 4mButtonPressMask24m 1m| 4m22mButtonRe-0m 4mleaseMask24m, and 4mpointer_mode24m and 4mkeyboard_mode24m 4mGrabModeAsync24m. If 4mXtMenuPopup24m is invoked on 4mButtonPress24m, it calls 4mXtPopup-0m 4mSpringLoaded24m on the specified shell widget. If 4mXtMenuPopup0m is invoked on 4mKeyPress24m or 4mEnterWindow24m, it calls 4mXtPopup24m on the specified shell widget with 4mgrab_kind24m set to 4mXtGrab-0m 4mNonexclusive24m. Otherwise, the translation manager generates a warning message and ignores the action. 4mXtMenuPopup24m tries to find the shell by searching the widget tree starting at the widget in which it is invoked. If it finds a shell with the specified name in the pop-up children of that widget, it pops up the shell with the appropriate parameters. Otherwise, it moves up the parent chain to find a pop-up child with the specified name. If 4mXtMenuPopup24m gets to the application top-level shell widget and has not found a matching shell, it generates a warning and returns immedi- ately. 1m5.5. Unmapping a Pop-Up Widget0m Pop-ups can be popped down through several mechanisms: · A call to 4mXtPopdown0m 1m1380m 1mX Toolkit Intrinsics X11 Release 6.40m · The supplied callback procedure 4mXtCallbackPopdown0m · The standard translation action 4mXtMenuPopdown0m To unmap a pop-up from within an application, use 4mXtPopdown24m. __ | void XtPopdown(4mpopup_shell24m) Widget 4mpopup_shell24m; 4mpopup_shell0m Specifies the shell widget to pop down. |__ The 4mXtPopdown24m function performs the following: · Calls 4mXtCheckSubclass24m to ensure 4mpopup_shell24m's class is a subclass of 4mshellWidgetClass24m. · Checks that the 4mpopped_up24m field of 4mpopup_shell24m is 4mTrue24m; otherwise, it returns immediately. · Unmaps 4mpopup_shell24m's window and, if 4moverride_redirect0m is 4mFalse24m, sends a synthetic 4mUnmapNotify24m event as speci- fied by the 4mInter-Client24m 4mCommunication24m 4mConventions24m 4mMan-0m 4mual24m. · If 4mpopup_shell24m's 4mgrab_kind24m is either 4mXtGrabNonexclusive0m or 4mXtGrabExclusive24m, it calls 4mXtRemoveGrab24m. · Sets 4mpopup_shell24m's 4mpopped_up24m field to 4mFalse24m. · Calls the callback procedures on the shell's 4mpop-0m 4mdown_callback24m list, specifying a pointer to the value of the shell's 4mgrab_kind24m field as the 4mcall_data24m argu- ment. To pop down a pop-up from a callback list, you may use the callback 4mXtCallbackPopdown24m. 1m1390m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtCallbackPopdown(4mw24m, 4mclient_data24m, 4mcall_data24m) Widget 4mw24m; XtPointer 4mclient_data24m; XtPointer 4mcall_data24m; 4mw24m Specifies the widget. 4mclient_data0m Specifies a pointer to the 4mXtPopdownID24m structure. 4mcall_data24m Specifies the callback data argument, which is not used by this procedure. |__ The 4mXtCallbackPopdown24m function casts the 4mclient_data24m parame- ter to a pointer of type 4mXtPopdownID24m. __ | typedef struct { Widget shell_widget; Widget enable_widget; } XtPopdownIDRec, *XtPopdownID; |__ The 4mshell_widget24m is the pop-up shell to pop down, and the 4menable_widget24m is usually the widget that was used to pop it up in one of the pop-up callback convenience procedures. 4mXtCallbackPopdown24m calls 4mXtPopdown24m with the specified 4mshell_widget24m and then calls 4mXtSetSensitive24m to resensitize 4menable_widget24m. Within a translation table, to pop down a spring-loaded menu when a key or pointer button is released or when the pointer is moved into a widget, use 4mXtMenuPopdown24m or its synonym, 4mMenuPopdown24m. From a translation writer's point of view, the definition for this translation action is 1m1400m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtMenuPopdown(4mshell_name24m) String 4mshell_name24m; 4mshell_name0m Specifies the name of the shell widget to pop down. |__ If a shell name is not given, 4mXtMenuPopdown24m calls 4mXtPopdown0m with the widget for which the translation is specified. If 4mshell_name24m is specified in the translation table, 4mXtMenuPop-0m 4mdown24m tries to find the shell by looking up the widget tree starting at the widget in which it is invoked. If it finds a shell with the specified name in the pop-up children of that widget, it pops down the shell; otherwise, it moves up the parent chain to find a pop-up child with the specified name. If 4mXtMenuPopdown24m gets to the application top-level shell widget and cannot find a matching shell, it generates a warning and returns immediately. 1m1410m 1mX Toolkit Intrinsics X11 Release 6.40m 1mChapter 60m 1mGeometry Management0m A widget does not directly control its size and location; rather, its parent is responsible for controlling them. Although the position of children is usually left up to their parent, the widgets themselves often have the best idea of their optimal sizes and, possibly, preferred loca- tions. To resolve physical layout conflicts between sibling widgets and between a widget and its parent, the Intrinsics provide the geometry management mechanism. Almost all composite widgets have a geometry manager specified in the 4mgeome-0m 4mtry_manager24m field in the widget class record that is respon- sible for the size, position, and stacking order of the wid- get's children. The only exception is fixed boxes, which create their children themselves and can ensure that their children will never make a geometry request. 1m6.1. Initiating Geometry Changes0m Parents, children, and clients each initiate geometry changes differently. Because a parent has absolute control of its children's geometry, it changes the geometry directly by calling 4mXtMoveWidget24m, 4mXtResizeWidget24m, or 4mXtConfigureWid-0m 4mget24m. A child must ask its parent for a geometry change by calling 4mXtMakeGeometryRequest24m or 4mXtMakeResizeRequest24m. An application or other client code initiates a geometry change by calling 4mXtSetValues24m on the appropriate geometry fields, thereby giving the widget the opportunity to modify or reject the client request before it gets propagated to the parent and the opportunity to respond appropriately to the parent's reply. When a widget that needs to change its size, position, bor- der width, or stacking depth asks its parent's geometry man- ager to make the desired changes, the geometry manager can allow the request, disallow the request, or suggest a com- promise. When the geometry manager is asked to change the geometry of a child, the geometry manager may also rearrange and resize any or all of the other children that it controls. The geometry manager can move children around freely using 4mXtMoveWidget24m. When it resizes a child (that is, changes the width, height, or border width) other than the one making 1m1420m 1mX Toolkit Intrinsics X11 Release 6.40m the request, it should do so by calling 4mXtResizeWidget24m. The requesting child may be given special treatment; see Section 6.5. It can simultaneously move and resize a child with a single call to 4mXtConfigureWidget24m. Often, geometry managers find that they can satisfy a request only if they can reconfigure a widget that they are not in control of; in particular, the composite widget may want to change its own size. In this case, the geometry manager makes a request to its parent's geometry manager. Geometry requests can cascade this way to arbitrary depth. Because such cascaded arbitration of widget geometry can involve extended negotiation, windows are not actually allo- cated to widgets at application startup until all widgets are satisfied with their geometry; see Sections 2.5 and 2.6. Notes 1. The Intrinsics treatment of stacking requests is deficient in several areas. Stacking requests for unrealized widgets are granted but will have no effect. In addition, there is no way to do an 4mXtSetValues24m that will gen- erate a stacking geometry request. 2. After a successful geometry request (one that returned 4mXtGeometryYes24m), a widget does not know whether its resize procedure has been called. Widgets should have resize proce- dures that can be called more than once with- out ill effects. 1m6.2. General Geometry Manager Requests0m When making a geometry request, the child specifies an 4mXtWidgetGeometry24m structure. 1m1430m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef unsigned long XtGeometryMask; typedef struct { XtGeometryMask request_mode; Position x, y; Dimension width, height; Dimension border_width; Widget sibling; int stack_mode; } XtWidgetGeometry; |__ To make a general geometry manager request from a widget, use 4mXtMakeGeometryRequest24m. __ | XtGeometryResult XtMakeGeometryRequest(4mw24m, 4mrequest24m, 4mreply_return24m) Widget 4mw24m; XtWidgetGeometry *4mrequest24m; XtWidgetGeometry *4mreply_return24m; 4mw24m Specifies the widget making the request. Must be of class RectObj or any subclass thereof. 4mrequest24m Specifies the desired widget geometry (size, posi- tion, border width, and stacking order). 4mreply_return0m Returns the allowed widget size, or may be NULL if the requesting widget is not interested in han- dling 4mXtGeometryAlmost24m. |__ Depending on the condition, 4mXtMakeGeometryRequest24m performs the following: · If the widget is unmanaged or the widget's parent is not realized, it makes the changes and returns 4mXtGeome-0m 4mtryYes24m. · If the parent's class is not a subclass of 4mcompos-0m 4miteWidgetClass24m or the parent's 4mgeometry_manager24m field is NULL, it issues an error. · If the widget's 4mbeing_destroyed24m field is 4mTrue24m, it returns 4mXtGeometryNo24m. · If the widget 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, and 4mborder_width0m fields are all equal to the requested values, it returns 4mXtGeometryYes24m; otherwise, it calls the parent's 1m1440m 1mX Toolkit Intrinsics X11 Release 6.40m geometry_manager procedure with the given parameters. · If the parent's geometry manager returns 4mXtGeometryYes0m and if 4mXtCWQueryOnly24m is not set in 4mrequest->request_mode24m and if the widget is realized, 4mXtMakeGeometryRequest24m calls the 4mXConfigureWindow24m Xlib function to reconfigure the widget's window (set its size, location, and stacking order as appropriate). · If the geometry manager returns 4mXtGeometryDone24m, the change has been approved and actually has been done. In this case, 4mXtMakeGeometryRequest24m does no configuring and returns 4mXtGeometryYes24m. 4mXtMakeGeometryRequest24m never returns 4mXtGeometryDone24m. · Otherwise, 4mXtMakeGeometryRequest24m just returns the resulting value from the parent's geometry manager. Children of primitive widgets are always unmanaged; there- fore, 4mXtMakeGeometryRequest24m always returns 4mXtGeometryYes0m when called by a child of a primitive widget. The return codes from geometry managers are __ | typedef enum { XtGeometryYes, XtGeometryNo, XtGeometryAlmost, XtGeometryDone } XtGeometryResult; |__ The 4mrequest_mode24m definitions are from <4mX11/X.h24m>. __ | #define 4mCWX24m (1<<0) #define 4mCWY24m (1<<1) #define 4mCWWidth24m (1<<2) #define 4mCWHeight24m (1<<3) #define 4mCWBorderWidth24m (1<<4) #define 4mCWSibling24m (1<<5) #define 4mCWStackMode24m (1<<6) |__ The Intrinsics also support the following value. 1m1450m 1mX Toolkit Intrinsics X11 Release 6.40m __ | #define 4mXtCWQueryOnly24m (1<<7) |__ 4mXtCWQueryOnly24m indicates that the corresponding geometry request is only a query as to what would happen if this geometry request were made and that no widgets should actu- ally be changed. 4mXtMakeGeometryRequest24m, like the 4mXConfigureWindow24m Xlib func- tion, uses 4mrequest_mode24m to determine which fields in the 4mXtWidgetGeometry24m structure the caller wants to specify. The 4mstack_mode24m definitions are from <4mX11/X.h24m>: __ | #define 4mAbove24m 0 #define 4mBelow24m 1 #define 4mTopIf24m 2 #define 4mBottomIf24m 3 #define 4mOpposite24m 4 |__ The Intrinsics also support the following value. __ | #define 4mXtSMDontChange24m 5 |__ For definition and behavior of 4mAbove24m, 4mBelow24m, 4mTopIf24m, 4mBot-0m 4mtomIf24m, and 4mOpposite24m, see Section 3.7 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX0m 4mInterface24m. 4mXtSMDontChange24m indicates that the widget wants its current stacking order preserved. 1m6.3. Resize Requests0m To make a simple resize request from a widget, you can use 4mXtMakeResizeRequest24m as an alternative to 4mXtMakeGeometry-0m 4mRequest24m. 1m1460m 1mX Toolkit Intrinsics X11 Release 6.40m __ | XtGeometryResult XtMakeResizeRequest(4mw24m, 4mwidth24m, 4mheight24m, 4mwidth_return24m, 4mheight_return24m) Widget 4mw24m; Dimension 4mwidth24m, 4mheight24m; Dimension *4mwidth_return24m, *4mheight_return24m; 4mw24m Specifies the widget making the request. Must be of class RectObj or any subclass thereof. 4mwidth24m Specify the desired widget width and height. 4mheight0m 4mwidth_return0m Return the allowed widget width and height. 4mheight_return0m |__ The 4mXtMakeResizeRequest24m function, a simple interface to 4mXtMakeGeometryRequest24m, creates an 4mXtWidgetGeometry24m structure and specifies that width and height should change by setting 4mrequest_mode24m to 4mCWWidth24m 1m| 4m22mCWHeight24m. The geometry manager is free to modify any of the other window attributes (position or stacking order) to satisfy the resize request. If the return value is 4mXtGeometryAlmost24m, 4mwidth_return24m and 4mheight_return24m contain a compromise width and height. If these are acceptable, the widget should immediately call 4mXtMakeResizeRequest24m again and request that the compromise width and height be applied. If the widget is not inter- ested in 4mXtGeometryAlmost24m replies, it can pass NULL for 4mwidth_return24m and 4mheight_return24m. 1m6.4. Potential Geometry Changes0m Sometimes a geometry manager cannot respond to a geometry request from a child without first making a geometry request to the widget's own parent (the original requestor's grand- parent). If the request to the grandparent would allow the parent to satisfy the original request, the geometry manager can make the intermediate geometry request as if it were the originator. On the other hand, if the geometry manager already has determined that the original request cannot be completely satisfied (for example, if it always denies posi- tion changes), it needs to tell the grandparent to respond to the intermediate request without actually changing the geometry because it does not know if the child will accept the compromise. To accomplish this, the geometry manager uses 4mXtCWQueryOnly24m in the intermediate request. When 4mXtCWQueryOnly24m is used, the geometry manager needs to cache enough information to exactly reconstruct the interme- diate request. If the grandparent's response to the inter- mediate query was 4mXtGeometryAlmost24m, the geometry manager 1m1470m 1mX Toolkit Intrinsics X11 Release 6.40m needs to cache the entire reply geometry in the event the child accepts the parent's compromise. If the grandparent's response was 4mXtGeometryAlmost24m, it may also be necessary to cache the entire reply geometry from the grandparent when 4mXtCWQueryOnly24m is not used. If the geometry manager is still able to satisfy the original request, it may immediately accept the grandparent's compro- mise and then act on the child's request. If the grandpar- ent's compromise geometry is insufficient to allow the child's request and if the geometry manager is willing to offer a different compromise to the child, the grandparent's compromise should not be accepted until the child has accepted the new compromise. Note that a compromise geometry returned with 4mXtGeometryAl-0m 4mmost24m is guaranteed only for the next call to the same wid- get; therefore, a cache of size 1 is sufficient. 1m6.5. Child Geometry Management: The geometry_manager Proce-0m 1mdure0m The geometry_manager procedure pointer in a composite widget class is of type 4mXtGeometryHandler24m. __ | typedef XtGeometryResult (*XtGeometryHandler)(Widget, XtWidgetGeometry*, XtWidgetGeometry*); Widget 4mw24m; XtWidgetGeometry *4mrequest24m; XtWidgetGeometry *4mgeometry_return24m; 4mw24m Passes the widget making the request. 4mrequest24m Passes the new geometry the child desires. 4mgeometry_return0m Passes a geometry structure in which the geome- try manager may store a compromise. |__ A class can inherit its superclass's geometry manager during class initialization. A bit set to zero in the request's 4mrequest_mode24m field means that the child widget does not care about the value of the corresponding field, so the geometry manager can change this field as it wishes. A bit set to 1 means that the child wants that geometry element set to the value in the corre- sponding field. 1m1480m 1mX Toolkit Intrinsics X11 Release 6.40m If the geometry manager can satisfy all changes requested and if 4mXtCWQueryOnly24m is not specified, it updates the wid- get's 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, and 4mborder_width24m fields appropri- ately. Then, it returns 4mXtGeometryYes24m, and the values pointed to by the 4mgeometry_return24m argument are undefined. The widget's window is moved and resized automatically by 4mXtMakeGeometryRequest24m. Homogeneous composite widgets often find it convenient to treat the widget making the request the same as any other widget, including reconfiguring it using 4mXtConfigureWidget0m or 4mXtResizeWidget24m as part of its layout process, unless 4mXtCWQueryOnly24m is specified. If it does this, it should return 4mXtGeometryDone24m to inform 4mXtMakeGeometryRequest24m that it does not need to do the configuration itself. Note To remain compatible with layout techniques used in older widgets (before 4mXtGeometryDone24m was added to the Intrinsics), a geometry manager should avoid using 4mXtResizeWidget24m or 4mXtConfigureWidget24m on the child making the request because the layout process of the child may be in an intermediate state in which it is not prepared to handle a call to its resize procedure. A self-contained widget set may choose this alternative geometry manage- ment scheme, however, provided that it clearly warns widget developers of the compatibility con- sequences. Although 4mXtMakeGeometryRequest24m resizes the widget's window (if the geometry manager returns 4mXtGeometryYes24m), it does not call the widget class's resize procedure. The requesting widget must perform whatever resizing calculations are needed explicitly. If the geometry manager disallows the request, the widget cannot change its geometry. The values pointed to by 4mgeome-0m 4mtry_return24m are undefined, and the geometry manager returns 4mXtGeometryNo24m. Sometimes the geometry manager cannot satisfy the request exactly but may be able to satisfy 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 the structure pointed to by 4mgeometry_return24m with the actual changes it is willing to make, including an appropriate 4mrequest_mode24m mask, and returns 4mXtGeometryAlmost24m. If a bit in 4mgeome-0m 4mtry_return->request_mode24m is zero, the geometry manager 1m1490m 1mX Toolkit Intrinsics X11 Release 6.40m agrees not to change the corresponding value if 4mgeome-0m 4mtry_return24m is used immediately in a new request. If a bit is 1, the geometry manager does change that element to the corresponding value in 4mgeometry_return24m. More bits may be set in 4mgeometry_return->request_mode24m than in the original request if the geometry manager intends to change other fields should the child accept the compromise. When 4mXtGeometryAlmost24m is returned, the widget must decide if the compromise suggested in 4mgeometry_return24m is acceptable. If it is, the widget must not change its geometry directly; rather, it must make another call to 4mXtMakeGeometryRequest24m. If the next geometry request from this child uses the 4mgeome-0m 4mtry_return24m values filled in by the geometry manager with an 4mXtGeometryAlmost24m return and if there have been no interven- ing 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 4mXtGeome-0m 4mtryYes24m. However, dynamic behavior in the user's window man- ager may affect the final outcome. To return 4mXtGeometryYes24m, the geometry manager frequently rearranges the position of other managed children by calling 4mXtMoveWidget24m. However, a few geometry managers may some- times change the size of other managed children by calling 4mXtResizeWidget24m or 4mXtConfigureWidget24m. If 4mXtCWQueryOnly24m is specified, the geometry manager must return data describing how it would react to this geometry request without actually moving or resizing any widgets. Geometry managers must not assume that the 4mrequest24m and 4mgeom-0m 4metry_return24m arguments point to independent storage. The caller is permitted to use the same field for both, and the geometry manager must allocate its own temporary storage, if necessary. 1m6.6. Widget Placement and Sizing0m To move a sibling widget of the child making the geometry request, the parent uses 4mXtMoveWidget24m. 1m1500m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtMoveWidget(4mw24m, 4mx24m, 4my24m) Widget 4mw24m; Position 4mx24m; Position 4my24m; 4mw24m Specifies the widget. Must be of class RectObj or any subclass thereof. 4mx0m 4my24m Specify the new widget x and y coordinates. |__ The 4mXtMoveWidget24m function returns immediately if the speci- fied geometry fields are the same as the old values. Other- wise, 4mXtMoveWidget24m writes the new 4mx24m and 4my24m values into the object and, if the object is a widget and is realized, issues an Xlib 4mXMoveWindow24m call on the widget's window. To resize a sibling widget of the child making the geometry request, the parent uses 4mXtResizeWidget24m. __ | void XtResizeWidget(4mw24m, 4mwidth24m, 4mheight24m, 4mborder_width24m) Widget 4mw24m; Dimension 4mwidth24m; Dimension 4mheight24m; Dimension 4mborder_width24m; 4mw24m Specifies the widget. Must be of class RectObj or any subclass thereof. 4mwidth0m 4mheight0m 4mborder_width0m Specify the new widget size. |__ The 4mXtResizeWidget24m function returns immediately if the spec- ified geometry fields are the same as the old values. Oth- erwise, 4mXtResizeWidget24m writes the new 4mwidth24m, 4mheight24m, and 4mborder_width24m values into the object and, if the object is a widget and is realized, issues an 4mXConfigureWindow24m call on the widget's window. If the new width or height is different from the old values, 4mXtResizeWidget24m calls the object's resize procedure to notify it of the size change. 1m1510m 1mX Toolkit Intrinsics X11 Release 6.40m To move and resize the sibling widget of the child making the geometry request, the parent uses 4mXtConfigureWidget24m. __ | void XtConfigureWidget(4mw24m, 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, 4mborder_width24m) Widget 4mw24m; Position 4mx24m; Position 4my24m; Dimension 4mwidth24m; Dimension 4mheight24m; Dimension 4mborder_width24m; 4mw24m Specifies the widget. Must be of class RectObj or any subclass thereof. 4mx0m 4my24m Specify the new widget x and y coordinates. 4mwidth0m 4mheight0m 4mborder_width0m Specify the new widget size. |__ The 4mXtConfigureWidget24m function returns immediately if the specified new geometry fields are all equal to the current values. Otherwise, 4mXtConfigureWidget24m writes the new 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, and 4mborder_width24m values into the object and, if the object is a widget and is realized, makes an Xlib 4mXConfigureWindow24m call on the widget's window. If the new width or height is different from its old value, 4mXtConfigureWidget24m calls the object's resize procedure to notify it of the size change; otherwise, it simply returns. To resize a child widget that already has the new values of its width, height, and border width, the parent uses 4mXtRe-0m 4msizeWindow24m. __ | void XtResizeWindow(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Core or any subclass thereof. |__ The 4mXtResizeWindow24m function calls the 4mXConfigureWindow24m Xlib function to make the window of the specified widget match 1m1520m 1mX Toolkit Intrinsics X11 Release 6.40m its width, height, and border width. This request is done unconditionally because there is no inexpensive way to tell if these values match the current values. Note that the widget's resize procedure is not called. There are very few times to use 4mXtResizeWindow24m; instead, the parent should use 4mXtResizeWidget24m. 1m6.7. Preferred Geometry0m Some parents may be willing to adjust their layouts to accommodate the preferred geometries of their children. They can use 4mXtQueryGeometry24m to obtain the preferred geome- try and, as they see fit, can use or ignore any portion of the response. To query a child widget's preferred geometry, use 4mXtQuery-0m 4mGeometry24m. __ | XtGeometryResult XtQueryGeometry(4mw24m, 4mintended24m, 4mpreferred_return24m) Widget 4mw24m; XtWidgetGeometry *4mintended24m; XtWidgetGeometry *4mpreferred_return24m; 4mw24m Specifies the widget. Must be of class RectObj or any subclass thereof. 4mintended24m Specifies the new geometry the parent plans to give to the child, or NULL. 4mpreferred_return0m Returns the child widget's preferred geometry. |__ To discover a child's preferred geometry, the child's parent stores the new geometry in the corresponding fields of the intended structure, sets the corresponding bits in 4mintended.request_mode24m, and calls 4mXtQueryGeometry24m. The par- ent should set only those fields that are important to it so that the child can determine whether it may be able to attempt changes to other fields. 4mXtQueryGeometry24m clears all bits in the 4mpre-0m 4mferred_return->request_mode24m field and checks the 4mquery_geom-0m 4metry24m field of the specified widget's class record. If 4mquery_geometry24m is not NULL, 4mXtQueryGeometry24m calls the query_geometry procedure and passes as arguments the speci- fied widget, 4mintended24m, and 4mpreferred_return24m structures. If the 4mintended24m argument is NULL, 4mXtQueryGeometry24m replaces it 1m1530m 1mX Toolkit Intrinsics X11 Release 6.40m with a pointer to an 4mXtWidgetGeometry24m structure with 4mrequest_mode24m equal to zero before calling the query_geometry procedure. Note If 4mXtQueryGeometry24m is called from within a geome- try_manager procedure for the widget that issued 4mXtMakeGeometryRequest24m or 4mXtMakeResizeRequest24m, the results are not guaranteed to be consistent with the requested changes. The change request passed to the geometry manager takes precedence over the preferred geometry. The query_geometry procedure pointer is of type 4mXtGeometry-0m 4mHandler24m. __ | typedef XtGeometryResult (*XtGeometryHandler)(Widget, XtWidgetGeometry*, XtWidgetGeometry*); Widget 4mw24m; XtWidgetGeometry *4mrequest24m; XtWidgetGeometry *4mpreferred_return24m; 4mw24m Passes the child widget whose preferred geometry is required. 4mrequest24m Passes the geometry changes that the parent plans to make. 4mpreferred_return0m Passes a structure in which the child returns its preferred geometry. |__ The query_geometry procedure is expected to examine the bits set in 4mrequest->request_mode24m, evaluate the preferred geome- try of the widget, and store the result in 4mpreferred_return0m (setting the bits in 4mpreferred_return->request_mode24m corre- sponding to those geometry fields that it cares about). If the proposed geometry change is acceptable without modifica- tion, the query_geometry procedure should return 4mXtGeome-0m 4mtryYes24m. If at least one field in 4mpreferred_return24m with a bit set in 4mpreferred_return->request_mode24m is different from the corresponding field in 4mrequest24m or if a bit was set in 4mpreferred_return->request_mode24m that was not set in the request, the query_geometry procedure should return 4mXtGeome-0m 4mtryAlmost24m. If the preferred geometry is identical to the current geometry, the query_geometry procedure should return 4mXtGeometryNo24m. 1m1540m 1mX Toolkit Intrinsics X11 Release 6.40m Note The query_geometry procedure may assume that no 4mXtMakeResizeRequest24m or 4mXtMakeGeometryRequest24m is in progress for the specified widget; that is, it is not required to construct a reply consistent with the requested geometry if such a request were actually outstanding. After calling the query_geometry procedure or if the 4mquery_geometry24m field is NULL, 4mXtQueryGeometry24m examines all the unset bits in 4mpreferred_return->request_mode24m and sets the corresponding fields in 4mpreferred_return24m to the current values from the widget instance. If 4mCWStackMode24m is not set, the 4mstack_mode24m field is set to 4mXtSMDontChange24m. 4mXtQuery-0m 4mGeometry24m returns the value returned by the query_geometry procedure or 4mXtGeometryYes24m if the 4mquery_geometry24m field is NULL. Therefore, the caller can interpret a return of 4mXtGeome-0m 4mtryYes24m as not needing to evaluate the contents of the reply and, more important, not needing to modify its layout plans. A return of 4mXtGeometryAlmost24m means either that both the par- ent 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 4mXtGeometryNo24m means that both the parent and the child expressed interest in a field and that the child suggests that the field's current value in the widget instance is its preferred value. In addition, whether or not the caller ignores the return value or the reply mask, it is guaranteed that the 4mpreferred_return24m structure contains complete geome- try information for the child. Parents are expected to call 4mXtQueryGeometry24m in their layout routine and wherever else the information is significant after change_managed has been called. The first time it is invoked, the changed_managed procedure may assume that the child's current geometry is its preferred geometry. Thus, the child is still responsible for storing values into its own geometry during its initialize procedure. 1m6.8. Size Change Management: The resize Procedure0m A child can be resized by its parent at any time. Widgets usually need to know when they have changed size so that they can lay out their displayed data again to match the new size. When a parent resizes a child, it calls 4mXtResizeWid-0m 4mget24m, which updates the geometry fields in the widget, con- figures the window if the widget is realized, and calls the child's resize procedure to notify the child. The resize 1m1550m 1mX Toolkit Intrinsics X11 Release 6.40m procedure pointer is of type 4mXtWidgetProc24m. If a class need not recalculate anything when a widget is resized, it can specify NULL for the 4mresize24m field in its class record. This is an unusual case and should occur only for widgets with very trivial display semantics. The resize procedure takes a widget as its only argument. The 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, and 4mborder_width24m fields of the widget contain the new values. The resize procedure should recalculate the layout of internal data as needed. (For example, a centered Label in a window that changes size should recalculate the starting position of the text.) The widget must obey resize as a command and must not treat it as a request. A widget must not issue an 4mXtMakeGeometryRequest24m or 4mXtMakeResiz-0m 4meRequest24m call from its resize procedure. 1m1560m 1mX Toolkit Intrinsics X11 Release 6.40m 1mChapter 70m 1mEvent Management0m While Xlib allows the reading and processing of events any- where in an application, widgets in the X Toolkit neither directly read events nor grab the server or pointer. Wid- gets register procedures that are to be called when an event or class of events occurs in that widget. A typical application consists of startup code followed by an event loop that reads events and dispatches them by call- ing the procedures that widgets have registered. The default event loop provided by the Intrinsics is 4mXtAppMain-0m 4mLoop24m. The event manager is a collection of functions to perform the following tasks: · Add or remove event sources other than X server events (in particular, timer interrupts, file input, or POSIX signals). · Query the status of event sources. · Add or remove procedures to be called when an event occurs for a particular widget. · Enable and disable the dispatching of user-initiated events (keyboard and pointer events) for a particular widget. · Constrain the dispatching of events to a cascade of pop-up widgets. · Register procedures to be called when specific events arrive. · Register procedures to be called when the Intrinsics will block. · Enable safe operation in a multi-threaded environment. Most widgets do not need to call any of the event handler functions explicitly. The normal interface to X events is through the higher-level translation manager, which maps sequences of X events, with modifiers, into procedure calls. Applications rarely use any of the event manager routines besides 4mXtAppMainLoop24m. 1m1570m 1mX Toolkit Intrinsics X11 Release 6.40m 1m7.1. Adding and Deleting Additional Event Sources0m While most applications are driven only by X events, some applications need to incorporate other sources of input into the Intrinsics event-handling mechanism. The event manager provides routines to integrate notification of timer events and file data pending into this mechanism. The next section describes functions that provide input gathering from files. The application registers the files with the Intrinsics read routine. When input is pending on one of the files, the registered callback procedures are invoked. 1m7.1.1. Adding and Removing Input Sources0m To register a new file as an input source for a given appli- cation context, use 4mXtAppAddInput24m. __ | XtInputId XtAppAddInput(4mapp_context24m, 4msource24m, 4mcondition24m, 4mproc24m, 4mclient_data24m) XtAppContext 4mapp_context24m; int 4msource24m; XtPointer 4mcondition24m; XtInputCallbackProc 4mproc24m; XtPointer 4mclient_data24m; 4mapp_context0m Specifies the application context that identifies the application. 4msource24m Specifies the source file descriptor on a POSIX- based system or other operating-system-dependent device specification. 4mcondition24m Specifies the mask that indicates a read, write, or exception condition or some other operating- system-dependent condition. 4mproc24m Specifies the procedure to be called when the con- dition is found. 4mclient_data0m Specifies an argument passed to the specified pro- cedure when it is called. |__ The 4mXtAppAddInput24m function registers with the Intrinsics read routine a new source of events, which is usually file input but can also be file output. Note that 4mfile24m should be loosely interpreted to mean any sink or source of data. 1m1580m 1mX Toolkit Intrinsics X11 Release 6.40m 4mXtAppAddInput24m also specifies the conditions under which the source can generate events. When an event is pending on this source, the callback procedure is called. The legal values for the 4mcondition24m argument are operating- system-dependent. On a POSIX-based system, 4msource24m is a file number and the condition is some union of the following: 1mXtInputReadMask0m Specifies that 4mproc24m is to be called when 4msource24m has data to be read. 1mXtInputWriteMask0m Specifies that 4mproc24m is to be called when 4msource24m is ready for writing. 1mXtInputExceptMask0m Specifies that 4mproc24m is to be called when 4msource24m has exception data. Callback procedure pointers used to handle file events are of type 4mXtInputCallbackProc24m. __ | typedef void (*XtInputCallbackProc)(XtPointer, int*, XtInputId*); XtPointer 4mclient_data24m; int *4msource24m; XtInputId *4mid24m; 4mclient_data0m Passes the client data argument that was regis- tered for this procedure in 4mXtAppAddInput24m. 4msource24m Passes the source file descriptor generating the event. 4mid24m Passes the id returned from the corresponding 4mXtAppAddInput24m call. |__ See Section 7.12 for information regarding the use of 4mXtAp-0m 4mpAddInput24m in multiple threads. To discontinue a source of input, use 4mXtRemoveInput24m. 1m1590m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtRemoveInput(4mid24m) XtInputId 4mid24m; 4mid24m Specifies the id returned from the corresponding 4mXtAppAddInput24m call. |__ The 4mXtRemoveInput24m function causes the Intrinsics read rou- tine to stop watching for events from the file source speci- fied by 4mid24m. See Section 7.12 for information regarding the use of 4mXtRemoveInput24m in multiple threads. 1m7.1.2. Adding and Removing Blocking Notifications0m Occasionally it is desirable for an application to receive notification when the Intrinsics event manager detects no pending input from file sources and no pending input from X server event sources and is about to block in an operating system call. To register a hook that is called immediately prior to event blocking, use 4mXtAppAddBlockHook24m. __ | XtBlockHookId XtAppAddBlockHook(4mapp_context24m, 4mproc24m, 4mclient_data24m) XtAppContext 4mapp_context24m; XtBlockHookProc 4mproc24m; XtPointer 4mclient_data24m; 4mapp_context0m Specifies the application context that identifies the application. 4mproc24m Specifies the procedure to be called before block- ing. 4mclient_data0m Specifies an argument passed to the specified pro- cedure when it is called. |__ The 4mXtAppAddBlockHook24m function registers the specified pro- cedure and returns an identifier for it. The hook procedure 4mproc24m is called at any time in the future when the Intrinsics are about to block pending some input. 1m1600m 1mX Toolkit Intrinsics X11 Release 6.40m The procedure pointers used to provide notification of event blocking are of type 4mXtBlockHookProc24m. __ | typedef void (*XtBlockHookProc)(XtPointer); XtPointer 4mclient_data24m; 4mclient_data0m Passes the client data argument that was regis- tered for this procedure in 4mXtAppAddBlockHook24m. |__ To discontinue the use of a procedure for blocking notifica- tion, use 4mXtRemoveBlockHook24m. __ | void XtRemoveBlockHook(4mid24m) XtBlockHookId 4mid24m; 4mid24m Specifies the identifier returned from the corre- sponding call to 4mXtAppAddBlockHook24m. |__ The 4mXtRemoveBlockHook24m function removes the specified proce- dure from the list of procedures that are called by the Intrinsics read routine before blocking on event sources. 1m7.1.3. Adding and Removing Timeouts0m The timeout facility notifies the application or the widget through a callback procedure that a specified time interval has elapsed. Timeout values are uniquely identified by an interval id. To register a timeout callback, use 4mXtAppAddTimeOut24m. 1m1610m 1mX Toolkit Intrinsics X11 Release 6.40m __ | XtIntervalId XtAppAddTimeOut(4mapp_context24m, 4minterval24m, 4mproc24m, 4mclient_data24m) XtAppContext 4mapp_context24m; unsigned long 4minterval24m; XtTimerCallbackProc 4mproc24m; XtPointer 4mclient_data24m; 4mapp_context0m Specifies the application context for which the timer is to be set. 4minterval24m Specifies the time interval in milliseconds. 4mproc24m Specifies the procedure to be called when the time expires. 4mclient_data0m Specifies an argument passed to the specified pro- cedure when it is called. |__ The 4mXtAppAddTimeOut24m function creates a timeout and returns an identifier for it. The timeout value is set to 4minterval24m. The callback procedure 4mproc24m is called when 4mXtAppNextEvent24m or 4mXtAppProcessEvent24m is next called after the time interval elapses, and then the timeout is removed. Callback procedure pointers used with timeouts are of type 4mXtTimerCallbackProc24m. __ | typedef void (*XtTimerCallbackProc)(XtPointer, XtIntervalId*); XtPointer 4mclient_data24m; XtIntervalId *4mtimer24m; 4mclient_data0m Passes the client data argument that was regis- tered for this procedure in 4mXtAppAddTimeOut24m. 4mtimer24m Passes the id returned from the corresponding 4mXtAppAddTimeOut24m call. |__ See Section 7.12 for information regarding the use of 4mXtAp-0m 4mpAddTimeOut24m in multiple threads. To clear a timeout value, use 4mXtRemoveTimeOut24m. 1m1620m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtRemoveTimeOut(4mtimer24m) XtIntervalId 4mtimer24m; 4mtimer24m Specifies the id for the timeout request to be cleared. |__ The 4mXtRemoveTimeOut24m function removes the pending timeout. Note that timeouts are automatically removed once they trig- ger. Please refer to Section 7.12 for information regarding the use of 4mXtRemoveTimeOut24m in multiple threads. 1m7.1.4. Adding and Removing Signal Callbacks0m The signal facility notifies the application or the widget through a callback procedure that a signal or other external asynchronous event has occurred. The registered callback procedures are uniquely identified by a signal id. Prior to establishing a signal handler, the application or widget should call 4mXtAppAddSignal24m and store the resulting identifier in a place accessible to the signal handler. When a signal arrives, the signal handler should call 4mXtNo-0m 4mticeSignal24m to notify the Intrinsics that a signal has occured. To register a signal callback use 4mXtAppAddSignal24m. __ | XtSignalId XtAppAddSignal(4mapp_context24m, 4mproc24m, 4mclient_data24m) XtAppContext 4mapp_context24m; XtSignalCallbackProc 4mproc24m; XtPointer 4mclient_data24m; 4mapp_context0m Specifies the application context that identifies the application. 4mproc24m Specifies the procedure to be called when the sig- nal is noticed. 4mclient_data0m Specifies an argument passed to the specified pro- cedure when it is called. |__ The callback procedure pointers used to handle signal events are of type 4mXtSignalCallbackProc24m. 1m1630m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtSignalCallbackProc)(XtPointer, XtSignalId*); XtPointer 4mclient_data24m; XtSignalId *4mid24m; 4mclient_data0m Passes the client data argument that was regis- tered for this procedure in 4mXtAppAddSignal24m. 4mid24m Passes the id returned from the corresponding 4mXtAppAddSignal24m call. |__ To notify the Intrinsics that a signal has occured, use 4mXtNoticeSignal24m. __ | void XtNoticeSignal(4mid24m) XtSignalId 4mid24m; 4mid24m Specifies the id returned from the corresponding 4mXtAppAddSignal24m call. |__ On a POSIX-based system, 4mXtNoticeSignal24m is the only Intrin- sics function that can safely be called from a signal han- dler. If 4mXtNoticeSignal24m is invoked multiple times before the Intrinsics are able to invoke the registered callback, the callback is only called once. Logically, the Intrinsics maintain ``pending'' flag for each registered callback. This flag is initially 4mFalse24m and is set to 4mTrue24m by 4mXtNo-0m 4mticeSignal24m. When 4mXtAppNextEvent24m or 4mXtAppProcessEvent24m (with a mask including 4mXtIMSignal24m) is called, all registered call- backs with ``pending'' 4mTrue24m are invoked and the flags are reset to 4mFalse24m. If the signal handler wants to track how many times the sig- nal has been raised, it can keep its own private counter. Typically the handler would not do any other work; the call- back does the actual processing for the signal. The Intrin- sics never block signals from being raised, so if a given signal can be raised multiple times before the Intrinsics can invoke the callback for that signal, the callback must be designed to deal with this. In another case, a signal might be raised just after the Intrinsics sets the pending flag to 4mFalse24m but before the callback can get control, in which case the pending flag will still be 4mTrue24m after the callback returns, and the Intrinsics will invoke the call- back again, even though all of the signal raises have been handled. The callback must also be prepared to handle this 1m1640m 1mX Toolkit Intrinsics X11 Release 6.40m case. To remove a registered signal callback, call 4mXtRemoveSignal24m. __ | void XtRemoveSignal(4mid24m) XtSignalId 4mid24m; 4mid24m Specifies the id returned by the corresponding call to 4mXtAppAddSignal24m. |__ The client should typically disable the source of the signal before calling 4mXtRemoveSignal24m. If the signal could have been raised again before the source was disabled and the client wants to process it, then after disabling the source but before calling 4mXtRemoveSignal24m the client can test for signals with 4mXtAppPending24m and process them by calling 4mXtApp-0m 4mProcessEvent24m with the mask 4mXtIMSignal24m. 1m7.2. Constraining Events to a Cascade of Widgets0m Modal widgets are widgets that, except for the input directed to them, lock out user input to the application. When a modal menu or modal dialog box is popped up using 4mXtPopup24m, user events (keyboard and pointer events) that occur outside the modal widget should be delivered to the modal widget or ignored. In no case will user events be delivered to a widget outside the modal widget. Menus can pop up submenus, and dialog boxes can pop up fur- ther 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 exposure events and the like keep the appli- cation's display up-to-date. Any event that occurs within the cascade is delivered as usual. The user events deliv- ered to the most recent spring-loaded shell in the cascade when they occur outside the cascade are called remap events and are 4mKeyPress24m, 4mKeyRelease24m, 4mButtonPress24m, and 4mButtonRe-0m 4mlease24m. The user events ignored when they occur outside the cascade are 4mMotionNotify24m and 4mEnterNotify24m. All other events are delivered normally. In particular, note that this is one way in which widgets can receive 4mLeaveNotify24m events without first receiving 4mEnterNotify24m events; they should be prepared to deal with this, typically by ignoring any unmatched 4mLeaveNotify24m events. 1m1650m 1mX Toolkit Intrinsics X11 Release 6.40m 4mXtPopup24m uses the 4mXtAddGrab24m and 4mXtRemoveGrab24m functions to constrain user events to a modal cascade and subsequently to remove a grab when the modal widget is popped down. To constrain or redirect user input to a modal widget, use 4mXtAddGrab24m. __ | void XtAddGrab(4mw24m, 4mexclusive24m, 4mspring_loaded24m) Widget 4mw24m; Boolean 4mexclusive24m; Boolean 4mspring_loaded24m; 4mw24m Specifies the widget to add to the modal cascade. Must be of class Core or any subclass thereof. 4mexclusive24m Specifies whether user events should be dispatched exclusively to this widget or also to previous widgets in the cascade. 4mspring_loaded0m Specifies whether this widget was popped up because the user pressed a pointer button. |__ The 4mXtAddGrab24m function appends the widget to the modal cas- cade and checks that 4mexclusive24m is 4mTrue24m if 4mspring_loaded24m is 4mTrue24m. If this condition is not met, 4mXtAddGrab24m generates a warning message. The modal cascade is used by 4mXtDispatchEvent24m when it tries to dispatch a user event. When at least one modal widget is in the widget cascade, 4mXtDispatchEvent24m first determines if the event should be delivered. It starts at the most recent cascade entry and follows the cascade up to and including the most recent cascade entry added with the 4mexclusive0m parameter 4mTrue24m. This subset of the modal cascade along with all descendants of these widgets comprise the active subset. User events that occur outside the widgets in this subset are ignored or remapped. Modal menus with submenus generally add a submenu widget to the cascade with 4mexclusive24m 4mFalse24m. Modal dialog boxes that need to restrict user input to the most deeply nested dialog box add a subdialog widget to the cascade with 4mexclusive24m 4mTrue24m. User events that occur within the active subset are delivered to the appropriate widget, which is usually a child or further descendant of the modal widget. 1m1660m 1mX Toolkit Intrinsics X11 Release 6.40m Regardless of where in the application they occur, remap events are always delivered to the most recent widget in the active subset of the cascade registered with 4mspring_loaded0m 4mTrue24m, if any such widget exists. If the event occurred in the active subset of the cascade but outside the spring- loaded widget, it is delivered normally before being deliv- ered also to the spring-loaded widget. Regardless of where it is dispatched, the Intrinsics do not modify the contents of the event. To remove the redirection of user input to a modal widget, use 4mXtRemoveGrab24m. __ | void XtRemoveGrab(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget to remove from the modal cas- cade. |__ The 4mXtRemoveGrab24m function removes widgets from the modal cascade starting at the most recent widget up to and includ- ing the specified widget. It issues a warning if the speci- fied widget is not on the modal cascade. 1m7.2.1. Requesting Key and Button Grabs0m The Intrinsics provide a set of key and button grab inter- faces that are parallel to those provided by Xlib and that allow the Intrinsics to modify event dispatching when neces- sary. X Toolkit applications and widgets that need to pas- sively grab keys or buttons or actively grab the keyboard or pointer should use the following Intrinsics routines rather than the corresponding Xlib routines. To passively grab a single key of the keyboard, use 4mXtGrabKey24m. 1m1670m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtGrabKey(4mwidget24m, 4mkeycode24m, 4mmodifiers24m, 4mowner_events24m, 4mpointer_mode24m, 4mkeyboard_mode24m) Widget 4mwidget24m; KeyCode 4mkeycode24m; Modifiers 4mmodifiers24m; Boolean 4mowner_events24m; int 4mpointer_mode24m, 4mkeyboard_mode24m; 4mwidget24m Specifies the widget in whose window the key is to be grabbed. Must be of class Core or any subclass thereof. 4mkeycode0m 4mmodifiers0m 4mowner_events0m 4mpointer_mode0m 4mkeyboard_mode0m Specify arguments to 4mXGrabKey24m; see Section 12.2 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m. |__ 4mXtGrabKey24m calls 4mXGrabKey24m specifying the widget's window as the grab window if the widget is realized. The remaining arguments are exactly as for 4mXGrabKey24m. If the widget is not realized, or is later unrealized, the call to 4mXGrabKey24m is performed (again) when the widget is realized and its window becomes mapped. In the future, if 4mXtDispatchEvent24m is called with a 4mKeyPress24m event matching the specified keycode and modifiers (which may be 4mAnyKey24m or 4mAnyModifier24m, respectively) for the widget's window, the Intrinsics will call 4mXtUn-0m 4mgrabKeyboard24m with the timestamp from the 4mKeyPress24m event if either of the following conditions is true: · There is a modal cascade and the widget is not in the active subset of the cascade and the keyboard was not previously grabbed, or · 4mXFilterEvent24m returns 4mTrue24m. To cancel a passive key grab, use 4mXtUngrabKey24m. 1m1680m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtUngrabKey(4mwidget24m, 4mkeycode,24m 4mmodifiers24m) Widget 4mwidget24m; KeyCode 4mkeycode24m; Modifiers 4mmodifiers24m; 4mwidget24m Specifies the widget in whose window the key was grabbed. 4mkeycode0m 4mmodifiers24m Specify arguments to 4mXUngrabKey24m; see Section 12.2 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m. |__ The 4mXtUngrabKey24m procedure calls 4mXUngrabKey24m specifying the widget's window as the ungrab window if the widget is real- ized. The remaining arguments are exactly as for 4mXUn-0m 4mgrabKey24m. If the widget is not realized, 4mXtUngrabKey24m removes a deferred 4mXtGrabKey24m request, if any, for the specified wid- get, keycode, and modifiers. To actively grab the keyboard, use 4mXtGrabKeyboard24m. __ | int XtGrabKeyboard(4mwidget24m, 4mowner_events24m, 4mpointer_mode24m, 4mkeyboard_mode24m, 4mtime24m) Widget 4mwidget24m; Boolean 4mowner_events24m; int 4mpointer_mode24m, 4mkeyboard_mode24m; Time 4mtime24m; 4mwidget24m Specifies the widget for whose window the keyboard is to be grabbed. Must be of class Core or any subclass thereof. 4mowner_events0m 4mpointer_mode0m 4mkeyboard_mode0m 4mtime24m Specify arguments to 4mXGrabKeyboard24m; see Section 12.2 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m. |__ If the specified widget is realized, 4mXtGrabKeyboard24m calls 4mXGrabKeyboard24m specifying the widget's window as the grab window. The remaining arguments and return value are exactly as for 4mXGrabKeyboard24m. If the widget is not real- ized, 4mXtGrabKeyboard24m immediately returns 4mGrabNotViewable24m. No future automatic ungrab is implied by 4mXtGrabKeyboard24m. 1m1690m 1mX Toolkit Intrinsics X11 Release 6.40m To cancel an active keyboard grab, use 4mXtUngrabKeyboard24m. __ | void XtUngrabKeyboard(4mwidget24m, 4mtime24m) Widget 4mwidget24m; Time 4mtime24m; 4mwidget24m Specifies the widget that has the active keyboard grab. 4mtime24m Specifies the additional argument to 4mXUngrabKey-0m 4mboard24m; see Section 12.2 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX0m 4mInterface24m. |__ 4mXtUngrabKeyboard24m calls 4mXUngrabKeyboard24m with the specified time. To passively grab a single pointer button, use 4mXtGrabButton24m. __ | void XtGrabButton(4mwidget24m, 4mbutton24m, 4mmodifiers24m, 4mowner_events24m, 4mevent_mask24m, 4mpointer_mode24m, 4mkeyboard_mode24m, 4mconfine_to24m, 4mcursor24m) Widget 4mwidget24m; int 4mbutton24m; Modifiers 4mmodifiers24m; Boolean 4mowner_events24m; unsigned int 4mevent_mask24m; int 4mpointer_mode24m, 4mkeyboard_mode24m; Window 4mconfine_to24m; Cursor 4mcursor24m; 4mwidget24m Specifies the widget in whose window the button is to be grabbed. Must be of class Core or any sub- class thereof. 4mbutton0m 4mmodifiers0m 4mowner_events0m 4mevent_mask0m 4mpointer_mode0m 4mkeyboard_mode0m 4mconfine_to0m 4mcursor24m Specify arguments to 4mXGrabButton24m; see Section 12.1 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m. |__ 4mXtGrabButton24m calls 4mXGrabButton24m specifying the widget's win- dow as the grab window if the widget is realized. The 1m1700m 1mX Toolkit Intrinsics X11 Release 6.40m remaining arguments are exactly as for 4mXGrabButton24m. If the widget is not realized, or is later unrealized, the call to 4mXGrabButton24m is performed (again) when the widget is realized and its window becomes mapped. In the future, if 4mXtDis-0m 4mpatchEvent24m is called with a 4mButtonPress24m event matching the specified button and modifiers (which may be 4mAnyButton24m or 4mAnyModifier24m, respectively) for the widget's window, the Intrinsics will call 4mXtUngrabPointer24m with the timestamp from the 4mButtonPress24m event if either of the following conditions is true: · There is a modal cascade and the widget is not in the active subset of the cascade and the pointer was not pre- viously grabbed, or · 4mXFilterEvent24m returns 4mTrue24m. To cancel a passive button grab, use 4mXtUngrabButton24m. __ | void XtUngrabButton(4mwidget24m, 4mbutton24m, 4mmodifiers24m) Widget 4mwidget24m; unsigned int 4mbutton24m; Modifiers 4mmodifiers24m; 4mwidget24m Specifies the widget in whose window the button was grabbed. 4mbutton0m 4mmodifiers24m Specify arguments to 4mXUngrabButton24m; see Section 12.1 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m. |__ The 4mXtUngrabButton24m procedure calls 4mXUngrabButton24m specifying the widget's window as the ungrab window if the widget is realized. The remaining arguments are exactly as for 4mXUn-0m 4mgrabButton24m. If the widget is not realized, 4mXtUngrabButton0m removes a deferred 4mXtGrabButton24m request, if any, for the specified widget, button, and modifiers. To actively grab the pointer, use 4mXtGrabPointer24m. 1m1710m 1mX Toolkit Intrinsics X11 Release 6.40m __ | int XtGrabPointer(4mwidget24m, 4mowner_events24m, 4mevent_mask24m, 4mpointer_mode24m, 4mkeyboard_mode24m, 4mconfine_to24m, 4mcursor24m, 4mtime24m) Widget 4mwidget24m; Boolean 4mowner_events24m; unsigned int 4mevent_mask24m; int 4mpointer_mode24m, 4mkeyboard_mode24m; Window 4mconfine_to24m; Cursor 4mcursor24m; Time 4mtime24m; 4mwidget24m Specifies the widget for whose window the pointer is to be grabbed. Must be of class Core or any subclass thereof. 4mowner_events0m 4mevent_mask0m 4mpointer_mode0m 4mkeyboard_mode0m 4mconfine_to0m 4mcursor0m 4mtime24m Specify arguments to 4mXGrabPointer24m; see Section 12.1 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m. |__ If the specified widget is realized, 4mXtGrabPointer24m calls 4mXGrabPointer24m, specifying the widget's window as the grab window. The remaining arguments and return value are exactly as for 4mXGrabPointer24m. If the widget is not realized, 4mXtGrabPointer24m immediately returns 4mGrabNotViewable24m. No future automatic ungrab is implied by 4mXtGrabPointer24m. To cancel an active pointer grab, use 4mXtUngrabPointer24m. __ | void XtUngrabPointer(4mwidget24m, 4mtime24m) Widget 4mwidget24m; Time 4mtime24m; 4mwidget24m Specifies the widget that has the active pointer grab. 4mtime24m Specifies the time argument to 4mXUngrabPointer24m; see Section 12.1 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m. |__ 4mXtUngrabPointer24m calls 4mXUngrabPointer24m with the specified time. 1m1720m 1mX Toolkit Intrinsics X11 Release 6.40m 1m7.3. Focusing Events on a Child0m To redirect keyboard input to a normal descendant of a wid- get without calling 4mXSetInputFocus24m, use 4mXtSetKeyboardFocus24m. __ | void XtSetKeyboardFocus(4msubtree24m 4mdescendant24m) Widget 4msubtree24m, 4mdescendant24m; 4msubtree24m Specifies the subtree of the hierarchy for which the keyboard focus is to be set. Must be of class Core or any subclass thereof. 4mdescendant0m Specifies either the normal (non-pop-up) descen- dant of 4msubtree24m to which keyboard events are logi- cally directed, or 4mNone24m. It is not an error to specify 4mNone24m when no input focus was previously set. Must be of class Object or any subclass thereof. |__ 4mXtSetKeyboardFocus24m causes 4mXtDispatchEvent24m to remap keyboard events occurring within the specified subtree and dispatch them to the specified descendant widget or to an ancestor. If the descendant's class is not a subclass of Core, the descendant is replaced by its closest windowed ancestor. When there is no modal cascade, keyboard events can be dis- patched to a widget in one of five ways. Assume the server delivered the event to the window for widget E (because of X input focus, key or keyboard grabs, or pointer position). · If neither E nor any of E's ancestors have redirected the keyboard focus, or if the event activated a grab for E as specified by a call to 4mXtGrabKey24m with any value of 4mowner_events24m, or if the keyboard is actively grabbed by E with 4mowner_events24m 4mFalse24m via 4mXtGrabKeyboard24m or 4mXtGrabKey0m on a previous key press, the event is dispatched to E. · Beginning with the ancestor of E closest to the root that has redirected the keyboard focus or E if no such ances- tor exists, if the target of that focus redirection has in turn redirected the keyboard focus, recursively follow this focus chain to find a widget F that has not redi- rected focus. - If E is the final focus target widget F or a descen- dant of F, the event is dispatched to E. - If E is not F, an ancestor of F, or a descendant of F, and the event activated a grab for E as specified by a 1m1730m 1mX Toolkit Intrinsics X11 Release 6.40m call to 4mXtGrabKey24m for E, 4mXtUngrabKeyboard24m is called. - If E is an ancestor of F, and the event is a key press, and either + E has grabbed the key with 4mXtGrabKey24m and 4mowner_events24m 4mFalse24m, or + E has grabbed the key with 4mXtGrabKey24m and 4mowner_events24m 4mTrue24m, and the coordinates of the event are outside the rectangle specified by E's geome- try, then the event is dispatched to E. - Otherwise, define A as the closest common ancestor of E and F: + If there is an active keyboard grab for any widget via either 4mXtGrabKeyboard24m or 4mXtGrabKey24m on a previ- ous key press, or if no widget between F and A (noninclusive) has grabbed the key and modifier combination with 4mXtGrabKey24m and any value of 4mowner_events24m, the event is dispatched to F. + Else, the event is dispatched to the ancestor of F closest to A that has grabbed the key and modifier combination with 4mXtGrabKey24m. When there is a modal cascade, if the final destination wid- get as identified above is in the active subset of the cas- cade, the event is dispatched; otherwise the event is remapped to a spring-loaded shell or discarded. Regardless of where it is dispatched, the Intrinsics do not modify the contents of the event. When 4msubtree24m or one of its descendants acquires the X input focus or the pointer moves into the subtree such that key- board events would now be delivered to the subtree, a 4mFocusIn24m event is generated for the descendant if 4mFocusChange0m events have been selected by the descendant. Similarly, when 4msubtree24m loses the X input focus or the keyboard focus for one of its ancestors, a 4mFocusOut24m event is generated for descendant if 4mFocusChange24m events have been selected by the descendant. A widget tree may also actively manage the X server input focus. To do so, a widget class specifies an accept_focus procedure. The accept_focus procedure pointer is of type 4mXtAcceptFocus-0m 4mProc24m. 1m1740m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef Boolean (*XtAcceptFocusProc)(Widget, Time*); Widget 4mw24m; Time *4mtime24m; 4mw24m Specifies the widget. 4mtime24m Specifies the X time of the event causing the accept focus. |__ Widgets that need the input focus can call 4mXSetInputFocus0m explicitly, pursuant to the restrictions of the 4mInter-Client0m 4mCommunication24m 4mConventions24m 4mManual24m. To allow outside agents, such as the parent, to cause a widget to take the input focus, every widget exports an accept_focus procedure. The widget returns a value indicating whether it actually took the focus or not, so that the parent can give the focus to another widget. Widgets that need to know when they lose the input focus must use the Xlib focus notification mecha- nism explicitly (typically by specifying translations for 4mFocusIn24m and 4mFocusOut24m events). Widgets classes that never want the input focus should set the 4maccept_focus24m field to NULL. To call a widget's accept_focus procedure, use 4mXtCallAccept-0m 4mFocus24m. __ | Boolean XtCallAcceptFocus(4mw24m, 4mtime24m) Widget 4mw24m; Time *4mtime24m; 4mw24m Specifies the widget. Must be of class Core or any subclass thereof. 4mtime24m Specifies the X time of the event that is causing the focus change. |__ The 4mXtCallAcceptFocus24m function calls the specified widget's accept_focus procedure, passing it the specified widget and time, and returns what the accept_focus procedure returns. If 4maccept_focus24m is NULL, 4mXtCallAcceptFocus24m returns 4mFalse24m. 1m7.3.1. Events for Drawables That Are Not a Widget's Window0m Sometimes an application must handle events for drawables that are not associated with widgets in its widget tree. 1m1750m 1mX Toolkit Intrinsics X11 Release 6.40m Examples include handling 4mGraphicsExpose24m and 4mNoExpose24m events on Pixmaps, and handling 4mPropertyNotify24m events on the root window. To register a drawable with the Intrinsics event dispatch- ing, use 4mXtRegisterDrawable24m. __ | void XtRegisterDrawable(4mdisplay24m, 4mdrawable24m, 4mwidget24m) Display *4mdisplay24m; Drawable 4mdrawable24m; Widget 4mwidget24m; 4mdisplay24m Specifies the drawable's display. 4mdrawable24m Specifies the drawable to register. 4mwidget24m Specifies the widget to register the drawable for. |__ 4mXtRegisterDrawable24m associates the specified drawable with the specified widget so that future calls to 4mXtWindowToWid-0m 4mget24m with the drawable will return the widget. The default event dispatcher will dispatch future events that arrive for the drawable to the widget in the same manner as events that contain the widget's window. If the drawable is already registered with another widget, or if the drawable is the window of a widget in the client's widget tree, the results of calling 4mXtRegisterDrawable24m are undefined. To unregister a drawable with the Intrinsics event dispatch- ing, use 4mXtUnregisterDrawable24m. __ | void XtUnregisterDrawable(4mdisplay24m, 4mdrawable24m) Display *4mdisplay24m; Drawable 4mdrawable24m; 4mdisplay24m Specifies the drawable's display. 4mdrawable24m Specifies the drawable to unregister. |__ 4mXtUnregisterDrawable24m removes an association created with 4mXtRegisterDrawable24m. If the drawable is the window of a wid- get in the client's widget tree the results of calling 4mXtUn-0m 4mregisterDrawable24m are undefined. 1m1760m 1mX Toolkit Intrinsics X11 Release 6.40m 1m7.4. Querying Event Sources0m The event manager provides several functions to examine and read events (including file and timer events) that are in the queue. The next three functions are Intrinsics equiva- lents of the 4mXPending24m, 4mXPeekEvent24m, and 4mXNextEvent24m Xlib calls. To determine if there are any events on the input queue for a given application, use 4mXtAppPending24m. __ | XtInputMask XtAppPending(4mapp_context24m) XtAppContext 4mapp_context24m; 4mapp_context0m Specifies the application context that identifies the application to check. |__ The 4mXtAppPending24m function returns a nonzero value if there are events pending from the X server, timer pending, other input sources pending, or signal sources pending. The value returned is a bit mask that is the OR of 4mXtIMXEvent24m, 4mXtIM-0m 4mTimer24m, 4mXtIMAlternateInput24m, and 4mXtIMSignal24m (see 4mXtAppProces-0m 4msEvent24m). If there are no events pending, 4mXtAppPending0m flushes the output buffers of each Display in the applica- tion context and returns zero. To return the event from the head of a given application's input queue without removing input from the queue, use 4mXtAppPeekEvent24m. __ | Boolean XtAppPeekEvent(4mapp_context24m, 4mevent_return24m) XtAppContext 4mapp_context24m; XEvent *4mevent_return24m; 4mapp_context0m Specifies the application context that identifies the application. 4mevent_return0m Returns the event information to the specified event structure. |__ If there is an X event in the queue, 4mXtAppPeekEvent24m copies 1m1770m 1mX Toolkit Intrinsics X11 Release 6.40m it into 4mevent_return24m and returns 4mTrue24m. If no X input is on the queue, 4mXtAppPeekEvent24m flushes the output buffers of each Display in the application context and blocks until some input is available (possibly calling some timeout callbacks in the interim). If the next available input is an X event, 4mXtAppPeekEvent24m fills in 4mevent_return24m and returns 4mTrue24m. Oth- erwise, the input is for an input source registered with 4mXtAppAddInput24m, and 4mXtAppPeekEvent24m returns 4mFalse24m. To remove and return the event from the head of a given application's X event queue, use 4mXtAppNextEvent24m. __ | void XtAppNextEvent(4mapp_context24m, 4mevent_return24m) XtAppContext 4mapp_context24m; XEvent *4mevent_return24m; 4mapp_context0m Specifies the application context that identifies the application. 4mevent_return0m Returns the event information to the specified event structure. |__ If the X event queue is empty, 4mXtAppNextEvent24m flushes the X output buffers of each Display in the application context and waits for an X event while looking at the other input sources and timeout values and calling any callback proce- dures triggered by them. This wait time can be used for background processing; see Section 7.8. 1m7.5. Dispatching Events0m The Intrinsics provide functions that dispatch events to widgets or other application code. Every client interested in X events on a widget uses 4mXtAddEventHandler24m to register which events it is interested in and a procedure (event han- dler) to be called when the event happens in that window. The translation manager automatically registers event han- dlers for widgets that use translation tables; see Chapter 10. ----------- The sample implementations provides XtAppPeekEvent as described. Timeout callbacks are called while blocking for input. If some input for an input source is available, 4mXtAppPeekEvent24m will return 4mTrue24m without returning an event. 1m1780m 1mX Toolkit Intrinsics X11 Release 6.40m Applications that need direct control of the processing of different types of input should use 4mXtAppProcessEvent24m. __ | void XtAppProcessEvent(4mapp_context24m, 4mmask24m) XtAppContext 4mapp_context24m; XtInputMask 4mmask24m; 4mapp_context0m Specifies the application context that identifies the application for which to process input. 4mmask24m Specifies what types of events to process. The mask is the bitwise inclusive OR of any combina- tion of 4mXtIMXEvent24m, 4mXtIMTimer24m, 4mXtIMAlternateInput24m, and 4mXtIMSignal24m. As a convenience, 4mIntrinsic.h0m defines the symbolic name 4mXtIMAll24m to be the bit- wise inclusive OR of these four event types. |__ The 4mXtAppProcessEvent24m function processes one timer, input source, signal source, or X event. If there is no event or input of the appropriate type to process, then 4mXtAppProces-0m 4msEvent24m blocks until there is. If there is more than one type of input available to process, it is undefined which will get processed. Usually, this procedure is not called by client applications; see 4mXtAppMainLoop24m. 4mXtAppProcessEv-0m 4ment24m processes timer events by calling any appropriate timer callbacks, input sources by calling any appropriate input callbacks, signal source by calling any appropriate signal callbacks, and X events by calling 4mXtDispatchEvent24m. When an X event is received, it is passed to 4mXtDis-0m 4mpatchEvent24m, which calls the appropriate event handlers and passes them the widget, the event, and client-specific data registered with each procedure. If no handlers for that event are registered, the event is ignored and the dis- patcher simply returns. To dispatch an event returned by 4mXtAppNextEvent24m, retrieved directly from the Xlib queue, or synthetically constructed, to any registered event filters or event handlers, call 4mXtDispatchEvent24m. 1m1790m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Boolean XtDispatchEvent(4mevent24m) XEvent *4mevent24m; 4mevent24m Specifies a pointer to the event structure to be dispatched to the appropriate event handlers. |__ The 4mXtDispatchEvent24m function first calls 4mXFilterEvent24m with the 4mevent24m and the window of the widget to which the Intrin- sics intend to dispatch the event, or the event window if the Intrinsics would not dispatch the event to any handlers. If 4mXFilterEvent24m returns 4mTrue24m and the event activated a server grab as identified by a previous call to 4mXtGrabKey24m or 4mXtGrabButton24m, 4mXtDispatchEvent24m calls 4mXtUngrabKeyboard24m or 4mXtUngrabPointer24m with the timestamp from the event and imme- diately returns 4mTrue24m. If 4mXFilterEvent24m returns 4mTrue24m and a grab was not activated, 4mXtDispatchEvent24m just immediately returns 4mTrue24m. Otherwise, 4mXtDispatchEvent24m sends the event to the event handler functions that have been previously regis- tered with the dispatch routine. 4mXtDispatchEvent24m returns 4mTrue24m if 4mXFilterEvent24m returned 4mTrue24m, or if the event was dis- patched to some handler, and 4mFalse24m if it found no handler to which to dispatch the event. 4mXtDispatchEvent24m records the last timestamp in any event that contains a timestamp (see 4mXtLastTimestampProcessed24m), regardless of whether it was fil- tered or dispatched. If a modal cascade is active with 4mspring_loaded24m 4mTrue24m, and if the event is a remap event as defined by 4mXtAddGrab24m, 4mXtDispatchEvent24m may dispatch the event a second time. If it does so, 4mXtDispatchEvent24m will call 4mXFilterEvent24m again with the window of the spring-loaded wid- get prior to the second dispatch, and if 4mXFilterEvent0m returns 4mTrue24m, the second dispatch will not be performed. 1m7.6. The Application Input Loop0m To process all input from a given application in a continu- ous loop, use the convenience procedure 4mXtAppMainLoop24m. __ | void XtAppMainLoop(4mapp_context24m) XtAppContext 4mapp_context24m; 4mapp_context0m Specifies the application context that identifies the application. |__ The 4mXtAppMainLoop24m function first reads the next incoming X event by calling 4mXtAppNextEvent24m and then dispatches the 1m1800m 1mX Toolkit Intrinsics X11 Release 6.40m event to the appropriate registered procedure by calling 4mXtDispatchEvent24m. This constitutes the main loop of X Tool- kit applications. There is nothing special about 4mXtAppMain-0m 4mLoop24m; it simply calls 4mXtAppNextEvent24m and then 4mXtDis-0m 4mpatchEvent24m in a conditional loop. At the bottom of the loop, it checks to see if the specified application con- text's destroy flag is set. If the flag is set, the loop breaks. The whole loop is enclosed between a matching 4mXtAp-0m 4mpLock24m and 4mXtAppUnlock24m. Applications can provide their own version of this loop, which tests some global termination flag or tests that the number of top-level widgets is larger than zero before cir- cling back to the call to 4mXtAppNextEvent24m. 1m7.7. Setting and Checking the Sensitivity State of a Widget0m Many widgets have a mode in which they assume a different appearance (for example, are grayed out or stippled), do not respond to user events, and become dormant. When dormant, a widget is considered to be insensitive. If a widget is insensitive, the event manager does not dispatch any events to the widget with an event type of 4mKeyPress24m, 4mKeyRelease24m, 4mButtonPress24m, 4mButtonRelease24m, 4mMotionNotify24m, 4mEnter-0m 4mNotify24m, 4mLeaveNotify24m, 4mFocusIn24m, or 4mFocusOut24m. A widget can be insensitive because its 4msensitive24m field is 4mFalse24m or because one of its ancestors is insensitive and thus the widget's 4mancestor_sensitive24m field also is 4mFalse24m. A widget can but does not need to distinguish these two cases visually. Note Pop-up shells will have 4mancestor_sensitive24m 4mFalse0m if the parent was insensitive when the shell was created. Since 4mXtSetSensitive24m on the parent will not modify the resource of the pop-up child, clients are advised to include a resource specifi- cation of the form ``*TransientShell.ancestorSen- sitive: True'' in the application defaults resource file or to otherwise ensure that the par- ent is sensitive when creating pop-up shells. To set the sensitivity state of a widget, use 4mXtSetSensi-0m 4mtive24m. 1m1810m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtSetSensitive(4mw24m, 4msensitive24m) Widget 4mw24m; Boolean 4msensitive24m; 4mw24m Specifies the widget. Must be of class RectObj or any subclass thereof. 4msensitive24m Specifies whether the widget should receive key- board, pointer, and focus events. |__ The 4mXtSetSensitive24m function first calls 4mXtSetValues24m on the current widget with an argument list specifying the XtNsen- sitive resource and the new value. If 4msensitive24m is 4mFalse0m and the widget's class is a subclass of Composite, 4mXtSetSen-0m 4msitive24m recursively propagates the new value down the child tree by calling 4mXtSetValues24m on each child to set 4mances-0m 4mtor_sensitive24m to 4mFalse24m. If 4msensitive24m is 4mTrue24m and the wid- get's class is a subclass of Composite and the widget's 4mancestor_sensitive24m field is 4mTrue24m, 4mXtSetSensitive24m sets the 4mancestor_sensitive24m of each child to 4mTrue24m and then recur- sively calls 4mXtSetValues24m on each normal descendant that is now sensitive to set 4mancestor_sensitive24m to 4mTrue24m. 4mXtSetSensitive24m calls 4mXtSetValues24m to change the 4msensitive24m and 4mancestor_sensitive24m fields of each affected widget. There- fore, when one of these changes, the widget's set_values procedure should take whatever display actions are needed (for example, graying out or stippling the widget). 4mXtSetSensitive24m maintains the invariant that, if the parent has either 4msensitive24m or 4mancestor_sensitive24m 4mFalse24m, then all children have 4mancestor_sensitive24m 4mFalse24m. To check the current sensitivity state of a widget, use 4mXtIsSensitive24m. __ | Boolean XtIsSensitive(4mw24m) Widget 4mw24m; 4mw24m Specifies the object. Must be of class Object or any subclass thereof. |__ The 4mXtIsSensitive24m function returns 4mTrue24m or 4mFalse24m to indicate whether user input events are being dispatched. If object's class is a subclass of RectObj and both 4msensitive24m and 4mances-0m 4mtor_sensitive24m are 4mTrue24m, 4mXtIsSensitive24m returns 4mTrue24m; 1m1820m 1mX Toolkit Intrinsics X11 Release 6.40m otherwise, it returns 4mFalse24m. 1m7.8. Adding Background Work Procedures0m The Intrinsics have some limited support for background pro- cessing. Because most applications spend most of their time waiting for input, you can register an idle-time work proce- dure that is called when the toolkit would otherwise block in 4mXtAppNextEvent24m or 4mXtAppProcessEvent24m. Work procedure pointers are of type 4mXtWorkProc24m. __ | typedef Boolean (*XtWorkProc)(XtPointer); XtPointer 4mclient_data24m; 4mclient_data0m Passes the client data specified when the work procedure was registered. |__ This procedure should return 4mTrue24m when it is done to indi- cate that it should be removed. If the procedure returns 4mFalse24m, it will remain registered and called again when the application is next idle. Work procedures should be very judicious about how much they do. If they run for more than a small part of a second, interactive feel is likely to suf- fer. To register a work procedure for a given application, use 4mXtAppAddWorkProc24m. 1m1830m 1mX Toolkit Intrinsics X11 Release 6.40m __ | XtWorkProcId XtAppAddWorkProc(4mapp_context24m, 4mproc24m, 4mclient_data24m) XtAppContext 4mapp_context24m; XtWorkProc 4mproc24m; XtPointer 4mclient_data24m; 4mapp_context0m Specifies the application context that identifies the application. 4mproc24m Specifies the procedure to be called when the application is idle. 4mclient_data0m Specifies the argument passed to the specified procedure when it is called. |__ The 4mXtAppAddWorkProc24m function adds the specified work proce- dure for the application identified by 4mapp_context24m and returns an opaque unique identifier for this work procedure. Multiple work procedures can be registered, and the most recently added one is always the one that is called. How- ever, if a work procedure adds another work procedure, the newly added one has lower priority than the current one. To remove a work procedure, either return 4mTrue24m from the pro- cedure when it is called or use 4mXtRemoveWorkProc24m outside of the procedure. __ | void XtRemoveWorkProc(4mid24m) XtWorkProcId 4mid24m; 4mid24m Specifies which work procedure to remove. |__ The 4mXtRemoveWorkProc24m function explicitly removes the speci- fied background work procedure. 1m7.9. X Event Filters0m The event manager provides filters that can be applied to specific X events. The filters, which screen out events that are redundant or are temporarily unwanted, handle pointer motion compression, enter/leave compression, and exposure compression. 1m1840m 1mX Toolkit Intrinsics X11 Release 6.40m 1m7.9.1. Pointer Motion Compression0m Widgets can have a hard time keeping up with a rapid stream of pointer motion events. Furthermore, they usually do not care about every motion event. To throw out redundant motion events, the widget class field 4mcompress_motion24m should be 4mTrue24m. When a request for an event would return a motion event, the Intrinsics check if there are any other motion events for the same widget immediately following the current one and, if so, skip all but the last of them. 1m7.9.2. Enter/Leave Compression0m To throw out pairs of enter and leave events that have no intervening events, as can happen when the user moves the pointer across a widget without stopping in it, the widget class field 4mcompress_enterleave24m should be 4mTrue24m. These enter and leave events are not delivered to the client if they are found together in the input queue. 1m7.9.3. Exposure Compression0m Many widgets prefer to process a series of exposure events as a single expose region rather than as individual rectan- gles. Widgets with complex displays might use the expose region as a clip list in a graphics context, and widgets with simple displays might ignore the region entirely and redisplay their whole window or might get the bounding box from the region and redisplay only that rectangle. In either case, these widgets do not care about getting par- tial exposure events. The 4mcompress_exposure24m field in the widget class structure specifies the type and number of exposure events that are dispatched to the widget's expose procedure. This field must be initialized to one of the following values: __ | #define XtExposeNoCompress ((XtEnum)False) #define XtExposeCompressSeries((XtEnum)True) #define XtExposeCompressMultiple #define XtExposeCompressMaximal |__ optionally ORed with any combination of the following flags (all with implementation-defined values): 4mXtExposeGraphic-0m 4msExpose24m, 4mXtExposeGraphicsExposeMerged24m, 4mXtExposeNoExpose24m, and 4mXtExposeNoRegion24m. 1m1850m 1mX Toolkit Intrinsics X11 Release 6.40m If the 4mcompress_exposure24m field in the widget class structure does not specify 4mXtExposeNoCompress24m, the event manager calls the widget's expose procedure only once for a series of exposure events. In this case, all 4mExpose24m or 4mGraphicsExpose0m events are accumulated into a region. When the final event is received, the event manager replaces the rectangle in the event with the bounding box for the region and calls the widget's expose procedure, passing the modified exposure event and (unless 4mXtExposeNoRegion24m is specified) the region. For more information on regions, see Section 16.5 in 4mXlib24m 4m--0m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m.) The values have the following interpretation: 4mXtExposeNoCompress0m No exposure compression is performed; every selected event is individually dispatched to the expose proce- dure with a 4mregion24m argument of NULL. 4mXtExposeCompressSeries0m Each series of exposure events is coalesced into a sin- gle event, which is dispatched when an exposure event with count equal to zero is reached. 4mXtExposeCompressMultiple0m Consecutive series of exposure events are coalesced into a single event, which is dispatched when an expo- sure event with count equal to zero is reached and either the event queue is empty or the next event is not an exposure event for the same widget. 4mXtExposeCompressMaximal0m All expose series currently in the queue for the widget are coalesced into a single event without regard to intervening nonexposure events. If a partial series is in the end of the queue, the Intrinsics will block until the end of the series is received. The additional flags have the following meaning: 4mXtExposeGraphicsExpose0m Specifies that 4mGraphicsExpose24m events are also to be dispatched to the expose procedure. 4mGraphicsExpose0m 1m1860m 1mX Toolkit Intrinsics X11 Release 6.40m events are compressed, if specified, in the same manner as 4mExpose24m events. 4mXtExposeGraphicsExposeMerged0m Specifies in the case of 4mXtExposeCompressMultiple24m and 4mXtExposeCompressMaximal24m that series of 4mGraphicsExpose0m and 4mExpose24m events are to be compressed together, with the final event type determining the type of the event passed to the expose procedure. If this flag is not set, then only series of the same event type as the event at the head of the queue are coalesced. This flag also implies 4mXtExposeGraphicsExpose24m. 4mXtExposeNoExpose0m Specifies that 4mNoExpose24m events are also to be dis- patched to the expose procedure. 4mNoExpose24m events are never coalesced with other exposure events or with each other. 4mXtExposeNoRegion0m Specifies that the final region argument passed to the expose procedure is NULL. The rectangle in the event will still contain bounding box information for the entire series of compressed exposure events. This option saves processing time when the region is not needed by the widget. 1m7.10. Widget Exposure and Visibility0m Every primitive widget and some composite widgets display data on the screen by means of direct Xlib calls. Widgets cannot simply write to the screen and forget what they have done. They must keep enough state to redisplay the window or parts of it if a portion is obscured and then reexposed. 1m7.10.1. Redisplay of a Widget: The expose Procedure0m The expose procedure pointer in a widget class is of type 4mXtExposeProc24m. 1m1870m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtExposeProc)(Widget, XEvent*, Region); Widget 4mw24m; XEvent *4mevent24m; Region 4mregion24m; 4mw24m Specifies the widget instance requiring redisplay. 4mevent24m Specifies the exposure event giving the rectangle requiring redisplay. 4mregion24m Specifies the union of all rectangles in this exposure sequence. |__ The redisplay of a widget upon exposure is the responsibil- ity of the expose procedure in the widget's class record. If a widget has no display semantics, it can specify NULL for the 4mexpose24m field. Many composite widgets serve only as containers for their children and have no expose procedure. Note If the 4mexpose24m procedure is NULL, 4mXtRealizeWidget0m fills in a default bit gravity of 4mNorthWestGravity0m before it calls the widget's realize procedure. If the widget's 4mcompress_exposure24m class field specifies 4mXtExposeNoCompress24m or 4mXtExposeNoRegion24m, or if the event type is 4mNoExpose24m (see Section 7.9.3), 4mregion24m is NULL. If 4mXtEx-0m 4mposeNoCompress24m is not specified and the event type is not 4mNoExpose24m, the event is the final event in the compressed series but 4mx24m, 4my24m, 4mwidth24m, and 4mheight24m contain the bounding box for all the compressed events. The region is created and destroyed by the Intrinsics, but the widget is permitted to modify the region contents. A small simple widget (for example, Label) can ignore the bounding box information in the event and redisplay the entire window. A more complicated widget (for example, Text) can use the bounding box information to minimize the amount of calculation and redisplay it does. A very complex widget uses the region as a clip list in a GC and ignores the event information. The expose procedure is not chained and is therefore responsible for exposure of all superclass data as well as its own. However, it often is possible to anticipate the display needs of several levels of subclassing. For example, rather than implement separate display procedures for the widgets Label, Pushbutton, and Toggle, you could write a single dis- play routine in Label that uses display state fields like 1m1880m 1mX Toolkit Intrinsics X11 Release 6.40m Boolean invert; Boolean highlight; Dimension highlight_width; Label would have 4minvert24m and 4mhighlight24m always 4mFalse24m and 4mhigh-0m 4mlight_width24m zero. Pushbutton would dynamically set 4mhigh-0m 4mlight24m and 4mhighlight_width24m, but it would leave 4minvert24m always 4mFalse24m. Finally, Toggle would dynamically set all three. In this case, the expose procedures for Pushbutton and Toggle inherit their superclass's expose procedure; see Section 1.6.10. 1m7.10.2. Widget Visibility0m Some widgets may use substantial computing resources to pro- duce the data they will display. However, this effort is wasted if the widget is not actually visible on the screen, that is, if the widget is obscured by another application or is iconified. The 4mvisible24m field in the core widget structure provides a hint to the widget that it need not compute display data. This field is guaranteed to be 4mTrue24m by the time an exposure event is processed if any part of the widget is visible, but is 4mFalse24m if the widget is fully obscured. Widgets can use or ignore the 4mvisible24m hint. If they ignore it, they should have 4mvisible_interest24m in their widget class record set 4mFalse24m. In such cases, the 4mvisible24m field is ini- tialized 4mTrue24m and never changes. If 4mvisible_interest24m is 4mTrue24m, the event manager asks for 4mVisibilityNotify24m events for the widget and sets 4mvisible24m to 4mTrue24m on 4mVisibilityUnobscured0m or 4mVisibilityPartiallyObscured24m events and 4mFalse24m on 4mVisibili-0m 4mtyFullyObscured24m events. 1m7.11. X Event Handlers0m Event handlers are procedures called when specified events occur in a widget. Most widgets need not use event handlers explicitly. Instead, they use the Intrinsics translation manager. Event handler procedure pointers are of the type 4mXtEventHandler24m. 1m1890m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtEventHandler)(Widget, XtPointer, XEvent*, Boolean*); Widget 4mw24m; XtPointer 4mclient_data24m; XEvent *4mevent24m; Boolean *4mcontinue_to_dispatch24m; 4mw24m Specifies the widget for which the event arrived. 4mclient_data0m Specifies any client-specific information regis- tered with the event handler. 4mevent24m Specifies the triggering event. 4mcontinue_to_dispatch0m Specifies whether the remaining event handlers registered for the current event should be called. |__ After receiving an event and before calling any event han- dlers, the Boolean pointed to by 4mcontinue_to_dispatch24m is initialized to 4mTrue24m. When an event handler is called, it may decide that further processing of the event is not desirable and may store 4mFalse24m in this Boolean, in which case any handlers remaining to be called for the event are ignored. The circumstances under which the Intrinsics may add event handlers to a widget are currently implementation-dependent. Clients must therefore be aware that storing 4mFalse24m into the 4mcontinue_to_dispatch24m argument can lead to portability prob- lems. 1m7.11.1. Event Handlers That Select Events0m To register an event handler procedure with the dispatch mechanism, use 4mXtAddEventHandler24m. 1m1900m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtAddEventHandler(4mw24m, 4mevent_mask24m, 4mnonmaskable24m, 4mproc24m, 4mclient_data24m) Widget 4mw24m; EventMask 4mevent_mask24m; Boolean 4mnonmaskable24m; XtEventHandler 4mproc24m; XtPointer 4mclient_data24m; 4mw24m Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. 4mevent_mask0m Specifies the event mask for which to call this procedure. 4mnonmaskable0m Specifies whether this procedure should be called on the nonmaskable events (4mGraphicsExpose24m, 4mNoEx-0m 4mpose24m, 4mSelectionClear24m, 4mSelectionRequest24m, 4mSelection-0m 4mNotify24m, 4mClientMessage24m, and 4mMappingNotify24m). 4mproc24m Specifies the procedure to be called. 4mclient_data0m Specifies additional data to be passed to the event handler. |__ The 4mXtAddEventHandler24m function registers a procedure with the dispatch mechanism that is to be called when an event that matches the mask occurs on the specified widget. Each widget has a single registered event handler list, which will contain any procedure/client_data pair exactly once regardless of the manner in which it is registered. If the procedure is already registered with the same 4mclient_data0m value, the specified mask augments the existing mask. If the widget is realized, 4mXtAddEventHandler24m calls 4mXSelectIn-0m 4mput24m, if necessary. The order in which this procedure is called relative to other handlers registered for the same event is not defined. To remove a previously registered event handler, use 4mXtRemoveEventHandler24m. 1m1910m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtRemoveEventHandler(4mw24m, 4mevent_mask24m, 4mnonmaskable24m, 4mproc24m, 4mclient_data24m) Widget 4mw24m; EventMask 4mevent_mask24m; Boolean 4mnonmaskable24m; XtEventHandler 4mproc24m; XtPointer 4mclient_data24m; 4mw24m Specifies the widget for which this procedure is registered. Must be of class Core or any subclass thereof. 4mevent_mask0m Specifies the event mask for which to unregister this procedure. 4mnonmaskable0m Specifies whether this procedure should be removed on the nonmaskable events (4mGraphicsExpose24m, 4mNoEx-0m 4mpose24m, 4mSelectionClear24m, 4mSelectionRequest24m, 4mSelection-0m 4mNotify24m, 4mClientMessage24m, and 4mMappingNotify24m). 4mproc24m Specifies the procedure to be removed. 4mclient_data0m Specifies the registered client data. |__ The 4mXtRemoveEventHandler24m function unregisters an event han- dler registered with 4mXtAddEventHandler24m or 4mXtInsertEven-0m 4mtHandler24m for the specified events. The request is ignored if 4mclient_data24m does not match the value given when the han- dler was registered. If the widget is realized and no other event handler requires the event, 4mXtRemoveEventHandler24m calls 4mXSelectInput24m. If the specified procedure has not been reg- istered or if it has been registered with a different value of 4mclient_data24m, 4mXtRemoveEventHandler24m returns without report- ing an error. To stop a procedure registered with 4mXtAddEventHandler24m or 4mXtInsertEventHandler24m from receiving all selected events, call 4mXtRemoveEventHandler24m with an 4mevent_mask24m of 4mXtAllEvents0m and 4mnonmaskable24m 4mTrue24m. The procedure will continue to receive any events that have been specified in calls to 4mXtAddRawEventHandler24m or 4mXtInsertRawEventHandler24m. To register an event handler procedure that receives events before or after all previously registered event handlers, use 4mXtInsertEventHandler24m. 1m1920m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef enum {XtListHead, XtListTail} XtListPosition; void XtInsertEventHandler(4mw24m, 4mevent_mask24m, 4mnonmaskable24m, 4mproc24m, 4mclient_data24m, 4mposition24m) Widget 4mw24m; EventMask 4mevent_mask24m; Boolean 4mnonmaskable24m; XtEventHandler 4mproc24m; XtPointer 4mclient_data24m; XtListPosition 4mposition24m; 4mw24m Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. 4mevent_mask0m Specifies the event mask for which to call this procedure. 4mnonmaskable0m Specifies whether this procedure should be called on the nonmaskable events (4mGraphicsExpose24m, 4mNoEx-0m 4mpose24m, 4mSelectionClear24m, 4mSelectionRequest24m, 4mSelection-0m 4mNotify24m, 4mClientMessage24m, and 4mMappingNotify24m). 4mproc24m Specifies the procedure to be called. 4mclient_data0m Specifies additional data to be passed to the client's event handler. 4mposition24m Specifies when the event handler is to be called relative to other previously registered handlers. |__ 4mXtInsertEventHandler24m is identical to 4mXtAddEventHandler24m with the additional 4mposition24m argument. If 4mposition24m is 4mXtList-0m 4mHead24m, the event handler is registered so that it is called before any event handlers that were previously registered for the same widget. If 4mposition24m is 4mXtListTail24m, the event handler is registered to be called after any previously reg- istered event handlers. If the procedure is already regis- tered with the same 4mclient_data24m value, the specified mask augments the existing mask and the procedure is repositioned in the list. 1m7.11.2. Event Handlers That Do Not Select Events0m On occasion, clients need to register an event handler pro- cedure with the dispatch mechanism without explicitly 1m1930m 1mX Toolkit Intrinsics X11 Release 6.40m causing the X server to select for that event. To do this, use 4mXtAddRawEventHandler24m. __ | void XtAddRawEventHandler(4mw24m, 4mevent_mask24m, 4mnonmaskable24m, 4mproc24m, 4mclient_data24m) Widget 4mw24m; EventMask 4mevent_mask24m; Boolean 4mnonmaskable24m; XtEventHandler 4mproc24m; XtPointer 4mclient_data24m; 4mw24m Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. 4mevent_mask0m Specifies the event mask for which to call this procedure. 4mnonmaskable0m Specifies whether this procedure should be called on the nonmaskable events (4mGraphicsExpose24m, 4mNoEx-0m 4mpose24m, 4mSelectionClear24m, 4mSelectionRequest24m, 4mSelection-0m 4mNotify24m, 4mClientMessage24m, and 4mMappingNotify24m). 4mproc24m Specifies the procedure to be called. 4mclient_data0m Specifies additional data to be passed to the client's event handler. |__ The 4mXtAddRawEventHandler24m function is similar to 4mXtAddEven-0m 4mtHandler24m except that it does not affect the widget's event mask and never causes an 4mXSelectInput24m for its events. Note that the widget might already have those mask bits set because of other nonraw event handlers registered on it. If the procedure is already registered with the same 4mclient_data24m, the specified mask augments the existing mask. The order in which this procedure is called relative to other handlers registered for the same event is not defined. To remove a previously registered raw event handler, use 4mXtRemoveRawEventHandler24m. 1m1940m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtRemoveRawEventHandler(4mw24m, 4mevent_mask24m, 4mnonmaskable24m, 4mproc24m, 4mclient_data24m) Widget 4mw24m; EventMask 4mevent_mask24m; Boolean 4mnonmaskable24m; XtEventHandler 4mproc24m; XtPointer 4mclient_data24m; 4mw24m Specifies the widget for which this procedure is registered. Must be of class Core or any subclass thereof. 4mevent_mask0m Specifies the event mask for which to unregister this procedure. 4mnonmaskable0m Specifies whether this procedure should be removed on the nonmaskable events (4mGraphicsExpose24m, 4mNoEx-0m 4mpose24m, 4mSelectionClear24m, 4mSelectionRequest24m, 4mSelection-0m 4mNotify24m, 4mClientMessage24m, and 4mMappingNotify24m). 4mproc24m Specifies the procedure to be registered. 4mclient_data0m Specifies the registered client data. |__ The 4mXtRemoveRawEventHandler24m function unregisters an event handler registered with 4mXtAddRawEventHandler24m or 4mXtInsertRaw-0m 4mEventHandler24m for the specified events without changing the window event mask. The request is ignored if 4mclient_data0m does not match the value given when the handler was regis- tered. If the specified procedure has not been registered or if it has been registered with a different value of 4mclient_data24m, 4mXtRemoveRawEventHandler24m returns without report- ing an error. To stop a procedure registered with 4mXtAddRawEventHandler24m or 4mXtInsertRawEventHandler24m from receiving all nonselected events, call 4mXtRemoveRawEventHandler24m with an 4mevent_mask24m of 4mXtAllEvents24m and 4mnonmaskable24m 4mTrue24m. The procedure will con- tinue to receive any events that have been specified in calls to 4mXtAddEventHandler24m or 4mXtInsertEventHandler24m. To register an event handler procedure that receives events before or after all previously registered event handlers without selecting for the events, use 4mXtInsertRawEven-0m 4mtHandler24m. 1m1950m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtInsertRawEventHandler(4mw24m, 4mevent_mask24m, 4mnonmaskable24m, 4mproc24m, 4mclient_data24m, 4mposition24m) Widget 4mw24m; EventMask 4mevent_mask24m; Boolean 4mnonmaskable24m; XtEventHandler 4mproc24m; XtPointer 4mclient_data24m; XtListPosition 4mposition24m; 4mw24m Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. 4mevent_mask0m Specifies the event mask for which to call this procedure. 4mnonmaskable0m Specifies whether this procedure should be called on the nonmaskable events (4mGraphicsExpose24m, 4mNoEx-0m 4mpose24m, 4mSelectionClear24m, 4mSelectionRequest24m, 4mSelection-0m 4mNotify24m, 4mClientMessage24m, and 4mMappingNotify24m). 4mproc24m Specifies the procedure to be registered. 4mclient_data0m Specifies additional data to be passed to the client's event handler. 4mposition24m Specifies when the event handler is to be called relative to other previously registered handlers. |__ The 4mXtInsertRawEventHandler24m function is similar to 4mXtIn-0m 4msertEventHandler24m except that it does not modify the widget's event mask and never causes an 4mXSelectInput24m for the speci- fied events. If the procedure is already registered with the same 4mclient_data24m value, the specified mask augments the existing mask and the procedure is repositioned in the list. 1m7.11.3. Current Event Mask0m To retrieve the event mask for a given widget, use 4mXtBuildE-0m 4mventMask24m. 1m1960m 1mX Toolkit Intrinsics X11 Release 6.40m __ | EventMask XtBuildEventMask(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Core or any subclass thereof. |__ The 4mXtBuildEventMask24m function returns the event mask repre- senting the logical OR of all event masks for event handlers registered on the widget with 4mXtAddEventHandler24m and 4mXtIn-0m 4msertEventHandler24m and all event translations, including accelerators, installed on the widget. This is the same event mask stored into the 4mXSetWindowAttributes24m structure by 4mXtRealizeWidget24m and sent to the server when event handlers and translations are installed or removed on the realized widget. 1m7.11.4. Event Handlers for X11 Protocol Extensions0m To register an event handler procedure with the Intrinsics dispatch mechanism according to an event type, use 4mXtIn-0m 4msertEventTypeHandler24m. 1m1970m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtInsertEventTypeHandler(4mwidget24m, 4mevent_type24m, 4mselect_data24m, 4mproc24m, 4mclient_data24m, 4mposition24m) Widget 4mwidget24m; int 4mevent_type24m; XtPointer 4mselect_data24m; XtEventHandler 4mproc24m; XtPointer 4mclient_data24m; XtListPosition 4mposition24m; 4mwidget24m Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. 4mevent_type0m Specifies the event type for which to call this event handler. 4mselect_data0m Specifies data used to request events of the spec- ified type from the server, or NULL. 4mproc24m Specifies the event handler to be called. 4mclient_data0m Specifies additional data to be passed to the event handler. 4mposition24m Specifies when the event handler is to be called relative to other previously registered handlers. |__ 4mXtInsertEventTypeHandler24m registers a procedure with the dis- patch mechanism that is to be called when an event that matches the specified 4mevent_type24m is dispatched to the speci- fied 4mwidget24m. If 4mevent_type24m specifies one of the core X protocol events, then 4mselect_data24m must be a pointer to a value of type 4mEvent-0m 4mMask24m, indicating the event mask to be used to select for the desired event. This event mask is included in the value returned by 4mXtBuildEventMask24m. If the widget is realized, 4mXtInsertEventTypeHandler24m calls 4mXSelectInput24m if necessary. Specifying NULL for 4mselect_data24m is equivalent to specifying a pointer to an event mask containing 0. This is similar to the 4mXtInsertRawEventHandler24m function. If 4mevent_type24m specifies an extension event type, then the semantics of the data pointed to by 4mselect_data24m are defined by the extension selector registered for the specified event type. In either case the Intrinsics are not required to copy the data pointed to by 4mselect_data24m, so the caller must ensure 1m1980m 1mX Toolkit Intrinsics X11 Release 6.40m that it remains valid as long as the event handler remains registered with this value of 4mselect_data24m. The 4mposition24m argument allows the client to control the order of invocation of event handlers registered for the same event type. If the client does not care about the order, it should normally specify 4mXtListTail24m, which registers this event handler after any previously registered handlers for this event type. Each widget has a single registered event handler list, which will contain any procedure/client_data pair exactly once if it is registered with 4mXtInsertEventTypeHandler24m, regardless of the manner in which it is registered and regardless of the value(s) of 4mselect_data24m. If the procedure is already registered with the same 4mclient_data24m value, the specified mask augments the existing mask and the procedure is repositioned in the list. To remove an event handler registered with 4mXtInsertEvent-0m 4mTypeHandler24m, use 4mXtRemoveEventTypeHandler24m. __ | void XtRemoveEventTypeHandler(4mwidget24m, 4mevent_type24m, 4mselect_data24m, 4mproc24m, 4mclient_data24m) Widget 4mwidget24m; int 4mevent_type24m; XtPointer 4mselect_data24m; XtEventHandler 4mproc24m; XtPointer 4mclient_data24m; 4mwidget24m Specifies the widget for which the event handler was registered. Must be of class Core or any sub- class thereof. 4mevent_type0m Specifies the event type for which the handler was registered. 4mselect_data0m Specifies data used to deselect events of the specified type from the server, or NULL. 4mproc24m Specifies the event handler to be removed. 4mclient_data0m Specifies the additional client data with which the procedure was registered. |__ The 4mXtRemoveEventTypeHandler24m function unregisters an event handler registered with 4mXtInsertEventTypeHandler24m for the 1m1990m 1mX Toolkit Intrinsics X11 Release 6.40m specified event type. The request is ignored if 4mclient_data0m does not match the value given when the handler was regis- tered. If 4mevent_type24m specifies one of the core X protocol events, 4mselect_data24m must be a pointer to a value of type 4mEvent-0m 4mMask,24mindicating mask to be used to deselect for the appro- priate event. If the widget is realized, 4mXtRemoveEventType-0m 4mHandler24m calls 4mXSelectInput24m if necessary. Specifying NULL for 4mselect_data24m is equivalent to specifying a pointer to an event mask containing 0. This is similar to the 4mXtRemoveR-0m 4mawEventHandler24m function. If 4mevent_type24m specifies an extension event type, then the semantics of the data pointed to by 4mselect_data24m are defined by the extension selector registered for the specified event type. To register a procedure to select extension events for a widget, use 4mXtRegisterExtensionSelector24m. __ | void XtRegisterExtensionSelector(4mdisplay24m, 4mmin_event_type24m, 4mmax_event_type24m, 4mproc24m, 4mclient_data24m) Display 4m*display24m; int 4mmin_event_type24m; int 4mmax_event_type24m; XtExtensionSelectProc 4mproc24m; XtPointer 4mclient_data24m; 4mdisplay24m Specifies the display for which the extension selector is to be registered. 4mmin_event_type0m 4mmax_event_type24m Specifies the range of event types for the extension. 4mproc24m Specifies the extension selector procedure. 4mclient_data24m Specifies additional data to be passed to the extension selector. |__ The 4mXtRegisterExtensionSelector24m function registers a proce- dure to arrange for the delivery of extension events to wid- gets. If 4mmin_event_type24m and 4mmax_event_type24m match the parameters to a previous call to 4mXtRegisterExtensionSelector24m for the same 4mdisplay24m, then 4mproc24m and 4mclient_data24m replace the previously 1m2000m 1mX Toolkit Intrinsics X11 Release 6.40m registered values. If the range specified by 4mmin_event_type0m and 4mmax_event_type24m overlaps the range of the parameters to a previous call for the same display in any other way, an error results. When a widget is realized, after the 4mcore.realize24m method is called, the Intrinsics check to see if any event handler specifies an event type within the range of a registered extension selector. If so, the Intrinsics call each such selector. If an event type handler is added or removed, the Intrinsics check to see if the event type falls within the range of a registered extension selector, and if it does, calls the selector. In either case the Intrinsics pass a list of all the widget's event types that are within the selector's range. The corresponding select data are also passed. The selector is responsible for enabling the deliv- ery of extension events required by the widget. An extension selector is of type 4mXtExtensionSelectProc24m. __ | typedef void (*XtExtensionSelectProc)(Widget, int *, XtPointer *, int, XtPointer); Widget 4mwidget24m; int *4mevent_types24m; XtPointer *4mselect_data24m; int 4mcount24m; XtPointer 4mclient_data24m; 4mwidget24m Specifies the widget that is being realized or is having an event handler added or removed. 4mevent_types0m Specifies a list of event types that the widget has registered event handlers for. 4mselect_data0m Specifies a list of the select_data parameters specified in 4mXtInsertEventTypeHandler24m. 4mcount24m Specifies the number of entries in the 4mevent_types0m and 4mselect_data24m lists. 4mclient_data0m Specifies the additional client data with which the procedure was registered. |__ The 4mevent_types24m and 4mselect_data24m lists will always have the same number of elements, specified by 4mcount24m. Each event type/select data pair represents one call to 4mXtInsertEvent-0m 4mTypeHandler24m. 1m2010m 1mX Toolkit Intrinsics X11 Release 6.40m To register a procedure to dispatch events of a specific type within 4mXtDispatchEvent24m, use 4mXtSetEventDispatcher24m. __ | XtEventDispatchProc XtSetEventDispatcher(4mdisplay24m, 4mevent_type24m, 4mproc24m) Display *4mdisplay24m; int 4mevent_type24m; XtEventDispatchProc 4mproc24m; 4mdisplay24m Specifies the display for which the event dis- patcher is to be registered. 4mevent_type0m Specifies the event type for which the dispatcher should be invoked. 4mproc24m Specifies the event dispatcher procedure. |__ The 4mXtSetEventDispatcher24m function registers the event dis- patcher procedure specified by 4mproc24m for events with the type 4mevent_type24m. The previously registered dispatcher (or the default dispatcher if there was no previously registered dispatcher) is returned. If 4mproc24m is NULL, the default pro- cedure is restored for the specified type. In the future, when 4mXtDispatchEvent24m is called with an event type of 4mevent_type24m, the specified 4mproc24m (or the default dis- patcher) is invoked to determine a widget to which to dis- patch the event. The default dispatcher handles the Intrinsics modal cascade and keyboard focus mechanisms, handles the semantics of 4mcom-0m 4mpress_enterleave24m and 4mcompress_motion24m, and discards all extension events. An event dispatcher procedure pointer is of type 4mXtEventDis-0m 4mpatchProc24m. __ | typedef Boolean (*XtEventDispatchProc)(XEvent*) XEvent *4mevent24m; 4mevent24m Passes the event to be dispatched. |__ The event dispatcher procedure should determine whether this event is of a type that should be dispatched to a widget. 1m2020m 1mX Toolkit Intrinsics X11 Release 6.40m If the event should be dispatched to a widget, the event dispatcher procedure should determine the appropriate widget to receive the event, call 4mXFilterEvent24m with the window of this widget, or 4mNone24m if the event is to be discarded, and if 4mXFilterEvent24m returns 4mFalse24m, dispatch the event to the widget using 4mXtDispatchEventToWidget24m. The procedure should return 4mTrue24m if either 4mXFilterEvent24m or 4mXtDispatchEventToWidget0m returned 4mTrue24m and 4mFalse24m otherwise. If the event should not be dispatched to a widget, the event dispatcher procedure should attempt to dispatch the event elsewhere as appropriate and return 4mTrue24m if it successfully dispatched the event and 4mFalse24m otherwise. Some dispatchers for extension events may wish to forward events according to the Intrinsics' keyboard focus mecha- nism. To determine which widget is the end result of key- board event forwarding, use 4mXtGetKeyboardFocusWidget24m. __ | Widget XtGetKeyboardFocusWidget(4mwidget24m) Widget 4mwidget24m; 4mwidget24m Specifies the widget to get forwarding information for. |__ The 4mXtGetKeyboardFocusWidget24m function returns the widget that would be the end result of keyboard event forwarding for a keyboard event for the specified widget. To dispatch an event to a specified widget, use 4mXtDis-0m 4mpatchEventToWidget24m. __ | Boolean XtDispatchEventToWidget(4mwidget24m, 4mevent24m) Widget 4mwidget24m; XEvent *4mevent24m; 4mwidget24m Specifies the widget to which to dispatch the event. 4mevent24m Specifies a pointer to the event to be dispatched. |__ The 4mXtDispatchEventToWidget24m function scans the list of reg- istered event handlers for the specified widget and calls each handler that has been registered for the specified 1m2030m 1mX Toolkit Intrinsics X11 Release 6.40m event type, subject to the 4mcontinue_to_dispatch24m value returned by each handler. The Intrinsics behave as if event handlers were registered at the head of the list for 4mExpose24m, 4mNoExpose24m, 4mGraphicsExpose24m, and 4mVisibilityNotify24m events to invoke the widget's expose procedure according to the expo- sure compression rules and to update the widget's 4mvisible0m field if 4mvisible_interest24m is 4mTrue24m. These internal event handlers never set 4mcontinue_to_dispatch24m to 4mFalse24m. 4mXtDispatchEventToWidget24m returns 4mTrue24m if any event handler was called and 4mFalse24m otherwise. 1m7.12. Using the Intrinsics in a Multi-Threaded Environment0m The Intrinsics may be used in environments that offer multi- ple threads of execution within the context of a single process. A multi-threaded application using the Intrinsics must explicitly initialize the toolkit for mutually exclu- sive access by calling 4mXtToolkitThreadInitialize24m. 1m7.12.1. Initializing a Multi-Threaded Intrinsics Applica-0m 1mtion0m To test and initialize Intrinsics support for mutually exclusive thread access, call 4mXtToolkitThreadInitialize24m. __ | Boolean XtToolkitThreadInitialize() |__ 4mXtToolkitThreadInitialize24m returns 1mTrue 22mif the Intrinsics support mutually exclusive thread access, otherwise it returns 1mFalse22m. 1mXtToolkitThreadInitialize 22mmust be called before 4mXtCreateApplicationContext24m, 4mXtAppInitialize24m, 4mXtOpe-0m 4mnApplication24m, or 4mXtSetLanguageProc24m is called. 1mXtToolkit-0m 1mThreadInitialize 22mmay be called more than once; however, the application writer must ensure that it is not called simul- taneously by two or more threads. 1m7.12.2. Locking X Toolkit Data Structures0m The Intrinsics employs two levels of locking: application context and process. Locking an application context ensures mutually exclusive access by a thread to the state associ- ated with the application context, including all displays and widgets associated with it. Locking a process ensures mutually exclusive access by a thread to Intrinsics process global data. 1m2040m 1mX Toolkit Intrinsics X11 Release 6.40m A client may acquire a lock multiple times and the effect is cumulative. The client must ensure that the lock is released an equal number of times in order for the lock to be acquired by another thread. Most application writers will have little need to use lock- ing as the Intrinsics performs the necessary locking inter- nally. Resource converters are an exception. They require the application context or process to be locked before the application can safely call them directly, for example: ... XtAppLock(app_context); XtCvtStringToPixel(dpy, args, num_args, fromVal, toVal, closure_ret); XtAppUnlock(app_context); ... When the application relies upon 4mXtConvertAndStore24m or a con- verter to provide the storage for the results of a conver- sion, the application should acquire the process lock before calling out and hold the lock until the results have been copied. Application writers who write their own utility functions, such as one which retrieves the being_destroyed field from a widget instance, must lock the application context before accessing widget internal data. For example: #include Boolean BeingDestroyed (widget) Widget widget; { Boolean ret; XtAppLock(XtWidgetToApplicationContext(widget)); ret = widget->core.being_destroyed; XtAppUnlock(XtWidgetToApplicationContext(widget)); return ret; } A client that wishes to atomically call two or more Intrin- sics functions must lock the application context. For exam- ple: 1m2050m 1mX Toolkit Intrinsics X11 Release 6.40m ... XtAppLock(XtWidgetToApplicationContext(widget)); XtUnmanageChild (widget1); XtManageChild (widget2); XtAppUnlock(XtWidgetToApplicationContext(widget)); ... 1m7.12.2.1. Locking the Application Context0m To ensure mutual exclusion of application context, display, or widget internal state, use 4mXtAppLock.0m __ | void XtAppLock(4mapp_context24m) XtAppContext 4mapp_context24m; 4mapp_context0m Specifies the application context to lock. |__ 1mXtAppLock 22mblocks until it is able to acquire the lock. Locking the application context also ensures that only the thread holding the lock makes Xlib calls from within Xt. An application that makes its own direct Xlib calls must either lock the application context around every call or enable thread locking in Xlib. To unlock a locked application context, use 4mXtAppUnlock.0m __ | void XtAppUnlock(4mapp_context24m) XtAppContext 4mapp_context24m; 4mapp_context0m Specifies the application context that was previ- ously locked. |__ 1m7.12.2.2. Locking the Process0m To ensure mutual exclusion of X Toolkit process global data, a widget writer must use 4mXtProcessLock.0m 1m2060m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtProcessLock() |__ 1mXtProcessLock 22mblocks until it is able to acquire the lock. Widget writers may use XtProcessLock to guarantee mutually exclusive access to widget static data. To unlock a locked process, use 4mXtProcessUnlock24m. __ | void XtProcessUnlock() |__ To lock both an application context and the process at the same time, call 4mXtAppLock24m first and then 4mXtProcessLock24m. To release both locks, call 4mXtProcessUnlock24m first and then 4mXtAppUnlock24m. The order is important to avoid deadlock. 1m7.12.3. Event Management in a Multi-Threaded Environment0m In a nonthreaded environment an application writer could reasonably assume that it is safe to exit the application from a quit callback. This assumption may no longer hold true in a multi-threaded environment; therefore it is desir- able to provide a mechanism to terminate an event-processing loop without necessarily terminating its thread. To indicate that the event loop should terminate after the current event dispatch has completed, use 4mXtAppSetExitFlag24m. __ | void XtAppSetExitFlag(4mapp_context24m) XtAppContext 4mapp_context24m; 4mapp_context0m Specifies the application context. |__ 4mXtAppMainLoop24m tests the value of the flag and will return if the flag is 1mTrue22m. Application writers who implement their own main loop may test the value of the exit flag with 4mXtAppGetExitFlag24m. 1m2070m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Boolean XtAppGetExitFlag(4mapp_context24m) XtAppContext 4mapp_context24m; 4mapp_context0m Specifies the application context. |__ 4mXtAppGetExitFlag24m will normally return 1mFalse22m, indicating that event processing may continue. When 4mXtAppGetExitFlag0m returns 1mTrue22m, the loop must terminate and return to the caller, which might then destroy the application context. Application writers should be aware that, if a thread is blocked in 4mXtAppNextEvent24m, 4mXtAppPeekEvent24m, or 4mXtAppProces-0m 4msEvent24m and another thread in the same application context opens a new display, adds an alternate input, or a timeout, any new source(s) will not normally be "noticed" by the blocked thread. Any new sources are "noticed" the next time one of these functions is called. The Intrinsics manage access to events on a last-in, first- out basis. If multiple threads in the same application con- text block in 4mXtAppNextEvent24m, 4mXtAppPeekEvent24m, or 4mXtAppPro-0m 4mcessEvent24m, the last thread to call one of these functions is the first thread to return. 1m2080m 1mX Toolkit Intrinsics X11 Release 6.40m 1mChapter 80m 1mCallbacks0m Applications and other widgets often need to register a pro- cedure with a widget that gets called under certain prespec- ified conditions. For example, when a widget is destroyed, every procedure on the widget's 4mdestroy_callbacks24m list is called to notify clients of the widget's impending doom. Every widget has an XtNdestroyCallbacks callback list resource. Widgets can define additional callback lists as they see fit. For example, the Pushbutton widget has a callback list to notify clients when the button has been activated. Except where otherwise noted, it is the intent that all Intrinsics functions may be called at any time, including from within callback procedures, action routines, and event handlers. 1m8.1. Using Callback Procedure and Callback List Definitions0m Callback procedure pointers for use in callback lists are of type 4mXtCallbackProc24m. __ | typedef void (*XtCallbackProc)(Widget, XtPointer, XtPointer); Widget 4mw24m; XtPointer 4mclient_data24m; XtPointer 4mcall_data24m; 4mw24m Specifies the widget owning the list in which the callback is registered. 4mclient_data0m Specifies additional data supplied by the client when the procedure was registered. 4mcall_data24m Specifies any callback-specific data the widget wants to pass to the client. For example, when Scrollbar executes its XtNthumbChanged callback list, it passes the new position of the thumb. |__ The 4mclient_data24m argument provides a way for the client reg- istering the callback procedure also to register client- 1m2090m 1mX Toolkit Intrinsics X11 Release 6.40m specific data, for example, a pointer to additional informa- tion about the widget, a reason for invoking the callback, and so on. The 4mclient_data24m value may be NULL if all neces- sary information is in the widget. The 4mcall_data24m argument is a convenience to avoid having simple cases where the client could otherwise always call 4mXtGetValues24m or a widget- specific function to retrieve data from the widget. Widgets should generally avoid putting complex state information in 4mcall_data24m. The client can use the more general data retrieval methods, if necessary. Whenever a client wants to pass a callback list as an argu- ment in an 4mXtCreateWidget24m, 4mXtSetValues24m, or 4mXtGetValues24m call, it should specify the address of a NULL-terminated array of type 4mXtCallbackList24m. __ | typedef struct { XtCallbackProc callback; XtPointer closure; } XtCallbackRec, *XtCallbackList; |__ For example, the callback list for procedures A and B with client data clientDataA and clientDataB, respectively, is static XtCallbackRec callbacks[] = { {A, (XtPointer) clientDataA}, {B, (XtPointer) clientDataB}, {(XtCallbackProc) NULL, (XtPointer) NULL} }; Although callback lists are passed by address in arglists and varargs lists, the Intrinsics recognize callback lists through the widget resource list and will copy the contents when necessary. Widget initialize and set_values procedures should not allocate memory for the callback list contents. The Intrinsics automatically do this, potentially using a different structure for their internal representation. 1m8.2. Identifying Callback Lists0m Whenever a widget contains a callback list for use by clients, 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. All the callback manipulation func- tions described in this chapter except 4mXtCallCallbackList0m 1m2100m 1mX Toolkit Intrinsics X11 Release 6.40m check to see that the requested callback list is indeed implemented by the widget. For the Intrinsics to find and correctly handle callback lists, they must be declared with a resource type of 4mXtR-0m 4mCallback24m. The internal representation of a callback list is implementation-dependent; widgets may make no assumptions about the value stored in this resource if it is non-NULL. Except to compare the value to NULL (which is equivalent to 4mXtCallbackStatus24m 4mXtCallbackHasNone24m), access to callback list resources must be made through other Intrinsics procedures. 1m8.3. Adding Callback Procedures0m To add a callback procedure to a widget's callback list, use 4mXtAddCallback24m. __ | void XtAddCallback(4mw24m, 4mcallback_name,24m 4mcallback24m, 4mclient_data24m) Widget 4mw24m; String 4mcallback_name24m; XtCallbackProc 4mcallback24m; XtPointer 4mclient_data24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. 4mcallback_name0m Specifies the callback list to which the procedure is to be appended. 4mcallback24m Specifies the callback procedure. 4mclient_data0m Specifies additional data to be passed to the specified procedure when it is invoked, or NULL. |__ A callback will be invoked as many times as it occurs in the callback list. To add a list of callback procedures to a given widget's callback list, use 4mXtAddCallbacks24m. 1m2110m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtAddCallbacks(4mw24m, 4mcallback_name,24m 4mcallbacks24m) Widget 4mw24m; String 4mcallback_name24m; XtCallbackList 4mcallbacks24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. 4mcallback_name0m Specifies the callback list to which the proce- dures are to be appended. 4mcallbacks24m Specifies the null-terminated list of callback procedures and corresponding client data. |__ 1m8.4. Removing Callback Procedures0m To delete a callback procedure from a widget's callback list, use 4mXtRemoveCallback24m. __ | void XtRemoveCallback(4mw24m, 4mcallback_name24m, 4mcallback24m, 4mclient_data24m) Widget 4mw24m; String 4mcallback_name24m; XtCallbackProc 4mcallback24m; XtPointer 4mclient_data24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. 4mcallback_name0m Specifies the callback list from which the proce- dure is to be deleted. 4mcallback24m Specifies the callback procedure. 4mclient_data0m Specifies the client data to match with the regis- tered callback entry. |__ The 4mXtRemoveCallback24m function removes a callback only if both the procedure and the client data match. To delete a list of callback procedures from a given wid- get's callback list, use 4mXtRemoveCallbacks24m. 1m2120m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtRemoveCallbacks(4mw24m, 4mcallback_name24m, 4mcallbacks24m) Widget 4mw24m; String 4mcallback_name24m; XtCallbackList 4mcallbacks24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. 4mcallback_name0m Specifies the callback list from which the proce- dures are to be deleted. 4mcallbacks24m Specifies the null-terminated list of callback procedures and corresponding client data. |__ To delete all callback procedures from a given widget's callback list and free all storage associated with the call- back list, use 4mXtRemoveAllCallbacks24m. __ | void XtRemoveAllCallbacks(4mw24m, 4mcallback_name24m) Widget 4mw24m; String 4mcallback_name24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. 4mcallback_name0m Specifies the callback list to be cleared. |__ 1m8.5. Executing Callback Procedures0m To execute the procedures in a given widget's callback list, specifying the callback list by resource name, use 4mXtCall-0m 4mCallbacks24m. 1m2130m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtCallCallbacks(4mw24m, 4mcallback_name24m, 4mcall_data24m) Widget 4mw24m; String 4mcallback_name24m; XtPointer 4mcall_data24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. 4mcallback_name0m Specifies the callback list to be executed. 4mcall_data24m Specifies a callback-list-specific data value to pass to each of the callback procedure in the list, or NULL. |__ 4mXtCallCallbacks24m calls each of the callback procedures in the list named by 4mcallback_name24m in the specified widget, passing the client data registered with the procedure and 4mcall-data24m. To execute the procedures in a callback list, specifying the callback list by address, use 4mXtCallCallbackList24m. __ | void XtCallCallbackList(4mwidget24m, 4mcallbacks24m, 4mcall_data24m) Widget 4mwidget24m; XtCallbackList 4mcallbacks24m; XtPointer 4mcall_data24m; 4mwidget24m Specifies the widget instance that contains the callback list. Must be of class Object or any subclass thereof. 4mcallbacks24m Specifies the callback list to be executed. 4mcall_data24m Specifies a callback-list-specific data value to pass to each of the callback procedures in the list, or NULL. |__ The 4mcallbacks24m parameter must specify the contents of a wid- get or object resource declared with representation type 4mXtRCallback24m. If 4mcallbacks24m is NULL, 4mXtCallCallbackList0m returns immediately; otherwise it calls each of the callback procedures in the list, passing the client data and 4mcall_data24m. 1m2140m 1mX Toolkit Intrinsics X11 Release 6.40m 1m8.6. Checking the Status of a Callback List0m To find out the status of a given widget's callback list, use 4mXtHasCallbacks24m. __ | typedef enum {XtCallbackNoList, XtCallbackHasNone, XtCallbackHasSome} XtCallbackStatus; XtCallbackStatus XtHasCallbacks(4mw24m, 4mcallback_name24m) Widget 4mw24m; String 4mcallback_name24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. 4mcallback_name0m Specifies the callback list to be checked. |__ The 4mXtHasCallbacks24m function first checks to see if the wid- get has a callback list identified by 4mcallback_name24m. If the callback list does not exist, 4mXtHasCallbacks24m returns 4mXtCall-0m 4mbackNoList24m. If the callback list exists but is empty, it returns 4mXtCallbackHasNone24m. If the callback list exists and has at least one callback registered, it returns 4mXtCallback-0m 4mHasSome24m. 1m2150m 1mX Toolkit Intrinsics X11 Release 6.40m 1mChapter 90m 1mResource Management0m A resource is a field in the widget record with a corre- sponding resource entry in the 4mresources24m list of the widget or any of its superclasses. This means that the field is settable by 4mXtCreateWidget24m (by naming the field in the argu- ment list), by an entry in a resource file (by using either the name or class), and by 4mXtSetValues24m. In addition, it is readable by 4mXtGetValues24m. Not all fields in a widget record are resources. Some are for bookkeeping use by the generic routines (like 4mmanaged24m and 4mbeing_destroyed24m). Others can be for local bookkeeping, and still others are derived from resources (many graphics contexts and pixmaps). Widgets typically need to obtain a large set of resources at widget creation time. Some of the resources come from the argument list supplied in the call to 4mXtCreateWidget24m, some from the resource database, and some from the internal defaults specified by the widget. Resources are obtained first from the argument list, then from the resource data- base for all resources not specified in the argument list, and last, from the internal default, if needed. 1m9.1. Resource Lists0m A resource entry specifies a field in the widget, the tex- tual name and class of the field that argument lists and external resource files use to refer to the field, and a default value that the field should get if no value is spec- ified. The declaration for the 4mXtResource24m structure is __ | typedef struct { String resource_name; String resource_class; String resource_type; Cardinal resource_size; Cardinal resource_offset; String default_type; XtPointer default_addr; } XtResource, *XtResourceList; |__ 1m2160m 1mX Toolkit Intrinsics X11 Release 6.40m When the resource list is specified as the 4mCoreClassPart24m, 4mObjectClassPart24m, 4mRectObjClassPart24m, or 4mConstraintClassPart0m 4mresources24m field, the strings pointed to by 4mresource_name24m, 4mresource_class24m, 4mresource_type24m, and 4mdefault_type24m must be per- manently allocated prior to or during the execution of the class initialization procedure and must not be subsequently deallocated. The 4mresource_name24m field contains the name used by clients to access the field in the widget. By convention, it starts with a lowercase letter and is spelled exactly like the field name, except all underscores (_) are deleted and the next letter is replaced by its uppercase counterpart. For example, the resource name for background_pixel becomes backgroundPixel. Resource names beginning with the two- character sequence ``xt'', and resource classes beginning with the two-character sequence ``Xt'' are reserved to the Intrinsics for future standard and implementation-dependent uses. Widget header files typically contain a symbolic name for each resource name. All resource names, classes, and types used by the Intrinsics are named in <4mX11/StringDefs.h24m>. The Intrinsics's symbolic resource names begin with ``XtN'' and are followed by the string name (for example, XtNbackgroundPixel for backgroundPixel). The 4mresource_class24m field contains the class string used in resource specification files to identify the field. A resource class provides two functions: · It isolates an application from different representa- tions that widgets can use for a similar resource. · It lets you specify values for several actual resources with a single name. A resource class should be chosen to span a group of closely related fields. For example, a widget can have several pixel resources: background, foreground, border, block cursor, pointer cur- sor, and so on. Typically, the background defaults to white and everything else to black. The resource class for each of these resources in the resource list should be chosen so that it takes the minimal number of entries in the resource database to make the background ivory and everything else darkblue. In this case, the background pixel should have a resource class of ``Background'' and all the other pixel entries a resource class of ``Foreground''. Then, the resource file needs only two lines to change all pixels to ivory or dark- blue: 1m2170m 1mX Toolkit Intrinsics X11 Release 6.40m *Background: ivory *Foreground: darkblue Similarly, a widget may have several font resources (such as normal and bold), but all fonts should have the class Font. Thus, changing all fonts simply requires only a single line in the default resource file: *Font: 6x13 By convention, resource classes are always spelled starting with a capital letter to distinguish them from resource names. Their symbolic names are preceded with ``XtC'' (for example, XtCBackground). The 4mresource_type24m field gives the physical representation type of the resource and also encodes information about the specific usage of the field. By convention, it starts with an uppercase letter and is spelled identically to the type name of the field. The resource type is used when resources are fetched to convert from the resource database format (usually 4mString24m) or the format of the resource default value (almost anything, but often 4mString24m) to the desired physical representation (see Section 9.6). The Intrinsics define the following resource types: ------------------------------------------------------ Resource Type Structure or Field Type ------------------------------------------------------ 4mXtRAcceleratorTable24m XtAccelerators 4mXtRAtom24m Atom 4mXtRBitmap24m Pixmap, depth=1 4mXtRBoolean24m Boolean 4mXtRBool24m Bool 4mXtRCallback24m XtCallbackList 4mXtRCardinal24m Cardinal 4mXtRColor24m XColor 4mXtRColormap24m Colormap 4mXtRCommandArgArray24m String* 4mXtRCursor24m Cursor 4mXtRDimension24m Dimension 4mXtRDirectoryString24m String 4mXtRDisplay24m Display* 4mXtREnum24m XtEnum 4mXtREnvironmentArray24m String* 4mXtRFile24m FILE* 4mXtRFloat24m float 4mXtRFont24m Font 4mXtRFontSet24m XFontSet 4mXtRFontStruct24m XFontStruct* 1m2180m 1mX Toolkit Intrinsics X11 Release 6.40m ------------------------------------------------------ Resource Type Structure or Field Type ------------------------------------------------------ 4mXtRFunction24m (*)() 4mXtRGeometry24m char*, format as defined by 4mXParseGeometry0m 4mXtRGravity24m int 4mXtRInitialState24m int 4mXtRInt24m int 4mXtRLongBoolean24m long 4mXtRObject24m Object 4mXtRPixel24m Pixel 4mXtRPixmap24m Pixmap 4mXtRPointer24m XtPointer 4mXtRPosition24m Position 4mXtRRestartStyle24m unsigned char 4mXtRScreen24m Screen* 4mXtRShort24m short 4mXtRSmcConn24m XtPointer 4mXtRString24m String 4mXtRStringArray24m String* 4mXtRStringTable24m String* 4mXtRTranslationTable24m XtTranslations 4mXtRUnsignedChar24m unsigned char 4mXtRVisual24m Visual* 4mXtRWidget24m Widget 4mXtRWidgetClass24m WidgetClass 4mXtRWidgetList24m WidgetList 4mXtRWindow24m Window ------------------------------------------------------ <4mX11/StringDefs.h24m> also defines the following resource types as a convenience for widgets, although they do not have any corresponding data type assigned: 4mXtREditMode24m, 4mXtRJustify24m, and 4mXtROrientation24m. The 4mresource_size24m field is the size of the physical repre- sentation in bytes; you should specify it as 4msizeof24m(4mtype24m) so that the compiler fills in the value. The 4mresource_offset0m field is the offset in bytes of the field within the widget. You should use the 4mXtOffsetOf24m macro to retrieve this value. The 4mdefault_type24m field is the representation type of the default resource value. If 4mdefault_type24m is different from 4mresource_type24m and the default value is needed, the resource manager invokes a conversion procedure from 4mdefault_type24m to 4mresource_type24m. Whenever possible, the default type should be identical to the resource type in order to minimize wid- get creation time. However, there are sometimes no values of the type that the program can easily specify. In this case, it should be a value for which the converter is guar- anteed to work (for example, 4mXtDefaultForeground24m for a pixel resource). The 4mdefault_addr24m field specifies the address of 1m2190m 1mX Toolkit Intrinsics X11 Release 6.40m the default resource value. As a special case, if 4mdefault_type24m is 4mXtRString24m, then the value in the 4mdefault_addr24m field is the pointer to the string rather than a pointer to the pointer. The default is used if a resource is not specified in the argument list or in the resource database or if the conversion from the representation type stored in the resource database fails, which can happen for various reasons (for example, a misspelled entry in a resource file). Two special representation types (XtRImmediate and XtRCall- Proc) are usable only as default resource types. XtRImmedi- ate indicates that the value in the 4mdefault_addr24m field is the actual value of the resource rather than the address of the value. The value must be in the correct representation type for the resource, coerced to an 4mXtPointer24m. No conver- sion is possible, since there is no source representation type. XtRCallProc indicates that the value in the 4mdefault_addr24m field is a procedure pointer. This procedure is automatically invoked with the widget, 4mresource_offset24m, and a pointer to an 4mXrmValue24m in which to store the result. XtRCallProc procedure pointers are of type 4mXtResourceDe-0m 4mfaultProc24m. __ | typedef void (*XtResourceDefaultProc)(Widget, int, XrmValue*); Widget 4mw24m; int 4moffset24m; XrmValue *4mvalue24m; 4mw24m Specifies the widget whose resource value is to be obtained. 4moffset24m Specifies the offset of the field in the widget record. 4mvalue24m Specifies the resource value descriptor to return. |__ The 4mXtResourceDefaultProc24m procedure should fill in the 4mvalue->addr24m field with a pointer to the resource value in its correct representation type. To get the resource list structure for a particular class, use 4mXtGetResourceList24m. 1m2200m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtGetResourceList(4mclass24m, 4mresources_return24m, 4mnum_resources_return24m); WidgetClass 4mclass24m; XtResourceList *4mresources_return24m; Cardinal *4mnum_resources_return24m; 4mclass24m Specifies the object class to be queried. It must be 4mobjectClass24m or any subclass thereof. 4mresources_return0m Returns the resource list. 4mnum_resources_return0m Returns the number of entries in the resource list. |__ If 4mXtGetResourceList24m is called before the class is initial- ized, it returns the resource list as specified in the class record. If it is called after the class has been initial- ized, 4mXtGetResourceList24m returns a merged resource list that includes the resources for all superclasses. The list returned by 4mXtGetResourceList24m should be freed using 4mXtFree0m when it is no longer needed. To get the constraint resource list structure for a particu- lar widget class, use 4mXtGetConstraintResourceList24m. __ | void XtGetConstraintResourceList(4mclass24m, 4mresources_return24m, 4mnum_resources_return24m) WidgetClass 4mclass24m; XtResourceList *4mresources_return24m; Cardinal *4mnum_resources_return24m; 4mclass24m Specifies the object class to be queried. It must be 4mobjectClass24m or any subclass thereof. 4mresources_return0m Returns the constraint resource list. 4mnum_resources_return0m Returns the number of entries in the con- straint resource list. |__ If 4mXtGetConstraintResourceList24m is called before the widget class is initialized, the resource list as specified in the widget class Constraint part is returned. If 4mXtGetCon-0m 4mstraintResourceList24m is called after the widget class has been initialized, the merged resource list for the class and 1m2210m 1mX Toolkit Intrinsics X11 Release 6.40m all Constraint superclasses is returned. If the specified class is not a subclass of 4mconstraintWidgetClass24m, *4mresources_return24m is set to NULL and *4mnum_resources_return0m is set to zero. The list returned by 4mXtGetConstraintRe-0m 4msourceList24m should be freed using 4mXtFree24m when it is no longer needed. The routines 4mXtSetValues24m and 4mXtGetValues24m also use the resource list to set and get widget state; see Sections 9.7.1 and 9.7.2. Here is an abbreviated version of a possible resource list for a Label widget: /* Resources specific to Label */ static XtResource resources[] = { {XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel), XtOffsetOf(LabelRec, label.foreground), XtRString, XtDefaultForeground}, {XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*), XtOffsetOf(LabelRec, label.font), XtRString, XtDefaultFont}, {XtNlabel, XtCLabel, XtRString, sizeof(String), XtOffsetOf(LabelRec, label.label), XtRString, NULL}, . . . } The complete resource name for a field of a widget instance is the concatenation of the application shell name (from 4mXtAppCreateShell24m), the instance names of all the widget's parents up to the top of the widget tree, the instance name of the widget itself, and the resource name of the specified field of the widget. Similarly, the full resource class of a field of a widget instance is the concatenation of the application class (from 4mXtAppCreateShell24m), the widget class names of all the widget's parents up to the top of the wid- get tree, the widget class name of the widget itself, and the resource class of the specified field of the widget. 1m9.2. Byte Offset Calculations0m To determine the byte offset of a field within a structure type, use 4mXtOffsetOf24m. 1m2220m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Cardinal XtOffsetOf(4mstructure_type24m, 4mfield_name24m) 4mType24m 4mstructure_type24m; 4mField24m 4mfield_name24m; 4mstructure_type0m Specifies a type that is declared as a structure. 4mfield_name0m Specifies the name of a member within the struc- ture. |__ The 4mXtOffsetOf24m macro expands to a constant expression that gives the offset in bytes to the specified structure member from the beginning of the structure. It is normally used to statically initialize resource lists and is more portable than 4mXtOffset24m, which serves the same function. To determine the byte offset of a field within a structure pointer type, use 4mXtOffset24m. __ | Cardinal XtOffset(4mpointer_type24m, 4mfield_name24m) 4mType24m 4mpointer_type24m; 4mField24m 4mfield_name24m; 4mpointer_type0m Specifies a type that is declared as a pointer to a structure. 4mfield_name0m Specifies the name of a member within the struc- ture. |__ The 4mXtOffset24m macro expands to a constant expression that gives the offset in bytes to the specified structure member from the beginning of the structure. It may be used to statically initialize resource lists. 4mXtOffset24m is less por- table than 4mXtOffsetOf24m. 1m9.3. Superclass-to-Subclass Chaining of Resource Lists0m The 4mXtCreateWidget24m function gets resources as a superclass- to-subclass chained operation. That is, the resources spec- ified in the 4mobjectClass24m resource list are fetched, then those in 4mrectObjClass24m, and so on down to the resources spec- ified for this widget's class. Within a class, resources are 1m2230m 1mX Toolkit Intrinsics X11 Release 6.40m fetched in the order they are declared. In general, if a widget resource field is declared in a superclass, that field is included in the superclass's resource list and need not be included in the subclass's resource list. For example, the Core class contains a resource entry for 4mbackground_pixel24m. Consequently, the implementation of Label need not also have a resource entry for 4mbackground_pixel24m. However, a subclass, by specifying a resource entry for that field in its own resource list, can override the resource entry for any field declared in a superclass. This is most often done to override the defaults provided in the superclass with new ones. At class initialization time, resource lists for that class are scanned from the superclass down to the class to look for resources with the same offset. A matching resource in a subclass will be reordered to override the superclass entry. If reordering is necessary, a copy of the superclass resource list is made to avoid affecting other subclasses of the superclass. Also at class initialization time, the Intrinsics produce an internal representation of the resource list to optimize access time when creating widgets. In order to save memory, the Intrinsics may overwrite the storage allocated for the resource list in the class record; therefore, widgets must allocate resource lists in writable storage and must not access the list contents directly after the class_initialize procedure has returned. 1m9.4. Subresources0m A widget does not do anything to retrieve its own resources; instead, 4mXtCreateWidget24m does this automatically before call- ing the class initialize procedure. Some widgets have subparts that are not widgets but for which the widget would like to fetch resources. Such wid- gets call 4mXtGetSubresources24m to accomplish this. 1m2240m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtGetSubresources(4mw24m, 4mbase24m, 4mname24m, 4mclass24m, 4mresources24m, 4mnum_resources24m, 4margs24m, 4mnum_args24m) Widget 4mw24m; XtPointer 4mbase24m; String 4mname24m; String 4mclass24m; XtResourceList 4mresources24m; Cardinal 4mnum_resources24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mw24m Specifies the object used to qualify the subpart resource name and class. Must be of class Object or any subclass thereof. 4mbase24m Specifies the base address of the subpart data structure into which the resources will be writ- ten. 4mname24m Specifies the name of the subpart. 4mclass24m Specifies the class of the subpart. 4mresources24m Specifies the resource list for the subpart. 4mnum_resources0m Specifies the number of entries in the resource list. 4margs24m Specifies the argument list to override any other resource specifications. 4mnum_args24m Specifies the number of entries in the argument list. |__ The 4mXtGetSubresources24m function constructs a name and class list from the application name and class, the names and classes of all the object's ancestors, and the object itself. Then it appends to this list the 4mname24m and 4mclass0m pair passed in. The resources are fetched from the argument list, the resource database, or the default values in the resource list. Then they are copied into the subpart record. If 4margs24m is NULL, 4mnum_args24m must be zero. However, if 4mnum_args24m is zero, the argument list is not referenced. 4mXtGetSubresources24m may overwrite the specified resource list with an equivalent representation in an internal format, which optimizes access time if the list is used repeatedly. The resource list must be allocated in writable storage, and the caller must not modify the list contents after the call if the same list is to be used again. Resources fetched by 4mXtGetSubresources24m are reference-counted as if they were 1m2250m 1mX Toolkit Intrinsics X11 Release 6.40m referenced by the specified object. Subresources might therefore be freed from the conversion cache and destroyed when the object is destroyed, but not before then. To fetch resources for widget subparts using varargs lists, use 4mXtVaGetSubresources24m. __ | void XtVaGetSubresources(4mw24m, 4mbase24m, 4mname24m, 4mclass24m, 4mresources24m, 4mnum_resources24m, ...) Widget 4mw24m; XtPointer 4mbase24m; String 4mname24m; String 4mclass24m; XtResourceList 4mresources24m; Cardinal 4mnum_resources24m; 4mw24m Specifies the object used to qualify the subpart resource name and class. Must be of class Object or any subclass thereof. 4mbase24m Specifies the base address of the subpart data structure into which the resources will be writ- ten. 4mname24m Specifies the name of the subpart. 4mclass24m Specifies the class of the subpart. 4mresources24m Specifies the resource list for the subpart. 4mnum_resources0m Specifies the number of entries in the resource list. ... Specifies the variable argument list to override any other resource specifications. |__ 4mXtVaGetSubresources24m is identical in function to 4mXtGetSubre-0m 4msources24m with the 4margs24m and 4mnum_args24m parameters replaced by a varargs list, as described in Section 2.5.1. 1m9.5. Obtaining Application Resources0m To retrieve resources that are not specific to a widget but apply to the overall application, use 4mXtGetApplicationRe-0m 4msources24m. 1m2260m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtGetApplicationResources(4mw24m, 4mbase24m, 4mresources24m, 4mnum_resources24m, 4margs24m, 4mnum_args24m) Widget 4mw24m; XtPointer 4mbase24m; XtResourceList 4mresources24m; Cardinal 4mnum_resources24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mw24m Specifies the object that identifies the resource database to search (the database is that associ- ated with the display for this object). Must be of class Object or any subclass thereof. 4mbase24m Specifies the base address into which the resource values will be written. 4mresources24m Specifies the resource list. 4mnum_resources0m Specifies the number of entries in the resource list. 4margs24m Specifies the argument list to override any other resource specifications. 4mnum_args24m Specifies the number of entries in the argument list. |__ The 4mXtGetApplicationResources24m function first uses the passed object, which is usually an application shell widget, to construct a resource name and class list. The full name and class of the specified object (that is, including its ances- tors, if any) is logically added to the front of each resource name and class. Then it retrieves the resources from the argument list, the resource database, or the resource list default values. After adding base to each address, 4mXtGetApplicationResources24m copies the resources into the addresses obtained by adding 4mbase24m to each 4moffset24m in the resource list. If 4margs24m is NULL, 4mnum_args24m must be zero. However, if 4mnum_args24m is zero, the argument list is not ref- erenced. The portable way to specify application resources is to declare them as members of a structure and pass the address of the structure as the 4mbase24m argument. 4mXtGetApplicationResources24m may overwrite the specified resource list with an equivalent representation in an inter- nal format, which optimizes access time if the list is used repeatedly. The resource list must be allocated in writable storage, and the caller must not modify the list contents after the call if the same list is to be used again. Any per-display resources fetched by 4mXtGetApplicationResources0m 1m2270m 1mX Toolkit Intrinsics X11 Release 6.40m will not be freed from the resource cache until the display is closed. To retrieve resources for the overall application using varargs lists, use 4mXtVaGetApplicationResources24m. __ | void XtVaGetApplicationResources(4mw24m, 4mbase24m, 4mresources24m, 4mnum_resources24m, ...) Widget 4mw24m; XtPointer 4mbase24m; XtResourceList 4mresources24m; Cardinal 4mnum_resources24m; 4mw24m Specifies the object that identifies the resource database to search (the database is that associ- ated with the display for this object). Must be of class Object or any subclass thereof. 4mbase24m Specifies the base address into which the resource values will be written. 4mresources24m Specifies the resource list for the subpart. 4mnum_resources0m Specifies the number of entries in the resource list. ... Specifies the variable argument list to override any other resource specifications. |__ 4mXtVaGetApplicationResources24m is identical in function to 4mXtGetApplicationResources24m with the 4margs24m and 4mnum_args24m parame- ters replaced by a varargs list, as described in Section 2.5.1. 1m9.6. Resource Conversions0m The Intrinsics provide a mechanism for registering represen- tation converters that are automatically invoked by the resource-fetching routines. The Intrinsics additionally provide and register several commonly used converters. This resource conversion mechanism serves several purposes: · It permits user and application resource files to con- tain textual representations of nontextual values. · It allows textual or other representations of default resource values that are dependent on the display, screen, or colormap, and thus must be computed at 1m2280m 1mX Toolkit Intrinsics X11 Release 6.40m runtime. · It caches conversion source and result data. Conver- sions that require much computation or space (for exam- ple, string-to-translation-table) or that require round-trips to the server (for example, string-to-font or string-to-color) are performed only once. 1m9.6.1. Predefined Resource Converters0m The Intrinsics define all the representations used in the Object, RectObj, Core, Composite, Constraint, and Shell wid- get classes. The Intrinsics register the following resource converters that accept input values of representation type 4mXtRString24m. --------------------------------------------------------------------------- Target Representation Converter Name Additional Args --------------------------------------------------------------------------- 4mXtRAcceleratorTable24m 4mXtCvtStringToAccelera-0m 4mtorTable0m 4mXtRAtom24m 4mXtCvtStringToAtom24m Display* 4mXtRBoolean24m 4mXtCvtStringToBoolean0m 4mXtRBool24m 4mXtCvtStringToBool0m 4mXtRCommandArgArray24m 4mXtCvtStringToCommandAr-0m 4mgArray0m 4mXtRCursor24m 4mXtCvtStringToCursor24m Display* 4mXtRDimension24m 4mXtCvtStringToDimension0m 4mXtRDirectoryString24m 4mXtCvtStringToDirectoryS-0m 4mtring0m 4mXtRDisplay24m 4mXtCvtStringToDisplay0m 4mXtRFile24m 4mXtCvtStringToFile0m 4mXtRFloat24m 4mXtCvtStringToFloat0m 4mXtRFont24m 4mXtCvtStringToFont24m Display* 4mXtRFontSet24m 4mXtCvtStringToFontSet24m Display*, String 4mlocale0m 4mXtRFontStruct24m 4mXtCvtStringToFontStruct24m Display* 4mXtRGravity24m 4mXtCvtStringToGravity0m 4mXtRInitialState24m 4mXtCvtStringToInitial-0m 4mState0m 4mXtRInt24m 4mXtCvtStringToInt0m 4mXtRPixel24m 4mXtCvtStringToPixel24m 4mcolorConvertArgs0m 4mXtRPosition24m 4mXtCvtStringToPosition0m 4mXtRRestartStyle24m 4mXtCvtStringToRestart-0m 4mStyle0m 4mXtRShort24m 4mXtCvtStringToShort0m 4mXtRTranslationTable24m 4mXtCvtStringToTransla-0m 4mtionTable0m 4mXtRUnsignedChar24m 4mXtCvtStringToUnsigned-0m 4mChar0m 4mXtRVisual24m 4mXtCvtStringToVisual24m Screen*, Cardinal 4mdepth0m --------------------------------------------------------------------------- 1m2290m 1mX Toolkit Intrinsics X11 Release 6.40m The String-to-Pixel conversion has two predefined constants that are guaranteed to work and contrast with each other: 4mXtDefaultForeground24m and 4mXtDefaultBackground24m. They evaluate to the black and white pixel values of the widget's screen, respectively. If the application resource reverseVideo is 4mTrue24m, they evaluate to the white and black pixel values of the widget's screen, respectively. Similarly, the String- to-Font and String-to-FontStruct converters recognize the constant 4mXtDefaultFont24m and evaluate this in the following manner: · Query the resource database for the resource whose full name is ``xtDefaultFont'', class ``XtDefaultFont'' (that is, no widget name/class prefixes), and use a type 4mXtRString24m value returned as the font name or a type 4mXtRFont24m or 4mXtRFontStruct24m value directly as the resource value. · If the resource database does not contain a value for xtDefaultFont, class XtDefaultFont, or if the returned font name cannot be successfully opened, an implementa- tion-defined font in ISO8859-1 character set encoding is opened. (One possible algorithm is to perform an 4mXListFonts24m using a wildcard font name and use the first font in the list. This wildcard font name should be as broad as possible to maximize the probability of locat- ing a useable font; for example, "-*-*-*-R-*-*-*-120-*-*-*-*-ISO8859-1".) · If no suitable ISO8859-1 font can be found, issue a warning message and return 4mFalse24m. The String-to-FontSet converter recognizes the constant 4mXtDefaultFontSet24m and evaluate this in the following manner: · Query the resource database for the resource whose full name is ``xtDefaultFontSet'', class ``XtDefault- FontSet'' (that is, no widget name/class prefixes), and use a type 4mXtRString24m value returned as the base font name list or a type 4mXtRFontSet24m value directly as the resource value. · If the resource database does not contain a value for xtDefaultFontSet, class XtDefaultFontSet, or if a font set cannot be successfully created from this resource, an implementation-defined font set is created. (One possible algorithm is to perform an 4mXCreateFontSet0m using a wildcard base font name. This wildcard base font name should be as broad as possible to maximize the probability of locating a useable font; for exam- ple, "-*-*-*-R-*-*-*-120-*-*-*-*".) · If no suitable font set can be created, issue a warning message and return 4mFalse24m. 1m2300m 1mX Toolkit Intrinsics X11 Release 6.40m If a font set is created but 4mmissing_charset_list24m is not empty, a warning is issued and the partial font set is returned. The Intrinsics register the String-to-FontSet converter with a conversion argument list that extracts the current process locale at the time the converter is invoked. This ensures that the converter is invoked again if the same conversion is required in a different locale. The String-to-Gravity conversion accepts string values that are the names of window and bit gravities and their numeri- cal equivalents, as defined in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInter-0m 4mface24m: 4mForgetGravity24m, 4mUnmapGravity24m, 4mNorthWestGravity24m, 4mNorth-0m 4mGravity24m, 4mNorthEastGravity24m, 4mWestGravity24m, 4mCenterGravity24m, 4mEast-0m 4mGravity24m, 4mSouthWestGravity24m, 4mSouthGravity24m, 4mSouthEastGravity24m, and 4mStaticGravity24m. Alphabetic case is not significant in the conversion. The String-to-CommandArgArray conversion parses a String into an array of strings. White space characters separate elements of the command line. The converter recognizes the backslash character ``\'' as an escape character to allow the following white space character to be part of the array element. The String-to-DirectoryString conversion recognizes the string ``XtCurrentDirectory'' and returns the result of a call to the operating system to get the current directory. The String-to-RestartStyle conversion accepts the values 4mRestartIfRunning24m, 4mRestartAnyway24m, 4mRestartImmediately24m, and 4mRestartNever24m as defined by the 4mX24m 4mSession24m 4mManagement24m 4mProto-0m 4mcol24m. The String-to-InitialState conversion accepts the values 4mNormalState24m or 4mIconicState24m as defined by the 4mInter-Client0m 4mCommunication24m 4mConventions24m 4mManual24m. The String-to-Visual conversion calls 4mXMatchVisualInfo24m using the 4mscreen24m and 4mdepth24m fields from the core part and returns the first matching Visual on the list. The widget resource list must be certain to specify any resource of type 4mXtRVi-0m 4msual24m after the depth resource. The allowed string values are the visual class names defined in 4mX24m 4mWindow24m 4mSystem24m 4mProto-0m 4mcol24m, Section 8; 4mStaticGray24m, 4mStaticColor24m, 4mTrueColor24m, 4mGrayScale24m, 4mPseudoColor24m, and 4mDirectColor24m. The Intrinsics register the following resource converter that accepts an input value of representation type 4mXtRColor24m. ----------------------------------------------------------------- Target Representation Converter Name Additional Args 1m2310m 1mX Toolkit Intrinsics X11 Release 6.40m ----------------------------------------------------------------- 4mXtRPixel24m 4mXtCvtColorToPixel0m ----------------------------------------------------------------- The Intrinsics register the following resource converters that accept input values of representation type 4mXtRInt24m. ----------------------------------------------------------------- Target Representation Converter Name Additional Args ----------------------------------------------------------------- 4mXtRBoolean24m 4mXtCvtIntToBoolean0m 4mXtRBool24m 4mXtCvtIntToBool0m 4mXtRColor24m 4mXtCvtIntToColor24m 4mcolorConver-0m 4mtArgs0m 4mXtRDimension24m 4mXtCvtIntToDimension0m 4mXtRFloat24m 4mXtCvtIntToFloat0m 4mXtRFont24m 4mXtCvtIntToFont0m 4mXtRPixel24m 4mXtCvtIntToPixel0m 4mXtRPixmap24m 4mXtCvtIntToPixmap0m 4mXtRPosition24m 4mXtCvtIntToPosition0m 4mXtRShort24m 4mXtCvtIntToShort0m 4mXtRUnsignedChar24m 4mXtCvtIntToUnsignedChar0m ----------------------------------------------------------------- The Intrinsics register the following resource converter that accepts an input value of representation type 4mXtRPixel24m. ----------------------------------------------------------------- Target Representation Converter Name Additional Args ----------------------------------------------------------------- 4mXtRColor24m 4mXtCvtPixelToColor0m ----------------------------------------------------------------- 1m9.6.2. New Resource Converters0m Type converters use pointers to 4mXrmValue24m structures (defined in <4mX11/Xresource.h24m>; see Section 15.4 in 4mXlib24m 4m--24m 4mC24m 4mLanguage0m 4mX24m 4mInterface24m) for input and output values. 1m2320m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct { unsigned int size; XPointer addr; } XrmValue, *XrmValuePtr; |__ The 4maddr24m field specifies the address of the data, and the 4msize24m field gives the total number of significant bytes in the data. For values of type 4mString24m, 4maddr24m is the address of the first character and 4msize24m includes the NULL-terminating byte. A resource converter procedure pointer is of type 4mXtTypeCon-0m 4mverter24m. __ | typedef Boolean (*XtTypeConverter)(Display*, XrmValue*, Cardinal*, XrmValue*, XrmValue*, XtPointer*); Display *4mdisplay24m; XrmValue *4margs24m; Cardinal *4mnum_args24m; XrmValue *4mfrom24m; XrmValue *4mto24m; XtPointer *4mconverter_data24m; 4mdisplay24m Specifies the display connection with which this conversion is associated. 4margs24m Specifies a list of additional 4mXrmValue24m arguments to the converter if additional context is needed to perform the conversion, or NULL. For example, the String-to-Font converter needs the widget's 4mdisplay24m, and the String-to-Pixel converter needs the widget's 4mscreen24m and 4mcolormap24m. 4mnum_args24m Specifies the number of entries in 4margs24m. 4mfrom24m Specifies the value to convert. 4mto24m Specifies a descriptor for a location into which to store the converted value. 4mconverter_data0m Specifies a location into which the converter may store converter-specific data associated with this conversion. |__ The 4mdisplay24m argument is normally used only when generating error messages, to identify the application context (with 1m2330m 1mX Toolkit Intrinsics X11 Release 6.40m the function 4mXtDisplayToApplicationContext24m). The 4mto24m argument specifies the size and location into which the converter should store the converted value. If the 4maddr0m field is NULL, the converter should allocate appropriate storage and store the size and location into the 4mto24m descrip- tor. If the type converter allocates the storage, it remains under the ownership of the converter and must not be modified by the caller. The type converter is permitted to use static storage for this purpose, and therefore the caller must immediately copy the data upon return from the converter. If the 4maddr24m field is not NULL, the converter must check the 4msize24m field to ensure that sufficient space has been allocated before storing the converted value. If insufficient space is specified, the converter should update the 4msize24m field with the number of bytes required and return 4mFalse24m without modifying the data at the specified location. If sufficient space was allocated by the caller, the con- verter should update the 4msize24m field with the number of bytes actually occupied by the converted value. For converted values of type 4mXtRString24m, the size should include the NULL- terminating byte, if any. The converter may store any value in the location specified in 4mconverter_data24m; this value will be passed to the destructor, if any, when the resource is freed by the Intrinsics. The converter must return 4mTrue24m if the conversion was suc- cessful and 4mFalse24m otherwise. If the conversion cannot be performed because of an improper source value, a warning message should also be issued with 4mXtAppWarningMsg24m. Most type converters just take the data described by the specified 4mfrom24m argument and return data by writing into the location specified in the 4mto24m argument. A few need other information, which is available in 4margs24m. A type converter can invoke another type converter, which allows differing sources that may convert into a common intermediate result to make maximum use of the type converter cache. Note that if an address is written into 4mto->addr24m, it cannot be that of a local variable of the converter because the data will not be valid after the converter returns. Static variables may be used, as in the following example. If the converter modifies the resource database, the changes affect any in-progress widget creation, 4mXtGetApplicationResources24m, or 4mXtGetSubresources24m in an implementation-defined manner; however, insertion of new entries or changes to existing entries is allowed and will not directly cause an error. The following is an example of a converter that takes a 4mstring24m and converts it to a 4mPixel24m. Note that the 4mdisplay0m parameter is used only to generate error messages; the 1m2340m 1mX Toolkit Intrinsics X11 Release 6.40m 4mScreen24m conversion argument is still required to inform the Intrinsics that the converted value is a function of the particular display (and colormap). #define done(type, value) \ { \ if (toVal->addr != NULL) { \ if (toVal->size < sizeof(type)) {\ toVal->size = sizeof(type);\ return False; \ } \ *(type*)(toVal->addr) = (value);\ } \ else { \ static type static_val; \ static_val = (value); \ toVal->addr = (XPointer)&static_val;\ } \ toVal->size = sizeof(type); \ return True; \ } static Boolean CvtStringToPixel(dpy, args, num_args, fromVal, toVal, converter_data) Display *dpy; XrmValue *args; Cardinal *num_args; XrmValue *fromVal; XrmValue *toVal; XtPointer *converter_data; { static XColor screenColor; XColor exactColor; Screen *screen; Colormap colormap; Status status; if (*num_args != 2) XtAppWarningMsg(XtDisplayToApplicationContext(dpy), "wrongParameters", "cvtStringToPixel", "XtToolkitError", "String to pixel conversion needs screen and colormap arguments", (String *)NULL, (Cardinal *)NULL); screen = *((Screen**) args[0].addr); colormap = *((Colormap *) args[1].addr); if (CompareISOLatin1(str, XtDefaultBackground) == 0) { *closure_ret = False; done(Pixel, WhitePixelOfScreen(screen)); } if (CompareISOLatin1(str, XtDefaultForeground) == 0) { *closure_ret = False; done(Pixel, BlackPixelOfScreen(screen)); 1m2350m 1mX Toolkit Intrinsics X11 Release 6.40m } status = XAllocNamedColor(DisplayOfScreen(screen), colormap, (char*)fromVal->addr, &screenColor, &exactColor); if (status == 0) { String params[1]; Cardinal num_params = 1; params[0] = (String)fromVal->addr; XtAppWarningMsg(XtDisplayToApplicationContext(dpy), "noColormap", "cvtStringToPixel", "XtToolkitError", "Cannot allocate colormap entry for \"%s\"", params, &num_params); *converter_data = (char *) False; return False; } else { *converter_data = (char *) True; done(Pixel, &screenColor.pixel); } } All type converters should define some set of conversion values for which they are guaranteed to succeed so these can be used in the resource defaults. This issue arises only with conversions, such as fonts and colors, where there is no string representation that all server implementations will necessarily recognize. For resources like these, the converter should define a symbolic constant in the same man- ner as 4mXtDefaultForeground24m, 4mXtDefaultBackground24m, and 4mXtDe-0m 4mfaultFont24m. To allow the Intrinsics to deallocate resources produced by type converters, a resource destructor procedure may also be provided. A resource destructor procedure pointer is of type 4mXtDe-0m 4mstructor24m. 1m2360m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtDestructor) (XtAppContext, XrmValue*, XtPointer, XrmValue*, Cardinal*); XtAppContext 4mapp24m; XrmValue *4mto24m; XtPointer 4mconverter_data24m; XrmValue *4margs24m; Cardinal *4mnum_args24m; 4mapp24m Specifies an application context in which the resource is being freed. 4mto24m Specifies a descriptor for the resource produced by the type converter. 4mconverter_data0m Specifies the converter-specific data returned by the type converter. 4margs24m Specifies the additional converter arguments as passed to the type converter when the conversion was performed. 4mnum_args24m Specifies the number of entries in 4margs24m. |__ The destructor procedure is responsible for freeing the resource specified by the 4mto24m argument, including any auxil- iary storage associated with that resource, but not the mem- ory directly addressed by the size and location in the 4mto0m argument or the memory specified by 4margs24m. 1m9.6.3. Issuing Conversion Warnings0m The 4mXtDisplayStringConversionWarning24m procedure is a conve- nience routine for resource type converters that convert from string values. 1m2370m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtDisplayStringConversionWarning(4mdisplay24m, 4mfrom_value24m, 4mto_type24m) Display *4mdisplay24m; String 4mfrom_value24m, 4mto_type24m; 4mdisplay24m Specifies the display connection with which the conversion is associated. 4mfrom_value0m Specifies the string that could not be converted. 4mto_type24m Specifies the target representation type requested. |__ The 4mXtDisplayStringConversionWarning24m procedure issues a warning message using 4mXtAppWarningMsg24m with 4mname24m ``conver- sionError'', 4mtype24m ``string'', 4mclass24m ``XtToolkitError'', and the default message ``Cannot convert "4mfrom_value24m" to type 4mto_type24m''. To issue other types of warning or error messages, the type converter should use 4mXtAppWarningMsg24m or 4mXtAppErrorMsg24m. To retrieve the application context associated with a given display connection, use 4mXtDisplayToApplicationContext24m. __ | XtAppContext XtDisplayToApplicationContext( 4mdisplay24m ) Display *4mdisplay24m; 4mdisplay24m Specifies an open and initialized display connec- tion. |__ The 4mXtDisplayToApplicationContext24m function returns the application context in which the specified 4mdisplay24m was ini- tialized. If the display is not known to the Intrinsics, an error message is issued. 1m9.6.4. Registering a New Resource Converter0m When registering a resource converter, the client must spec- ify the manner in which the conversion cache is to be used when there are multiple calls to the converter. Conversion cache control is specified via an 4mXtCacheType0m argument. 1m2380m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef int XtCacheType; |__ An 4mXtCacheType24m field may contain one of the following val- ues: 4mXtCacheNone0m Specifies that the results of a previous conversion may not be reused to satisfy any other resource requests; the specified converter will be called each time the converted value is required. 4mXtCacheAll0m Specifies that the results of a previous conversion should be reused for any resource request that depends upon the same source value and conversion arguments. 4mXtCacheByDisplay0m Specifies that the results of a previous conversion should be used as for 4mXtCacheAll24m but the destructor will be called, if specified, if 4mXtCloseDisplay24m is called for the display connection associated with the converted value, and the value will be removed from the conversion cache. The qualifier 4mXtCacheRefCount24m may be ORed with any of the above values. If 4mXtCacheRefCount24m is specified, calls to 4mXtCreateWidget24m, 4mXtCreateManagedWidget24m, 4mXtGetApplicationRe-0m 4msources24m, and 4mXtGetSubresources24m that use the converted value will be counted. When a widget using the converted value is destroyed, the count is decremented, and, if the count reaches zero, the destructor procedure will be called and the converted value will be removed from the conversion cache. To register a type converter for all application contexts in a process, use 4mXtSetTypeConverter24m, and to register a type converter in a single application context, use 4mXtAppSetType-0m 4mConverter24m. 1m2390m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtSetTypeConverter(4mfrom_type24m, 4mto_type24m, 4mconverter24m, 4mconvert_args24m, 4mnum_args24m, 4mcache_type24m, 4mdestructor24m) String 4mfrom_type24m; String 4mto_type24m; XtTypeConverter 4mconverter24m; XtConvertArgList 4mconvert_args24m; Cardinal 4mnum_args24m; XtCacheType 4mcache_type24m; XtDestructor 4mdestructor24m; 4mfrom_type24m Specifies the source type. 4mto_type24m Specifies the destination type. 4mconverter24m Specifies the resource type converter procedure. 4mconvert_args0m Specifies additional conversion arguments, or NULL. 4mnum_args24m Specifies the number of entries in 4mconvert_args24m. 4mcache_type0m Specifies whether or not resources produced by this converter are sharable or display-specific and when they should be freed. 4mdestructor0m Specifies a destroy procedure for resources pro- duced by this conversion, or NULL if no additional action is required to deallocate resources pro- duced by the converter. void XtAppSetTypeConverter(4mapp_context24m, 4mfrom_type24m, 4mto_type24m, 4mconverter24m, 4mconvert_args24m, 4mnum_args24m, 4mcache_type24m, 4mdestructor24m) XtAppContext 4mapp_context24m; String 4mfrom_type24m; String 4mto_type24m; XtTypeConverter 4mconverter24m; XtConvertArgList 4mconvert_args24m; Cardinal 4mnum_args24m; XtCacheType 4mcache_type24m; XtDestructor 4mdestructor24m; 4mapp_context0m Specifies the application context. 4mfrom_type24m Specifies the source type. 4mto_type24m Specifies the destination type. 1m2400m 1mX Toolkit Intrinsics X11 Release 6.40m 4mconverter24m Specifies the resource type converter procedure. 4mconvert_args0m Specifies additional conversion arguments, or NULL. 4mnum_args24m Specifies the number of entries in 4mconvert_args24m. 4mcache_type0m Specifies whether or not resources produced by this converter are sharable or display-specific and when they should be freed. 4mdestructor0m Specifies a destroy procedure for resources pro- duced by this conversion, or NULL if no additional action is required to deallocate resources pro- duced by the converter. |__ 4mXtSetTypeConverter24m registers the specified type converter and destructor in all application contexts created by the calling process, including any future application contexts that may be created. 4mXtAppSetTypeConverter24m registers the specified type converter in the single application context specified. If the same 4mfrom_type24m and 4mto_type24m are specified in multiple calls to either function, the most recent over- rides the previous ones. For the few type converters that need additional arguments, the Intrinsics conversion mechanism provides a method of specifying how these arguments should be computed. The enu- merated type 4mXtAddressMode24m and the structure 4mXtConvertArgRec0m specify how each argument is derived. These are defined in <4mX11/Intrinsic.h24m>. 1m2410m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef enum { /* address mode parameter representation */ XtAddress, /* address */ XtBaseOffset, /* offset */ XtImmediate, /* constant */ XtResourceString,/* resource name string */ XtResourceQuark, /* resource name quark */ XtWidgetBaseOffset,/* offset */ XtProcedureArg /* procedure to call */ } XtAddressMode; typedef struct { XtAddressMode address_mode; XtPointer address_id; Cardinal size; } XtConvertArgRec, *XtConvertArgList; |__ The 4msize24m field specifies the length of the data in bytes. The 4maddress_mode24m field specifies how the 4maddress_id24m field should be interpreted. 4mXtAddress24m causes 4maddress_id24m to be interpreted as the address of the data. 4mXtBaseOffset24m causes 4maddress_id24m to be interpreted as the offset from the widget base. 4mXtImmediate24m causes 4maddress_id24m to be interpreted as a constant. 4mXtResourceString24m causes 4maddress_id24m to be inter- preted as the name of a resource that is to be converted into an offset from the widget base. 4mXtResourceQuark24m causes 4maddress_id24m to be interpreted as the result of an 4mXrmString-0m 4mToQuark24m conversion on the name of a resource, which is to be converted into an offset from the widget base. 4mXtWidget-0m 4mBaseOffset24m is similar to 4mXtBaseOffset24m except that it searches for the closest windowed ancestor if the object is not of a subclass of Core (see Chapter 12). 4mXtProcedureArg0m specifies that 4maddress_id24m is a pointer to a procedure to be invoked to return the conversion argument. If 4mXtProce-0m 4mdureArg24m is specified, 4maddress_id24m must contain the address of a function of type 4mXtConvertArgProc24m. 1m2420m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtConvertArgProc)(Widget, Cardinal*, XrmValue*); Widget 4mobject24m; Cardinal *4msize24m; XrmValue *4mvalue24m; 4mobject24m Passes the object for which the resource is being converted, or NULL if the converter was invoked by 4mXtCallConverter24m or 4mXtDirectConvert24m. 4msize24m Passes a pointer to the 4msize24m field from the 4mXtCon-0m 4mvertArgRec24m. 4mvalue24m Passes a pointer to a descriptor into which the procedure must store the conversion argument. |__ When invoked, the 4mXtConvertArgProc24m procedure must derive a conversion argument and store the address and size of the argument in the location pointed to by 4mvalue24m. In order to permit reentrancy, the 4mXtConvertArgProc24m should return the address of storage whose lifetime is no shorter than the lifetime of 4mobject24m. If 4mobject24m is NULL, the life- time of the conversion argument must be no shorter than the lifetime of the resource with which the conversion argument is associated. The Intrinsics do not guarantee to copy this storage but do guarantee not to reference it if the resource is removed from the conversion cache. The following example illustrates how to register the Cvt- StringToPixel routine given earlier: static XtConvertArgRec colorConvertArgs[] = { {XtWidgetBaseOffset, (XtPointer)XtOffset(Widget, core.screen), sizeof(Screen*)}, {XtWidgetBaseOffset, (XtPointer)XtOffset(Widget, core.colormap),sizeof(Colormap)} }; XtSetTypeConverter(XtRString, XtRPixel, CvtStringToPixel, colorConvertArgs, XtNumber(colorConvertArgs), XtCacheByDisplay, NULL); The conversion argument descriptors 4mcolorConvertArgs24m and 4mscreenConvertArg24m are predefined by the Intrinsics. Both take the values from the closest windowed ancestor if the object is not of a subclass of Core. The 4mscreenConvertArg0m descriptor puts the widget's 4mscreen24m field into 4margs24m[0]. The 4mcolorConvertArgs24m descriptor puts the widget's 4mscreen24m field into 4margs24m[0], and the widget's 4mcolormap24m field into 4margs24m[1]. Conversion routines should not just put a descriptor for the address of the base of the widget into 4margs24m[0], and use that 1m2430m 1mX Toolkit Intrinsics X11 Release 6.40m in the routine. They should pass in the actual values on which the conversion depends. By keeping the dependencies of the conversion procedure specific, it is more likely that subsequent conversions will find what they need in the con- version cache. This way the cache is smaller and has fewer and more widely applicable entries. If any conversion arguments of type 4mXtBaseOffset24m, 4mXtRe-0m 4msourceString24m, 4mXtResourceQuark24m, and 4mXtWidgetBaseOffset24m are specified for conversions performed by 4mXtGetApplicationRe-0m 4msources24m, 4mXtGetSubresources24m, 4mXtVaGetApplicationResources24m, or 4mXtVaGetSubresources24m, the arguments are computed with respect to the specified widget, not the base address or resource list specified in the call. If the 4mXtConvertArgProc24m modifies the resource database, the changes affect any in-progress widget creation, 4mXtGetAppli-0m 4mcationResources24m, or 4mXtGetSubresources24m in an implementation- defined manner; however, insertion of new entries or changes to existing entries are allowed and will not directly cause an error. 1m9.6.5. Resource Converter Invocation0m All resource-fetching routines (for example, 4mXtGetSubre-0m 4msources24m, 4mXtGetApplicationResources24m, and so on) call resource converters if the resource database or varargs list speci- fies a value that has a different representation from the desired representation or if the widget's default resource value representation is different from the desired represen- tation. To invoke explicit resource conversions, use 4mXtConvertAnd-0m 4mStore24m or 4mXtCallConverter24m. 1m2440m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef XtPointer XtCacheRef; Boolean XtCallConverter(4mdisplay24m, 4mconverter24m, 4mconversion_args24m, 4mnum_args24m, 4mfrom24m, 4mto_in_out24m, 4mcache_ref_return24m) Display* 4mdisplay24m; XtTypeConverter 4mconverter24m; XrmValuePtr 4mconversion_args24m; Cardinal 4mnum_args24m; XrmValuePtr 4mfrom24m; XrmValuePtr 4mto_in_out24m; XtCacheRef *4mcache_ref_return24m; 4mdisplay24m Specifies the display with which the conver- sion is to be associated. 4mconverter24m Specifies the conversion procedure to be called. 4mconversion_args0m Specifies the additional conversion arguments needed to perform the conversion, or NULL. 4mnum_args24m Specifies the number of entries in 4mconver-0m 4msion_args24m. 4mfrom24m Specifies a descriptor for the source value. 4mto_in_out24m Returns the converted value. 4mcache_ref_return0m Returns a conversion cache id. |__ The 4mXtCallConverter24m function looks up the specified type converter in the application context associated with the display and, if the converter was not registered or was reg- istered with cache type 4mXtCacheAll24m or 4mXtCacheByDisplay24m, looks in the conversion cache to see if this conversion pro- cedure has been called with the specified conversion argu- ments. If so, it checks the success status of the prior call, and if the conversion failed, 4mXtCallConverter24m returns 4mFalse24m immediately; otherwise it checks the size specified in the 4mto24m argument, and, if it is greater than or equal to the size stored in the cache, copies the information stored in the cache into the location specified by 4mto->addr24m, stores the cache size into 4mto->size24m, and returns 4mTrue24m. If the size specified in the 4mto24m argument is smaller than the size stored in the cache, 4mXtCallConverter24m copies the cache size into 4mto->size24m and returns 4mFalse24m. If the converter was registered with cache type 4mXtCacheNone24m or no value was found in the conversion cache, 4mXtCallConverter24m calls the converter, and 1m2450m 1mX Toolkit Intrinsics X11 Release 6.40m if it was not registered with cache type 4mXtCacheNone24m, enters the result in the cache. 4mXtCallConverter24m then returns what the converter returned. The 4mcache_ref_return24m field specifies storage allocated by the caller in which an opaque value will be stored. If the type converter has been registered with the 4mXtCacheRefCount0m modifier and if the value returned in 4mcache_ref_return24m is non-NULL, then the caller should store the 4mcache_ref_return0m value in order to decrement the reference count when the converted value is no longer required. The 4mcache_ref_return0m argument should be NULL if the caller is unwilling or unable to store the value. To explicitly decrement the reference counts for resources obtained from 4mXtCallConverter24m, use 4mXtAppReleaseCacheRefs24m. __ | void XtAppReleaseCacheRefs(4mapp_context24m, 4mrefs24m) XtAppContext 4mapp_context24m; XtCacheRef *4mrefs24m; 4mapp_context0m Specifies the application context. 4mrefs24m Specifies the list of cache references to be released. |__ 4mXtAppReleaseCacheRefs24m decrements the reference count for the conversion entries identified by the 4mrefs24m argument. This argument is a pointer to a NULL-terminated list of 4mXtCacheRef24m values. If any reference count reaches zero, the destructor, if any, will be called and the resource removed from the conversion cache. As a convenience to clients needing to explicitly decrement reference counts via a callback function, the Intrinsics define two callback procedures, 4mXtCallbackReleaseCacheRef0m and 4mXtCallbackReleaseCacheRefList24m. 1m2460m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtCallbackReleaseCacheRef(4mobject24m, 4mclient_data24m, 4mcall_data24m) Widget 4mobject24m; XtPointer 4mclient_data24m; XtPointer 4mcall_data24m; 4mobject24m Specifies the object with which the resource is associated. 4mclient_data0m Specifies the conversion cache entry to be released. 4mcall_data24m Is ignored. |__ This callback procedure may be added to a callback list to release a previously returned 4mXtCacheRef24m value. When adding the callback, the callback 4mclient_data24m argument must be specified as the value of the 4mXtCacheRef24m data cast to type 4mXtPointer24m. __ | void XtCallbackReleaseCacheRefList(4mobject24m, 4mclient_data24m, 4mcall_data24m) Widget 4mobject24m; XtPointer 4mclient_data24m; XtPointer 4mcall_data24m; 4mobject24m Specifies the object with which the resources are associated. 4mclient_data0m Specifies the conversion cache entries to be released. 4mcall_data24m Is ignored. |__ This callback procedure may be added to a callback list to release a list of previously returned 4mXtCacheRef24m values. When adding the callback, the callback 4mclient_data24m argument must be specified as a pointer to a NULL-terminated list of 4mXtCacheRef24m values. To lookup and call a resource converter, copy the resulting value, and free a cached resource when a widget is destroyed, use 4mXtConvertAndStore24m. 1m2470m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Boolean XtConvertAndStore(4mobject24m, 4mfrom_type24m, 4mfrom24m, 4mto_type24m, 4mto_in_out24m) Widget 4mobject24m; String 4mfrom_type24m; XrmValuePtr 4mfrom24m; String 4mto_type24m; XrmValuePtr 4mto_in_out24m; 4mobject24m Specifies the object to use for additional argu- ments, if any are needed, and the destroy callback list. Must be of class Object or any subclass thereof. 4mfrom_type24m Specifies the source type. 4mfrom24m Specifies the value to be converted. 4mto_type24m Specifies the destination type. 4mto_in_out24m Specifies a descriptor for storage into which the converted value will be returned. |__ The 4mXtConvertAndStore24m function looks up the type converter registered to convert 4mfrom_type24m to 4mto_type24m, computes any additional arguments needed, and then calls 4mXtCallConverter0m (or 4mXtDirectConvert24m if an old-style converter was registered with 4mXtAddConverter24m or 4mXtAppAddConverter24m; see Appendix C) with the 4mfrom24m and 4mto_in_out24m arguments. The 4mto_in_out24m argu- ment specifies the size and location into which the con- verted value will be stored and is passed directly to the converter. If the location is specified as NULL, it will be replaced with a pointer to private storage and the size will be returned in the descriptor. The caller is expected to copy this private storage immediately and must not modify it in any way. If a non-NULL location is specified, the caller must allocate sufficient storage to hold the converted value and must also specify the size of that storage in the descriptor. The 4msize24m field will be modified on return to indicate the actual size of the converted data. If the con- version succeeds, 4mXtConvertAndStore24m returns 4mTrue24m; otherwise, it returns 4mFalse24m. 4mXtConvertAndStore24m adds 4mXtCallbackReleaseCacheRef24m to the destroyCallback list of the specified object if the conver- sion returns an 4mXtCacheRef24m value. The resulting resource should not be referenced after the object has been destroyed. 4mXtCreateWidget24m performs processing equivalent to 4mXtConver-0m 4mtAndStore24m when initializing the object instance. Because there is extra memory overhead required to implement refer- ence counting, clients may distinguish those objects that 1m2480m 1mX Toolkit Intrinsics X11 Release 6.40m are never destroyed before the application exits from those that may be destroyed and whose resources should be deallo- cated. To specify whether reference counting is to be enabled for the resources of a particular object when the object is cre- ated, the client can specify a value for the 4mBoolean0m resource XtNinitialResourcesPersistent, class XtCInitialRe- sourcesPersistent. When 4mXtCreateWidget24m is called, if this resource is not spec- ified as 4mFalse24m in either the arglist or the resource data- base, then the resources referenced by this object are not reference-counted, regardless of how the type converter may have been registered. The effective default value is 4mTrue24m; thus clients that expect to destroy one or more objects and want resources deallocated must explicitly specify 4mFalse24m for XtNinitialResourcesPersistent. The resources are still freed and destructors called when 4mXtCloseDisplay24m is called if the conversion was registered as 4mXtCacheByDisplay24m. 1m9.7. Reading and Writing Widget State0m Any resource field in a widget can be read or written by a client. On a write operation, the widget decides what changes it will actually allow and updates all derived fields appropriately. 1m9.7.1. Obtaining Widget State0m To retrieve the current values of resources associated with a widget instance, use 4mXtGetValues24m. 1m2490m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtGetValues(4mobject24m, 4margs24m, 4mnum_args24m) Widget 4mobject24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mobject24m Specifies the object whose resource values are to be returned. Must be of class Object or any sub- class thereof. 4margs24m Specifies the argument list of name/address pairs that contain the resource names and the addresses into which the resource values are to be stored. The resource names are widget-dependent. 4mnum_args24m Specifies the number of entries in the argument list. |__ The 4mXtGetValues24m function starts with the resources specified for the Object class and proceeds down the subclass chain to the class of the object. The 4mvalue24m field of a passed argu- ment list must contain the address into which to copy the contents of the corresponding object instance field. If the field is a pointer type, the lifetime of the pointed-to data is defined by the object class. For the Intrinsics-defined resources, the following lifetimes apply: · Not valid following any operation that modifies the resource: - XtNchildren resource of composite widgets. - All resources of representation type XtRCallback. · Remain valid at least until the widget is destroyed: - XtNaccelerators, XtNtranslations. · Remain valid until the Display is closed: - XtNscreen. It is the caller's responsibility to allocate and deallocate storage for the copied data according to the size of the resource representation type used within the object. If the class of the object's parent is a subclass of 4mcon-0m 4mstraintWidgetClass24m, 4mXtGetValues24m then fetches the values for any constraint resources requested. It starts with the con- straint resources specified for 4mconstraintWidgetClass24m and proceeds down the subclass chain to the parent's constraint resources. If the argument list contains a resource name 1m2500m 1mX Toolkit Intrinsics X11 Release 6.40m that is not found in any of the resource lists searched, the value at the corresponding address is not modified. If any get_values_hook procedures in the object's class or super- class records are non-NULL, they are called in superclass- to-subclass order after all the resource values have been fetched by 4mXtGetValues24m. Finally, if the object's parent is a subclass of 4mconstraintWidgetClass24m, and if any of the par- ent's class or superclass records have declared 4mConstraint-0m 4mClassExtension24m records in the Constraint class part 4mexten-0m 4msion24m field with a record type of 4mNULLQUARK24m, and if the 4mget_values_hook24m field in the extension record is non-NULL, 4mXtGetValues24m calls the get_values_hook procedures in super- class-to-subclass order. This permits a Constraint parent to provide nonresource data via 4mXtGetValues24m. Get_values_hook procedures may modify the data stored at the location addressed by the 4mvalue24m field, including (but not limited to) making a copy of data whose resource representa- tion is a pointer. None of the Intrinsics-defined object classes copy data in this manner. Any operation that modi- fies the queried object resource may invalidate the pointed- to data. To retrieve the current values of resources associated with a widget instance using varargs lists, use 4mXtVaGetValues24m. __ | void XtVaGetValues(4mobject24m, ...) Widget 4mobject24m; 4mobject24m Specifies the object whose resource values are to be returned. Must be of class Object or any sub- class thereof. ... Specifies the variable argument list for the resources to be returned. |__ 4mXtVaGetValues24m is identical in function to 4mXtGetValues24m with the 4margs24m and 4mnum_args24m parameters replaced by a varargs list, as described in Section 2.5.1. All value entries in the list must specify pointers to storage allocated by the caller to which the resource value will be copied. It is the caller's responsibility to ensure that sufficient stor- age is allocated. If 4mXtVaTypedArg24m is specified, the 4mtype0m argument specifies the representation desired by the caller and 4mthe24m size argument specifies the number of bytes allo- cated to store the result of the conversion. If the size is insufficient, a warning message is issued and the list entry is skipped. 1m2510m 1mX Toolkit Intrinsics X11 Release 6.40m 1m9.7.1.1. Widget Subpart Resource Data: The get_values_hook0m 1mProcedure0m Widgets that have subparts can return resource values from them through 4mXtGetValues24m by supplying a get_values_hook pro- cedure. The get_values_hook procedure pointer is of type 4mXtArgsProc24m. __ | typedef void (*XtArgsProc)(Widget, ArgList, Cardinal*); Widget 4mw24m; ArgList 4margs24m; Cardinal *4mnum_args24m; 4mw24m Specifies the widget whose subpart resource values are to be retrieved. 4margs24m Specifies the argument list that was passed to 4mXtGetValues24m or the transformed varargs list passed to 4mXtVaGetValues24m. 4mnum_args24m Specifies the number of entries in the argument list. |__ The widget with subpart resources should call 4mXtGetSubvalues0m in the get_values_hook procedure and pass in its subresource list and the 4margs24m and 4mnum_args24m parameters. 1m9.7.1.2. Widget Subpart State0m To retrieve the current values of subpart resource data associated with a widget instance, use 4mXtGetSubvalues24m. For a discussion of subpart resources, see Section 9.4. 1m2520m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtGetSubvalues(4mbase24m, 4mresources24m, 4mnum_resources24m, 4margs24m, 4mnum_args24m) XtPointer 4mbase24m; XtResourceList 4mresources24m; Cardinal 4mnum_resources24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mbase24m Specifies the base address of the subpart data structure for which the resources should be retrieved. 4mresources24m Specifies the subpart resource list. 4mnum_resources0m Specifies the number of entries in the resource list. 4margs24m Specifies the argument list of name/address pairs that contain the resource names and the addresses into which the resource values are to be stored. 4mnum_args24m Specifies the number of entries in the argument list. |__ The 4mXtGetSubvalues24m function obtains resource values from the structure identified by 4mbase24m. The 4mvalue24m field in each argu- ment entry must contain the address into which to store the corresponding resource value. It is the caller's responsi- bility to allocate and deallocate this storage according to the size of the resource representation type used within the subpart. If the argument list contains a resource name that is not found in the resource list, the value at the corre- sponding address is not modified. To retrieve the current values of subpart resources associ- ated with a widget instance using varargs lists, use 4mXtVaGetSubvalues24m. 1m2530m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtVaGetSubvalues(4mbase24m, 4mresources24m, 4mnum_resources24m, ...) XtPointer 4mbase24m; XtResourceList 4mresources24m; Cardinal 4mnum_resources24m; 4mbase24m Specifies the base address of the subpart data structure for which the resources should be retrieved. 4mresources24m Specifies the subpart resource list. 4mnum_resources0m Specifies the number of entries in the resource list. ... Specifies a variable argument list of name/address pairs that contain the resource names and the addresses into which the resource values are to be stored. |__ 4mXtVaGetSubvalues24m is identical in function to 4mXtGetSubvalues0m with the 4margs24m and 4mnum_args24m parameters replaced by a varargs list, as described in Section 2.5.1. 4mXtVaTypedArg24m is not supported for 4mXtVaGetSubvalues24m. If 4mXtVaTypedArg24m is speci- fied in the list, a warning message is issued and the entry is then ignored. 1m9.7.2. Setting Widget State0m To modify the current values of resources associated with a widget instance, use 4mXtSetValues24m. 1m2540m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtSetValues(4mobject24m, 4margs24m, 4mnum_args24m) Widget 4mobject24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mobject24m Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof. 4margs24m Specifies the argument list of name/value pairs that contain the resources to be modified and their new values. 4mnum_args24m Specifies the number of entries in the argument list. |__ The 4mXtSetValues24m function starts with the resources specified for the Object class fields and proceeds down the subclass chain to the object. At each stage, it replaces the 4mobject0m resource fields with any values specified in the argument list. 4mXtSetValues24m then calls the set_values procedures for the object in superclass-to-subclass order. If the object has any non-NULL 4mset_values_hook24m fields, these are called immediately after the corresponding set_values procedure. This procedure permits subclasses to set subpart data via 4mXtSetValues24m. If the class of the object's parent is a subclass of 4mcon-0m 4mstraintWidgetClass24m, 4mXtSetValues24m also updates the object's constraints. It starts with the constraint resources speci- fied for 4mconstraintWidgetClass24m and proceeds down the sub- class chain to the parent's class. At each stage, it replaces the constraint resource fields with any values specified in the argument list. It then calls the con- straint set_values procedures from 4mconstraintWidgetClass0m down to the parent's class. The constraint set_values pro- cedures are called with widget arguments, as for all set_values procedures, not just the constraint records, so that they can make adjustments to the desired values based on full information about the widget. Any arguments speci- fied that do not match a resource list entry are silently ignored. If the object is of a subclass of RectObj, 4mXtSetValues0m determines if a geometry request is needed by comparing the old object to the new object. If any geometry changes are required, 4mXtSetValues24m restores the original geometry and makes the request on behalf of the widget. If the geometry manager returns 4mXtGeometryYes24m, 4mXtSetValues24m calls the object's resize procedure. If the geometry manager returns 4mXtGeometryDone24m, 4mXtSetValues24m continues, as the object's 1m2550m 1mX Toolkit Intrinsics X11 Release 6.40m resize procedure should have been called by the geometry manager. If the geometry manager returns 4mXtGeometryNo24m, 4mXtSetValues24m ignores the geometry request and continues. If the geometry manager returns 4mXtGeometryAlmost24m, 4mXtSetValues0m calls the set_values_almost procedure, which determines what should be done. 4mXtSetValues24m then repeats this process, deciding once more whether the geometry manager should be called. Finally, if any of the set_values procedures returned 4mTrue24m, and the widget is realized, 4mXtSetValues24m causes the widget's expose procedure to be invoked by calling 4mXClearArea24m on the widget's window. To modify the current values of resources associated with a widget instance using varargs lists, use 4mXtVaSetValues24m. __ | void XtVaSetValues(4mobject24m, ...) Widget 4mobject24m; 4mobject24m Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof. ... Specifies the variable argument list of name/value pairs that contain the resources to be modified and their new values. |__ 4mXtVaSetValues24m is identical in function to 4mXtSetValues24m with the 4margs24m and 4mnum_args24m parameters replaced by a varargs list, as described in Section 2.5.1. 1m9.7.2.1. Widget State: The set_values Procedure0m The set_values procedure pointer in a widget class is of type 4mXtSetValuesFunc24m. 1m2560m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef Boolean (*XtSetValuesFunc)(Widget, Widget, Widget, ArgList, Cardinal*); Widget 4mcurrent24m; Widget 4mrequest24m; Widget 4mnew24m; ArgList 4margs24m; Cardinal *4mnum_args24m; 4mcurrent24m Specifies a copy of the widget as it was before the 4mXtSetValues24m call. 4mrequest24m Specifies a copy of the widget with all values changed as asked for by the 4mXtSetValues24m call before any class set_values procedures have been called. 4mnew24m Specifies the widget with the new values that are actually allowed. 4margs24m Specifies the argument list passed to 4mXtSetValues0m or the transformed argument list passed to 4mXtVaSetValues24m. 4mnum_args24m Specifies the number of entries in the argument list. |__ The set_values procedure should recompute any field derived from resources that are changed (for example, many GCs depend on foreground and background pixels). If no recompu- tation is necessary, and if none of the resources specific to a subclass require the window to be redisplayed when their values are changed, you can specify NULL for the 4mset_values24m field in the class record. Like the initialize procedure, set_values mostly deals only with the fields defined in the subclass, but it has to resolve conflicts with its superclass, especially conflicts over width and height. Sometimes a subclass may want to overwrite values filled in by its superclass. In particular, size calculations of a superclass are often incorrect for a subclass, and, in this case, the subclass must modify or recalculate fields declared and computed by its superclass. As an example, a subclass can visually surround its super- class display. In this case, the width and height calcu- lated by the superclass set_values procedure are too small and need to be incremented by the size of the surround. The subclass needs to know if its superclass's size was calcu- lated by the superclass or was specified explicitly. All widgets must place themselves into whatever size is 1m2570m 1mX Toolkit Intrinsics X11 Release 6.40m explicitly given, but they should compute a reasonable size if no size is requested. How does a subclass know the dif- ference between a specified size and a size computed by a superclass? The 4mrequest24m and 4mnew24m parameters provide the necessary infor- mation. The 4mrequest24m widget is a copy of the widget, updated as originally requested. The 4mnew24m widget starts with the values in the request, but it has additionally been updated by all superclass set_values procedures called so far. A subclass set_values procedure can compare these two to resolve any potential conflicts. The set_values procedure need not refer to the 4mrequest24m widget unless it must resolve conflicts between the 4mcurrent24m and 4mnew24m widgets. Any changes the widget needs to make, including geometry changes, should be made in the 4mnew24m widget. In the above example, the subclass with the visual surround can see if the 4mwidth24m and 4mheight24m in the 4mrequest24m widget are zero. If so, it adds its surround size to the 4mwidth24m and 4mheight24m fields in the 4mnew24m widget. If not, it must make do with the size originally specified. In this case, zero is a special value defined by the class to permit the application to invoke this behavior. The 4mnew24m widget is the actual widget instance record. There- fore, the set_values procedure should do all its work on the 4mnew24m widget; the 4mrequest24m widget should never be modified. If the set_values procedure needs to call any routines that operate on a widget, it should specify 4mnew24m as the widget instance. Before calling the set_values procedures, the Intrinsics modify the resources of the 4mrequest24m widget according to the contents of the arglist; if the widget names all its resources in the class resource list, it is never necessary to examine the contents of 4margs24m. Finally, the set_values procedure must return a Boolean that indicates whether the widget needs to be redisplayed. Note that a change in the geometry fields alone does not require the set_values procedure to return 4mTrue24m; the X server will eventually generate an 4mExpose24m event, if necessary. After calling all the set_values procedures, 4mXtSetValues24m forces a redisplay by calling 4mXClearArea24m if any of the set_values procedures returned 4mTrue24m. Therefore, a set_values procedure should not try to do its own redisplaying. Set_values procedures should not do any work in response to changes in geometry because 4mXtSetValues24m eventually will per- form a geometry request, and that request might be denied. If the widget actually changes size in response to a call to 4mXtSetValues24m, its resize procedure is called. Widgets should do any geometry-related work in their resize procedure. 1m2580m 1mX Toolkit Intrinsics X11 Release 6.40m Note that it is permissible to call 4mXtSetValues24m before a widget is realized. Therefore, the set_values procedure must not assume that the widget is realized. 1m9.7.2.2. Widget State: The set_values_almost Procedure0m The set_values_almost procedure pointer in the widget class record is of type 4mXtAlmostProc24m. __ | typedef void (*XtAlmostProc)(Widget, Widget, XtWidgetGeometry*, XtWidgetGeometry*); Widget 4mold24m; Widget 4mnew24m; XtWidgetGeometry *4mrequest24m; XtWidgetGeometry *4mreply24m; 4mold24m Specifies a copy of the object as it was before the 4mXtSetValues24m call. 4mnew24m Specifies the object instance record. 4mrequest24m Specifies the original geometry request that was sent to the geometry manager that caused 4mXtGeome-0m 4mtryAlmost24m to be returned. 4mreply24m Specifies the compromise geometry that was returned by the geometry manager with 4mXtGeome-0m 4mtryAlmost24m. |__ Most classes inherit the set_values_almost procedure from their superclass by specifying 4mXtInheritSetValuesAlmost24m in the class initialization. The set_values_almost procedure in 4mrectObjClass24m accepts the compromise suggested. The set_values_almost procedure is called when a client tries to set a widget's geometry by means of a call to 4mXtSetValues24m and the geometry manager cannot satisfy the request but instead returns 4mXtGeometryNo24m or 4mXtGeometryAlmost0m and a compromise geometry. The 4mnew24m object is the actual instance record. The 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, and 4mborder_width0m fields contain the original values as they were before the 4mXtSetValues24m call, and all other fields contain the new val- ues. The 4mrequest24m parameter contains the new geometry request that was made to the parent. The 4mreply24m parameter contains 4mreply->request_mode24m equal to zero if the parent returned 4mXtGeometryNo24m and contains the parent's compromise geometry otherwise. The set_values_almost procedure takes the original geometry and the compromise geometry and deter- mines if the compromise is acceptable or whether to try a different compromise. It returns its results in the 4mrequest0m 1m2590m 1mX Toolkit Intrinsics X11 Release 6.40m parameter, which is then sent back to the geometry manager for another try. To accept the compromise, the procedure must copy the contents of the 4mreply24m geometry into the 4mrequest24m geometry; to attempt an alternative geometry, the procedure may modify any part of the 4mrequest24m argument; to terminate the geometry negotiation and retain the original geometry, the procedure must set 4mrequest->request_mode24m to zero. The geometry fields of the 4mold24m and 4mnew24m instances must not be modified directly. 1m9.7.2.3. Widget State: The ConstraintClassPart set_values0m 1mProcedure0m The constraint set_values procedure pointer is of type 4mXtSetValuesFunc24m. The values passed to the parent's con- straint set_values procedure are the same as those passed to the child's class set_values procedure. A class can specify NULL for the 4mset_values24m field of the 4mConstraintPart24m if it need not compute anything. The constraint set_values procedure should recompute any constraint fields derived from constraint resources that are changed. Furthermore, it may modify other 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 procedure may reset the 4mheight24m field in the widget. 1m9.7.2.4. Widget Subpart State0m To set the current values of subpart resources associated with a widget instance, use 4mXtSetSubvalues24m. For a discus- sion of subpart resources, see Section 9.4. 1m2600m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtSetSubvalues(4mbase24m, 4mresources24m, 4mnum_resources24m, 4margs24m, 4mnum_args24m) XtPointer 4mbase24m; XtResourceList 4mresources24m; Cardinal 4mnum_resources24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mbase24m Specifies the base address of the subpart data structure into which the resources should be writ- ten. 4mresources24m Specifies the subpart resource list. 4mnum_resources0m Specifies the number of entries in the resource list. 4margs24m Specifies the argument list of name/value pairs that contain the resources to be modified and their new values. 4mnum_args24m Specifies the number of entries in the argument list. |__ The 4mXtSetSubvalues24m function updates the resource fields of the structure identified by 4mbase24m. Any specified arguments that do not match an entry in the resource list are silently ignored. To set the current values of subpart resources associated with a widget instance using varargs lists, use 4mXtVaSetSub-0m 4mvalues24m. 1m2610m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtVaSetSubvalues(4mbase24m, 4mresources24m, 4mnum_resources24m, ...) XtPointer 4mbase24m; XtResourceList 4mresources24m; Cardinal 4mnum_resources24m; 4mbase24m Specifies the base address of the subpart data structure into which the resources should be writ- ten. 4mresources24m Specifies the subpart resource list. 4mnum_resources0m Specifies the number of entries in the resource list. ... Specifies the variable argument list of name/value pairs that contain the resources to be modified and their new values. |__ 4mXtVaSetSubvalues24m is identical in function to 4mXtSetSubvalues0m with the 4margs24m and 4mnum_args24m parameters replaced by a varargs list, as described in Section 2.5.1. 4mXtVaTypedArg24m is not supported for 4mXtVaSetSubvalues24m. If an entry containing 4mXtVaTypedArg24m is specified in the list, a warning message is issued and the entry is ignored. 1m9.7.2.5. Widget Subpart Resource Data: The set_values_hook0m 1mProcedure0m 1mNote0m The set_values_hook procedure is obsolete, as the same information is now available to the set_val- ues procedure. The procedure has been retained for those widgets that used it in versions prior to Release 4. Widgets that have a subpart can set the subpart resource values through 4mXtSetValues24m by supplying a set_values_hook procedure. The set_values_hook procedure pointer in a wid- get class is of type 4mXtArgsFunc24m. 1m2620m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef Boolean (*XtArgsFunc)(Widget, Arglist, Cardinal*); Widget 4mw24m; Arglist 4margs24m; Cardinal *4mnum_args24m; 4mw24m Specifies the widget whose subpart resource values are to be changed. 4margs24m Specifies the argument list that was passed to 4mXtSetValues24m or the transformed varargs list passed to 4mXtVaSetValues24m. 4mnum_args24m Specifies the number of entries in the argument list. |__ The widget with subpart resources may call 4mXtSetValues24m from the set_values_hook procedure and pass in its subresource list and the 4margs24m and 4mnum_args24m parameters. 1m2630m 1mX Toolkit Intrinsics X11 Release 6.40m 1mChapter 100m 1mTranslation Management0m Except under unusual circumstances, widgets do not hardwire the mapping of user events into widget behavior by using the event manager. Instead, they provide a default mapping of events into behavior that you can override. The translation manager provides an interface to specify and manage the mapping of X event sequences into widget-supplied functionality, for example, calling procedure 4mAbc24m when the 4my0m key is pressed. The translation manager uses two kinds of tables to perform translations: · The action tables, which are in the widget class struc- ture, specify the mapping of externally available pro- cedure name strings to the corresponding procedure implemented by the widget class. · A translation table, which is in the widget class structure, specifies the mapping of event sequences to procedure name strings. You can override the translation table in the class struc- ture for a specific widget instance by supplying a different translation table for the widget instance. The resources XtNtranslations and XtNbaseTranslations are used to modify the class default translation table; see Section 10.3. 1m10.1. Action Tables0m All widget class records contain an action table, an array of 4mXtActionsRec24m entries. In addition, an application can register its own action tables with the translation manager so that the translation tables it provides to widget instances can access application functionality directly. The translation action procedure pointer is of type 4mXtAc-0m 4mtionProc24m. 1m2640m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtActionProc)(Widget, XEvent*, String*, Cardinal*); Widget 4mw24m; XEvent *4mevent24m; String *4mparams24m; Cardinal *4mnum_params24m; 4mw24m Specifies the widget that caused the action to be called. 4mevent24m Specifies the event that caused the action to be called. If the action is called after a sequence of events, then the last event in the sequence is used. 4mparams24m Specifies a pointer to the list of strings that were specified in the translation table as argu- ments to the action, or NULL. 4mnum_params0m Specifies the number of entries in 4mparams24m. typedef struct _XtActionsRec { String string; XtActionProc proc; } XtActionsRec, *XtActionList; |__ The 4mstring24m field is the name used in translation tables to access the procedure. The 4mproc24m field is a pointer to a pro- cedure that implements the functionality. When the action list is specified as the 4mCoreClassPart0m 4mactions24m field, the string pointed to by 4mstring24m must be per- manently allocated prior to or during the execution of the class initialization procedure and must not be subsequently deallocated. Action procedures should not assume that the widget in which they are invoked is realized; an accelerator specification can cause an action procedure to be called for a widget that does not yet have a window. Widget writers should also note which of a widget's callback lists are invoked from action procedures and warn clients not to assume the widget is realized in those callbacks. For example, a Pushbutton widget has procedures to take the following actions: · Set the button to indicate it is activated. 1m2650m 1mX Toolkit Intrinsics X11 Release 6.40m · Unset the button back to its normal mode. · Highlight the button borders. · Unhighlight the button borders. · Notify any callbacks that the button has been acti- vated. The action table for the Pushbutton widget class makes these functions available to translation tables written for Push- button or any subclass. The string entry is the name used in translation tables. The procedure entry (usually spelled identically to the string) is the name of the C procedure that implements that function: XtActionsRec actionTable[] = { {"Set", Set}, {"Unset", Unset}, {"Highlight",Highlight}, {"Unhighlight",Unhighlight} {"Notify",Notify}, }; The Intrinsics reserve all action names and parameters starting with the characters ``Xt'' for future standard enhancements. Users, applications, and widgets should not declare action names or pass parameters starting with these characters except to invoke specified built-in Intrinsics functions. 1m10.1.1. Action Table Registration0m The 4mactions24m and 4mnum_actions24m fields of 4mCoreClassPart24m specify the actions implemented by a widget class. These are auto- matically registered with the Intrinsics when the class is initialized and must be allocated in writable storage prior to Core class_part initialization, and never deallocated. To save memory and optimize access, the Intrinsics may over- write the storage in order to compile the list into an internal representation. To declare an action table within an application and regis- ter it with the translation manager, use 4mXtAppAddActions24m. 1m2660m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtAppAddActions(4mapp_context24m, 4mactions24m, 4mnum_actions24m) XtAppContext 4mapp_context24m; XtActionList 4mactions24m; Cardinal 4mnum_actions24m; 4mapp_context0m Specifies the application context. 4mactions24m Specifies the action table to register. 4mnum_actions0m Specifies the number of entries in this action ta- ble. |__ If more than one action is registered with the same name, the most recently registered action is used. If duplicate actions exist in an action table, the first is used. The Intrinsics register an action table containing 4mXtMenuPopup0m and 4mXtMenuPopdown24m as part of 4mXtCreateApplicationContext24m. 1m10.1.2. Action Names to Procedure Translations0m The translation manager uses a simple algorithm to resolve the name of a procedure specified in a translation table into the actual procedure specified in an action table. When the widget is realized, the translation manager per- forms a search for the name in the following tables, in order: · The widget's class and all superclass action tables, in subclass-to-superclass order. · The parent's class and all superclass action tables, in subclass-to-superclass order, then on up the ancestor tree. · The action tables registered with 4mXtAppAddActions24m and 4mXtAddActions24m from the most recently added table to the oldest table. As soon as it finds a name, the translation manager stops the search. If it cannot find a name, the translation man- ager generates a warning message. 1m10.1.3. Action Hook Registration0m An application can specify a procedure that will be called just before every action routine is dispatched by the trans- lation manager. To do so, the application supplies a 1m2670m 1mX Toolkit Intrinsics X11 Release 6.40m procedure pointer of type 4mXtActionHookProc24m. __ | typedef void (*XtActionHookProc)(Widget, XtPointer, String, XEvent*, String*, Cardinal*); Widget 4mw24m; XtPointer 4mclient_data24m; String 4maction_name24m; XEvent* 4mevent24m; String* 4mparams24m; Cardinal* 4mnum_params24m; 4mw24m Specifies the widget whose action is about to be dispatched. 4mclient_data0m Specifies the application-specific closure that was passed to 4mXtAppAddActionHook.0m 4maction_name0m Specifies the name of the action to be dispatched. 4mevent24m Specifies the event argument that will be passed to the action routine. 4mparams24m Specifies the action parameters that will be passed to the action routine. 4mnum_params0m Specifies the number of entries in 4mparams24m. |__ Action hooks should not modify any of the data pointed to by the arguments other than the 4mclient_data24m argument. To add an action hook, use 4mXtAppAddActionHook24m. 1m2680m 1mX Toolkit Intrinsics X11 Release 6.40m __ | XtActionHookId XtAppAddActionHook(4mapp24m, 4mproc24m, 4mclient_data24m) XtAppContext 4mapp24m; XtActionHookProc 4mproc24m; XtPointer 4mclient_data24m; 4mapp24m Specifies the application context. 4mproc24m Specifies the action hook procedure. 4mclient_data0m Specifies application-specific data to be passed to the action hook. |__ 4mXtAppAddActionHook24m adds the specified procedure to the front of a list maintained in the application context. In the future, when an action routine is about to be invoked for any widget in this application context, either through the translation manager or via 4mXtCallActionProc24m, the action hook procedures will be called in reverse order of registration just prior to invoking the action routine. Action hook procedures are removed automatically and the 4mXtActionHookId24mis destroyed when the application context in which they were added is destroyed. To remove an action hook procedure without destroying the application context, use 4mXtRemoveActionHook24m. __ | void XtRemoveActionHook(4mid24m) XtActionHookId 4mid24m; 4mid24m Specifies the action hook id returned by 4mXtAppAd-0m 4mdActionHook24m. |__ 4mXtRemoveActionHook24m removes the specified action hook proce- dure from the list in which it was registered. 1m10.2. Translation Tables0m All widget instance records contain a translation table, which is a resource with a default value specified elsewhere in the class record. A translation table specifies what action procedures are invoked for an event or a sequence of events. A translation table is a string containing a list of translations from an event sequence into one or more 1m2690m 1mX Toolkit Intrinsics X11 Release 6.40m action procedure calls. The translations are separated from one another by newline characters (ASCII LF). The complete syntax of translation tables is specified in Appendix B. As an example, the default behavior of Pushbutton is · Highlight on enter window. · Unhighlight on exit window. · Invert on left button down. · Call callbacks and reinvert on left button up. The following illustrates Pushbutton's default translation table: static String defaultTranslations = ":Highlight()\n\ :Unhighlight()\n\ :Set()\n\ : Notify() Unset()"; The 4mtm_table24m field of the 4mCoreClassPart24m should be filled in at class initialization time with the string containing the class's default translations. If a class wants to inherit its superclass's translations, it can store the special value 4mXtInheritTranslations24m into 4mtm_table24m. In Core's class part initialization procedure, the Intrinsics compile this translation table into an efficient internal form. Then, at widget creation time, this default translation table is com- bined with the XtNtranslations and XtNbaseTranslations resources; see Section 10.3. The resource conversion mechanism automatically compiles string translation tables that are specified in the resource database. If a client uses translation tables that are not retrieved via a resource conversion, it must compile them itself using 4mXtParseTranslationTable24m. The Intrinsics use the compiled form of the translation ta- ble 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 trans- lation manager. 1m10.2.1. Event Sequences0m An event sequence is a comma-separated list of X event descriptions that describes a specific sequence of X events to map to a set of program actions. Each X event 1m2700m 1mX Toolkit Intrinsics X11 Release 6.40m description consists of three parts: The X event type, a prefix consisting of the X modifier bits, and an event-spe- cific suffix. Various abbreviations are supported to make translation tables easier to read. The events must match incoming events in left-to-right order to trigger the action sequence. 1m10.2.2. Action Sequences0m Action sequences specify what program or widget actions to take in response to incoming X events. An action sequence consists of space-separated action procedure call specifica- tions. Each action procedure call consists of the name of an action procedure and a parenthesized list of zero or more comma-separated string parameters to pass to that procedure. The actions are invoked in left-to-right order as specified in the action sequence. 1m10.2.3. Multi-Click Time0m Translation table entries may specify actions that are taken when two or more identical events occur consecutively within a short time interval, called the multi-click time. The multi-click time value may be specified as an application resource with name ``multiClickTime'' and class ``Mul- tiClickTime'' and may also be modified dynamically by the application. The multi-click time is unique for each Dis- play value and is retrieved from the resource database by 4mXtDisplayInitialize24m. If no value is specified, the initial value is 200 milliseconds. To set the multi-click time dynamically, use 4mXtSetMul-0m 4mtiClickTime24m. __ | void XtSetMultiClickTime(4mdisplay24m, 4mtime24m) Display *4mdisplay24m; int 4mtime24m; 4mdisplay24m Specifies the display connection. 4mtime24m Specifies the multi-click time in milliseconds. |__ 4mXtSetMultiClickTime24m sets the time interval used by the translation manager to determine when multiple events are interpreted as a repeated event. When a repeat count is 1m2710m 1mX Toolkit Intrinsics X11 Release 6.40m specified in a translation entry, the interval between the timestamps in each pair of repeated events (e.g., between two 4mButtonPress24m events) must be less than the multi-click time in order for the translation actions to be taken. To read the multi-click time, use 4mXtGetMultiClickTime24m. __ | int XtGetMultiClickTime(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the display connection. |__ 4mXtGetMultiClickTime24m returns the time in milliseconds that the translation manager uses to determine if multiple events are to be interpreted as a repeated event for purposes of matching a translation entry containing a repeat count. 1m10.3. Translation Table Management0m Sometimes an application needs to merge its own translations with a widget's translations. For example, a window manager provides functions to move a window. The window manager wishes to bind this operation to a specific pointer button in the title bar without the possibility of user override and bind it to other buttons that may be overridden by the user. To accomplish this, the window manager should first create the title bar and then should merge the two translation tables into the title bar's translations. One translation table contains the translations that the window manager wants only if the user has not specified a translation for a particular event or event sequence (i.e., those that may be overridden). The other translation table contains the translations that the window manager wants regardless of what the user has specified. Three Intrinsics functions support this merging: 4mXtParseTransla-24m Compiles a translation table. 4mtionTable0m 4mXtAugmentTransla-24m Merges a compiled translation table 4mtions24m into a widget's compiled translation table, ignoring any new translations that conflict with existing transla- tions. 1m2720m 1mX Toolkit Intrinsics X11 Release 6.40m 4mXtOverrideTransla-24m Merges a compiled translation table 4mtions24m into a widget's compiled translation table, replacing any existing trans- lations that conflict with new trans- lations. To compile a translation table, use 4mXtParseTranslationTable24m. __ | XtTranslations XtParseTranslationTable(4mtable24m) String 4mtable24m; 4mtable24m Specifies the translation table to compile. |__ The 4mXtParseTranslationTable24m function compiles the transla- tion table, provided in the format given in Appendix B, into an opaque internal representation of type 4mXtTranslations24m. Note that if an empty translation table is required for any purpose, one can be obtained by calling 4mXtParseTransla-0m 4mtionTable24m and passing an empty string. To merge additional translations into an existing transla- tion table, use 4mXtAugmentTranslations24m. __ | void XtAugmentTranslations(4mw24m, 4mtranslations24m) Widget 4mw24m; XtTranslations 4mtranslations24m; 4mw24m Specifies the widget into which the new transla- tions are to be merged. Must be of class Core or any subclass thereof. 4mtranslations0m Specifies the compiled translation table to merge in. |__ The 4mXtAugmentTranslations24m function merges the new transla- tions into the existing widget translations, ignoring any 4m#replace24m, 4m#augment24m, or 4m#override24m directive that may have been specified in the translation string. The translation table specified by 4mtranslations24m is not altered by this process. 4mXtAugmentTranslations24m logically appends the string representation of the new translations to the string repre- sentation of the widget's current translations and reparses 1m2730m 1mX Toolkit Intrinsics X11 Release 6.40m the result with no warning messages about duplicate left- hand sides, then stores the result back into the widget instance; i.e., if the new translations contain an event or event sequence that already exists in the widget's transla- tions, the new translation is ignored. To overwrite existing translations with new translations, use 4mXtOverrideTranslations24m. __ | void XtOverrideTranslations(4mw24m, 4mtranslations24m) Widget 4mw24m; XtTranslations 4mtranslations24m; 4mw24m Specifies the widget into which the new transla- tions are to be merged. Must be of class Core or any subclass thereof. 4mtranslations0m Specifies the compiled translation table to merge in. |__ The 4mXtOverrideTranslations24m function merges the new transla- tions into the existing widget translations, ignoring any 4m#replace24m, 4m#augment24m, or 4m#override24m directive that may have been specified in the translation string. The translation table specified by 4mtranslations24m is not altered by this process. 4mXtOverrideTranslations24m logically appends the string representation of the widget's current translations to the string representation of the new translations and reparses the result with no warning messages about duplicate left-hand sides, then stores the result back into the widget instance; i.e., if the new translations contain an event or event sequence that already exists in the widget's transla- tions, the new translation overrides the widget's transla- tion. To replace a widget's translations completely, use 4mXtSetVal-0m 4mues24m on the XtNtranslations resource and specify a compiled translation table as the value. To make it possible for users to easily modify translation tables in their resource files, the string-to-translation- table resource type converter allows the string to specify whether the table should replace, augment, or override any existing translation table in the widget. To specify this, a pound sign (#) is given as the first character of the ta- ble followed by one of the keywords ``replace'', ``aug- ment'', or ``override'' to indicate whether to replace, 1m2740m 1mX Toolkit Intrinsics X11 Release 6.40m augment, or override the existing table. The replace or merge operation is performed during the Core instance ini- tialization. Each merge operation produces a new transla- tion resource value; if the original tables were shared by other widgets, they are unaffected. If no directive is specified, ``#replace'' is assumed. At instance initialization the XtNtranslations resource is first fetched. Then, if it was not specified or did not contain ``#replace'', the resource database is searched for the resource XtNbaseTranslations. If XtNbaseTranslations is found, it is merged into the widget class translation table. Then the widget 4mtranslations24m field is merged into the result or into the class translation table if XtNbaseTranslations was not found. This final table is then stored into the widget 4mtranslations24m field. If the XtNtranslations resource specified ``#replace'', no merge is done. If neither XtNbaseTranslations or XtNtranslations are specified, the class translation table is copied into the widget instance. To completely remove existing translations, use 4mXtUninstall-0m 4mTranslations24m. __ | void XtUninstallTranslations(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget from which the translations are to be removed. Must be of class Core or any subclass thereof. |__ The 4mXtUninstallTranslations24m function causes the entire translation table for the widget to be removed. 1m10.4. Using Accelerators0m It is often desirable to be able to bind events in one wid- get to actions in another. In particular, it is often use- ful to be able to invoke menu actions from the keyboard. The Intrinsics provide a facility, called accelerators, that lets you accomplish this. An accelerator table is a trans- lation table that is bound with its actions in the context of a particular widget, the 4msource24m widget. The accelerator table can then be installed on one or more 4mdestination24m wid- gets. When an event sequence in the destination widget would cause an accelerator action to be taken, and if the source widget is sensitive, the actions are executed as though triggered by the same event sequence in the accelera- tor source widget. The event is passed to the action 1m2750m 1mX Toolkit Intrinsics X11 Release 6.40m procedure without modification. The action procedures used within accelerators must not assume that the source widget is realized nor that any fields of the event are in refer- ence to the source widget's window if the widget is real- ized. Each widget instance contains that widget's exported accel- erator table as a resource. Each class of widget exports a method that takes a displayable string representation of the accelerators so that widgets can display their current accelerators. The representation is the accelerator table in canonical translation table form (see Appendix B). The display_accelerator procedure pointer is of type 4mXtString-0m 4mProc24m. __ | typedef void (*XtStringProc)(Widget, String); Widget 4mw24m; String 4mstring24m; 4mw24m Specifies the source widget that supplied the accelerators. 4mstring24m Specifies the string representation of the accel- erators for this widget. |__ Accelerators can be specified in resource files, and the string representation is the same as for a translation ta- ble. However, the interpretation of the 4m#augment24m and 4m#over-0m 4mride24m directives applies to what will happen when the accel- erator is installed; that is, whether or not the accelerator translations will override the translations in the destina- tion widget. The default is 4m#augment24m, which means that the accelerator translations have lower priority than the desti- nation translations. The 4m#replace24m directive is ignored for accelerator tables. To parse an accelerator table, use 4mXtParseAcceleratorTable24m. __ | XtAccelerators XtParseAcceleratorTable(4msource24m) String 4msource24m; 4msource24m Specifies the accelerator table to compile. |__ The 4mXtParseAcceleratorTable24m function compiles the accelera- tor table into an opaque internal representation. The 1m2760m 1mX Toolkit Intrinsics X11 Release 6.40m client should set the XtNaccelerators resource of each wid- get that is to be activated by these translations to the returned value. To install accelerators from a widget on another widget, use 4mXtInstallAccelerators24m. __ | void XtInstallAccelerators(4mdestination24m, 4msource24m) Widget 4mdestination24m; Widget 4msource24m; 4mdestination0m Specifies the widget on which the accelerators are to be installed. Must be of class Core or any subclass thereof. 4msource24m Specifies the widget from which the accelerators are to come. Must be of class Core or any sub- class thereof. |__ The 4mXtInstallAccelerators24m function installs the 4maccelerators0m resource value from 4msource24m onto 4mdestination24m by merging the source accelerators into the destination translations. If the source 4mdisplay_accelerator24m field is non-NULL, 4mXtInstal-0m 4mlAccelerators24m calls it with the source widget and a string representation of the accelerator table, which indicates that its accelerators have been installed and that it should display them appropriately. The string representation of the accelerator table is its canonical translation table representation. As a convenience for installing all accelerators from a wid- get and all its descendants onto one destination, use 4mXtIn-0m 4mstallAllAccelerators24m. 1m2770m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtInstallAllAccelerators(4mdestination24m, 4msource24m) Widget 4mdestination24m; Widget 4msource24m; 4mdestination0m Specifies the widget on which the accelerators are to be installed. Must be of class Core or any subclass thereof. 4msource24m Specifies the root widget of the widget tree from which the accelerators are to come. Must be of class Core or any subclass thereof. |__ The 4mXtInstallAllAccelerators24m function recursively descends the widget tree rooted at 4msource24m and installs the accelera- tors resource value of each widget encountered onto 4mdestina-0m 4mtion24m. A common use is to call 4mXtInstallAllAccelerators24m and pass the application main window as the source. 1m10.5. KeyCode-to-KeySym Conversions0m The translation manager provides support for automatically translating KeyCodes in incoming key events into KeySyms. KeyCode-to-KeySym translator procedure pointers are of type 4mXtKeyProc24m. 1m2780m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtKeyProc)(Display*, KeyCode, Modifiers, Modifiers*, KeySym*); Display *4mdisplay24m; KeyCode 4mkeycode24m; Modifiers 4mmodifiers24m; Modifiers *4mmodifiers_return24m; KeySym *4mkeysym_return24m; 4mdisplay24m Specifies the display that the KeyCode is from. 4mkeycode24m Specifies the KeyCode to translate. 4mmodifiers24m Specifies the modifiers to the KeyCode. 4mmodifiers_return0m Specifies a location in which to store a mask that indicates the subset of all modifiers that are examined by the key translator for the speci- fied keycode. 4mkeysym_return0m Specifies a location in which to store the resulting KeySym. |__ This procedure takes a KeyCode and modifiers and produces a KeySym. For any given key translator function and keyboard encoding, 4mmodifiers_return24m will be a constant per KeyCode that indicates the subset of all modifiers that are examined by the key translator for that KeyCode. The KeyCode-to-KeySym translator procedure must be imple- mented such that multiple calls with the same 4mdisplay24m, 4mkey-0m 4mcode24m, and 4mmodifiers24m return the same result until either a new case converter, an 4mXtCaseProc24m, is installed or a 4mMap-0m 4mpingNotify24m event is received. The Intrinsics maintain tables internally to map KeyCodes to KeySyms for each open display. Translator procedures and other clients may share a single copy of this table to per- form the same mapping. To return a pointer to the KeySym-to-KeyCode mapping table for a particular display, use 4mXtGetKeysymTable24m. 1m2790m 1mX Toolkit Intrinsics X11 Release 6.40m __ | KeySym *XtGetKeysymTable(4mdisplay24m, 4mmin_keycode_return24m, 4mkeysyms_per_keycode_return24m) Display *4mdisplay24m; KeyCode *4mmin_keycode_return24m; int *4mkeysyms_per_keycode_return24m; 4mdisplay24m Specifies the display whose table is required. 4mmin_keycode_return0m Returns the minimum KeyCode valid for the display. 4mkeysyms_per_keycode_return0m Returns the number of KeySyms stored for each Key- Code. |__ 4mXtGetKeysymTable24m returns a pointer to the Intrinsics' copy of the server's KeyCode-to-KeySym table. This table must not be modified. There are 4mkeysyms_per_keycode_return0m KeySyms associated with each KeyCode, located in the table with indices starting at index (test_keycode - min_keycode_return) * keysyms_per_keycode_return for KeyCode 4mtest_keycode24m. Any entries that have no KeySyms associated with them contain the value 4mNoSymbol24m. Clients should not cache the KeySym table but should call 4mXtGetKeysymTable24m each time the value is needed, as the table may change prior to dispatching each event. For more information on this table, see Section 12.7 in 4mXlib0m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m. To register a key translator, use 4mXtSetKeyTranslator24m. __ | void XtSetKeyTranslator(4mdisplay24m, 4mproc24m) Display *4mdisplay24m; XtKeyProc 4mproc24m; 4mdisplay24m Specifies the display from which to translate the events. 4mproc24m Specifies the procedure to perform key transla- tions. |__ The 4mXtSetKeyTranslator24m function sets the specified procedure as the current key translator. The default translator is 1m2800m 1mX Toolkit Intrinsics X11 Release 6.40m 4mXtTranslateKey24m, an 4mXtKeyProc24m that uses the Shift, Lock, num- lock, and group modifiers with the interpretations defined in 4mX24m 4mWindow24m 4mSystem24m 4mProtocol24m, Section 5. It is provided so that new translators can call it to get default KeyCode-to- KeySym translations and so that the default translator can be reinstalled. To invoke the currently registered KeyCode-to-KeySym trans- lator, use 4mXtTranslateKeycode24m. __ | void XtTranslateKeycode(4mdisplay24m, 4mkeycode24m, 4mmodifiers24m, 4mmodifiers_return24m, 4mkeysym_return24m) Display *4mdisplay24m; KeyCode 4mkeycode24m; Modifiers 4mmodifiers24m; Modifiers *4mmodifiers_return24m; KeySym *4mkeysym_return24m; 4mdisplay24m Specifies the display that the KeyCode is from. 4mkeycode24m Specifies the KeyCode to translate. 4mmodifiers24m Specifies the modifiers to the KeyCode. 4mmodifiers_return0m Returns a mask that indicates the modifiers actu- ally used to generate the KeySym. 4mkeysym_return0m Returns the resulting KeySym. |__ The 4mXtTranslateKeycode24m function passes the specified argu- ments directly to the currently registered KeyCode-to-KeySym translator. To handle capitalization of nonstandard KeySyms, the Intrin- sics allow clients to register case conversion routines. Case converter procedure pointers are of type 4mXtCaseProc24m. 1m2810m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtCaseProc)(Display*, KeySym, KeySym*, KeySym*); Display *4mdisplay24m; KeySym 4mkeysym24m; KeySym *4mlower_return24m; KeySym *4mupper_return24m; 4mdisplay24m Specifies the display connection for which the conversion is required. 4mkeysym24m Specifies the KeySym to convert. 4mlower_return0m Specifies a location into which to store the low- ercase equivalent for the KeySym. 4mupper_return0m Specifies a location into which to store the uppercase equivalent for the KeySym. |__ If there is no case distinction, this procedure should store the KeySym into both return values. To register a case converter, use 4mXtRegisterCaseConverter24m. __ | void XtRegisterCaseConverter(4mdisplay24m, 4mproc24m, 4mstart24m, 4mstop24m) Display *4mdisplay24m; XtCaseProc 4mproc24m; KeySym 4mstart24m; KeySym 4mstop24m; 4mdisplay24m Specifies the display from which the key events are to come. 4mproc24m Specifies the 4mXtCaseProc24m to do the conversions. 4mstart24m Specifies the first KeySym for which this con- verter is valid. 4mstop24m Specifies the last KeySym for which this converter is valid. |__ The 4mXtRegisterCaseConverter24m registers the specified case converter. The 4mstart24m and 4mstop24m arguments provide the inclu- sive range of KeySyms for which this converter is to be called. The new converter overrides any previous converters for KeySyms in that range. No interface exists to remove 1m2820m 1mX Toolkit Intrinsics X11 Release 6.40m converters; you need to register an identity converter. When a new converter is registered, the Intrinsics refresh the keyboard state if necessary. The default converter understands case conversion for all Latin KeySyms defined in 4mX24m 4mWindow24m 4mSystem24m 4mProtocol24m, Appendix A. To determine uppercase and lowercase equivalents for a KeySym, use 4mXtConvertCase24m. __ | void XtConvertCase(4mdisplay24m, 4mkeysym24m, 4mlower_return24m, 4mupper_return24m) Display *4mdisplay24m; KeySym 4mkeysym24m; KeySym *4mlower_return24m; KeySym *4mupper_return24m; 4mdisplay24m Specifies the display that the KeySym came from. 4mkeysym24m Specifies the KeySym to convert. 4mlower_return0m Returns the lowercase equivalent of the KeySym. 4mupper_return0m Returns the uppercase equivalent of the KeySym. |__ The 4mXtConvertCase24m function calls the appropriate converter and returns the results. A user-supplied 4mXtKeyProc24m may need to use this function. 1m10.6. Obtaining a KeySym in an Action Procedure0m When an action procedure is invoked on a 4mKeyPress24m or 4mKeyRe-0m 4mlease24m event, it often has a need to retrieve the KeySym and modifiers corresponding to the event that caused it to be invoked. In order to avoid repeating the processing that was just performed by the Intrinsics to match the transla- tion entry, the KeySym and modifiers are stored for the duration of the action procedure and are made available to the client. To retrieve the KeySym and modifiers that matched the final event specification in the translation table entry, use 4mXtGetActionKeysym24m. 1m2830m 1mX Toolkit Intrinsics X11 Release 6.40m __ | KeySym XtGetActionKeysym(4mevent24m, 4mmodifiers_return24m) XEvent *4mevent24m; Modifiers *4mmodifiers_return24m; 4mevent24m Specifies the event pointer passed to the action procedure by the Intrinsics. 4mmodifiers_return0m Returns the modifiers that caused the match, if non-NULL. |__ If 4mXtGetActionKeysym24m is called after an action procedure has been invoked by the Intrinsics and before that action proce- dure returns, and if the event pointer has the same value as the event pointer passed to that action routine, and if the event is a 4mKeyPress24m or 4mKeyRelease24m event, then 4mXtGetAction-0m 4mKeysym24m returns the KeySym that matched the final event spec- ification in the translation table and, if 4mmodifiers_return0m is non-NULL, the modifier state actually used to generate this KeySym; otherwise, if the event is a 4mKeyPress24m or 4mKeyRe-0m 4mlease24m event, then 4mXtGetActionKeysym24m calls 4mXtTranslateKeycode0m and returns the results; else it returns 4mNoSymbol24m and does not examine 4mmodifiers_return24m. Note that if an action procedure invoked by the Intrinsics invokes a subsequent action procedure (and so on) via 4mXtCallActionProc24m, the nested action procedure may also call 4mXtGetActionKeysym24m to retrieve the Intrinsics' KeySym and modifiers. 1m10.7. KeySym-to-KeyCode Conversions0m To return the list of KeyCodes that map to a particular KeySym in the keyboard mapping table maintained by the Intrinsics, use 4mXtKeysymToKeycodeList24m. 1m2840m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtKeysymToKeycodeList(4mdisplay24m, 4mkeysym24m, 4mkeycodes_return24m, 4mkeycount_return24m) Display *4mdisplay24m; KeySym 4mkeysym24m; KeyCode **4mkeycodes_return24m; Cardinal *4mkeycount_return24m; 4mdisplay24m Specifies the display whose table is required. 4mkeysym24m Specifies the KeySym for which to search. 4mkeycodes_return0m Returns a list of KeyCodes that have 4mkeysym0m associated with them, or NULL if 4mkeycount_return0m is 0. 4mkeycount_return0m Returns the number of KeyCodes in the keycode list. |__ The 4mXtKeysymToKeycodeList24m procedure returns all the KeyCodes that have 4mkeysym24m in their entry for the keyboard mapping ta- ble associated with 4mdisplay24m. For each entry in the table, the first four KeySyms (groups 1 and 2) are interpreted as specified by 4mX24m 4mWindow24m 4mSystem24m 4mProtocol24m, Section 5. If no KeyCodes map to the specified KeySym, 4mkeycount_return24m is zero and *4mkeycodes_return24m is NULL. The caller should free the storage pointed to by 4mkey-0m 4mcodes_return24m using 4mXtFree24m when it is no longer useful. If the caller needs to examine the KeyCode-to-KeySym table for a particular KeyCode, it should call 4mXtGetKeysymTable24m. 1m10.8. Registering Button and Key Grabs for Actions0m To register button and key grabs for a widget's window according to the event bindings in the widget's translation table, use 4mXtRegisterGrabAction24m. 1m2850m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtRegisterGrabAction(4maction_proc24m, 4mowner_events24m, 4mevent_mask24m, 4mpointer_mode24m, 4mkeyboard_mode24m) XtActionProc 4maction_proc24m; Boolean 4mowner_events24m; unsigned int 4mevent_mask24m; int 4mpointer_mode24m, 4mkeyboard_mode24m; 4maction_proc0m Specifies the action procedure to search for in translation tables. 4mowner_events0m 4mevent_mask0m 4mpointer_mode0m 4mkeyboard_mode0m Specify arguments to 4mXtGrabButton24m or 4mXtGrabKey24m. |__ 4mXtRegisterGrabAction24m adds the specified 4maction_proc24m to a list known to the translation manager. When a widget is realized, or when the translations of a realized widget or the accelerators installed on a realized widget are modi- fied, its translation table and any installed accelerators are scanned for action procedures on this list. If any are invoked on 4mButtonPress24m or 4mKeyPress24m events as the only or final event in a sequence, the Intrinsics will call 4mXtGrab-0m 4mButton24m or 4mXtGrabKey24m for the widget with every button or Key- Code which maps to the event detail field, passing the spec- ified 4mowner_events24m, 4mevent_mask24m, 4mpointer_mode24m, and 4mkey-0m 4mboard_mode24m. For 4mButtonPress24m events, the modifiers specified in the grab are determined directly from the translation specification and 4mconfine_to24m and 4mcursor24m are specified as 4mNone24m. For 4mKeyPress24m events, if the translation table entry specifies colon (:) in the modifier list, the modifiers are determined by calling the key translator procedure regis- tered for the display and calling 4mXtGrabKey24m for every combi- nation of standard modifiers which map the KeyCode to the specified event detail KeySym, and ORing any modifiers spec- ified in the translation table entry, and 4mevent_mask24m is ignored. If the translation table entry does not specify colon in the modifier list, the modifiers specified in the grab are those specified in the translation table entry only. For both 4mButtonPress24m and 4mKeyPress24m events, don't-care modifiers are ignored unless the translation entry explic- itly specifies ``Any'' in the 4mmodifiers24m field. If the specified 4maction_proc24m is already registered for the calling process, the new values will replace the previously specified values for any widgets that become realized fol- lowing the call, but existing grabs are not altered on cur- rently realized widgets. 1m2860m 1mX Toolkit Intrinsics X11 Release 6.40m When translations or installed accelerators are modified for a realized widget, any previous key or button grabs regis- tered as a result of the old bindings are released if they do not appear in the new bindings and are not explicitly grabbed by the client with 4mXtGrabKey24m or 4mXtGrabButton24m. 1m10.9. Invoking Actions Directly0m Normally action procedures are invoked by the Intrinsics when an event or event sequence arrives for a widget. To invoke an action procedure directly, without generating (or synthesizing) events, use 4mXtCallActionProc24m. __ | void XtCallActionProc(4mwidget24m, 4maction24m, 4mevent24m, 4mparams24m, 4mnum_params24m) Widget 4mwidget24m; String 4maction24m; XEvent *4mevent24m; String *4mparams24m; Cardinal 4mnum_params24m; 4mwidget24m Specifies the widget in which the action is to be invoked. Must be of class Core or any subclass thereof. 4maction24m Specifies the name of the action routine. 4mevent24m Specifies the contents of the 4mevent24m passed to the action routine. 4mparams24m Specifies the contents of the 4mparams24m passed to the action routine. 4mnum_params0m Specifies the number of entries in 4mparams24m. |__ 4mXtCallActionProc24m searches for the named action routine in the same manner and order as translation tables are bound, as described in Section 10.1.2, except that application action tables are searched, if necessary, as of the time of the call to 4mXtCallActionProc24m. If found, the action routine is invoked with the specified widget, event pointer, and parameters. It is the responsibility of the caller to ensure that the contents of the 4mevent24m, 4mparams24m, and 4mnum_params24m arguments are appropriate for the specified action routine and, if necessary, that the specified widget is realized or sensitive. If the named action routine can- not be found, 4mXtCallActionProc24m generates a warning message and returns. 1m2870m 1mX Toolkit Intrinsics X11 Release 6.40m 1m10.10. Obtaining a Widget's Action List0m Occasionally a subclass will require the pointers to one or more of its superclass's action procedures. This would be needed, for example, in order to envelop the superclass's action. To retrieve the list of action procedures regis- tered in the superclass's 4mactions24m field, use 4mXtGetAction-0m 4mList24m. __ | void XtGetActionList(4mwidget_class24m, 4mactions_return24m, 4mnum_actions_return24m) WidgetClass 4mwidget_class24m; XtActionList *4mactions_return24m; Cardinal *4mnum_actions_return24m; 4mwidget_class24m Specifies the widget class whose actions are to be returned. 4mactions_return24m Returns the action list. 4mnum_actions_return0m Returns the number of action procedures declared by the class. |__ 4mXtGetActionList24m returns the action table defined by the specified widget class. This table does not include actions defined by the superclasses. If 4mwidget_class24m is not ini- tialized, or is not 4mcoreWidgetClass24m or a subclass thereof, or if the class does not define any actions, *4mactions_return0m will be NULL and *4mnum_actions_return24m will be zero. If *4mactions_return24m is non-NULL the client is responsible for freeing the table using 4mXtFree24m when it is no longer needed. 1m2880m 1mX Toolkit Intrinsics X11 Release 6.40m 1mChapter 110m 1mUtility Functions0m The Intrinsics provide a number of utility functions that you can use to · Determine the number of elements in an array. · Translate strings to widget instances. · Manage memory usage. · Share graphics contexts. · Manipulate selections. · Merge exposure events into a region. · Translate widget coordinates. · Locate a widget given a window id. · Handle errors. · Set the WM_COLORMAP_WINDOWS property. · Locate files by name with string substitutions. · Register callback functions for external agents. · Locate all the displays of an application context. 1m11.1. Determining the Number of Elements in an Array0m To determine the number of elements in a fixed-size array, use 4mXtNumber24m. __ | Cardinal XtNumber(4marray24m) 4mArrayType24m 4marray24m; 4marray24m Specifies a fixed-size array of arbitrary type. |__ The 4mXtNumber24m macro returns the number of elements allocated to the array. 1m2890m 1mX Toolkit Intrinsics X11 Release 6.40m 1m11.2. Translating Strings to Widget Instances0m To translate a widget name to a widget instance, use 4mXtName-0m 4mToWidget24m. __ | Widget XtNameToWidget(4mreference24m, 4mnames24m) Widget 4mreference24m; String 4mnames24m; 4mreference24m Specifies the widget from which the search is to start. Must be of class Core or any subclass thereof. 4mnames24m Specifies the partially qualified name of the desired widget. |__ The 4mXtNameToWidget24m function searches for a descendant of the 4mreference24m widget whose name matches the specified names. The 4mnames24m parameter specifies a simple object name or a series of simple object name components separated by periods or asterisks. 4mXtNameToWidget24m returns the descendant with the shortest name matching the specification according to the following rules, where child is either a pop-up child or a normal child if the widget's class is a subclass of Com- posite : · Enumerate the object subtree rooted at the reference widget in breadth-first order, qualifying the name of each object with the names of all its ancestors up to, but not including, the reference widget. The ordering between children of a common parent is not defined. · Return the first object in the enumeration that matches the specified name, where each component of 4mnames0m matches exactly the corresponding component of the qualified object name and asterisk matches any series of components, including none. · If no match is found, return NULL. Since breadth-first traversal is specified, the descendant with the shortest matching name (i.e., the fewest number of components), if any, will always be returned. However, since the order of enumeration of children is undefined and since the Intrinsics do not require that all children of a widget have unique names, 4mXtNameToWidget24m may return any child that matches if there are multiple objects in the sub- tree with the same name. Consecutive separators (periods or asterisks) including at least one asterisk are treated as a single asterisk. Consecutive periods are treated as a 1m2900m 1mX Toolkit Intrinsics X11 Release 6.40m single period. 1m11.3. Managing Memory Usage0m The Intrinsics memory management functions provide uniform checking for null pointers and error reporting on memory allocation errors. These functions are completely compati- ble with their standard C language runtime counterparts 4mmal-0m 4mloc24m, 4mcalloc24m, 4mrealloc24m, and 4mfree24m with the following added functionality: · 4mXtMalloc24m, 4mXtCalloc24m, and 4mXtRealloc24m give an error if there is not enough memory. · 4mXtFree24m simply returns if passed a NULL pointer. · 4mXtRealloc24m simply allocates new storage if passed a NULL pointer. See the standard C library documentation on 4mmalloc24m, 4mcalloc24m, 4mrealloc24m, and 4mfree24m for more information. To allocate storage, use 4mXtMalloc24m. __ | char *XtMalloc(4msize24m) Cardinal 4msize24m; 4msize24m Specifies the number of bytes desired. |__ The 4mXtMalloc24m function returns a pointer to a block of stor- age of at least the specified 4msize24m bytes. If there is insufficient memory to allocate the new block, 4mXtMalloc0m calls 4mXtErrorMsg24m. To allocate and initialize an array, use 4mXtCalloc24m. 1m2910m 1mX Toolkit Intrinsics X11 Release 6.40m __ | char *XtCalloc(4mnum24m, 4msize24m) Cardinal 4mnum24m; Cardinal 4msize24m; 4mnum24m Specifies the number of array elements to allo- cate. 4msize24m Specifies the size of each array element in bytes. |__ The 4mXtCalloc24m function allocates space for the specified num- ber of array elements of the specified size and initializes the space to zero. If there is insufficient memory to allo- cate the new block, 4mXtCalloc24m calls 4mXtErrorMsg24m. 4mXtCalloc0m returns the address of the allocated storage. To change the size of an allocated block of storage, use 4mXtRealloc24m. __ | char *XtRealloc(4mptr24m, 4mnum24m) char *4mptr24m; Cardinal 4mnum24m; 4mptr24m Specifies a pointer to the old storage allocated with 4mXtMalloc24m, 4mXtCalloc24m, or 4mXtRealloc24m, or NULL. 4mnum24m Specifies number of bytes desired in new storage. |__ The 4mXtRealloc24m function changes the size of a block of stor- age, possibly moving it. Then it copies the old contents (or as much as will fit) into the new block and frees the old block. If there is insufficient memory to allocate the new block, 4mXtRealloc24m calls 4mXtErrorMsg24m. If 4mptr24m is NULL, 4mXtRealloc24m simply calls 4mXtMalloc24m. 4mXtRealloc24m then returns the address of the new block. To free an allocated block of storage, use 4mXtFree24m. 1m2920m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtFree(4mptr24m) char *4mptr24m; 4mptr24m Specifies a pointer to a block of storage allo- cated with 4mXtMalloc24m, 4mXtCalloc24m, or 4mXtRealloc24m, or NULL. |__ The 4mXtFree24m function returns storage, allowing it to be reused. If 4mptr24m is NULL, 4mXtFree24m returns immediately. To allocate storage for a new instance of a type, use 4mXtNew24m. __ | 4mtype24m *XtNew(4mtype24m) 4mtype24m 4mt24m; 4mtype24m Specifies a previously declared type. |__ 4mXtNew24m returns a pointer to the allocated storage. If there is insufficient memory to allocate the new block, 4mXtNew0m calls 4mXtErrorMsg24m. 4mXtNew24m is a convenience macro that calls 4mXtMalloc24m with the following arguments specified: ((type *) XtMalloc((unsigned) sizeof(type))) The storage allocated by 4mXtNew24m should be freed using 4mXtFree24m. To copy an instance of a string, use 4mXtNewString24m. __ | String XtNewString(4mstring24m) String 4mstring24m; 4mstring24m Specifies a previously declared string. |__ 4mXtNewString24m returns a pointer to the allocated storage. If there is insufficient memory to allocate the new block, 4mXtNewString24m calls 4mXtErrorMsg24m. 4mXtNewString24m is a convenience macro that calls 4mXtMalloc24m with the following arguments spec- ified: 1m2930m 1mX Toolkit Intrinsics X11 Release 6.40m (strcpy(XtMalloc((unsigned)strlen(str) + 1), str)) The storage allocated by 4mXtNewString24m should be freed using 4mXtFree24m. 1m11.4. Sharing Graphics Contexts0m The Intrinsics provide a mechanism whereby cooperating objects 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 allows for clients to declare both modifiable and nonmodifiable fields of the shared GCs. To obtain a shareable GC with modifiable fields, use 4mXtAllo-0m 4mcateGC24m. __ | GC XtAllocateGC(4mwidget24m, 4mdepth24m, 4mvalue_mask24m, 4mvalues24m, 4mdynamic_mask24m, 4munused_mask24m) Widget 4mobject24m; Cardinal 4mdepth24m; XtGCMask 4mvalue_mask24m; XGCValues *4mvalues24m; XtGCMask 4mdynamic_mask24m; XtGCMask 4munused_mask24m; 4mobject24m Specifies an object, giving the screen for which the returned GC is valid. Must be of class Object or any subclass thereof. 4mdepth24m Specifies the depth for which the returned GC is valid, or 0. 4mvalue_mask0m Specifies fields of the GC that are initialized from 4mvalues24m. 4mvalues24m Specifies the values for the initialized fields. 4mdynamic_mask0m Specifies fields of the GC that will be modified by the caller. 4munused_mask0m Specifies fields of the GC that will not be needed by the caller. |__ The 4mXtAllocateGC24m function returns a shareable GC that may be modified by the client. The 4mscreen24m field of the specified 1m2940m 1mX Toolkit Intrinsics X11 Release 6.40m widget or of the nearest widget ancestor of the specified object and the specified 4mdepth24m argument supply the root and drawable depths for which the GC is to be valid. If 4mdepth0m is zero, the depth is taken from the 4mdepth24m field of the specified widget or of the nearest widget ancestor of the specified object. The 4mvalue_mask24m argument specifies fields of the GC that are initialized with the respective member of the 4mvalues24m struc- ture. The 4mdynamic_mask24m argument specifies fields that the caller intends to modify during program execution. The caller must ensure that the corresponding GC field is set prior to each use of the GC. The 4munused_mask24m argument spec- ifies fields of the GC that are of no interest to the caller. The caller may make no assumptions about the con- tents of any fields specified in 4munused_mask24m. The caller may assume that at all times all fields not specified in either 4mdynamic_mask24m or 4munused_mask24m have their default value if not specified in 4mvalue_mask24m or the value specified by 4mvalues24m. If a field is specified in both 4mvalue_mask24m and 4mdynamic_mask24m, the effect is as if it were specified only in 4mdynamic_mask24m and then immediately set to the value in 4mval-0m 4mues24m. If a field is set in 4munused_mask24m and also in either 4mvalue_mask24m or 4mdynamic_mask24m, the specification in 4munused_mask0m is ignored. 4mXtAllocateGC24m tries to minimize the number of unique GCs cre- ated by comparing the arguments with those of previous calls and returning an existing GC when there are no conflicts. 4mXtAllocateGC24m may modify and return an existing GC if it was allocated with a nonzero 4munused_mask24m. To obtain a shareable GC with no modifiable fields, use 4mXtGetGC24m. 1m2950m 1mX Toolkit Intrinsics X11 Release 6.40m __ | GC XtGetGC(4mobject24m, 4mvalue_mask24m, 4mvalues24m) Widget 4mobject24m; XtGCMask 4mvalue_mask24m; XGCValues *4mvalues24m; 4mobject24m Specifies an object, giving the screen and depth for which the returned GC is valid. Must be of class Object or any subclass thereof. 4mvalue_mask0m Specifies which fields of the 4mvalues24m structure are specified. 4mvalues24m Specifies the actual values for this GC. |__ The 4mXtGetGC24m function returns a shareable, read-only GC. The parameters to this function are the same as those for 4mXCre-0m 4mateGC24m except that an Object is passed instead of a Display. 4mXtGetGC24m is equivalent to 4mXtAllocateGC24m with 4mdepth24m, 4mdynamic_mask24m, and 4munused_mask24m all zero. 4mXtGetGC24m shares only GCs in which all values in the GC returned by 4mXCreateGC24m are the same. In particular, it does not use the 4mvalue_mask24m provided to determine which fields of the GC a widget considers relevant. The 4mvalue_mask24m is used only to tell the server which fields should be filled in from 4mvalues24m and which it should fill in with default values. To deallocate a shared GC when it is no longer needed, use 4mXtReleaseGC24m. __ | void XtReleaseGC(4mobject24m, 4mgc24m) Widget 4mobject24m; GC 4mgc24m; 4mobject24m Specifies any object on the Display for which the GC was created. Must be of class Object or any subclass thereof. 4mgc24m Specifies the shared GC obtained with either 4mXtAl-0m 4mlocateGC24m or 4mXtGetGC24m. |__ References to shareable GCs are counted and a free request is generated to the server when the last user of a given GC releases it. 1m2960m 1mX Toolkit Intrinsics X11 Release 6.40m 1m11.5. Managing Selections0m Arbitrary widgets in multiple applications can communicate with each other by means of the Intrinsics global selection mechanism, which conforms to the specifications in the 4mInter-Client24m 4mCommunication24m 4mConventions24m 4mManual24m. The Intrin- sics supply functions for providing and receiving selection data in one logical piece (atomic transfers) or in smaller logical segments (incremental transfers). The incremental interface is provided for a selection owner or selection requestor that cannot or prefers not to pass the selection value to and from the Intrinsics in a single call. For instance, either an application that is running on a machine with limited memory may not be able to store the entire selection value in memory or a selection owner may already have the selection value available in discrete chunks, and it would be more efficient not to have to allo- cate additional storage to copy the pieces contiguously. Any owner or requestor that prefers to deal with the selec- tion value in segments can use the incremental interfaces to do so. The transfer between the selection owner or requestor and the Intrinsics is not required to match the underlying transport protocol between the application and the X server; the Intrinsics will break too large a selec- tion into smaller pieces for transport if necessary and will coalesce a selection transmitted incrementally if the value was requested atomically. 1m11.5.1. Setting and Getting the Selection Timeout Value0m To set the Intrinsics selection timeout, use 4mXtAppSetSelec-0m 4mtionTimeout24m. __ | void XtAppSetSelectionTimeout(4mapp_context24m, 4mtimeout24m) XtAppContext 4mapp_context24m; unsigned long 4mtimeout24m; 4mapp_context0m Specifies the application context. 4mtimeo24m|4m24m__ Specifies the selection timeout in milliseconds. To get the current selection timeout value, use 4mXtAppGetSe-0m 4mlectionTimeout24m. 1m2970m 1mX Toolkit Intrinsics X11 Release 6.40m __ | unsigned long XtAppGetSelectionTimeout(4mapp_context24m) XtAppContext 4mapp_context24m; 4mapp_context0m Specifies the application context. |__ The 4mXtAppGetSelectionTimeout24m function returns the current selection timeout value in milliseconds. The selection timeout is the time within which the two communicating applications must respond to one another. The initial time- out value is set by the selectionTimeout application resource as retrieved by 4mXtDisplayInitialize24m. If selection- Timeout is not specified, the default is five seconds. 1m11.5.2. Using Atomic Transfers0m When using atomic transfers, the owner will completely process one selection request at a time. The owner may con- sider each request individually, since there is no possibil- ity for overlap between evaluation of two requests. 1m11.5.2.1. Atomic Transfer Procedures0m The following procedures are used by the selection owner when providing selection data in a single unit. The procedure pointer specified by the owner to supply the selection data to the Intrinsics is of type 4mXtConvertSelec-0m 4mtionProc24m. 1m2980m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef Boolean (*XtConvertSelectionProc)(Widget, Atom*, Atom*, Atom*, XtPointer*, unsigned long*, int*); Widget 4mw24m; Atom *4mselection24m; Atom *4mtarget24m; Atom *4mtype_return24m; XtPointer *4mvalue_return24m; unsigned long *4mlength_return24m; int *4mformat_return24m; 4mw24m Specifies the widget that currently owns this selection. 4mselection24m Specifies the atom naming the selection requested (for example, 4mXA_PRIMARY24m or 4mXA_SECONDARY24m). 4mtarget24m Specifies the target type of the selection that has been requested, which indicates the desired information about the selection (for example, File Name, Text, Window). 4mtype_return0m Specifies a pointer to an atom into which the property type of the converted value of the selec- tion is to be stored. For instance, either File Name or Text might have property type 4mXA_STRING24m. 4mvalue_return0m Specifies a pointer into which a pointer to the converted value of the selection is to be stored. The selection owner is responsible for allocating this storage. If the selection owner has provided an 4mXtSelectionDoneProc24m for the selection, this storage is owned by the selection owner; other- wise, it is owned by the Intrinsics selection mechanism, which frees it by calling 4mXtFree24m when it is done with it. 4mlength_return0m Specifies a pointer into which the number of ele- ments in 4mvalue_return24m, each of size indicated by 4mformat_return24m, is to be stored. 4mformat_return0m Specifies a pointer into which the size in bits of the data elements of the selection value is to be stored. |__ This procedure is called by the Intrinsics selection mecha- nism to get the value of a selection as a given type from the current selection owner. It returns 4mTrue24m if the owner 1m2990m 1mX Toolkit Intrinsics X11 Release 6.40m successfully converted the selection to the target type or 4mFalse24m otherwise. If the procedure returns 4mFalse24m, the values of the return arguments are undefined. Each 4mXtConvertSelec-0m 4mtionProc24m should respond to target value 4mTARGETS24m by returning a value containing the list of the targets into which it is prepared to convert the selection. The value returned in 4mformat_return24m must be one of 8, 16, or 32 to allow the server to byte-swap the data if necessary. This procedure does not need to worry about responding to the MULTIPLE or the TIMESTAMP target values (see Section 2.6.2 in the 4mInter-Client24m 4mCommunication24m 4mConventions24m 4mManual24m). A selection request with the MULTIPLE target type is trans- parently transformed into a series of calls to this proce- dure, one for each target type, and a selection request with the TIMESTAMP target value is answered automatically by the Intrinsics using the time specified in the call to 4mXtOwnSe-0m 4mlection24m or 4mXtOwnSelectionIncremental24m. To retrieve the 4mSelectionRequest24m event that triggered the 4mXtConvertSelectionProc24m procedure, use 4mXtGetSelectionRequest24m. __ | XSelectionRequestEvent *XtGetSelectionRequest(4mw24m, 4mselection24m, 4mrequest_id24m) Widget 4mw24m; Atom 4mselection24m; XtRequestId 4mrequest_id24m; 4mw24m Specifies the widget that currently owns this selection. Must be of class Core or any subclass thereof. 4mselection24m Specifies the selection being processed. 4mrequest_id0m Specifies the requestor id in the case of incre- mental selections, or NULL in the case of atomic transfers. |__ 4mXtGetSelectionRequest24m may be called only from within an 4mXtConvertSelectionProc24m procedure and returns a pointer to the 4mSelectionRequest24m event that caused the conversion proce- dure to be invoked. 4mRequest_id24m specifies a unique id for the individual request in the case that multiple incremental transfers are outstanding. For atomic transfers, 4mrequest_id0m must be specified as NULL. If no 4mSelectionRequest24m event is being processed for the specified 4mwidget24m, 4mselection24m, and 4mrequest_id24m, 4mXtGetSelectionRequest24m returns NULL. 1m3000m 1mX Toolkit Intrinsics X11 Release 6.40m The procedure pointer specified by the owner when it desires notification upon losing ownership is of type 4mXtLoseSelec-0m 4mtionProc24m. __ | typedef void (*XtLoseSelectionProc)(Widget, Atom*); Widget 4mw24m; Atom *4mselection24m; 4mw24m Specifies the widget that has lost selection own- ership. 4mselection24m Specifies the atom naming the selection. |__ This procedure is called by the Intrinsics selection mecha- nism to inform the specified widget that it has lost the given selection. Note that this procedure does not ask the widget to relinquish the selection ownership; it is merely informative. The procedure pointer specified by the owner when it desires notification of receipt of the data or when it manages the storage containing the data is of type 4mXtSelectionDoneProc24m. __ | typedef void (*XtSelectionDoneProc)(Widget, Atom*, Atom*); Widget 4mw24m; Atom *4mselection24m; Atom *4mtarget24m; 4mw24m Specifies the widget that owns the converted selection. 4mselection24m Specifies the atom naming the selection that was converted. 4mtarget24m Specifies the target type to which the conversion was done. |__ This procedure is called by the Intrinsics selection mecha- nism to inform the selection owner that a selection requestor has successfully retrieved a selection value. If the selection owner has registered an 4mXtSelectionDoneProc24m, it should expect it to be called once for each conversion that it performs, after the converted value has been suc- cessfully transferred to the requestor. If the selection owner has registered an 4mXtSelectionDoneProc24m, it also owns 1m3010m 1mX Toolkit Intrinsics X11 Release 6.40m the storage containing the converted selection value. 1m11.5.2.2. Getting the Selection Value0m The procedure pointer specified by the requestor to receive the selection data from the Intrinsics is of type 4mXtSelec-0m 4mtionCallbackProc24m. __ | typedef void (*XtSelectionCallbackProc)(Widget, XtPointer, Atom*, Atom*, XtPointer, unsigned long*, int*); Widget 4mw24m; XtPointer 4mclient_data24m; Atom *4mselection24m; Atom *4mtype24m; XtPointer 4mvalue24m; unsigned long *4mlength24m; int *4mformat24m; 4mw24m Specifies the widget that requested the selection value. 4mclient_data0m Specifies a value passed in by the widget when it requested the selection. 4mselection24m Specifies the name of the selection that was requested. 4mtype24m Specifies the representation type of the selection value (for example, 4mXA_STRING24m). Note that it is not the target that was requested (which the client must remember for itself), but the type that is used to represent the target. The special symbolic constant 4mXT_CONVERT_FAIL24m is used to indi- cate that the selection conversion failed because the selection owner did not respond within the Intrinsics selection timeout interval. 4mvalue24m Specifies a pointer to the selection value. The requesting client owns this storage and is respon- sible for freeing it by calling 4mXtFree24m when it is done with it. 4mlength24m Specifies the number of elements in 4mvalue24m. 4mformat24m Specifies the size in bits of the data in each element of 4mvalue24m. |__ This procedure is called by the Intrinsics selection mecha- nism to deliver the requested selection to the requestor. 1m3020m 1mX Toolkit Intrinsics X11 Release 6.40m If the 4mSelectionNotify24m event returns a property of 4mNone24m, meaning the conversion has been refused because there is no owner for the specified selection or the owner cannot con- vert the selection to the requested target for any reason, the procedure is called with a value of NULL and a length of zero. To obtain the selection value in a single logical unit, use 4mXtGetSelectionValue24m or 4mXtGetSelectionValues24m. __ | void XtGetSelectionValue(4mw24m, 4mselection24m, 4mtarget24m, 4mcallback24m, 4mclient_data24m, 4mtime24m) Widget 4mw24m; Atom 4mselection24m; Atom 4mtarget24m; XtSelectionCallbackProc 4mcallback24m; XtPointer 4mclient_data24m; Time 4mtime24m; 4mw24m Specifies the widget making the request. Must be of class Core or any subclass thereof. 4mselection24m Specifies the particular selection desired; for example, 4mXA_PRIMARY24m. 4mtarget24m Specifies the type of information needed about the selection. 4mcallback24m Specifies the procedure to be called when the selection value has been obtained. Note that this is how the selection value is communicated back to the client. 4mclient_data0m Specifies additional data to be passed to the specified procedure when it is called. 4mtime24m Specifies the timestamp that indicates when the selection request was initiated. This should be the timestamp of the event that triggered this request; the value 4mCurrentTime24m is not acceptable. |__ The 4mXtGetSelectionValue24m function requests the value of the selection converted to the target type. The specified call- back is called at some time after 4mXtGetSelectionValue24m is called, when the selection value is received from the X server. It may be called before or after 4mXtGetSelectionVa-0m 4mlue24m returns. For more information about 4mselection24m, 4mtarget24m, and 4mtime24m, see Section 2.6 in the 4mInter-Client24m 4mCommunication0m 4mConventions24m 4mManual24m. 1m3030m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtGetSelectionValues(4mw24m, 4mselection24m, 4mtargets24m, 4mcount24m, 4mcallback24m, 4mclient_data24m, 4mtime24m) Widget 4mw24m; Atom 4mselection24m; Atom *4mtargets24m; int 4mcount24m; XtSelectionCallbackProc 4mcallback24m; XtPointer *4mclient_data24m; Time 4mtime24m; 4mw24m Specifies the widget making the request. Must be of class Core or any subclass thereof. 4mselection24m Specifies the particular selection desired (that is, primary or secondary). 4mtargets24m Specifies the types of information needed about the selection. 4mcount24m Specifies the length of the 4mtargets24m and 4mclient_data24m lists. 4mcallback24m Specifies the callback procedure to be called with each selection value obtained. Note that this is how the selection values are communicated back to the client. 4mclient_data0m Specifies a list of additional data values, one for each target type, that are passed to the call- back procedure when it is called for that target. 4mtime24m Specifies the timestamp that indicates when the selection request was initiated. This should be the timestamp of the event that triggered this request; the value 4mCurrentTime24m is not acceptable. |__ The 4mXtGetSelectionValues24m function is similar to multiple calls to 4mXtGetSelectionValue24m except that it guarantees that no other client can assert ownership between requests and therefore that all the conversions will refer to the same selection value. The callback is invoked once for each tar- get value with the corresponding client data. For more information about 4mselection24m, 4mtarget24m, and 4mtime24m, see Section 2.6 in the 4mInter-Client24m 4mCommunication24m 4mConventions24m 4mManual24m. 1m11.5.2.3. Setting the Selection Owner0m To set the selection owner and indicate that the selection value will be provided in one piece, use 4mXtOwnSelection24m. 1m3040m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Boolean XtOwnSelection(4mw24m, 4mselection24m, 4mtime24m, 4mconvert_proc24m, 4mlose_selection24m, 4mdone_proc24m) Widget 4mw24m; Atom 4mselection24m; Time 4mtime24m; XtConvertSelectionProc 4mconvert_proc24m; XtLoseSelectionProc 4mlose_selection24m; XtSelectionDoneProc 4mdone_proc24m; 4mw24m Specifies the widget that wishes to become the owner. Must be of class Core or any subclass thereof. 4mselection24m Specifies the name of the selection (for example, 4mXA_PRIMARY24m). 4mtime24m Specifies the timestamp that indicates when the ownership request was initiated. This should be the timestamp of the event that triggered owner- ship; the value 4mCurrentTime24m is not acceptable. 4mconvert_proc0m Specifies the procedure to be called whenever a client requests the current value of the selec- tion. 4mlose_selection0m Specifies the procedure to be called whenever the widget has lost selection ownership, or NULL if the owner is not interested in being called back. 4mdone_proc24m Specifies the procedure called after the requestor has received the selection value, or NULL if the owner is not interested in being called back. |__ The 4mXtOwnSelection24m function informs the Intrinsics selection mechanism that a widget wishes to own a selection. It returns 4mTrue24m if the widget successfully becomes the owner and 4mFalse24m otherwise. The widget may fail to become the owner if some other widget has asserted ownership at a time later than this widget. The widget can lose selection own- ership either because some other widget asserted later own- ership of the selection or because the widget voluntarily gave up ownership of the selection. The lose_selection pro- cedure is not called if the widget fails to obtain selection ownership in the first place. If a done_proc is specified, the client owns the storage allocated for passing the value to the Intrinsics. If 4mdone_proc24m is NULL, the convert_proc must allocate storage using 4mXtMalloc24m, 4mXtRealloc24m, or 4mXtCalloc24m, and the value speci- fied is freed by the Intrinsics when the transfer is 1m3050m 1mX Toolkit Intrinsics X11 Release 6.40m complete. Usually, a selection owner maintains ownership indefinitely until some other widget requests ownership, at which time the Intrinsics selection mechanism informs the previous owner that it has lost ownership of the selection. However, in response to some user actions (for example, when a user deletes the information selected), the application may wish to explicitly inform the Intrinsics by using 4mXtDisownSelec-0m 4mtion24m that it no longer is to be the selection owner. __ | void XtDisownSelection(4mw24m, 4mselection24m, 4mtime24m) Widget 4mw24m; Atom 4mselection24m; Time 4mtime24m; 4mw24m Specifies the widget that wishes to relinquish ownership. 4mselection24m Specifies the atom naming the selection being given up. 4mtime24m Specifies the timestamp that indicates when the request to relinquish selection ownership was ini- tiated. |__ The 4mXtDisownSelection24m function informs the Intrinsics selec- tion mechanism that the specified widget is to lose owner- ship of the selection. If the widget does not currently own the selection, either because it lost the selection or because it never had the selection to begin with, 4mXtDisownS-0m 4melection24m does nothing. After a widget has called 4mXtDisownSelection24m, its convert procedure is not called even if a request arrives later with a timestamp during the period that this widget owned the selection. However, its done procedure is called if a con- version that started before the call to 4mXtDisownSelection0m finishes after the call to 4mXtDisownSelection24m. 1m11.5.3. Using Incremental Transfers0m When using the incremental interface, an owner may have to process more than one selection request for the same selec- tion, converted to the same target, at the same time. The incremental functions take a 4mrequest_id24m argument, which is an identifier that is guaranteed to be unique among all incremental requests that are active concurrently. 1m3060m 1mX Toolkit Intrinsics X11 Release 6.40m For example, consider the following: · Upon receiving a request for the selection value, the owner sends the first segment. · While waiting to be called to provide the next segment value but before sending it, the owner receives another request from a different requestor for the same selec- tion value. · To distinguish between the requests, the owner uses the request_id value. This allows the owner to distinguish between the first requestor, which is asking for the second segment, and the second requestor, which is ask- ing for the first segment. 1m11.5.3.1. Incremental Transfer Procedures0m The following procedures are used by selection owners who wish to provide the selection data in multiple segments. The procedure pointer specified by the incremental owner to supply the selection data to the Intrinsics is of type 4mXtConvertSelectionIncrProc24m. 1m3070m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef XtPointer XtRequestId; typedef Boolean (*XtConvertSelectionIncrProc)(Widget, Atom*, Atom*, Atom*, XtPointer*, unsigned long*, int*, unsigned long*, XtPointer, XtRequestId*); Widget 4mw24m; Atom *4mselection24m; Atom *4mtarget24m; Atom *4mtype_return24m; XtPointer *4mvalue_return24m; unsigned long *4mlength_return24m; int *4mformat_return24m; unsigned long *4mmax_length24m; XtPointer 4mclient_data24m; XtRequestId *4mrequest_id24m; 4mw24m Specifies the widget that currently owns this selection. 4mselection24m Specifies the atom that names the selection requested. 4mtarget24m Specifies the type of information required about the selection. 4mtype_return0m Specifies a pointer to an atom into which the property type of the converted value of the selec- tion is to be stored. 4mvalue_return0m Specifies a pointer into which a pointer to the converted value of the selection is to be stored. The selection owner is responsible for allocating this storage. 4mlength_return0m Specifies a pointer into which the number of ele- ments in 4mvalue_return24m, each of size indicated by 4mformat_return24m, is to be stored. 4mformat_return0m Specifies a pointer into which the size in bits of the data elements of the selection value is to be stored so that the server may byte-swap the data if necessary. 4mmax_length0m Specifies the maximum number of bytes which may be transferred at any one time. 4mclient_data0m 1m3080m 1mX Toolkit Intrinsics X11 Release 6.40m Specifies the value passed in by the widget when it took ownership of the selection. 4mrequest_id0m Specifies an opaque identification for a specific request. |__ This procedure is called repeatedly by the Intrinsics selec- tion mechanism to get the next incremental chunk of data from a selection owner who has called 4mXtOwnSelectionIncre-0m 4mmental24m. It must return 4mTrue24m if the procedure has succeeded in converting the selection data or 4mFalse24m otherwise. On the first call with a particular request id, the owner must begin a new incremental transfer for the requested selection and target. On subsequent calls with the same request id, the owner may assume that the previously supplied value is no longer needed by the Intrinsics; that is, a fixed trans- fer area may be allocated and returned in 4mvalue_return24m for each segment to be transferred. This procedure should store a non-NULL value in 4mvalue_return24m and zero in 4mlength_return0m to indicate that the entire selection has been delivered. After returning this final segment, the request id may be reused by the Intrinsics to begin a new transfer. To retrieve the 4mSelectionRequest24m event that triggered the selection conversion procedure, use 4mXtGetSelectionRequest24m, described in Section 11.5.2.1. The procedure pointer specified by the incremental selection owner when it desires notification upon no longer having ownership is of type 4mXtLoseSelectionIncrProc24m. __ | typedef void (*XtLoseSelectionIncrProc)(Widget, Atom*, XtPointer); Widget 4mw24m; Atom *4mselection24m; XtPointer 4mclient_data24m; 4mw24m Specifies the widget that has lost the selection ownership. 4mselection24m Specifies the atom that names the selection. 4mclient_data0m Specifies the value passed in by the widget when it took ownership of the selection. |__ This procedure, which is optional, is called by the Intrin- sics to inform the selection owner that it no longer owns 1m3090m 1mX Toolkit Intrinsics X11 Release 6.40m the selection. The procedure pointer specified by the incremental selection owner when it desires notification of receipt of the data or when it manages the storage containing the data is of type 4mXtSelectionDoneIncrProc24m. __ | typedef void (*XtSelectionDoneIncrProc)(Widget, Atom*, Atom*, XtRequestId*, XtPointer); Widget 4mw24m; Atom *4mselection24m; Atom *4mtarget24m; XtRequestId *4mrequest_id24m; XtPointer 4mclient_data24m; 4mw24m Specifies the widget that owns the selection. 4mselection24m Specifies the atom that names the selection being transferred. 4mtarget24m Specifies the target type to which the conversion was done. 4mrequest_id0m Specifies an opaque identification for a specific request. 4mclient_data0m Specified the value passed in by the widget when it took ownership of the selection. |__ This procedure, which is optional, is called by the Intrin- sics after the requestor has retrieved the final (zero- length) segment of the incremental transfer to indicate that the entire transfer is complete. If this procedure is not specified, the Intrinsics will free only the final value returned by the selection owner using 4mXtFree24m. The procedure pointer specified by the incremental selection owner to notify it if a transfer should be terminated prema- turely is of type 4mXtCancelConvertSelectionProc24m. 1m3100m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtCancelConvertSelectionProc)(Widget, Atom*, Atom*, XtRequestId*, XtPointer); Widget 4mw24m; Atom *4mselection24m; Atom *4mtarget24m; XtRequestId *4mrequest_id24m; XtPointer 4mclient_data24m; 4mw24m Specifies the widget that owns the selection. 4mselection24m Specifies the atom that names the selection being transferred. 4mtarget24m Specifies the target type to which the conversion was done. 4mrequest_id0m Specifies an opaque identification for a specific request. 4mclient_data0m Specifies the value passed in by the widget when it took ownership of the selection. |__ This procedure is called by the Intrinsics when it has been determined by means of a timeout or other mechanism that any remaining segments of the selection no longer need to be transferred. Upon receiving this callback, the selection request is considered complete and the owner can free the memory and any other resources that have been allocated for the transfer. 1m11.5.3.2. Getting the Selection Value Incrementally0m To obtain the value of the selection using incremental transfers, use 4mXtGetSelectionValueIncremental24m or 4mXtGetSelec-0m 4mtionValuesIncremental24m. 1m3110m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtGetSelectionValueIncremental(4mw24m, 4mselection24m, 4mtarget24m, 4mselection_callback24m, 4mclient_data24m, 4mtime24m) Widget 4mw24m; Atom 4mselection24m; Atom 4mtarget24m; XtSelectionCallbackProc 4mselection_callback24m; XtPointer 4mclient_data24m; Time 4mtime24m; 4mw24m Specifies the widget making the request. Must be of class Core or any subclass thereof. 4mselection24m Specifies the particular selection desired. 4mtarget24m Specifies the type of information needed about the selection. 4mselection_callback0m Specifies the callback procedure to be called to receive each data segment. 4mclient_data0m Specifies client-specific data to be passed to the specified callback procedure when it is invoked. 4mtime24m Specifies the timestamp that indicates when the selection request was initiated. This should be the timestamp of the event that triggered this request; the value 4mCurrentTime24m is not acceptable. |__ The 4mXtGetSelectionValueIncremental24m function is similar to 4mXtGetSelectionValue24m except that the selection_callback pro- cedure will be called repeatedly upon delivery of multiple segments of the selection value. The end of the selection value is indicated when 4mselection_callback24m is called with a non-NULL value of length zero, which must still be freed by the client. If the transfer of the selection is aborted in the middle of a transfer (for example, because of a time- out), the selection_callback procedure is called with a type value equal to the symbolic constant 4mXT_CONVERT_FAIL24m so that the requestor can dispose of the partial selection value it has collected up until that point. Upon receiving 4mXT_CON-0m 4mVERT_FAIL24m, the requesting client must determine for itself whether or not a partially completed data transfer is mean- ingful. For more information about 4mselection24m, 4mtarget24m, and 4mtime24m, see Section 2.6 in the 4mInter-Client24m 4mCommunication24m 4mCon-0m 4mventions24m 4mManual24m. 1m3120m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtGetSelectionValuesIncremental(4mw24m, 4mselection24m, 4mtargets24m, 4mcount24m, 4mselection_callback24m, 4mclient_data24m, 4mtime24m) Widget 4mw24m; Atom 4mselection24m; Atom *4mtargets24m; int 4mcount24m; XtSelectionCallbackProc 4mselection_callback24m; XtPointer *4mclient_data24m; Time 4mtime24m; 4mw24m Specifies the widget making the request. Must be of class Core or any subclass thereof. 4mselection24m Specifies the particular selection desired. 4mtargets24m Specifies the types of information needed about the selection. 4mcount24m Specifies the length of the 4mtargets24m and 4mclient_data24m lists. 4mselection_callback0m Specifies the callback procedure to be called to receive each selection value. 4mclient_data0m Specifies a list of client data (one for each tar- get type) values that are passed to the callback procedure when it is invoked for the corresponding target. 4mtime24m Specifies the timestamp that indicates when the selection request was initiated. This should be the timestamp of the event that triggered this request; the value 4mCurrentTime24m is not acceptable. |__ The 4mXtGetSelectionValuesIncremental24m function is similar to 4mXtGetSelectionValueIncremental24m except that it takes a list of targets and client data. 4mXtGetSelectionValuesIncremental0m is equivalent to calling 4mXtGetSelectionValueIncremental24m suc- cessively for each 4mtarget/client_data24m pair except that 4mXtGetSelectionValuesIncremental24m does guarantee that all the conversions will use the same selection value because the ownership of the selection cannot change in the middle of the list, as would be possible when calling 4mXtGetSelection-0m 4mValueIncremental24m repeatedly. For more information about 4mselection24m, 4mtarget24m, and 4mtime24m, see Section 2.6 in the 4mInter-0m 4mClient24m 4mCommunication24m 4mConventions24m 4mManual24m. 1m3130m 1mX Toolkit Intrinsics X11 Release 6.40m 1m11.5.3.3. Setting the Selection Owner for Incremental0m 1mTransfers0m To set the selection owner when using incremental transfers, use 4mXtOwnSelectionIncremental24m. 1m3140m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Boolean XtOwnSelectionIncremental(4mw24m, 4mselection24m, 4mtime24m, 4mconvert_callback24m, 4mlose_callback24m, 4mdone_callback24m, 4mcancel_callback24m, 4mclient_data24m) Widget 4mw24m; Atom 4mselection24m; Time 4mtime24m; XtConvertSelectionIncrProc 4mconvert_callback24m; XtLoseSelectionIncrProc 4mlose_callback24m; XtSelectionDoneIncrProc 4mdone_callback24m; XtCancelConvertSelectionProc 4mcancel_callback24m; XtPointer 4mclient_data24m; 4mw24m Specifies the widget that wishes to become the owner. Must be of class Core or any subclass thereof. 4mselection24m Specifies the atom that names the selection. 4mtime24m Specifies the timestamp that indicates when the selection ownership request was initiated. This should be the timestamp of the event that trig- gered ownership; the value 4mCurrentTime24m is not acceptable. 4mconvert_callback0m Specifies the procedure to be called whenever the current value of the selection is requested. 4mlose_callback0m Specifies the procedure to be called whenever the widget has lost selection ownership, or NULL if the owner is not interested in being noti- fied. 4mdone_callback0m Specifies the procedure called after the requestor has received the entire selection, or NULL if the owner is not interested in being notified. 4mcancel_callback0m Specifies the callback procedure to be called when a selection request aborts because a time- out expires, or NULL if the owner is not inter- ested in being notified. 4mclient_data24m Specifies the argument to be passed to each of the callback procedures when they are called. |__ The 4mXtOwnSelectionIncremental24m procedure informs the Intrin- sics incremental selection mechanism that the specified wid- get wishes to own the selection. It returns 4mTrue24m if the 1m3150m 1mX Toolkit Intrinsics X11 Release 6.40m specified widget successfully becomes the selection owner or 4mFalse24m otherwise. For more information about 4mselection24m, 4mtar-0m 4mget24m, and 4mtime24m, see Section 2.6 in the 4mInter-Client24m 4mCommuni-0m 4mcation24m 4mConventions24m 4mManual24m. If a done_callback procedure is specified, the client owns the storage allocated for passing the value to the Intrin- sics. If 4mdone_callback24m is NULL, the convert_callback proce- dure must allocate storage using 4mXtMalloc24m, 4mXtRealloc24m, or 4mXtCalloc24m, and the final value specified is freed by the Intrinsics when the transfer is complete. After a selection transfer has started, only one of the done_callback or can- cel_callback procedures is invoked to indicate completion of the transfer. The lose_callback procedure does not indicate completion of any in-progress transfers; it is invoked at the time a 4mSelectionClear24m event is dispatched regardless of any active transfers, which are still expected to continue. A widget that becomes the selection owner using 4mXtOwnSelec-0m 4mtionIncremental24m may use 4mXtDisownSelection24m to relinquish selection ownership. 1m11.5.4. Setting and Retrieving Selection Target Parameters0m To specify target parameters for a selection request with a single target, use 4mXtSetSelectionParameters24m. 1m3160m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtSetSelectionParameters(4mrequestor24m, 4mselection24m, 4mtype24m, 4mvalue24m, 4mlength24m, 4mformat24m) Widget 4mrequestor24m; Atom 4mselection24m; Atom 4mtype24m; XtPointer 4mvalue24m; unsigned long 4mlength24m; int 4mformat24m; 4mrequestor24m Specifies the widget making the request. Must be of class Core or any subclass thereof. 4mselection24m Specifies the atom that names the selection. 4mtype24m Specifies the type of the property in which the parameters are passed. 4mvalue24m Specifies a pointer to the parameters. 4mlength24m Specifies the number of elements containing data in 4mvalue24m, each element of a size indicated by 4mfor-0m 4mmat24m. 4mformat24m Specifies the size in bits of the data in the ele- ments of 4mvalue24m. The specified parameters are copied and stored in a new property of the specified type and format on the requestor's window. To initiate a selection request with a target and these parameters, a subsequent call to 4mXtGetSelectionValue0m or to 4mXtGetSelectionValueIncremental24m specifying the same requestor widget and selection atom will generate a 4mConvert-0m 4mSelection24m request referring to the property containing the parameters. If 4mXtSetSelectionParameters24m is called more than once with the same widget and selection without a call to specify a request, the most recently specified parameters are used in the subsequent request. |__ The possible values of 4mformat24m are 8, 16, or 32. If the for- mat is 8, the elements of 4mvalue24m are assumed to be sizeof(char); if 16, sizeof(short); if 32, sizeof(long). To generate a MULTIPLE target request with parameters for any of the multiple targets of the selection request, pre- cede individual calls to 4mXtGetSelectionValue24m and 4mXtGetSelec-0m 4mtionValueIncremental24m with corresponding individual calls to 4mXtSetSelectionParameters24m, and enclose these all within 4mXtCreateSelectionRequest24m and 4mXtSendSelectionRequest.24m 4mXtGetS-0m 4melectionValues24m and 4mXtGetSelectionValuesIncremental24m cannot be used to make selection requests with parameterized targets. 1m3170m 1mX Toolkit Intrinsics X11 Release 6.40m To retrieve any target parameters needed to perform a selec- tion conversion, the selection owner calls 4mXtGetSelectionPa-0m 4mrameters24m. __ | void XtGetSelectionParameters(4mowner24m, 4mselection24m, 4mrequest_id24m, 4mtype_return24m, 4mvalue_return24m, 4mlength_return24m, 4mformat_return24m) Widget 4mowner24m; Atom 4mselection24m; XtRequestId 4mrequest_id24m; Atom *4mtype_return24m; XtPointer *4mvalue_return24m; unsigned long *4mlength_return24m; int *4mformat_return24m; 4mowner24m Specifies the widget that owns the specified selection. 4mselection24m Specifies the selection being processed. 4mrequest_id0m Specifies the requestor id in the case of incre- mental selections, or NULL in the case of atomic transfers. 4mtype_return0m Specifies a pointer to an atom in which the prop- erty type of the parameters is stored. 4mvalue_return0m Specifies a pointer into which a pointer to the parameters is to be stored. A NULL is stored if no parameters accompany the request. 4mlength_return0m Specifies a pointer into which the number of data elements in 4mvalue_return24m of size indicated by 4mfor-0m 4mmat_return24m are stored. 4mformat_return0m Specifies a pointer into which the size in bits of the parameter data in the elements of 4mvalue24m is stored. |__ 4mXtGetSelectionParameters24m may be called only from within an 4mXtConvertSelectionProc24m or from within the first call to an 4mXtConvertSelectionIncrProc24m with a new request_id. It is the responsibility of the caller to free the returned parameters using 4mXtFree24m when the parameters are no longer needed. 1m3180m 1mX Toolkit Intrinsics X11 Release 6.40m 1m11.5.5. Generating MULTIPLE Requests0m To have the Intrinsics bundle multiple calls to make selec- tion requests into a single request using a MULTIPLE target, use 4mXtCreateSelectionRequest24m and 4mXtSendSelectionRequest24m. __ | void XtCreateSelectionRequest(4mrequestor24m, 4mselection24m) Widget 4mrequestor24m; Atom 4mselection24m; 4mrequestor24m Specifies the widget making the request. Must be of class Core or any subclass thereof. 4mselection24m Specifies the particular selection desired. |__ When 4mXtCreateSelectionRequest24m is called, subsequent calls to 4mXtGetSelectionValue24m, 4mXtGetSelectionValueIncremental24m, 4mXtGetS-0m 4melectionValues24m, and 4mXtGetSelectionValuesIncremental24m, with the requestor and selection as specified to 4mXtCreateSelec-0m 4mtionRequest24m, are bundled into a single selection request with multiple targets. The request is made by calling 4mXtSendSelectionRequest24m. __ | void XtSendSelectionRequest(4mrequestor24m, 4mselection24m, 4mtime24m) Widget 4mrequestor24m; Atom 4mselection24m; Time 4mtime24m; 4mrequestor24m Specifies the widget making the request. Must be of class Core or any subclass thereof. 4mselection24m Specifies the particular selection desired. 4mtime24m Specifies the timestamp that indicates when the selection request was initiated. The value 4mCur-0m 4mrentTime24m is not acceptable. |__ When 4mXtSendSelectionRequest24m is called with a value of 4mrequestor24m and 4mselection24m matching a previous call to 4mXtCre-0m 4mateSelectionRequest24m, a selection request is sent to the selection owner. If a single target request is queued, that request is made. If multiple targets are queued, they are bundled into a single request with a target of MULTIPLE using the specified timestamp. As the values are returned, the callbacks specified in 4mXtGetSelectionValue24m, 4mXtGetSelec-0m 4mtionValueIncremental24m, 4mXtGetSelectionValues24m, and 1m3190m 1mX Toolkit Intrinsics X11 Release 6.40m 4mXtGetSelectionValueIncremental24m are invoked. Multi-threaded applications should lock the application con- text before calling 4mXtCreateSelectionRequest24m and release the lock after calling 4mXtSendSelectionRequest24m to ensure that the thread assembling the request is safe from interference by another thread assembling a different request naming the same widget and selection. To relinquish the composition of a MULTIPLE request without sending it, use 4mXtCancelSelectionRequest24m. __ | void XtCancelSelectionRequest(4mrequestor24m, 4mselection24m) Widget 4mrequestor24m; Atom 4mselection24m; 4mrequestor24m Specifies the widget making the request. Must be of class Core or any subclass thereof. 4mselection24m Specifies the particular selection desired. |__ When 4mXtCancelSelectionRequest24m is called, any requests queued since the last call to 4mXtCreateSelectionRequest24m for the same widget and selection are discarded and any resources reserved are released. A subsequent call to 4mXtSendSelec-0m 4mtionRequest24m will not result in any request being made. Sub- sequent calls to 4mXtGetSelectionValue24m, 4mXtGetSelectionValues24m, 4mXtGetSelectionValueIncremental24m, or 4mXtGetSelectionValuesIn-0m 4mcremental24m will not be deferred. 1m11.5.6. Auxiliary Selection Properties0m Certain uses of parameterized selections require clients to name other window properties within a selection parameter. To permit reuse of temporary property names in these circum- stances and thereby reduce the number of unique atoms cre- ated in the server, the Intrinsics provides two interfaces for acquiring temporary property names. To acquire a temporary property name atom for use in a selection request, the client may call 4mXtReserveProperty-0m 4mAtom24m. 1m3200m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Atom XtReservePropertyAtom(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget making a selection request. |__ 4mXtReservePropertyAtom24m returns an atom that may be used as a property name during selection requests involving the speci- fied widget. As long as the atom remains reserved, it is unique with respect to all other reserved atoms for the wid- get. To return a temporary property name atom for reuse and to delete the property named by that atom, use 4mXtReleaseProp-0m 4mertyAtom24m. __ | void XtReleasePropertyAtom(4mw24m, 4matom24m) Widget 4mw24m; Atom 4matom24m; 4mw24m Specifies the widget used to reserve the property name atom. 4matom24m Specifies the property name atom returned by 4mXtRe-0m 4mservePropertyAtom24m that is to be released for re- use. |__ 4mXtReleasePropertyAtom24m marks the specified property name atom as no longer in use and ensures that any property having that name on the specified widget's window is deleted. If 4matom24m does not specify a value returned by 4mXtReserveProperty-0m 4mAtom24m for the specified widget, the results are undefined. 1m11.5.7. Retrieving the Most Recent Timestamp0m To retrieve the timestamp from the most recent call to 4mXtDispatchEvent24m that contained a timestamp, use 4mXtLastTimes-0m 4mtampProcessed24m. 1m3210m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Time XtLastTimestampProcessed(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies an open display connection. |__ If no 4mKeyPress24m, 4mKeyRelease24m, 4mButtonPress24m, 4mButtonRelease24m, 4mMotionNotify24m, 4mEnterNotify24m, 4mLeaveNotify24m, 4mPropertyNotify24m, or 4mSelectionClear24m event has yet been passed to 4mXtDispatchEvent0m for the specified display, 4mXtLastTimestampProcessed24m returns zero. 1m11.5.8. Retrieving the Most Recent Event0m To retrieve the event from the most recent call to 4mXtDis-0m 4mpatchEvent24m for a specific display, use 4mXtLastEventProcessed24m. __ | XEvent *XtLastEventProcessed(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the display connection from which to retrieve the event. |__ Returns the last event passed to 4mXtDispatchEvent24m for the specified display. Returns NULL if there is no such event. The client must not modify the contents of the returned event. 1m11.6. Merging Exposure Events into a Region0m The Intrinsics provide an 4mXtAddExposureToRegion24m utility function that merges 4mExpose24m and 4mGraphicsExpose24m events into a region for clients to process at once rather than processing individual rectangles. For further information about regions, see Section 16.5 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m. To merge 4mExpose24m and 4mGraphicsExpose24m events into a region, use 4mXtAddExposureToRegion24m. 1m3220m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtAddExposureToRegion(4mevent24m, 4mregion24m) XEvent *4mevent24m; Region 4mregion24m; 4mevent24m Specifies a pointer to the 4mExpose24m or 4mGraphicsEx-0m 4mpose24m event. 4mregion24m Specifies the region object (as defined in <4mX11/Xutil.h24m>). |__ The 4mXtAddExposureToRegion24m function computes the union of the rectangle defined by the exposure event and the specified region. Then it stores the results back in 4mregion24m. If the event argument is not an 4mExpose24m or 4mGraphicsExpose24m event, 4mXtAddExposureToRegion24m returns without an error and without modifying 4mregion24m. This function is used by the exposure compression mechanism; see Section 7.9.3. 1m11.7. Translating Widget Coordinates0m To translate an x-y coordinate pair from widget coordinates to root window absolute coordinates, use 4mXtTranslateCoords24m. __ | void XtTranslateCoords(4mw24m, 4mx24m, 4my24m, 4mrootx_return24m, 4mrooty_return24m) Widget 4mw24m; Position 4mx24m, 4my24m; Position *4mrootx_return24m, *4mrooty_return24m; 4mw24m Specifies the widget. Must be of class RectObj or any subclass thereof. 4mx0m 4my24m Specify the widget-relative x and y coordinates. 4mrootx_return0m 4mrooty_return0m Return the root-relative x and y coordinates. |__ While 4mXtTranslateCoords24m is similar to the Xlib 4mXTranslateCo-0m 4mordinates24m function, it does not generate a server request because all the required information already is in the wid- get's data structures. 1m3230m 1mX Toolkit Intrinsics X11 Release 6.40m 1m11.8. Translating a Window to a Widget0m To translate a given window and display pointer into a wid- get instance, use 4mXtWindowToWidget24m. __ | Widget XtWindowToWidget(4mdisplay24m, 4mwindow24m) Display *4mdisplay24m; Window 4mwindow24m; 4mdisplay24m Specifies the display on which the window is defined. 4mwindow24m Specifies the drawable for which you want the wid- get. |__ If there is a realized widget whose window is the specified drawable on the specified 4mdisplay24m, 4mXtWindowToWidget24m returns that widget. If not and if the drawable has been associated with a widget through 4mXtRegisterDrawable24m, 4mXtWindowToWidget0m returns the widget associated with the drawable. In other cases it returns NULL. 1m11.9. Handling Errors0m The Intrinsics allow a client to register procedures that are 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 retrieves the error message text from an error resource database. · A low-level interface that takes a simple string to display. The high-level functions construct a string to pass to the lower-level interface. The strings may be specified in application code and are overridden by the contents of an external systemwide file, the ``error database file''. The location and name of this file are implementation-dependent. 1m3240m 1mX Toolkit Intrinsics X11 Release 6.40m Note The application-context-specific error handling is not implemented on many systems, although the interfaces are always present. Most implementa- tions will have just one set of error handlers for all application contexts within a process. If they are set for different application contexts, the ones registered last will prevail. To obtain the error database (for example, to merge with an application- or widget-specific database), use 4mXtAppGetEr-0m 4mrorDatabase24m. __ | XrmDatabase *XtAppGetErrorDatabase(4mapp_context24m) XtAppContext 4mapp_context24m; 4mapp_context0m Specifies the application context. |__ The 4mXtAppGetErrorDatabase24m function returns the address of the error database. The Intrinsics do a lazy binding of the error database and do not merge in the database file until the first call to 4mXtAppGetErrorDatabaseText24m. For a complete listing of all errors and warnings that can be generated by the Intrinsics, see Appendix D. The high-level error and warning handler procedure pointers are of type 4mXtErrorMsgHandler24m. 1m3250m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtErrorMsgHandler)(String, String, String, String, String*, Cardinal*); String 4mname24m; String 4mtype24m; String 4mclass24m; String 4mdefaultp24m; String *4mparams24m; Cardinal *4mnum_params24m; 4mname24m Specifies the name to be concatenated with the specified type to form the resource name of the error message. 4mtype24m Specifies the type to be concatenated with the name to form the resource name of the error mes- sage. 4mclass24m Specifies the resource class of the error message. 4mdefaultp24m Specifies the default message to use if no error database entry is found. 4mparams24m Specifies a pointer to a list of parameters to be substituted in the message. 4mnum_params0m Specifies the number of entries in 4mparams24m. |__ The specified name can be a general kind of error, like ``invalidParameters'' or ``invalidWindow'', and the speci- fied type gives extra information such as the name of the routine in which the error was detected. Standard 4mprintf0m notation is used to substitute the parameters into the mes- sage. An error message handler can obtain the error database text for an error or a warning by calling 4mXtAppGetErrorDatabase-0m 4mText24m. 1m3260m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtAppGetErrorDatabaseText(4mapp_context24m, 4mname24m, 4mtype24m, 4mclass24m, 4mdefault24m, 4mbuffer_return24m, 4mnbytes24m, 4mdatabase24m) XtAppContext 4mapp_context24m; String 4mname24m, 4mtype24m, 4mclass24m; String 4mdefault24m; String 4mbuffer_return24m; int 4mnbytes24m; XrmDatabase 4mdatabase24m; 4mapp_context0m Specifies the application context. 4mname0m 4mtype24m Specify the name and type concatenated to form the resource name of the error message. 4mclass24m Specifies the resource class of the error message. 4mdefault24m Specifies the default message to use if an error database entry is not found. 4mbuffer_return0m Specifies the buffer into which the error message is to be returned. 4mnbytes24m Specifies the size of the buffer in bytes. 4mdatabase24m Specifies the name of the alternative database to be used, or NULL if the application context's error database is to be used. |__ The 4mXtAppGetErrorDatabaseText24m returns the appropriate mes- sage from the error database or returns the specified default message if one is not found in the error database. To form the full resource name and class when querying the database, the 4mname24m and 4mtype24m are concatenated with a single ``.'' between them and the 4mclass24m is concatenated with itself with a single ``.'' if it does not already contain a ``.''. To return the application name and class as passed to 4mXtDis-0m 4mplayInitialize24m for a particular Display, use 4mXtGetApplica-0m 4mtionNameAndClass24m. 1m3270m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtGetApplicationNameAndClass(4mdisplay24m, 4mname_return24m, 4mclass_return24m) Display* 4mdisplay24m; String* 4mname_return24m; String* 4mclass_return24m; 4mdisplay24m Specifies an open display connection that has been initialized with 4mXtDisplayInitialize24m. 4mname_return0m Returns the application name. 4mclass_return0m Returns the application class. |__ 4mXtGetApplicationNameAndClass24m returns the application name and class passed to 4mXtDisplayInitialize24m for the specified display. If the display was never initialized or has been closed, the result is undefined. The returned strings are owned by the Intrinsics and must not be modified or freed by the caller. To register a procedure to be called on fatal error condi- tions, use 4mXtAppSetErrorMsgHandler24m. __ | XtErrorMsgHandler XtAppSetErrorMsgHandler(4mapp_context24m, 4mmsg_handler24m) XtAppContext 4mapp_context24m; XtErrorMsgHandler 4mmsg_handler24m; 4mapp_context0m Specifies the application context. 4mmsg_handler0m Specifies the new fatal error procedure, which should not return. |__ 4mXtAppSetErrorMsgHandler24m returns a pointer to the previously installed high-level fatal error handler. The default high- level fatal error handler provided by the Intrinsics is named 4m_XtDefaultErrorMsg24m and constructs a string from the error resource database and calls 4mXtError24m. Fatal error mes- sage handlers should not return. If one does, subsequent Intrinsics behavior is undefined. To call the high-level error handler, use 4mXtAppErrorMsg24m. 1m3280m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtAppErrorMsg(4mapp_context24m, 4mname24m, 4mtype24m, 4mclass24m, 4mdefault24m, 4mparams24m, 4mnum_params24m) XtAppContext 4mapp_context24m; String 4mname24m; String 4mtype24m; String 4mclass24m; String 4mdefault24m; String *4mparams24m; Cardinal *4mnum_params24m; 4mapp_context0m Specifies the application context. 4mname24m Specifies the general kind of error. 4mtype24m Specifies the detailed name of the error. 4mclass24m Specifies the resource class. 4mdefault24m Specifies the default message to use if an error database entry is not found. 4mparams24m Specifies a pointer to a list of values to be stored in the message. 4mnum_params0m Specifies the number of entries in 4mparams24m. |__ The Intrinsics internal errors all have class ``XtToolkitEr- ror''. To register a procedure to be called on nonfatal error con- ditions, use 4mXtAppSetWarningMsgHandler24m. __ | XtErrorMsgHandler XtAppSetWarningMsgHandler(4mapp_context24m, 4mmsg_handler24m) XtAppContext 4mapp_context24m; XtErrorMsgHandler 4mmsg_handler24m; 4mapp_context0m Specifies the application context. 4mmsg_handler0m Specifies the new nonfatal error procedure, which usually returns. |__ 4mXtAppSetWarningMsgHandler24m returns a pointer to the previ- ously installed high-level warning handler. The default 1m3290m 1mX Toolkit Intrinsics X11 Release 6.40m high-level warning handler provided by the Intrinsics is named 4m_XtDefaultWarningMsg24m and constructs a string from the error resource database and calls 4mXtWarning24m. To call the installed high-level warning handler, use 4mXtApp-0m 4mWarningMsg24m. __ | void XtAppWarningMsg(4mapp_context24m, 4mname24m, 4mtype24m, 4mclass24m, 4mdefault24m, 4mparams24m, 4mnum_params24m) XtAppContext 4mapp_context24m; String 4mname24m; String 4mtype24m; String 4mclass24m; String 4mdefault24m; String *4mparams24m; Cardinal *4mnum_params24m; 4mapp_context0m Specifies the application context. 4mname24m Specifies the general kind of error. 4mtype24m Specifies the detailed name of the error. 4mclass24m Specifies the resource class. 4mdefault24m Specifies the default message to use if an error database entry is not found. 4mparams24m Specifies a pointer to a list of values to be stored in the message. 4mnum_params0m Specifies the number of entries in 4mparams24m. |__ The Intrinsics internal warnings all have class ``XtToolkitError''. The low-level error and warning handler procedure pointers are of type 4mXtErrorHandler24m. 1m3300m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtErrorHandler)(String); String 4mmessage24m; 4mmessage24m Specifies the error message. |__ The error handler should display the message string in some appropriate fashion. To register a procedure to be called on fatal error condi- tions, use 4mXtAppSetErrorHandler24m. __ | XtErrorHandler XtAppSetErrorHandler(4mapp_context24m, 4mhandler24m) XtAppContext 4mapp_context24m; XtErrorHandler 4mhandler24m; 4mapp_context0m Specifies the application context. 4mhandler24m Specifies the new fatal error procedure, which should not return. |__ 4mXtAppSetErrorHandler24m returns a pointer to the previously installed low-level fatal error handler. The default low- level error handler provided by the Intrinsics is 4m_XtDe-0m 4mfaultError24m. On POSIX-based systems, it prints the message to standard error and terminates the application. Fatal error message handlers should not return. If one does, sub- sequent Intrinsics behavior is undefined. To call the installed fatal error procedure, use 4mXtAppError24m. __ | void XtAppError(4mapp_context24m, 4mmessage24m) XtAppContext 4mapp_context24m; String 4mmessage24m; 4mapp_context0m Specifies the application context. 4mmessage24m Specifies the message to be reported. |__ Most programs should use 4mXtAppErrorMsg24m, not 4mXtAppError24m, to 1m3310m 1mX Toolkit Intrinsics X11 Release 6.40m provide for customization and internationalization of error messages. To register a procedure to be called on nonfatal error con- ditions, use 4mXtAppSetWarningHandler24m. __ | XtErrorHandler XtAppSetWarningHandler(4mapp_context24m, 4mhandler24m) XtAppContext 4mapp_context24m; XtErrorHandler 4mhandler24m; 4mapp_context0m Specifies the application context. 4mhandler24m Specifies the new nonfatal error procedure, which usually returns. |__ 4mXtAppSetWarningHandler24m returns a pointer to the previously installed low-level warning handler. The default low-level warning handler provided by the Intrinsics is 4m_XtDefault-0m 4mWarning24m. On POSIX-based systems, it prints the message to standard error and returns to the caller. To call the installed nonfatal error procedure, use 4mXtApp-0m 4mWarning24m. __ | void XtAppWarning(4mapp_context24m, 4mmessage24m) XtAppContext 4mapp_context24m; String 4mmessage24m; 4mapp_context0m Specifies the application context. 4mmessage24m Specifies the nonfatal error message to be reported. |__ Most programs should use 4mXtAppWarningMsg24m, not 4mXtAppWarning24m, to provide for customization and internationalization of warning messages. 1m11.10. Setting WM_COLORMAP_WINDOWS0m A client may set the value of the WM_COLORMAP_WINDOWS prop- erty on a widget's window by calling 4mXtSetWMColormapWindows24m. 1m3320m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtSetWMColormapWindows(4mwidget24m, 4mlist24m, 4mcount24m) Widget 4mwidget24m; Widget* 4mlist24m; Cardinal 4mcount24m; 4mwidget24m Specifies the widget on whose window the WM_COL- ORMAP_WINDOWS property is stored. Must be of class Core or any subclass thereof. 4mlist24m Specifies a list of widgets whose windows are potentially to be listed in the WM_COLORMAP_WIN- DOWS property. 4mcount24m Specifies the number of widgets in 4mlist24m. |__ 4mXtSetWMColormapWindows24m returns immediately if 4mwidget24m is not realized or if 4mcount24m is 0. Otherwise, 4mXtSetWMColormapWin-0m 4mdows24m constructs an ordered list of windows by examining each widget in 4mlist24m in turn and ignoring the widget if it is not realized, or adding the widget's window to the window list if the widget is realized and if its colormap resource is different from the colormap resources of all widgets whose windows are already on the window list. Finally, 4mXtSetWMColormapWindows24m stores the resulting window list in the WM_COLORMAP_WINDOWS property on the specified widget's window. Refer to Section 4.1.8 in the 4mInter-Client0m 4mCommunication24m 4mConventions24m 4mManual24m for details of the seman- tics of the WM_COLORMAP_WINDOWS property. 1m11.11. Finding File Names0m The Intrinsics provide procedures to look for a file by name, allowing string substitutions in a list of file speci- fications. Two routines are provided for this: 4mXtFindFile0m and 4mXtResolvePathname24m. 4mXtFindFile24m uses an arbitrary set of client-specified substitutions, and 4mXtResolvePathname24m uses a set of standard substitutions corresponding to the 4mX/Open0m 4mPortability24m 4mGuide24m language localization conventions. Most applications should use 4mXtResolvePathname24m. A string substitution is defined by a list of 4mSubstitution0m entries. 1m3330m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct { char match; String substitution; } SubstitutionRec, *Substitution; |__ File name evaluation is handled in an operating-system- dependent fashion by an 4mXtFilePredicate24m procedure. __ | typedef Boolean (*XtFilePredicate)(String); String 4mfilename24m; 4mfilename24m Specifies a potential filename. |__ A file predicate procedure is called with a string that is potentially a file name. It should return 4mTrue24m if this string specifies a file that is appropriate for the intended use and 4mFalse24m otherwise. To search for a file using substitutions in a path list, use 4mXtFindFile24m. __ | String XtFindFile(4mpath24m, 4msubstitutions24m, 4mnum_substitutions24m, 4mpredicate24m) String 4mpath24m; Substitution 4msubstitutions24m; Cardinal 4mnum_substitutions24m; XtFilePredicate 4mpredicate24m; 4mpath24m Specifies a path of file names, including sub- stitution characters. 4msubstitutions0m Specifies a list of substitutions to make into the path. 4mnum_substitutions0m Specifies the number of substitutions passed in. 4mpredicate24m Specifies a procedure called to judge each potential file name, or NULL. |__ The 4mpath24m parameter specifies a string that consists of a series of potential file names delimited by colons. Within 1m3340m 1mX Toolkit Intrinsics X11 Release 6.40m each name, the percent character specifies a string substi- tution selected by the following character. The character sequence ``%:'' specifies an embedded colon that is not a delimiter; the sequence is replaced by a single colon. The character sequence ``%%'' specifies a percent character that does not introduce a substitution; the sequence is replaced by a single percent character. If a percent character is followed by any other character, 4mXtFindFile24m looks through the specified 4msubstitutions24m for that character in the 4mmatch0m field and, if found, replaces the percent and match charac- ters with the string in the corresponding 4msubstitution0m field. A 4msubstitution24m field entry of NULL is equivalent to a pointer to an empty string. If the operating system does not interpret multiple embedded name separators in the path (i.e., ``/'' in POSIX) the same way as a single separator, 4mXtFindFile24m will collapse multiple separators into a single one after performing all string substitutions. Except for collapsing embedded separators, the contents of the string substitutions are not interpreted by 4mXtFindFile24m and may therefore contain any operating-system-dependent characters, including additional name separators. Each resulting string is passed to the predicate procedure until a string is found for which the procedure returns 4mTrue24m; this string is the return value for 4mXtFindFile24m. If no string yields a 4mTrue0m return from the predicate, 4mXtFindFile24m returns NULL. If the 4mpredicate24m parameter is NULL, an internal procedure that checks if the file exists, is readable, and is not a directory is used. It is the responsibility of the caller to free the returned string using 4mXtFree24m when it is no longer needed. To search for a file using standard substitutions in a path list, use 4mXtResolvePathname24m. 1m3350m 1mX Toolkit Intrinsics X11 Release 6.40m __ | String XtResolvePathname(4mdisplay24m, 4mtype24m, 4mfilename24m, 4msuffix24m, 4mpath24m, 4msubstitutions24m, 4mnum_substitutions24m, 4mpredicate24m) Display *4mdisplay24m; String 4mtype24m, 4mfilename24m, 4msuffix24m, 4mpath24m; Substitution 4msubstitutions24m; Cardinal 4mnum_substitutions24m; XtFilePredicate 4mpredicate24m; 4mdisplay24m Specifies the display to use to find the lan- guage for language substitutions. 4mtype0m 4mfilename0m 4msuffix24m Specify values to substitute into the path. 4mpath24m Specifies the list of file specifications, or NULL. 4msubstitutions0m Specifies a list of additional substitutions to make into the path, or NULL. 4mnum_substitutions0m Specifies the number of entries in 4msubstitu-0m 4mtions24m. 4mpredicate24m Specifies a procedure called to judge each potential file name, or NULL. |__ The substitutions specified by 4mXtResolvePathname24m are deter- mined from the value of the language string retrieved by 4mXtDisplayInitialize24m for the specified display. To set the language for all applications specify ``*xnlLanguage: 4mlang24m'' in the resource database. The format and content of the language string are implementation-defined. One suggested syntax is to compose the language string of three parts; a ``language part'', a ``territory part'' and a ``codeset part''. The manner in which this composition is accom- plished is implementation-defined, and the Intrinsics make no interpretation of the parts other than to use them in substitutions as described below. 4mXtResolvePathname24m calls 4mXtFindFile24m with the following sub- stitutions in addition to any passed by the caller and returns the value returned by 4mXtFindFile24m: %N The value of the 4mfilename24m parameter, or the applica- tion's class name if 4mfilename24m is NULL. %T The value of the 4mtype24m parameter. 1m3360m 1mX Toolkit Intrinsics X11 Release 6.40m %S The value of the 4msuffix24m parameter. %L The language string associated with the specified dis- play. %l The language part of the display's language string. %t The territory part of the display's language string. %c The codeset part of the display's language string. %C The customization string retrieved from the resource database associated with 4mdisplay24m. %D The value of the implementation-specific default path. If a path is passed to 4mXtResolvePathname24m, it is passed along to 4mXtFindFile24m. If the 4mpath24m argument is NULL, the value of the 4mXFILESEARCHPATH24m environment variable is passed to 4mXtFindFile24m. If 4mXFILESEARCHPATH24m is not defined, an implemen- tation-specific default path is used that contains at least six entries. These entries must contain the following sub- stitutions: 1. %C, %N, %S, %T, %L or%C, %N, %S, %T, %l, %t, %c 2. %C, %N, %S, %T, %l 3. %C, %N, %S, %T 4. %N, %S, %T, %L or %N, %S, %T, %l, %t, %c 5. %N, %S, %T, %l 6. %N, %S, %T The order of these six entries within the path must be as given above. The order and use of substitutions within a given entry are implementation-dependent. If the path begins with a colon, it is preceded by %N%S. If the path includes two adjacent colons, 1m%N%S 22mis inserted between them. The 4mtype24m parameter is intended to be a category of files, usually being translated into a directory in the pathname. Possible values might include ``app-defaults'', ``help'', and ``bitmap''. The 4msuffix24m parameter is intended to be appended to the file name. Possible values might include ``.txt'', ``.dat'', and ``.bm''. A suggested value for the default path on POSIX-based sys- tems is /usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:\ /usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:\ /usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S 1m3370m 1mX Toolkit Intrinsics X11 Release 6.40m Using this example, if the user has specified a language, it is used as a subdirectory of /usr/lib/X11 that is searched for other files. If the desired file is not found there, the lookup is tried again using just the language part of the specification. If the file is not there, it is looked for in /usr/lib/X11. The 4mtype24m parameter is used as a subdi- rectory of the language directory or of /usr/lib/X11, and 4msuffix24m is appended to the file name. The %D substitution allows the addition of path elements to the implementation-specific default path, typically to allow additional directories to be searched without preventing resources in the system directories from being found. For example, a user installing resource files under a directory called ``ourdir'' might set 4mXFILESEARCHPATH24m to %D:ourdir/%T/%N%C:ourdir/%T/%N The customization string is obtained by querying the resource database currently associated with the display (the database returned by 4mXrmGetDatabase24m) for the resource 4mappli-0m 4mcation_name24m.customization, class 4mapplication_class24m.Cus- tomization, where 4mapplication_name24m and 4mapplication_class24m are the values returned by 4mXtGetApplicationNameAndClass24m. If no value is specified in the database, the empty string is used. It is the responsibility of the caller to free the returned string using 4mXtFree24m when it is no longer needed. 1m11.12. Hooks for External Agents0m Applications may register functions that are called at a particular control points in the Intrinsics. These func- tions are intended to be used to provide notification of an "X Toolkit event", such as widget creation, to an external agent, such as an interactive resource editor, drag-and-drop server, or an aid for physically challenged users. The con- trol points containing such registration hooks are identi- fied in a "hook registration" object. To retrieve the hook registration widget, use 4mXtHooksOfDis-0m 4mplay24m. 1m3380m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtHooksOfDisplay(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the desired display. |__ The class of this object is a private, implementation-depen- dent subclass of 4mObject24m. The hook object has no parent. The resources of this object are the callback lists for hooks and the read-only resources for getting a list of par- entless shells. All of the callback lists are initially empty. When a display is closed, the hook object associated with it is destroyed. The following procedures can be called with the hook regis- tration object as an argument: 4mXtAddCallback24m, 4mXtAddCallbacks24m, 4mXtRemoveCallback24m, 4mXtRemoveCallbacks24m, 4mXtRemoveAllCallbacks24m, 4mXtCallCall-0m 4mbacks24m, 4mXtHasCallbacks24m, 4mXtCallCallbackList0m 4mXtClass24m, 4mXtSuperclass24m, 4mXtIsSubclass24m, 4mXtCheckSubclass24m, 4mXtIsObject24m, 4mXtIsRectObj24m, 4mXtIsWidget24m, 4mXtIsComposite24m, 4mXtIsConstraint24m, 4mXtIsShell24m, 4mXtIsOverrideShell24m, 4mXtIsWMShell24m, 4mXtIsVendorShell24m, 4mXtIsTransientShell24m, 4mXtIsToplevelShell24m, 4mXtIsApplicationShell24m, 4mXtIsSession-0m 4mShell0m 4mXtWidgetToApplicationContext0m 4mXtName24m, 4mXtParent24m, 4mXtDisplayOfObject24m, 4mXtScreenOfObject0m 4mXtSetValues24m, 4mXtGetValues24m, 4mXtVaSetValues24m, 4mXtVaGetValues0m 1m11.12.1. Hook Object Resources0m The resource names, classes, and representation types that are specified in the hook object resource list are: 1m3390m 1mX Toolkit Intrinsics X11 Release 6.40m --------------------------------------------------------------- Name Class Representation --------------------------------------------------------------- XtNcreateHook XtCCallback XtRCallback XtNchangeHook XtCCallback XtRCallback XtNconfigureHook XtCCallback XtRCallback XtNgeometryHook XtCCallback XtRCallback XtNdestroyHook XtCCallback XtRCallback XtNshells XtCReadOnly XtRWidgetList XtNnumShells XtCReadOnly XtRCardinal --------------------------------------------------------------- Descriptions of each of these resources: The XtNcreateHook callback list is called from: 4mXtCreateWid-0m 4mget24m, 4mXtCreateManagedWidget24m, 4mXtCreatePopupShell24m, 4mXtAppCre-0m 4mateShell24m, and their corresponding varargs versions. The 4mcall_data24m parameter in a createHook callback may be cast to type 4mXtCreateHookData24m. __ | typedef struct { String type; Widget widget; ArgList args; Cardinal num_args; } XtCreateHookDataRec, *XtCreateHookData; |__ The 4mtype24m is set to 4mXtHcreate24m, 4mwidget24m is the newly created widget, and 4margs24m and 4mnum_args24m are the arguments passed to the create function. The callbacks are called before return- ing from the create function. The XtNchangeHook callback list is called from: 4mXtSetValues24m, 4mXtVaSetValues0m 4mXtManageChild24m, 4mXtManageChildren24m, 4mXtUnmanageChild24m, 4mXtUn-0m 4mmanageChildren0m 4mXtRealizeWidget24m, 4mXtUnrealizeWidget0m 4mXtAddCallback24m, 4mXtRemoveCallback24m, 4mXtAddCallbacks,0m 4mXtRemoveCallbacks24m, 4mXtRemoveAllCallbacks0m 4mXtAugmentTranslations24m, 4mXtOverrideTranslations24m, 4mXtUnin-0m 4mstallTranslations0m 1m3400m 1mX Toolkit Intrinsics X11 Release 6.40m 4mXtSetKeyboardFocus24m, 4mXtSetWMColormapWindows0m 4mXtSetMappedWhenManaged24m, 4mXtMapWidget24m, 4mXtUnmapWidget0m 4mXtPopup24m, 4mXtPopupSpringLoaded24m, 4mXtPopdown0m The 4mcall_data24m parameter in a changeHook callback may be cast to type 4mXtChangeHookData24m. __ | typedef struct { String type; Widget widget; XtPointer event_data; Cardinal num_event_data; } XtChangeHookDataRec, *XtChangeHookData; |__ When the changeHook callbacks are called as a result of a call to 4mXtSetValues24m or 4mXtVaSetValues24m, 4mtype24m is set to 4mXtHset-0m 4mValues24m, 4mwidget24m is the new widget passed to the set_values procedure, and 4mevent_data24m may be cast to type 4mXtChangeHook-0m 4mSetValuesData24m. __ | typedef struct { Widget old, req; ArgList args; Cardinal num_args; } XtChangeHookSetValuesDataRec, *XtChangeHookSetValuesData; |__ The 4mold24m, 4mreq24m, 4margs24m, and 4mnum_args24m are the parameters passed to the set_values procedure. The callbacks are called after the set_values and constraint set_values procedures have been called. When the changeHook callbacks are called as a result of a call to 4mXtManageChild24m or 4mXtManageChildren24m, 4mtype24m is set to 4mXtHmanageChildren24m, 4mwidget24m is the parent, 4mevent_data24m may be cast to type WidgetList and is the list of children being managed, and 4mnum_event_data24m is the length of the widget list. The callbacks are called after the children have been managed. When the changeHook callbacks are called as a result of a call to 4mXtUnmanageChild24m or 4mXtUnmanageChildren24m, 4mtype24m is set to 4mXtHunmanageChildren24m, 4mwidget24m is the parent, 4mevent_data24m may 1m3410m 1mX Toolkit Intrinsics X11 Release 6.40m be cast to type WidgetList and is a list of the children being unmanaged, and 4mnum_event_data24m is the length of the widget list. The callbacks are called after the children have been unmanaged. The changeHook callbacks are called twice as a result of a call to 4mXtChangeManagedSet24m, once after unmanaging and again after managing. When the callbacks are called the first time, 4mtype24m is set to 4mXtHunmanageSet24m, 4mwidget24m is the parent, 4mevent_data24m may be cast to type WidgetList and is a list of the children being unmanaged, and 4mnum_event_data24m is the length of the widget list. When the callbacks are called the second time, the 4mtype24m is set to 4mXtHmanageSet24m, 4mwidget24m is the parent, 4mevent_data24m may be cast to type WidgetList and is a list of the children being managed, and 4mnum_event_data24m is the length of the widget list. When the changeHook callbacks are called as a result of a call to 4mXtRealizeWidget24m, the 4mtype24m is set to 4mXtHrealizeWidget0m and 4mwidget24m is the widget being realized. The callbacks are called after the widget has been realized. When the changeHook callbacks are called as a result of a call to 4mXtUnrealizeWidget24m, the 4mtype24m is set to 4mXtHunreal-0m 4mizeWidget24m, and 4mwidget24m is the widget being unrealized. The callbacks are called after the widget has been unrealized. When the changeHook callbacks are called as a result of a call to 4mXtAddCallback24m, 4mtype24m is set to 4mXtHaddCallback24m, 4mwidget0m is the widget to which the callback is being added, and 4mevent_data24m may be cast to type String and is the name of the callback being added. The callbacks are called after the callback has been added to the widget. When the changeHook callbacks are called as a result of a call to 4mXtAddCallbacks24m, the 4mtype24m is set to 4mXtHaddCallbacks24m, 4mwidget24m is the widget to which the callbacks are being added, and 4mevent_data24m may be cast to type String and is the name of the callbacks being added. The callbacks are called after the callbacks have been added to the widget. When the changeHook callbacks are called as a result of a call to 4mXtRemoveCallback24m, the 4mtype24m is set to 4mXtHremoveCall-0m 4mback24m, 4mwidget24m is the widget from which the callback is being removed, and 4mevent_data24m may be cast to type String and is the name of the callback being removed. The callbacks are called after the callback has been removed from the widget. When the changeHook callbacks are called as a result of a call to 4mXtRemoveCallbacks24m, the 4mtype24m is set to 4mXtHremoveCall-0m 4mbacks24m, 4mwidget24m is the widget from which the callbacks are being removed, and 4mevent_data24m may be cast to type String and is the name of the callbacks being removed. The callbacks are called after the callbacks have been removed from the 1m3420m 1mX Toolkit Intrinsics X11 Release 6.40m widget. When the changeHook callbacks are called as a result of a call to 4mXtRemoveAllCallbacks24m, the 4mtype24m is set to 4mXtHre-0m 4mmoveAllCallbacks24m and 4mwidget24m is the widget from which the callbacks are being removed. The callbacks are called after the callbacks have been removed from the widget. When the changeHook callbacks are called as a result of a call to 4mXtAugmentTranslations24m, the 4mtype24m is set to 4mXtHaug-0m 4mmentTranslations24m and 4mwidget24m is the widget whose translations are being modified. The callbacks are called after the wid- get's translations have been modified. When the changeHook callbacks are called as a result of a call to 4mXtOverrideTranslations24m, the 4mtype24m is set to 4mXtHover-0m 4mrideTranslations24m and 4mwidget24m is the widget whose translations are being modified. The callbacks are called after the wid- get's translations have been modified. When the changeHook callbacks are called as a result of a call to 4mXtUninstallTranslations24m, The 4mtype24m is 4mXtHuninstall-0m 4mTranslations24m and 4mwidget24m is the widget whose translations are being uninstalled. The callbacks are called after the wid- get's translations have been uninstalled. When the changeHook callbacks are called as a result of a call to 4mXtSetKeyboardFocus24m, the 4mtype24m is set to 4mXtHsetKey-0m 4mboardFocus24m and 4mevent_data24m may be cast to type Widget and is the value of the descendant argument passed to 1mXtSetKey-0m 1mboardFocus22m. The callbacks are called before returning from 1mXtSetKeyboardFocus22m. When the changeHook callbacks are called as a result of a call to 4mXtSetWMColormapWindows24m, 4mtype24m is set to 4mXtHsetWMCol-0m 4mormapWindows24m, 4mevent_data24m may be cast to type WidgetList and is the value of the list argument passed to 1mXtSetWMColormap-0m 1mWindows22m, and 4mnum_event_data24m is the length of the list. The callbacks are called before returning from 1mXtSetWMColormap-0m 1mWindows22m. When the changeHook callbacks are called as a result of a call to 4mXtSetMappedWhenManaged24m, the 4mtype24m is set to 4mXtH-0m 4msetMappedWhenManaged24m and 4mevent_data24m may be cast to type Boolean and is the value of the mapped_when_managed argument passed to 1mXtSetMappedWhenManaged22m. The callbacks are called after setting the widget's mapped_when_managed field and before realizing or unrealizing the widget. When the changeHook callbacks are called as a result of a call to 4mXtMapWidget24m, the 4mtype24m is set to 4mXtHmapWidget24m and 4mwidget24m is the widget being mapped. The callbacks are called after mapping the widget. 1m3430m 1mX Toolkit Intrinsics X11 Release 6.40m When the changeHook callbacks are called as a result of a call to 4mXtUnmapWidget24m, the 4mtype24m is set to 4mXtHunmapWidget0m and 4mwidget24m is the widget being unmapped. The callbacks are called after unmapping the widget. When the changeHook callbacks are called as a result of a call to 4mXtPopup24m, the 4mtype24m is set to 4mXtHpopup24m, 4mwidget24m is the widget being popped up, and 4mevent_data24m may be cast to type XtGrabKind and is the value of the grab_kind argument passed to 1mXtPopup22m. The callbacks are called before returning from 1mXtPopup22m. When the changeHook callbacks are called as a result of a call to 4mXtPopupSpringLoaded24m, the 4mtype24m is set to 4mXtHpopup-0m 4mSpringLoaded24m and 4mwidget24m is the widget being popped up. The callbacks are called before returning from 1mXtPopup-0m 1mSpringLoaded22m. When the changeHook callbacks are called as a result of a call to 4mXtPopdown24m, the 4mtype24m is set to 4mXtHpopdown24m and 4mwidget0m is the widget being popped down. The callbacks are called before returning from 1mXtPopdown22m. A widget set that exports interfaces that change application state without employing the Intrinsics library should invoke the change hook itself. This is done by: XtCallCallbacks(XtHooksOfDisplay(dpy), XtNchangeHook, call_data); The XtNconfigureHook callback list is called any time the Intrinsics move, resize, or configure a widget and when 4mXtResizeWindow24m is called. The 4mcall_data24m parameter may be cast to type 4mXtConfigureHook-0m 4mData.0m __ | typedef struct { String type; Widget widget; XtGeometryMask changeMask; XWindowChanges changes; } XtConfigureHookDataRec, *XtConfigureHookData; |__ When the configureHook callbacks are called, the 4mtype24m is 4mXtHconfigure24m, 4mwidget24m is the widget being configured, and 4mchangeMask24m and 4mchanges24m reflect the changes made to the 1m3440m 1mX Toolkit Intrinsics X11 Release 6.40m widget. The callbacks are called after changes have been made to the widget. The XtNgeometryHook callback list is called from 4mXtMake-0m 4mGeometryRequest24m and 4mXtMakeResizeRequest24m once before and once after geometry negotiation occurs. The 4mcall_data24m parameter may be cast to type 4mXtGeometryHook-0m 4mData24m. __ | typedef struct { String type; Widget widget; XtWidgetGeometry* request; XtWidgetGeometry* reply; XtGeometryResult result; } XtGeometryHookDataRec, *XtGeometryHookData; |__ When the geometryHook callbacks are called prior to geometry negotiation, the 4mtype24m is 4mXtHpreGeometry24m, 4mwidget24m is the wid- get for which the request is being made, and 4mrequest24m is the requested geometry. When the geometryHook callbacks are called after geometry negotiation, the 4mtype24m is 4mXtHpostGeome-0m 4mtry24m, 4mwidget24m is the widget for which the request was made, 4mrequest24m is the requested geometry, 4mreply24m is the resulting geometry granted, and 4mresult24m is the value returned from the geometry negotiation. The XtNdestroyHook callback list is called when a widget is destroyed. The 4mcall_data24m 4mparameter24m may be cast to type 4mXtDestroyHookData24m. __ | typedef struct { String type; Widget widget; } XtDestroyHookDataRec, *XtDestroyHookData; |__ When the destroyHook callbacks are called as a result of a call to 4mXtDestroyWidget24m, the 4mtype24m is 4mXtHdestroy24m and 4mwidget0m is the widget being destroyed. The callbacks are called upon completion of phase one destroy for a widget. 1m3450m 1mX Toolkit Intrinsics X11 Release 6.40m The XtNshells and XtnumShells are read-only resources that report a list of all parentless shell widgets associated with a display. Clients who use these hooks must exercise caution in calling Intrinsics functions in order to avoid recursion. 1m11.12.2. Querying Open Displays0m To retrieve a list of the Displays associated with an appli- cation context, use 4mXtGetDisplays24m. __ | void XtGetDisplays(4mapp_context24m, 4mdpy_return24m, 4mnum_dpy_return24m) XtAppContext 4mapp_context24m; Display ***4mdpy_return24m; Cardinal *4mnum_dpy_return24m; 4mapp_context24m Specifies the application context. 4mdpy_return24m Returns a list of open Display connections in the specified application context. 4mnum_dpy_return24m Returns the count of open Display connections in 4mdpy_return24m. |__ 1mXtGetDisplays 22mmay be used by an external agent to query the list of open displays that belong to an application context. To free the list of displays, use 4mXtFree24m. 1m3460m 1mX Toolkit Intrinsics X11 Release 6.40m 1mChapter 120m 1mNonwidget Objects0m Although widget writers are free to treat Core as the base class of the widget hierarchy, there are actually three classes above it. These classes are Object, RectObj (Rec- tangle Object), and (4munnamed24m), and members of these classes are referred to generically as 4mobjects24m. By convention, the term 4mwidget24m refers only to objects that are a subclass of Core, and the term 4mnonwidget24m refers to objects that are not a subclass of Core. In the preceding portion of this speci- fication, the interface descriptions indicate explicitly whether the generic 4mwidget24m argument is restricted to partic- ular subclasses of Object. Sections 12.2.5, 12.3.5, and 12.5 summarize the permissible classes of the arguments to, and return values from, each of the Intrinsics routines. 1m12.1. Data Structures0m In order not to conflict with previous widget code, the data structures used by nonwidget objects do not follow all the same conventions as those for widgets. In particular, the class records are not composed of parts but instead are com- plete data structures with filler for the widget fields they do not use. This allows the static class initializers for existing widgets to remain unchanged. 1m12.2. Object Objects0m The Object object contains the definitions of fields common to all objects. It encapsulates the mechanisms for resource management. All objects and widgets are members of sub- classes of Object, which is defined by the 4mObjectClassPart0m and 4mObjectPart24m structures. 1m12.2.1. ObjectClassPart Structure0m The common fields for all object classes are defined in the 4mObjectClassPart24m structure. All fields have the same pur- pose, function, and restrictions as the corresponding fields in 4mCoreClassPart24m; fields whose names are obj4mn24m for some inte- ger 4mn24m are not used for Object, but exist to pad the data structure so that it matches Core's class record. The class record initialization must fill all obj4mn24m fields with NULL or zero as appropriate to the type. 1m3470m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct _ObjectClassPart { WidgetClass superclass; String class_name; Cardinal widget_size; XtProc class_initialize; XtWidgetClassProc class_part_initialize; XtEnum class_inited; XtInitProc initialize; XtArgsProc initialize_hook; XtProc obj1; XtPointer obj2; Cardinal obj3; XtResourceList resources; Cardinal num_resources; XrmClass xrm_class; Boolean obj4; XtEnum obj5; Boolean obj6; Boolean obj7; XtWidgetProc destroy; XtProc obj8; XtProc obj9; XtSetValuesFunc set_values; XtArgsFunc set_values_hook; XtProc obj10; XtArgsProc get_values_hook; XtProc obj11; XtVersionType version; XtPointer callback_private; String obj12; XtProc obj13; XtProc obj14; XtPointer extension; } ObjectClassPart; |__ The extension record defined for 4mObjectClassPart24m with a 4mrecord_type24m equal to 4mNULLQUARK24m is 4mObjectClassExtensionRec24m. 1m3480m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct { XtPointer next_extension;See Section 1.6.12 XrmQuark record_type; See Section 1.6.12 long version; See Section 1.6.12 Cardinal record_size; See Section 1.6.12 XtAllocateProc allocate; See Section 2.5.5. XtDeallocateProc deallocate;See Section 2.8.4. } ObjectClassExtensionRec, *ObjectClassExtension; |__ The prototypical 4mObjectClass24m consists of just the 4mObject-0m 4mClassPart24m. __ | typedef struct _ObjectClassRec { ObjectClassPart object_class; } ObjectClassRec, *ObjectClass; |__ The predefined class record and pointer for 4mObjectClassRec0m are In 4mIntrinsicP.h24m: __ | extern ObjectClassRec objectClassRec; |__ In 4mIntrinsic.h24m: __ | extern WidgetClass objectClass; |__ The opaque types 4mObject24m and 4mObjectClass24m and the opaque vari- able 4mobjectClass24m are defined for generic actions on objects. The symbolic constant for the 4mObjectClassExtension24m version identifier is 4mXtObjectExtensionVersion24m (see Section 1.6.12). 4mIntrinsic.h24m uses an incomplete structure definition to ensure that the compiler catches attempts to access private data: 1m3490m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct _ObjectClassRec* ObjectClass; |__ 1m12.2.2. ObjectPart Structure0m The common fields for all object instances are defined in the 4mObjectPart24m structure. All fields have the same meaning as the corresponding fields in 4mCorePart24m. __ | typedef struct _ObjectPart { Widget self; WidgetClass widget_class; Widget parent; Boolean being_destroyed; XtCallbackList destroy_callbacks; XtPointer constraints; } ObjectPart; |__ All object instances have the Object fields as their first component. The prototypical type 4mObject24m is defined with only this set of fields. Various routines can cast object pointers, as needed, to specific object types. In 4mIntrinsicP.h24m: __ | typedef struct _ObjectRec { ObjectPart object; } ObjectRec, *Object; |__ In 4mIntrinsic.h24m: __ | typedef struct _ObjectRec *Object; |__ 1m3500m 1mX Toolkit Intrinsics X11 Release 6.40m 1m12.2.3. Object Resources0m The resource names, classes, and representation types speci- fied in the 4mobjectClassRec24m resource list are: ----------------------------------------------------------------- Name Class Representation ----------------------------------------------------------------- XtNdestroyCallback XtCCallback XtRCallback ----------------------------------------------------------------- 1m12.2.4. ObjectPart Default Values0m All fields in 4mObjectPart24m have the same default values as the corresponding fields in 4mCorePart24m. 1m12.2.5. Object Arguments to Intrinsics Routines0m The WidgetClass arguments to the following procedures may be 4mobjectClass24m or any subclass: 4mXtInitializeWidgetClass24m, 4mXtCreateWidget24m, 4mXtVaCreateWid-0m 4mget0m 4mXtIsSubclass24m, 4mXtCheckSubclass0m 4mXtGetResourceList24m, 4mXtGetConstraintResourceList0m The Widget arguments to the following procedures may be of class Object or any subclass: 4mXtCreateWidget24m, 4mXtVaCreateWidget0m 4mXtAddCallback24m, 4mXtAddCallbacks24m, 4mXtRemoveCallback24m, 4mXtRemoveCallbacks24m, 4mXtRemoveAllCallbacks24m, 4mXtCallCall-0m 4mbacks24m, 4mXtHasCallbacks24m, 4mXtCallCallbackList0m 4mXtClass24m, 4mXtSuperclass24m, 4mXtIsSubclass24m, 4mXtCheckSubclass24m, 4mXtIsObject24m, 4mXtIsRectObj24m, 4mXtIsWidget24m, 4mXtIsComposite24m, 4mXtIsConstraint24m, 4mXtIsShell24m, 4mXtIsOverrideShell24m, 4mXtIsWMShell24m, 4mXtIsVendorShell24m, 4mXtIsTransientShell24m, 4mXtIsToplevelShell24m, 4mXtIsApplicationShell24m, 4mXtIsSession-0m 4mShell0m 4mXtIsManaged24m, 4mXtIsSensitive0m (both will return 4mFalse24m if argument is not a subclass of RectObj) 1m3510m 1mX Toolkit Intrinsics X11 Release 6.40m 4mXtIsRealized0m (returns the state of the nearest windowed ancestor if class of argument is not a subclass of Core) 4mXtWidgetToApplicationContext0m 4mXtDestroyWidget0m 4mXtParent24m, 4mXtDisplayOfObject24m, 4mXtScreenOfObject24m, 4mXtWin-0m 4mdowOfObject0m 4mXtSetKeyboardFocus24m (descendant) 4mXtGetGC24m, 4mXtReleaseGC0m 4mXtName0m 4mXtSetValues24m, 4mXtGetValues24m, 4mXtVaSetValues24m, 4mXtVaGetValues0m 4mXtGetSubresources24m, 4mXtGetApplicationResources24m, 4mXtVaGet-0m 4mSubresources24m, 4mXtVaGetApplicationResources0m 4mXtConvert24m, 4mXtConvertAndStore0m The return value of the following procedures will be of class Object or a subclass: 4mXtCreateWidget24m, 4mXtVaCreateWidget0m 4mXtParent0m 4mXtNameToWidget0m The return value of the following procedures will be 4mobject-0m 4mClass24m or a subclass: 4mXtClass24m, 4mXtSuperclass0m 1m12.2.6. Use of Objects0m The Object class exists to enable programmers to use the Intrinsics' classing and resource-handling mechanisms for things smaller and simpler than widgets. Objects make obso- lete many common uses of subresources as described in Sec- tions 9.4, 9.7.2.4, and 9.7.2.5. Composite widget classes that wish to accept nonwidget chil- dren must set the 4maccepts_objects24m field in the 4mComposite-0m 4mClassExtension24m structure to 4mTrue24m. 4mXtCreateWidget24m will 1m3520m 1mX Toolkit Intrinsics X11 Release 6.40m otherwise generate an error message on an attempt to create a nonwidget child. Of the classes defined by the Intrinsics, ApplicationShell and SessionShell accept nonwidget children, and the class of any nonwidget child must not be 4mrectObjClass24m or any sub- class. The intent of allowing Object children of Applica- tionShell and SessionShell is to provide clients a simple mechanism for establishing the resource-naming root of an object hierarchy. 1m12.3. Rectangle Objects0m The class of rectangle objects is a subclass of Object that represents rectangular areas. It encapsulates the mecha- nisms for geometry management and is called RectObj to avoid conflict with the Xlib 4mRectangle24m data type. 1m12.3.1. RectObjClassPart Structure0m As with the 4mObjectClassPart24m structure, all fields in the 4mRectObjClassPart24m structure have the same purpose and func- tion as the corresponding fields in 4mCoreClassPart24m; fields whose names are rect4mn24m for some integer 4mn24m are not used for RectObj, but exist to pad the data structure so that it matches Core's class record. The class record initializa- tion must fill all rect4mn24m fields with NULL or zero as appro- priate to the type. 1m3530m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct _RectObjClassPart { WidgetClass superclass; String class_name; Cardinal widget_size; XtProc class_initialize; XtWidgetClassProc class_part_initialize; XtEnum class_inited; XtInitProc initialize; XtArgsProc initialize_hook; XtProc rect1; XtPointer rect2; Cardinal rect3; XtResourceList resources; Cardinal num_resources; XrmClass xrm_class; Boolean rect4; XtEnum rect5; Boolean rect6; Boolean rect7; XtWidgetProc destroy; XtWidgetProc resize; XtExposeProc expose; XtSetValuesFunc set_values; XtArgsFunc set_values_hook; XtAlmostProc set_values_almost; XtArgsProc get_values_hook; XtProc rect9; XtVersionType version; XtPointer callback_private; String rect10; XtGeometryHandler query_geometry; XtProc rect11; XtPointer extension ; } RectObjClassPart; |__ The RectObj class record consists of just the 4mRectObjClass-0m 4mPart24m. __ | typedef struct _RectObjClassRec { RectObjClassPart rect_class; } RectObjClassRec, *RectObjClass; |__ The predefined class record and pointer for 4mRectObjClassRec0m are In 4mIntrinsic.h24m: 1m3540m 1mX Toolkit Intrinsics X11 Release 6.40m __ | extern RectObjClassRec rectObjClassRec; |__ In 4mIntrinsic.h24m: __ | extern WidgetClass rectObjClass; |__ The opaque types 4mRectObj24m and 4mRectObjClass24m and the opaque variable 4mrectObjClass24m are defined for generic actions on objects whose class is RectObj or a subclass of RectObj. 4mIntrinsic.h24m uses an incomplete structure definition to ensure that the compiler catches attempts to access private data: __ | typedef struct _RectObjClassRec* RectObjClass; |__ 1m12.3.2. RectObjPart Structure0m In addition to the 4mObjectPart24m fields, RectObj objects have the following fields defined in the 4mRectObjPart24m structure. All fields have the same meaning as the corresponding field in 4mCorePart24m. __ | typedef struct _RectObjPart { Position x, y; Dimension width, height; Dimension border_width; Boolean managed; Boolean sensitive; Boolean ancestor_sensitive; } RectObjPart; |__ RectObj objects have the RectObj fields immediately follow- ing the Object fields. 1m3550m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct _RectObjRec { ObjectPart object; RectObjPart rectangle; } RectObjRec, *RectObj; |__ In 4mIntrinsic.h24m: __ | typedef struct _RectObjRec* RectObj; |__ 1m12.3.3. RectObj Resources0m The resource names, classes, and representation types that are specified in the 4mrectObjClassRec24m resource list are: ------------------------------------------------------------------- Name Class Representation ------------------------------------------------------------------- XtNancestorSensitive XtCSensitive XtRBoolean XtNborderWidth XtCBorderWidth XtRDimension XtNheight XtCHeight XtRDimension XtNsensitive XtCSensitive XtRBoolean XtNwidth XtCWidth XtRDimension XtNx XtCPosition XtRPosition XtNy XtCPosition XtRPosition ------------------------------------------------------------------- 1m12.3.4. RectObjPart Default Values0m All fields in 4mRectObjPart24m have the same default values as the corresponding fields in 4mCorePart24m. 1m12.3.5. Widget Arguments to Intrinsics Routines0m The WidgetClass arguments to the following procedures may be 4mrectObjClass24m or any subclass: 4mXtCreateManagedWidget24m, 4mXtVaCreateManagedWidget0m The Widget arguments to the following procedures may be of class RectObj or any subclass: 1m3560m 1mX Toolkit Intrinsics X11 Release 6.40m 4mXtConfigureWidget24m, 4mXtMoveWidget24m, 4mXtResizeWidget0m 4mXtMakeGeometryRequest24m, 4mXtMakeResizeRequest0m 4mXtManageChildren24m, 4mXtManageChild24m, 4mXtUnmanageChildren24m, 4mXtUnmanageChild24m, 4mXtChangeManagedSet0m 4mXtQueryGeometry0m 4mXtSetSensitive0m 4mXtTranslateCoords0m The return value of the following procedures will be of class RectObj or a subclass: 4mXtCreateManagedWidget24m, 4mXtVaCreateManagedWidget0m 1m12.3.6. Use of Rectangle Objects0m RectObj can be subclassed to provide widgetlike objects (sometimes called gadgets) that do not use windows and do not have those features that are seldom used in simple wid- gets. This can save memory resources both in the server and in applications but requires additional support code in the parent. In the following discussion, 4mrectobj24m refers only to objects whose class is RectObj or a subclass of RectObj, but not Core or a subclass of Core. Composite widget classes that wish to accept rectobj chil- dren must set the 4maccepts_objects24m field in the 4mComposite-0m 4mClassExtension24m extension structure to 4mTrue24m. 4mXtCreateWidget0m or 4mXtCreateManagedWidget24m will otherwise generate an error if called to create a nonwidget child. If the composite widget supports only children of class RectObj or a subclass (i.e., not of the general Object class), it must declare an insert_child procedure and check the subclass of each new child in that procedure. None of the classes defined by the Intrinsics accept rectobj children. If gadgets are defined in an object set, the parent is responsible for much more than the parent of a widget. The parent must request and handle input events that occur for the gadget and is responsible for making sure that when it receives an exposure event the gadget children get drawn correctly. Rectobj children may have expose procedures specified in their class records, but the parent is free to ignore them, instead drawing the contents of the child itself. This can potentially save graphics context switch- ing. The precise contents of the exposure event and region arguments to the RectObj expose procedure are not specified 1m3570m 1mX Toolkit Intrinsics X11 Release 6.40m by the Intrinsics; a particular rectangle object is free to define the coordinate system origin (self-relative or par- ent-relative) and whether or not the rectangle or region is assumed to have been intersected with the visible region of the object. In general, it is expected that a composite widget that accepts nonwidget children will document those children it is able to handle, since a gadget cannot be viewed as a com- pletely self-contained entity, as can a widget. Since a particular composite widget class is usually designed to handle nonwidget children of only a limited set of classes, it should check the classes of newly added children in its insert_child procedure to make sure that it can deal with them. The Intrinsics will clear areas of a parent window obscured by rectobj children, causing exposure events, under the fol- lowing circumstances: · A rectobj child is managed or unmanaged. · In a call to 4mXtSetValues24m on a rectobj child, one or more of the set_values procedures returns 4mTrue24m. · In a call to 4mXtConfigureWidget24m on a rectobj child, areas will be cleared corresponding to both the old and the new child geometries, including the border, if the geometry changes. · In a call to 4mXtMoveWidget24m on a rectobj child, areas will be cleared corresponding to both the old and the new child geometries, including the border, if the geometry changes. · In a call to 4mXtResizeWidget24m on a rectobj child, a sin- gle rectangle will be cleared corresponding to the larger of the old and the new child geometries if they are different. · In a call to 4mXtMakeGeometryRequest24m (or 4mXtMakeResiz-0m 4meRequest24m) on a rectobj child with 4mXtQueryOnly24m not set, if the manager returns 4mXtGeometryYes24m, two rectangles will be cleared corresponding to both the old and the new child geometries. Stacking order is not supported for rectobj children. Com- posite widgets with rectobj children are free to define any semantics desired if the child geometries overlap, including making this an error. When a rectobj is playing the role of a widget, developers must be reminded to avoid making assumptions about the object passed in the Widget argument to a callback 1m3580m 1mX Toolkit Intrinsics X11 Release 6.40m procedure. 1m12.4. Undeclared Class0m The Intrinsics define an unnamed class between RectObj and Core for possible future use by the X Consortium. The only assumptions that may be made about the unnamed class are · The 4mcore_class.superclass24m field of 4mcoreWidgetClassRec0m contains a pointer to the unnamed class record. · A pointer to the unnamed class record when dereferenced as an 4mObjectClass24m will contain a pointer to 4mrectObj-0m 4mClassRec24m in its 4mobject_class.superclass24m field. Except for the above, the contents of the class record for this class and the result of an attempt to subclass or to create a widget of this unnamed class are undefined. 1m12.5. Widget Arguments to Intrinsics Routines0m The WidgetClass arguments to the following procedures must be of class Shell or a subclass: 4mXtCreatePopupShell24m, 4mXtVaCreatePopupShell24m, 4mXtAppCre-0m 4mateShell24m, 4mXtVaAppCreateShell24m, 4mXtOpenApplication24m, 4mXtVaOpenApplication0m The Widget arguments to the following procedures must be of class Core or any subclass: 4mXtCreatePopupShell24m, 4mXtVaCreatePopupShell0m 4mXtAddEventHandler24m, 4mXtAddRawEventHandler24m, 4mXtRemoveEven-0m 4mtHandler24m, 4mXtRemoveRawEventHandler24m, 4mXtInsertEventHandler24m, 4mXtInser-0m 4mtRawEventHandler0m 4mXtInsertEventTypeHandler24m, 4mXtRemoveEventTypeHandler24m, 4mXtRegisterDrawable24m 4mXtDispatchEventToWidget0m 4mXtAddGrab24m, 4mXtRemoveGrab24m, 4mXtGrabKey24m, 4mXtGrabKeyboard24m, 4mXtUngrabKey24m, 4mXtUngrabKeyboard24m, 4mXtGrabButton24m, 4mXtGrab-0m 4mPointer24m, 4mXtUngrabButton24m, 4mXtUngrabPointer0m 4mXtBuildEventMask0m 1m3590m 1mX Toolkit Intrinsics X11 Release 6.40m 4mXtCreateWindow24m, 4mXtDisplay24m, 4mXtScreen24m, 4mXtWindow0m 4mXtNameToWidget0m 4mXtGetSelectionValue24m, 4mXtGetSelectionValues24m, 4mXtOwnSelec-0m 4mtion24m, 4mXtDisownSelection24m, 4mXtOwnSelectionIncremental24m, 4mXtGetSelectionValueIncremental24m, 4mXtGetSelectionValuesIn-0m 4mcremental24m, 4mXtGetSelectionRequest0m 4mXtInstallAccelerators24m, 4mXtInstallAllAccelerators24m (both destination and source) 4mXtAugmentTranslations24m, 4mXtOverrideTranslations24m, 4mXtUnin-0m 4mstallTranslations24m, 4mXtCallActionProc0m 4mXtMapWidget24m, 4mXtUnmapWidget0m 4mXtRealizeWidget24m, 4mXtUnrealizeWidget0m 4mXtSetMappedWhenManaged0m 4mXtCallAcceptFocus24m, 4mXtSetKeyboardFocus24m (subtree) 4mXtResizeWindow0m 4mXtSetWMColormapWindows0m The Widget arguments to the following procedures must be of class Composite or any subclass: 4mXtCreateManagedWidget24m, 4mXtVaCreateManagedWidget0m The Widget arguments to the following procedures must be of a subclass of Shell: 4mXtPopdown24m, 4mXtCallbackPopdown24m, 4mXtPopup24m, 4mXtCallbackNone24m, 4mXtCallbackNonexclusive24m, 4mXtCallbackExclusive24m, 4mXtPopup-0m 4mSpringLoaded0m The return value of the following procedure will be of class Core or a subclass: 4mXtWindowToWidget0m 1m3600m 1mX Toolkit Intrinsics X11 Release 6.40m The return value of the following procedures will be of a subclass of Shell: 4mXtAppCreateShell24m, 4mXtVaAppCreateShell24m, 4mXtAppInitialize24m, 4mXtVaAppInitialize24m, 4mXtCreatePopupShell24m, 4mXtVaCreatePopup-0m 4mShell0m 1m3610m 1mX Toolkit Intrinsics X11 Release 6.40m 1mChapter 130m 1mEvolution of the Intrinsics0m The interfaces described by this specification have under- gone several sets of revisions in the course of adoption as an X Consortium standard specification. Having now been adopted by the Consortium as a standard part of the X Window System, it is expected that this and future revisions will retain backward compatibility in the sense that fully con- forming implementations of these specifications may be pro- duced that provide source compatibility with widgets and applications written to previous Consortium standard revi- sions. The Intrinsics do not place any special requirement on wid- get programmers to retain source or binary compatibility for their widgets as they evolve, but several conventions have been established to assist those developers who want to pro- vide such compatibility. In particular, widget programmers may wish to conform to the convention described in Section 1.6.12 when defining class extension records. 1m13.1. Determining Specification Revision Level0m Widget and application developers who wish to maintain a common source pool that will build properly with implementa- tions of the Intrinsics at different revision levels of these specifications but that take advantage of newer fea- tures added in later revisions may use the symbolic macro 4mXtSpecificationRelease24m. #define XtSpecificationRelease 6 As the symbol 4mXtSpecificationRelease24m was new to Release 4, widgets and applications desiring to build against earlier implementations should test for the presence of this symbol and assume only Release 3 interfaces if the definition is not present. 1m3620m 1mX Toolkit Intrinsics X11 Release 6.40m 1m13.2. Release 3 to Release 4 Compatibility0m At the data structure level, Release 4 retains binary com- patibility with Release 3 (the first X Consortium standard release) for all data structures except 4mWMShellPart,0m 4mTopLevelShellPart24m, and 4mTransientShellPart24m. Release 4 changed the argument type to most procedures that now take arguments of type 4mXtPointer24m and structure members that are now of type 4mXtPointer24m in order to avoid potential ANSI C conformance problems. It is expected that most implementa- tions will be binary compatible with the previous defini- tion. Two fields in 4mCoreClassPart24m were changed from 4mBoolean24m to 4mXtEnum24m to allow implementations additional freedom in speci- fying the representations of each. This change should require no source modification. 1m13.2.1. Additional Arguments0m Arguments were added to the procedure definitions for 4mXtInitProc24m, 4mXtSetValuesFunc24m, and 4mXtEventHandler24m to provide more information and to allow event handlers to abort fur- ther dispatching of the current event (caution is advised!). The added arguments to 4mXtInitProc24m and 4mXtSetValuesFunc24m make the initialize_hook and set_values_hook methods obsolete, but the hooks have been retained for those widgets that used them in Release 3. 1m13.2.2. set_values_almost Procedures0m The use of the arguments by a set_values_almost procedure was poorly described in Release 3 and was inconsistent with other conventions. The current specification for the manner in which a set_val- ues_almost procedure returns information to the Intrinsics is not compatible with the Release 3 specification, and all widget implementations should verify that any set_val- ues_almost procedures conform to the current interface. No known implementation of the Intrinsics correctly imple- mented the Release 3 interface, so it is expected that the impact of this specification change is small. 1m13.2.3. Query Geometry0m A composite widget layout routine that calls 4mXtQueryGeometry0m is now expected to store the complete new geometry in the intended structure; previously the specification said ``store the changes it intends to make''. Only by storing 1m3630m 1mX Toolkit Intrinsics X11 Release 6.40m the complete geometry does the child have any way to know what other parts of the geometry may still be flexible. Existing widgets should not be affected by this, except to take advantage of the new information. 1m13.2.4. unrealizeCallback Callback List0m In order to provide a mechanism for widgets to be notified when they become unrealized through a call to 4mXtUnreal-0m 4mizeWidget24m, the callback list name ``unrealizeCallback'' has been defined by the Intrinsics. A widget class that requires notification on unrealize may declare a callback list resource by this name. No class is required to declare this resource, but any class that did so in a prior revision may find it necessary to modify the resource name if it does not wish to use the new semantics. 1m13.2.5. Subclasses of WMShell0m The formal adoption of the 4mInter-Client24m 4mCommunication24m 4mCon-0m 4mventions24m 4mManual24m as an X Consortium standard has meant the addition of four fields to 4mWMShellPart24m and one field to 4mTopLevelShellPart24m. In deference to some widget libraries that had developed their own additional conventions to pro- vide binary compatibility, these five new fields were added at the end of the respective data structures. To provide more convenience for TransientShells, a field was added to the previously empty 4mTransientShellPart24m. On some architectures the size of the part structure will not have changed as a result of this. Any widget implementation whose class is a subclass of TopLevelShell or TransientShell must at minimum be recom- piled with the new data structure declarations. Because 4mWMShellPart24m no longer contains a contiguous 4mXSizeHints24m data structure, a subclass that expected to do a single structure assignment of an 4mXSizeHints24m structure to the 4msize_hints0m field of 4mWMShellPart24m must be revised, though the old fields remain at the same positions within 4mWMShellPart24m. 1m13.2.6. Resource Type Converters0m A new interface declaration for resource type converters was defined to provide more information to converters, to sup- port conversion cache cleanup with resource reference count- ing, and to allow additional procedures to be declared to free resources. The old interfaces remain (in the compati- bility section), and a new set of procedures was defined that work only with the new type converter interface. 1m3640m 1mX Toolkit Intrinsics X11 Release 6.40m In the now obsolete old type converter interface, converters are reminded that they must return the size of the converted value as well as its address. The example indicated this, but the description of 4mXtConverter24m was incomplete. 1m13.2.7. KeySym Case Conversion Procedure0m The specification for the 4mXtCaseProc24m function type has been changed to match the Release 3 implementation, which included necessary additional information required by the function (a pointer to the display connection), and corrects the argument type of the source KeySym parameter. No known implementation of the Intrinsics implemented the previously documented interface. 1m13.2.8. Nonwidget Objects0m Formal support for nonwidget objects is new to Release 4. A prototype implementation was latent in at least one Release 3 implementation of the Intrinsics, but the specification has changed somewhat. The most significant change is the requirement for a composite widget to declare the 4mComposite-0m 4mClassExtension24m record with the 4maccepts_objects24m field set to 4mTrue24m in order to permit a client to create a nonwidget child. The addition of this extension field ensures that composite widgets written under Release 3 will not encounter unex- pected errors if an application attempts to create a nonwid- get child. In Release 4 there is no requirement that all composite widgets implement the extra functionality required to manage windowless children, so the 4maccept_objects24m field allows a composite widget to declare that it is not prepared to do so. 1m13.3. Release 4 to Release 5 Compatibility0m At the data structure level, Release 5 retains complete binary compatibility with Release 4. The specification of the 4mObjectPart24m, 4mRectObjPart24m, 4mCorePart24m, 4mCompositePart24m, 4mShell-0m 4mPart24m, 4mWMShellPart24m, 4mTopLevelShellPart24m, and 4mApplicationShell-0m 4mPart24m instance records was made less strict to permit imple- mentations to add internal fields to these structures. Any implementation that chooses to do so would, of course, force a recompilation. The Xlib specification for 4mXrmValue24m and 4mXrmOptionDescRec24m was updated to use a new type, 4mXPointer24m, for the 4maddr24m and 4mvalue24m fields, respectively, to avoid ANSI C conformance problems. The definition of 4mXPointer24m is binary compatible with the previous implementation. 1m3650m 1mX Toolkit Intrinsics X11 Release 6.40m 1m13.3.1. baseTranslations Resource0m A new pseudo-resource, XtNbaseTranslations, was defined to permit application developers to specify translation tables in application defaults files while still giving end users the ability to augment or override individual event sequences. This change will affect only those applications that wish to take advantage of the new functionality or those widgets that may have previously defined a resource named ``baseTranslations''. Applications wishing to take advantage of the new function- ality would change their application defaults file, e.g., from app.widget.translations: 4mvalue0m to app.widget.baseTranslations: 4mvalue0m If it is important to the application to preserve complete compatibility of the defaults file between different ver- sions of the application running under Release 4 and Release 5, the full translations can be replicated in both the ``translations'' and the ``baseTranslations'' resource. 1m13.3.2. Resource File Search Path0m The current specification allows implementations greater flexibility in defining the directory structure used to hold the application class and per-user application defaults files. Previous specifications required the substitution strings to appear in the default path in a certain order, preventing sites from collecting all the files for a spe- cific application together in one directory. The Release 5 specification allows the default path to specify the substi- tution strings in any order within a single path entry. Users will need to pay close attention to the documentation for the specific implementation to know where to find these files and how to specify their own 4mXFILESEARCHPATH24m and 4mXUSERFILESEARCHPATH24m values when overriding the system defaults. 1m13.3.3. Customization Resource0m 4mXtResolvePathname24m supports a new substitution string, %C, for specifying separate application class resource files according to arbitrary user-specified categories. The 1m3660m 1mX Toolkit Intrinsics X11 Release 6.40m primary motivation for this addition was separate monochrome and color application class defaults files. The substitu- tion value is obtained by querying the current resource database for the application resource name ``customiza- tion'', class ``Customization''. Any application that pre- viously used this resource name and class will need to be aware of the possibly conflicting semantics. 1m13.3.4. Per-Screen Resource Database0m To allow a user to specify separate preferences for each screen of a display, a per-screen resource specification string has been added and multiple resource databases are created; one for each screen. This will affect any applica- tion that modified the (formerly unique) resource database associated with the display subsequent to the Intrinsics database initialization. Such applications will need to be aware of the particular screen on which each shell widget is to be created. Although the wording of the specification changed substan- tially in the description of the process by which the resource database(s) is initialized, the net effect is the same as in prior releases with the exception of the added per-screen resource specification and the new customization substitution string in 4mXtResolvePathname24m. 1m13.3.5. Internationalization of Applications0m Internationalization as defined by ANSI is a technology that allows support of an application in a single locale. In adding support for internationalization to the Intrinsics the restrictions of this model have been followed. In par- ticular, the new Intrinsics interfaces are designed not to preclude an application from using other alternatives. For this reason, no Intrinsics routine makes a call to establish the locale. However, a convenience routine to establish the locale at initialize time has been provided, in the form of a default procedure that must be explicitly installed if the application desires ANSI C locale behavior. As many objects in X, particularly resource databases, now inherit the global locale when they are created, applica- tions wishing to use the ANSI C locale model should use the new function 4mXtSetLanguageProc24m to do so. The internationalization additions also define event filters as a part of the Xlib Input Method specifications. The Intrinsics enable the use of event filters through additions to 4mXtDispatchEvent24m. Applications that may not be 1m3670m 1mX Toolkit Intrinsics X11 Release 6.40m dispatching all events through 4mXtDispatchEvent24m should be reviewed in the context of this new input method mechanism. In order to permit internationalization of error messages, the name and path of the error database file are now allowed to be implementation-dependent. No adequate standard mecha- nism has yet been suggested to allow the Intrinsics to locate the database from localization information supplied by the client. The previous specification for the syntax of the language string specified by 4mxnlLanguage24m has been dropped to avoid potential conflicts with other standards. The language string syntax is now implementation-defined. The example syntax cited is consistent with the previous specification. 1m13.3.6. Permanently Allocated Strings0m In order to permit additional memory savings, an Xlib inter- face was added to allow the resource manager to avoid copy- ing certain string constants. The Intrinsics specification was updated to explicitly require the Object 4mclass_name24m, 4mresource_name24m, 4mresource_class24m, 4mresource_type24m, 4mdefault_type0m in resource tables, Core 4mactions24m 4mstring24m field, and Con- straint 4mresource_name24m, 4mresource_class24m, 4mresource_type24m, and 4mdefault_type24m resource fields to be permanently allocated. This explicit requirement is expected to affect only appli- cations that may create and destroy classes on the fly. 1m13.3.7. Arguments to Existing Functions0m The 4margs24m argument to 4mXtAppInitialize24m, 4mXtVaAppInitialize24m, 4mXtOpenDisplay24m, 4mXtDisplayInitialize24m, and 4mXtInitialize24m were changed from 4mCardinal24m* to int* to conform to pre-existing convention and avoid otherwise annoying typecasting in ANSI C environments. 1m13.4. Release 5 to Release 6 Compatibility0m At the data structure level, Release 6 retains binary com- patibility with Release 5 for all data structures except 4mWMShellPart24m. Three resources were added to the specifica- tion. The known implementations had unused space in the data structure, therefore on some architectures and imple- mentations, the size of the part structure will not have changed as a result of this. 1m3680m 1mX Toolkit Intrinsics X11 Release 6.40m 1m13.4.1. Widget Internals0m Two new widget methods for instance allocation and dealloca- tion were added to the Object class. These new methods allow widgets to be treated as C++ objects in the C++ envi- ronment when an appropriate allocation method is specified or inherited by the widget class. The textual descriptions of the processes of widget creation and widget destruction have been edited to provide clarifi- cation to widget writers. Widgets writers may have reason to rely on the specific order of the stages of widget cre- ation and destruction; with that motivation, the specifica- tion now more exactly describes the process. As a convenience, an interface to locate a widget class extension record on a linked list, 4mXtGetClassExtension24m, has been added. A new option to allow bundled changes to the managed set of a Composite widget is introduced in the Composite class extension record. Widgets that define a change_managed pro- cedure that can accommodate additions and deletions to the managed set of children in a single invocation should set allows_change_managed_set to 1mTrue 22min the extension record. The wording of the process followed by 4mXtUnmanageChildren0m has changed slightly to better handle changes to the managed set during phase 2 destroy processing. A new exposure event compression flag, 4mXtExposeNoRegion24m, was added. Many widgets specify exposure compression, but either ignore the actual damage region passed to the core expose procedure or use only the cumulative bounding box data available in the event. Widgets with expose procedures that do not make use of exact exposure region information can indicate that the Intrinsics need not compute the region. 1m13.4.2. General Application Development0m 4mXtOpenApplication24m is a new convenience procedure to initial- ize the toolkit, create an application context, open an X display connection, and create the root of the widget instance tree. It is identical to the interface it replaces, 4mXtAppInitialize24m, in all respects except that it takes an additional argument specifying the widget class of the root shell to create. This interface is now the recom- mended one so that clients may easily become session partic- ipants. The old convenience procedures appear in the com- patibility section. 1m3690m 1mX Toolkit Intrinsics X11 Release 6.40m The toolkit initialization function 4mXtToolkitInitialize24m may be called multiple times without penalty. In order to optimize changes in geometry to a set of geome- try-managed children, a new interface, 4mXtChangeManagedSet24m, has been added. 1m13.4.3. Communication with Window and Session Managers0m The revision of the 4mInter-Client24m 4mCommunication24m 4mConventions0m 4mManual24m as an X Consortium standard has resulted in the addi- tion of three fields to the specification of 4mWMShellPart24m. These are 4murgency24m, 4mclient_leader24m, and 4mwindow_role24m. The adoption of the 4mX24m 4mSession24m 4mManagement24m 4mProtocol24m as an X Consortium standard has resulted in the addition of a new shell widget, 4mSessionShell24m, and an accompanying subclass verification interface, 4mXtIsSessionShell24m. This widget pro- vides support for communication between an application and a session manager, as well as a window manager. In order to preserve compatibility with existing subclasses of 4mApplica-0m 4mtionShell24m, the 4mApplicationShell24m was subclassed to create the new widget class. The session protocol requires a modal response to certain checkpointing operations by participat- ing applications. The 4mSessionShell24m structures the applica- tion's notification of and responses to messages from the session manager by use of various callback lists and by use of the new interfaces 4mXtSessionGetToken24m and 4mXtSessionReturn-0m 4mToken24m. There is also a new command line argument, -xtses- sionID, which facilitates the session manager in restarting applications based on the Intrinsics. The resource name and class strings defined by the Intrin- sics shell widgets in <4mX11/Shell.h24m> are now listed in Appen- dix E. The addition of a new symbol for the 4mWMShell0m 4mwait_for_wm24m resource was made to bring the external symbol and the string it represents into agreement. The actual resource name string in 4mWMShell24m has not changed. The resource representation type of the XtNwinGravity resource of the 4mWMShell24m was changed to XtRGravity in order to regis- ter a type converter so that window gravity resource values could be specified by name. 1m13.4.4. Geometry Management0m A clarification to the specification was made to indicate that geometry requests may include current values along with the requested changes. 1m3700m 1mX Toolkit Intrinsics X11 Release 6.40m 1m13.4.5. Event Management0m In Release 6, support is provided for registering selectors and event handlers for events generated by X protocol exten- sions and for dispatching those events to the appropriate widget. The new event handler registration interfaces are 4mXtInsertEventTypeHandler24m and 4mXtRemoveEventTypeHandler24m. Since the mechanism to indicate selection of extension events is specific to the extension being used, the Intrin- sics introduces 4mXtRegisterExtensionSelector24m, which allows the application to select for the events of interest. In order to change the dispatching algorithm to accommodate extension events as well as core X protocol events, the Intrinsics event dispatcher may now be replaced or enveloped by the application with 4mXtSetEventDispatcher24m. The dis- patcher may wish to call 4mXtGetKeyboardFocusWidget24m to deter- mine the widget with the current Intrinsics keyboard focus. A dispatcher, after determining the destination widget, may use 4mXtDispatchEventToWidget24m to cause the event to be dis- patched to the event handlers registered by a specific wid- get. To permit the dispatching of events for nonwidget drawables, such as pixmaps that are not associated with a widget's win- dow, 4mXtRegisterDrawable24m and 4mXtUnregisterDrawable24m have been added to the library. A related update was made to the description of 4mXtWindowToWidget24m. The library is now thread-safe, allowing one thread at a time to enter the library and protecting global data as nec- essary from concurrent use. Threaded toolkit applications are supported by the new interfaces 4mXtToolkitThreadInitial-0m 4mize24m, 4mXtAppLock24m, 4mXtAppUnlock24m, 4mXtAppSetExitFlag24m, and 4mXtAppGe-0m 4mtExitFlag24m. Widget writers may also use 4mXtProcessLock24m and 4mXtProcessUnlock24m. Safe handling of POSIX signals and other asynchronous noti- fications is now provided by use of 4mXtAppAddSignal24m, 4mXtNo-0m 4mticeSignal24m, and 4mXtRemoveSignal24m. The application can receive notification of an impending block in the Intrinsics event manager by registering inter- est through 4mXtAppAddBlockHook24m and 4mXtRemoveBlockHook24m. 4mXtLastEventProcessed24m returns the most recent event passed to 4mXtDispatchEvent24m for a specified display. 1m13.4.6. Resource Management0m Resource converters are registered by the Intrinsics for window gravity and for three new resource types associated with session participation: RestartStyle, CommandArgArray and DirectoryString. 1m3710m 1mX Toolkit Intrinsics X11 Release 6.40m The file search path syntax has been extended to make it easier to include the default search path, which controls resource database construction, by using the new substitu- tion string, %D. 1m13.4.7. Translation Management0m The default key translator now recognizes the NumLock modi- fier. If NumLock is on and the second keysym is a keypad keysym (a standard keysym named with a ``KP'' prefix or a vendor-specific keysym in the hexadecimal range 0x11000000 to 0x1100FFFF), then the default key translator will use the first keysym if Shift and/or ShiftLock is on and will use the second keysym if neither is on. Otherwise, it will ignore NumLock and apply the normal protocol semantics. 1m13.4.8. Selections0m The targets of selection requests may be parameterized, as described by the revised 4mInter-Client24m 4mCommunication24m 4mConven-0m 4mtions24m 4mManual24m. When such requests are made, 4mXtSetSelection-0m 4mParameters24m is used by the requestor to specify the target parameters and 4mXtGetSelectionParameters24m is used by the selection owner to retrieve the parameters. When a parame- terized target is specified in the context of a bundled request for multiple targets, 4mXtCreateSelectionRequest24m, 4mXtCancelSelectionRequest24m, and 4mXtSendSelectionRequest24m are used to envelop the assembly of the request. When the parameters themselves are the names of properties, the Intrinsics provides support for the economical use of prop- erty atom names; see 4mXtReservePropertyAtom24m and 4mXtRelease-0m 4mPropertyAtom24m. 1m13.4.9. External Agent Hooks0m External agent hooks were added for the benefit of applica- tions that instrument other applications for purposes of accessibility, testing, and customization. The external agent and the application communicate by a shared protocol which is transparent to the application. The hook callbacks permit the external agent to register interest in groups or classes of toolkit activity and to be notified of the type and details of the activity as it occurs. The new inter- faces related to this effort are 4mXtHooksOfDisplay24m, which returns the hook registration widget, and 4mXtGetDisplays24m, which returns a list of the X displays associated with an application context. 1m3720m 1mX Toolkit Intrinsics X11 Release 6.40m 1mAppendix A0m 1mResource File Format0m A resource file contains text representing the default resource values for an application or set of applications. The format of resource files is defined by 4mXlib24m 4m--24m 4mC24m 4mLan-0m 4mguage24m 4mX24m 4mInterface24m and is reproduced here for convenience only. The format of a resource specification is ResourceLine = Comment | IncludeFile | ResourceSpec | Comment = ``!'' {} IncludeFile = ``#'' WhiteSpace ``include'' WhiteSpace FileName WhiteSpace FileName = ResourceSpec = WhiteSpace ResourceName WhiteSpace ``:'' WhiteSpace Value ResourceName = [Binding] {Component Binding} ComponentName Binding = ``.'' | ``*'' WhiteSpace = { | } Component = ``?'' | ComponentName ComponentName = NameChar {NameChar} NameChar = ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' Value = {} Elements separated by vertical bar (|) are alternatives. Curly braces ({...}) indicate zero or more repetitions of the enclosed elements. Square brackets ([...]) indicate that the enclosed element is optional. Quotes (``...'') are used around literal characters. If the last character on a line is a backslash (\), that line is assumed to continue on the next line. To allow a Value to begin with whitespace, the two-character sequence ``\4mspace24m'' (backslash followed by space) is recog- nized and replaced by a space character, and the two-charac- ter sequence ``\4mtab24m'' (backslash followed by horizontal tab) is recognized and replaced by a horizontal tab character. To allow a Value to contain embedded newline characters, the two-character sequence ``\n'' is recognized and replaced by a newline character. To allow a Value to be broken across multiple lines in a text file, the two-character sequence ``\4mnewline24m'' (backslash followed by newline) is recognized and removed from the value. To allow a Value to contain arbitrary character codes, the 1m3730m 1mX Toolkit Intrinsics X11 Release 6.40m four-character sequence ``\4mnnn24m'', where each 4mn24m is a digit character in the range of ``0''-``7'', is recognized and replaced with a single byte that contains the octal value specified by the sequence. Finally, the two-character sequence ``\\'' is recognized and replaced with a single backslash. 1m3740m 1mX Toolkit Intrinsics X11 Release 6.40m 1mAppendix B0m 1mTranslation Table Syntax0m 1mNotation0m Syntax is specified in EBNF notation with the following con- ventions: [ a ] Means either nothing or ``a'' { a } Means zero or more occurrences of ``a'' ( a | b ) Means either ``a'' or ``b'' \\n Is the newline character All terminals are enclosed in double quotation marks (`` ''). Informal descriptions are enclosed in angle brackets (< >). 1mSyntax0m The syntax of a translation table is translationTable = [ directive ] { production } directive = ( ``#replace'' | ``#override'' | ``#augment'' ) ``\\n'' production = lhs ``:'' rhs ``\\n'' lhs = ( event | keyseq ) { ``,'' (event | keyseq) } keyseq = ``"'' keychar {keychar} ``"'' keychar = [ ``^'' | ``$'' | ``\\'' ] event = [modifier_list] ``<''event_type``>'' [ ``('' count[``+''] ``)'' ] {detail} modifier_list = ( [``!''] [``:''] {modifier} ) | ``None'' modifier = [``~''] modifier_name count = (``1'' | ``2'' | ``3'' | ``4'' | ...) modifier_name = ``@'' | event_type = detail = rhs = { name ``('' [params] ``)'' } name = namechar { namechar } namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' } params = string {``,'' string} string = quoted_string | unquoted_string quoted_string = ``"'' { | escape_char} [``\\\\'' ] ``"'' escape_char = ``\\"'' unquoted_string = {} The 4mparams24m field is parsed into a list of 4mString24m values that will be passed to the named action procedure. A 4mquoted0m 1m3750m 1mX Toolkit Intrinsics X11 Release 6.40m 4mstring24m may contain an embedded quotation mark if the quota- tion mark is preceded by a single backslash (\). The three- character sequence ``\\"'' is interpreted as ``single back- slash followed by end-of-string''. 1mModifier Names0m The modifier field is used to specify standard X keyboard and button modifier mask bits. Modifiers are legal on event types 4mKeyPress24m, 4mKeyRelease24m, 4mButtonPress24m, 4mButtonRelease24m, 4mMotionNotify24m, 4mEnterNotify24m, 4mLeaveNotify24m, and their abbrevia- tions. An error is generated when a translation table that contains modifiers for any other events is parsed. · If the modifier list has no entries and is not ``None'', it means ``don't care'' on all modifiers. · If an exclamation point (!) is specified at the begin- ning of the modifier list, it means that the listed modifiers must be in the correct state and no other modifiers can be asserted. · If any modifiers are specified and an exclamation point (!) is not specified, it means that the listed modi- fiers must be in the correct state and ``don't care'' about any other modifiers. · If a modifier is preceded by a tilde (~), it means that that modifier must not be asserted. · If ``None'' is specified, it means no modifiers can be asserted. · If a colon (:) is specified at the beginning of the modifier list, it directs the Intrinsics to apply any standard modifiers in the event to map the event key- code into a KeySym. The default standard modifiers are Shift and Lock, with the interpretation as defined in 4mX0m 4mWindow24m 4mSystem24m 4mProtocol24m, Section 5. The resulting KeySym must exactly match the specified KeySym, and the nonstandard modifiers in the event must match the modi- fier list. For example, ``:a'' is distinct from ``:A'', and ``:ShiftA'' is distinct from ``:A''. · If both an exclamation point (!) and a colon (:) are specified at the beginning of the modifier list, it means that the listed modifiers must be in the correct state and that no other modifiers except the standard modifiers can be asserted. Any standard modifiers in the event are applied as for colon (:) above. 1m3760m 1mX Toolkit Intrinsics X11 Release 6.40m · If a colon (:) is not specified, no standard modifiers are applied. Then, for example, ``A'' and ``a'' are equivalent. In key sequences, a circumflex (^) is an abbreviation for the Control modifier, a dollar sign ($) is an abbreviation for Meta, and a backslash (\) can be used to quote any char- acter, in particular a double quote ("), a circumflex (^), a dollar sign ($), and another backslash (\). Briefly: No modifiers: None detail Any modifiers: detail Only these modifiers: ! mod1 mod2 detail These modifiers and any others:mod1 mod2 detail The use of ``None'' for a modifier list is identical to the use of an exclamation point with no modifers. ----------------------------------------------------------- Modifier Abbreviation Meaning ----------------------------------------------------------- Ctrl c Control modifier bit Shift s Shift modifier bit Lock l Lock modifier bit Meta m Meta key modifier Hyper h Hyper key modifier Super su Super key modifier Alt a Alt key modifier Mod1 Mod1 modifier bit Mod2 Mod2 modifier bit Mod3 Mod3 modifier bit Mod4 Mod4 modifier bit Mod5 Mod5 modifier bit Button1 Button1 modifier bit Button2 Button2 modifier bit Button3 Button3 modifier bit Button4 Button4 modifier bit Button5 Button5 modifier bit None No modifiers Any Any modifier combination ----------------------------------------------------------- A key modifier is any modifier bit one of whose correspond- ing KeyCodes contains the corresponding left or right KeySym. For example, ``m'' or ``Meta'' means any modifier bit mapping to a KeyCode whose KeySym list contains XK_Meta_L or XK_Meta_R. Note that this interpretation is for each display, not global or even for each application context. The Control, Shift, and Lock modifier names refer explicitly to the corresponding modifier bits; there is no 1m3770m 1mX Toolkit Intrinsics X11 Release 6.40m additional interpretation of KeySyms for these modifiers. Because it is possible to associate arbitrary KeySyms with modifiers, the set of key modifiers is extensible. The ``@'' syntax means any modifier bit whose corre- sponding KeyCode contains the specified KeySym name. A modifier_list/KeySym combination in a translation matches a modifiers/KeyCode combination in an event in the following ways: 1. If a colon (:) is used, the Intrinsics call the dis- play's 4mXtKeyProc24m with the KeyCode and modifiers. To match, (4mmodifiers24m & ~4mmodifiers_return24m) must equal 4mmodi-0m 4mfier_list24m, and 4mkeysym_return24m must equal the given KeySym. 2. If (:) is not used, the Intrinsics mask off all don't- care bits from the modifiers. This value must be equal to 4mmodifier_list24m. Then, for each possible combination of don't-care modifiers in the modifier list, the Intrinsics call the display's 4mXtKeyProc24m with the Key- Code and that combination ORed with the cared-about modifier bits from the event. 4mKeysym_return24m must match the KeySym in the translation. 1mEvent Types0m The event-type field describes XEvent types. In addition to the standard Xlib symbolic event type names, the following event type synonyms are defined: ------------------------------------------------- Type Meaning ------------------------------------------------- Key 4mKeyPress0m KeyDown 4mKeyPress0m KeyUp 4mKeyRelease0m BtnDown 4mButtonPress0m BtnUp 4mButtonRelease0m Motion 4mMotionNotify0m PtrMoved 4mMotionNotify0m MouseMoved 4mMotionNotify0m Enter 4mEnterNotify0m EnterWindow 4mEnterNotify0m Leave 4mLeaveNotify0m LeaveWindow 4mLeaveNotify0m FocusIn 4mFocusIn0m FocusOut 4mFocusOut0m Keymap 4mKeymapNotify0m Expose 4mExpose0m GrExp 4mGraphicsExpose0m NoExp 4mNoExpose0m 1m3780m 1mX Toolkit Intrinsics X11 Release 6.40m ------------------------------------------------- Type Meaning ------------------------------------------------- Visible 4mVisibilityNotify0m Create 4mCreateNotify0m Destroy 4mDestroyNotify0m Unmap 4mUnmapNotify0m Map 4mMapNotify0m MapReq 4mMapRequest0m Reparent 4mReparentNotify0m Configure 4mConfigureNotify0m ConfigureReq 4mConfigureRequest0m Grav 4mGravityNotify0m ResReq 4mResizeRequest0m Circ 4mCirculateNotify0m CircReq 4mCirculateRequest0m Prop 4mPropertyNotify0m SelClr 4mSelectionClear0m SelReq 4mSelectionRequest0m Select 4mSelectionNotify0m Clrmap 4mColormapNotify0m Message 4mClientMessage0m Mapping 4mMappingNotify0m ------------------------------------------------- The supported abbreviations are: ---------------------------------------------------------- Abbreviation Event Type Including ---------------------------------------------------------- Ctrl 4mKeyPress24m with Control modifier Meta 4mKeyPress24m with Meta modifier Shift 4mKeyPress24m with Shift modifier Btn1Down 4mButtonPress24m with Button1 detail Btn1Up 4mButtonRe-24m with Button1 detail 4mlease0m Btn2Down 4mButtonPress24m with Button2 detail Btn2Up 4mButtonRe-24m with Button2 detail 4mlease0m Btn3Down 4mButtonPress24m with Button3 detail Btn3Up 4mButtonRe-24m with Button3 detail 4mlease0m Btn4Down 4mButtonPress24m with Button4 detail Btn4Up 4mButtonRe-24m with Button4 detail 4mlease0m Btn5Down 4mButtonPress24m with Button5 detail Btn5Up 4mButtonRe-24m with Button5 detail 4mlease0m BtnMotion 4mMotionNotify24m with any button modifier Btn1Motion 4mMotionNotify24m with Button1 modifier Btn2Motion 4mMotionNotify24m with Button2 modifier Btn3Motion 4mMotionNotify24m with Button3 modifier Btn4Motion 4mMotionNotify24m with Button4 modifier 1m3790m 1mX Toolkit Intrinsics X11 Release 6.40m ---------------------------------------------------------- Abbreviation Event Type Including ---------------------------------------------------------- Btn5Motion 4mMotionNotify24m with Button5 modifier ---------------------------------------------------------- The detail field is event-specific and normally corresponds to the detail field of the corresponding event as described by 4mX24m 4mWindow24m 4mSystem24m 4mProtocol24m, Section 11. The detail field is supported for the following event types: ------------------------------------------------------ Event Event Field ------------------------------------------------------ KeyPress KeySym from event 4mdetail24m (keycode) KeyRelease KeySym from event 4mdetail24m (keycode) ButtonPress button from event 4mdetail0m ButtonRelease button from event 4mdetail0m MotionNotify event 4mdetail0m EnterNotify event 4mmode0m LeaveNotify event 4mmode0m FocusIn event 4mmode0m FocusOut event 4mmode0m PropertyNotify 4matom0m SelectionClear 4mselection0m SelectionRequest 4mselection0m SelectionNotify 4mselection0m ClientMessage 4mtype0m MappingNotify 4mrequest0m ------------------------------------------------------ If the event type is 4mKeyPress24m or 4mKeyRelease24m, the detail field specifies a KeySym name in standard format which is matched against the event as described above, for example, A. For the 4mPropertyNotify24m, 4mSelectionClear24m, 4mSelectionRequest24m, 4mSelectionNotify24m, and 4mClientMessage24m events the detail field is specified as an atom name; for example, WM_PRO- TOCOLS. For the 4mMotionNotify24m, 4mEnterNotify24m, 4mLeaveNotify24m, 4mFocusIn24m, 4mFocusOut24m, and 4mMappingNotify24m events, either the sym- bolic constants as defined by 4mX24m 4mWindow24m 4mSystem24m 4mProtocol24m, Sec- tion 11, or the numeric values may be specified. If no detail field is specified, then any value in the event detail is accepted as a match. A KeySym can be specified as any of the standard KeySym names, a hexadecimal number prefixed with ``0x'' or ``0X'', an octal number prefixed with ``0'', or a decimal number. A 1m3800m 1mX Toolkit Intrinsics X11 Release 6.40m 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 <4mX11/keysymdef.h24m> with the ``XK_'' prefix removed. 1mCanonical Representation0m Every translation table has a unique, canonical text repre- sentation. This representation is passed to a widget's 4mdis-0m 4mplay_accelerator24m procedure to describe the accelerators installed on that widget. The canonical representation of a translation table is (see also ``Syntax'') translationTable = { production } production = lhs ``:'' rhs ``\\n'' lhs = event { ``,'' event } event = [modifier_list] ``<''event_type``>'' [ ``('' count[``+''] ``)'' ] {detail} modifier_list = [``!''] [``:''] {modifier} modifier = [``~''] modifier_name count = (``1'' | ``2'' | ``3'' | ``4'' | ...) modifier_name = ``@'' | event_type = detail = rhs = { name ``('' [params] ``)'' } name = namechar { namechar } namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' } params = string {``,'' string} string = quoted_string quoted_string = ``"'' { | escape_char} [``\\\\'' ] ``"'' escape_char = ``\\"'' The canonical modifier names are Ctrl Mod1 Button1 Shift Mod2 Button2 Lock Mod3 Button3 Mod4 Button4 Mod5 Button5 The canonical event types are 4mKeyPress24m 4mKeyRelease0m 4mButtonPress24m 4mButtonRelease0m 4mMotionNotify24m 4mEnterNotify0m 4mLeaveNotify24m 4mFocusIn0m 4mFocusOut24m 4mKeymapNotify0m 1m3810m 1mX Toolkit Intrinsics X11 Release 6.40m 4mExpose24m 4mGraphicsExpose,0m 4mNoExpose24m 4mVisibilityNotify0m 4mCreateNotify24m 4mDestroyNotify0m 4mUnmapNotify24m 4mMapNotify0m 4mMapRequest24m 4mReparentNotify0m 4mConfigureNotify24m 4mConfigureRequest0m 4mGravityNotify24m 4mResizeRequest0m 4mCirculateNotify24m 4mCirculateRequest0m 4mPropertyNotify24m 4mSelectionClear0m 4mSelectionRequest24m 4mSelectionNotify0m 4mColormapNotify24m 4mClientMessage0m 1mExamples0m · Always put more specific events in the table before more general ones: Shift : twas()\n\ : brillig() · For double-click on Button1 Up with Shift, use this specification: Shift(2) : and() This is equivalent to the following line with appropri- ate timers set between events: Shift,Shift,Shift,Shift : and() · For double-click on Button1 Down with Shift, use this specification: Shift(2) : the() This is equivalent to the following line with appropri- ate timers set between events: Shift,Shift,Shift : the() 1m3820m 1mX Toolkit Intrinsics X11 Release 6.40m · Mouse motion is always discarded when it occurs between events in a table where no motion event is specified: , : slithy() This is taken, even if the pointer moves a bit between the down and up events. Similarly, any motion event specified in a translation matches any number of motion events. If the motion event causes an action procedure to be invoked, the procedure is invoked after each motion event. · If an event sequence consists of a sequence of events that is also a noninitial subsequence of another trans- lation, it is not taken if it occurs in the context of the longer sequence. This occurs mostly in sequences like the following: , : toves()\n\ : did() The second translation is taken only if the button release is not preceded by a button press or if there are intervening events between the press and the release. Be particularly aware of this when using the repeat notation, above, with buttons and keys, because their expansion includes additional events; and when specifying motion events, because they are implicitly included between any two other events. In particular, pointer motion and double-click translations cannot coexist in the same translation table. · For single click on Button1 Up with Shift and Meta, use this specification: Shift Meta , Shift Meta: gyre() · For multiple clicks greater or equal to a minimum num- ber, a plus sign (+) may be appended to the final (rightmost) count in an event sequence. The actions will be invoked on the 4mcount24m-th click and each subse- quent one arriving within the multi-click time inter- val. For example: Shift (2+) : and() 1m3830m 1mX Toolkit Intrinsics X11 Release 6.40m · To indicate 4mEnterNotify24m with any modifiers, use this specification: : gimble() · To indicate 4mEnterNotify24m with no modifiers, use this specification: None : in() · To indicate 4mEnterNotify24m with Button1 Down and Button2 Up and ``don't care'' about the other modifiers, use this specification: Button1 ~Button2 : the() · To indicate 4mEnterNotify24m with Button1 down and Button2 down exclusively, use this specification: ! Button1 Button2 : wabe() You do not need to use a tilde (~) with an exclamation point (!). 1m3840m 1mX Toolkit Intrinsics X11 Release 6.40m 1mAppendix C0m 1mCompatibility Functions0m In prototype versions of the X Toolkit each widget class implemented an Xt<4mWidget24m>Create (for example, 4mXtLabelCreate24m) function, in which most of the code was identical from wid- get to widget. In the Intrinsics, a single generic 4mXtCre-0m 4mateWidget24m performs most of the common work and then calls the initialize procedure implemented for the particular wid- get class. Each Composite class also implemented the procedures Xt<4mWid-0m 4mget24m>Add and an Xt<4mWidget24m>Delete (for example, 4mXtButtonBoxAd-0m 4mdButton24m and 4mXtButtonBoxDeleteButton24m). In the Intrinsics, the Composite generic procedures 4mXtManageChildren24m and 4mXtUn-0m 4mmanageChildren24m perform error checking and screening out of certain children. Then they call the change_managed proce- dure implemented for the widget's Composite class. If the widget's parent has not yet been realized, the call to the change_managed procedure is delayed until realization time. Old-style calls can be implemented in the X Toolkit by defining one-line procedures or macros that invoke a generic routine. For example, you could define the macro 4mXtLabel-0m 4mCreate24m as: #define XtLabelCreate(4mname24m, 4mparent24m, 4margs24m, 4mnum_args24m) \ ((LabelWidget) XtCreateWidget(4mname24m, 4mlabelWidgetClass24m, 4mparent24m, 4margs24m, 4mnum_args24m)) Pop-up shells in some of the prototypes automatically per- formed an 4mXtManageChild24m on their child within their insert_child procedure. Creators of pop-up children need to call 4mXtManageChild24m themselves. 4mXtAppInitialize24m and 4mXtVaAppInitialize24m have been replaced by 4mXtOpenApplication24m and 4mXtVaOpenApplication24m. To initialize the Intrinsics internals, create an applica- tion context, open and initialize a display, and create the initial application shell instance, an application may use 4mXtAppInitialize24m or 4mXtVaAppInitialize24m. ----------- This appendix is part of the formal Intrinsics Specification. 1m3850m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtAppInitialize(4mapp_context_return24m, 4mapplication_class24m, 4moptions24m, 4mnum_options24m, 4margc_in_out24m, 4margv_in_out24m, 4mfallback_resources24m, 4margs24m, 4mnum_args24m) XtAppContext *4mapp_context_return24m; String 4mapplication_class24m; XrmOptionDescList 4moptions24m; Cardinal 4mnum_options24m; int *4margc_in_out24m; String *4margv_in_out24m; String *4mfallback_resources24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mapp_context_return0m Returns the application context, if non-NULL. 4mapplication_class0m Specifies the class name of the application. 4moptions24m Specifies the command line options table. 4mnum_options24m Specifies the number of entries in 4moptions24m. 4margc_in_out24m Specifies a pointer to the number of command line arguments. 4margv_in_out24m Specifies a pointer to the command line argu- ments. 4mfallback_resources0m Specifies resource values to be used if the application class resource file cannot be opened or read, or NULL. 4margs24m Specifies the argument list to override any other resource specifications for the created shell widget. 4mnum_args24m Specifies the number of entries in the argu- ment list. |__ The 4mXtAppInitialize24m function calls 4mXtToolkitInitialize24m fol- lowed by 4mXtCreateApplicationContext24m, then calls 4mXtOpenDis-0m 4mplay24m with 4mdisplay_string24m NULL and 4mapplication_name24m NULL, and finally calls 4mXtAppCreateShell24m with 4mapplication_name24m NULL, 4mwidget_class24m 4mapplicationShellWidgetClass24m, and the specified 4margs24m and 4mnum_args24m and returns the created shell. The modi- fied 4margc24m and 4margv24m returned by 4mXtDisplayInitialize24m are returned in 4margc_in_out24m and 4margv_in_out24m. If 4mapp_con-0m 4mtext_return24m is not NULL, the created application context is also returned. If the display specified by the command line cannot be opened, an error message is issued and 1m3860m 1mX Toolkit Intrinsics X11 Release 6.40m 4mXtAppInitialize24m terminates the application. If 4mfall-0m 4mback_resources24m is non-NULL, 4mXtAppSetFallbackResources24m is called with the value prior to calling 4mXtOpenDisplay24m. __ | Widget XtVaAppInitialize(4mapp_context_return24m, 4mapplication_class24m, 4moptions24m, 4mnum_options24m, 4margc_in_out24m, 4margv_in_out24m, 4mfallback_resources24m, ...) XtAppContext *4mapp_context_return24m; String 4mapplication_class24m; XrmOptionDescList 4moptions24m; Cardinal 4mnum_options24m; int *4margc_in_out24m; String *4margv_in_out24m; String *4mfallback_resources24m; 4mapp_context_return0m Returns the application context, if non-NULL. 4mapplication_class0m Specifies the class name of the application. 4moptions24m Specifies the command line options table. 4mnum_options24m Specifies the number of entries in 4moptions24m. 4margc_in_out24m Specifies a pointer to the number of command line arguments. 4margv_in_out24m Specifies the command line arguments array. 4mfallback_resources0m Specifies resource values to be used if the application class resource file cannot be opened, or NULL. ... Specifies the variable argument list to over- ride any other resource specifications for the created shell. |__ The 4mXtVaAppInitialize24m procedure is identical in function to 4mXtAppInitialize24m with the 4margs24m and 4mnum_args24m parameters replaced by a varargs list, as described in Section 2.5.1. As a convenience to people converting from earlier versions of the toolkit without application contexts, the following routines exist: 4mXtInitialize24m, 4mXtMainLoop24m, 4mXtNextEvent24m, 4mXtProcessEvent24m, 4mXtPeekEvent24m, 4mXtPending24m, 4mXtAddInput24m, 4mXtAd-0m 4mdTimeOut24m, 4mXtAddWorkProc24m, 4mXtCreateApplicationShell24m, 4mXtAddAc-0m 4mtions24m, 4mXtSetSelectionTimeout24m, and 4mXtGetSelectionTimeout24m. 1m3870m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtInitialize(4mshell_name24m, 4mapplication_class24m, 4moptions24m, 4mnum_options24m, 4margc24m, 4margv24m) String 4mshell_name24m; String 4mapplication_class24m; XrmOptionDescRec 4moptions24m[]; Cardinal 4mnum_options24m; int *4margc24m; String 4margv24m[]; 4mshell_name0m This parameter is ignored; therefore, you can specify NULL. 4mapplication_class0m Specifies the class name of this application. 4moptions24m Specifies how to parse the command line for any application-specific resources. The 4moptions24m argu- ment is passed as a parameter to 4mXrmParseCommand24m. 4mnum_options0m Specifies the number of entries in the options list. 4margc24m Specifies a pointer to the number of command line parameters. 4margv24m Specifies the command line parameters. |__ 4mXtInitialize24m calls 4mXtToolkitInitialize24m to initialize the toolkit internals, creates a default application context for use by the other convenience routines, calls 4mXtOpenDisplay0m with 4mdisplay_string24m NULL and 4mapplication_name24m NULL, and finally calls 4mXtAppCreateShell24m with 4mapplication_name24m NULL and returns the created shell. The semantics of calling 4mXtInitialize24m more than once are undefined. This routine has been replaced by 4mXtOpenApplication24m. __ | void XtMainLoop(void) |__ 4mXtMainLoop24m first reads the next alternate input, timer, or X event by calling 4mXtNextEvent24m. Then it dispatches this to the appropriate registered procedure by calling 4mXtDis-0m 4mpatchEvent24m. This routine has been replaced by 4mXtAppMain-0m 4mLoop24m. 1m3880m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtNextEvent(4mevent_return24m) XEvent *4mevent_return24m; 4mevent_return0m Returns the event information to the specified event structure. |__ If no input is on the X input queue for the default applica- tion context, 4mXtNextEvent24m flushes the X output buffer and waits for an event while looking at the alternate input sources and timeout values and calling any callback proce- dures triggered by them. This routine has been replaced by 4mXtAppNextEvent24m. 4mXtInitialize24m must be called before using this routine. __ | void XtProcessEvent(4mmask24m) XtInputMask 4mmask24m; 4mmask24m Specifies the type of input to process. |__ 4mXtProcessEvent24m processes one X event, timeout, or alternate input source (depending on the value of 4mmask24m), blocking if necessary. It has been replaced by 4mXtAppProcessEvent24m. 4mXtInitialize24m must be called before using this function. __ | Boolean XtPeekEvent(4mevent_return24m) XEvent *4mevent_return24m; 4mevent_return0m Returns the event information to the specified event structure. |__ If there is an event in the queue for the default applica- tion context, 4mXtPeekEvent24m fills in the event and returns a nonzero value. If no X input is on the queue, 4mXtPeekEvent0m flushes the output buffer and blocks until input is avail- able, possibly calling some timeout callbacks in the process. If the input is an event, 4mXtPeekEvent24m fills in the event and returns a nonzero value. Otherwise, the input is for an alternate input source, and 4mXtPeekEvent24m returns zero. This routine has been replaced by 4mXtAppPeekEvent24m. 4mXtIni-0m 4mtialize24m must be called before using this routine. 1m3890m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Boolean XtPending() |__ 4mXtPending24m returns a nonzero value if there are events pend- ing from the X server or alternate input sources in the default application context. If there are no events pend- ing, it flushes the output buffer and returns a zero value. It has been replaced by 4mXtAppPending24m. 4mXtInitialize24m must be called before using this routine. __ | XtInputId XtAddInput(4msource24m, 4mcondition24m, 4mproc24m, 4mclient_data24m) int 4msource24m; XtPointer 4mcondition24m; XtInputCallbackProc 4mproc24m; XtPointer 4mclient_data24m; 4msource24m Specifies the source file descriptor on a POSIX- based system or other operating-system-dependent device specification. 4mcondition24m Specifies the mask that indicates either a read, write, or exception condition or some operating- system-dependent condition. 4mproc24m Specifies the procedure called when input is available. 4mclient_data0m Specifies the parameter to be passed to 4mproc24m when input is available. |__ The 4mXtAddInput24m function registers in the default application context a new source of events, which is usually file input but can also be file output. (The word 4mfile24m should be loosely interpreted to mean any sink or source of data.) 4mXtAddInput24m also specifies the conditions under which the source can generate events. When input is pending on this source in the default application context, the callback pro- cedure is called. This routine has been replaced by 4mXtAp-0m 4mpAddInput24m. 4mXtInitialize24m must be called before using this routine. 1m3900m 1mX Toolkit Intrinsics X11 Release 6.40m __ | XtIntervalId XtAddTimeOut(4minterval24m, 4mproc24m, 4mclient_data24m) unsigned long 4minterval24m; XtTimerCallbackProc 4mproc24m; XtPointer 4mclient_data24m; 4minterval24m Specifies the time interval in milliseconds. 4mproc24m Specifies the procedure to be called when time expires. 4mclient_data0m Specifies the parameter to be passed to 4mproc24m when it is called. |__ The 4mXtAddTimeOut24m function creates a timeout in the default application context and returns an identifier for it. The timeout value is set to 4minterval24m. The callback procedure will be called after the time interval elapses, after which the timeout is removed. This routine has been replaced by 4mXtAppAddTimeOut24m. 4mXtInitialize24m must be called before using this routine. __ | XtWorkProcId XtAddWorkProc(4mproc24m, 4mclient_data24m) XtWorkProc 4mproc24m; XtPointer 4mclient_data24m; 4mproc24m Procedure to call to do the work. 4mclient_data0m Client data to pass to 4mproc24m when it is called. |__ This routine registers a work procedure in the default application context. It has been replaced by 4mXtAppAd-0m 4mdWorkProc24m. 4mXtInitialize24m must be called before using this routine. 1m3910m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtCreateApplicationShell(4mname24m, 4mwidget_class24m, 4margs24m, 4mnum_args24m) String 4mname24m; WidgetClass 4mwidget_class24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mname24m This parameter is ignored; therefore, you can specify NULL. 4mwidget_class0m Specifies the widget class pointer for the created application shell widget. This will usually be 4mtopLevelShellWidgetClass24m or a subclass thereof. 4margs24m Specifies the argument list to override any other resource specifications. 4mnum_args24m Specifies the number of entries in 4margs24m. |__ The procedure 4mXtCreateApplicationShell24m calls 4mXtAppCre-0m 4mateShell24m with 4mapplication_name24m NULL, the application class passed to 4mXtInitialize24m, and the default application context created by 4mXtInitialize24m. This routine has been replaced by 4mXtAppCreateShell24m. An old-format resource type converter procedure pointer is of type 4mXtConverter24m. __ | typedef void (*XtConverter)(XrmValue*, Cardinal*, XrmValue*, XrmValue*); XrmValue *4margs24m; Cardinal *4mnum_args24m; XrmValue *4mfrom24m; XrmValue *4mto24m; 4margs24m Specifies a list of additional 4mXrmValue24m arguments to the converter if additional context is needed to perform the conversion, or NULL. 4mnum_args24m Specifies the number of entries in 4margs24m. 4mfrom24m Specifies the value to convert. 4mto24m Specifies the descriptor to use to return the con- verted value. |__ Type converters should perform the following actions: 1m3920m 1mX Toolkit Intrinsics X11 Release 6.40m · Check to see that the number of arguments passed is correct. · Attempt the type conversion. · If successful, return the size and pointer to the data in the 4mto24m argument; otherwise, call 4mXtWarningMsg24m and return without modifying the 4mto24m argument. Most type converters just take the data described by the specified 4mfrom24m argument and return data by writing into the specified 4mto24m argument. A few need other information, which is available in the specified argument list. A type con- verter can invoke another type converter, which allows dif- fering sources that may convert into a common intermediate result to make maximum use of the type converter cache. Note that the address returned in 4mto->addr24m cannot be that of a local variable of the converter because this is not valid after the converter returns. It should be a pointer to a static variable. The procedure type 4mXtConverter24m has been replaced by 4mXtType-0m 4mConverter24m. The 4mXtStringConversionWarning24m function is a convenience rou- tine for old-format resource converters that convert from strings. __ | void XtStringConversionWarning(4msrc24m, 4mdst_type24m) String 4msrc24m, 4mdst_type24m; 4msrc24m Specifies the string that could not be converted. 4mdst_type24m Specifies the name of the type to which the string could not be converted. |__ The 4mXtStringConversionWarning24m function issues a warning mes- sage with name ``conversionError'', type ``string'', class ``XtToolkitError, and the default message string ``Cannot convert "4msrc24m" to type 4mdst_type24m''. This routine has been superseded by 4mXtDisplayStringConversionWarning24m. To register an old-format converter, use 4mXtAddConverter24m or 4mXtAppAddConverter24m. 1m3930m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtAddConverter(4mfrom_type24m, 4mto_type24m, 4mconverter24m, 4mconvert_args24m, 4mnum_args24m) String 4mfrom_type24m; String 4mto_type24m; XtConverter 4mconverter24m; XtConvertArgList 4mconvert_args24m; Cardinal 4mnum_args24m; 4mfrom_type24m Specifies the source type. 4mto_type24m Specifies the destination type. 4mconverter24m Specifies the type converter procedure. 4mconvert_args0m Specifies how to compute the additional arguments to the converter, or NULL. 4mnum_args24m Specifies the number of entries in 4mconvert_args24m. |__ 4mXtAddConverter24m is equivalent in function to 4mXtSetTypeCon-0m 4mverter24m with 4mcache_type24m equal to 4mXtCacheAll24m for old-format type converters. It has been superseded by 4mXtSetTypeCon-0m 4mverter24m. 1m3940m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtAppAddConverter(4mapp_context24m, 4mfrom_type24m, 4mto_type24m, 4mconverter24m, 4mconvert_args24m, 4mnum_args24m) XtAppContext 4mapp_context24m; String 4mfrom_type24m; String 4mto_type24m; XtConverter 4mconverter24m; XtConvertArgList 4mconvert_args24m; Cardinal 4mnum_args24m; 4mapp_context0m Specifies the application context. 4mfrom_type24m Specifies the source type. 4mto_type24m Specifies the destination type. 4mconverter24m Specifies the type converter procedure. 4mconvert_args0m Specifies how to compute the additional arguments to the converter, or NULL. 4mnum_args24m Specifies the number of entries in 4mconvert_args24m. |__ 4mXtAppAddConverter24m is equivalent in function to 4mXtAppSetType-0m 4mConverter24m with 4mcache_type24m equal to 4mXtCacheAll24m for old-format type converters. It has been superseded by 4mXtAppSetTypeCon-0m 4mverter24m. To invoke resource conversions, a client may use 4mXtConvert0m or, for old-format converters only, 4mXtDirectConvert24m. 1m3950m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtConvert(4mw24m, 4mfrom_type24m, 4mfrom24m, 4mto_type24m, 4mto_return24m) Widget 4mw24m; String 4mfrom_type24m; XrmValuePtr 4mfrom24m; String 4mto_type24m; XrmValuePtr 4mto_return24m; 4mw24m Specifies the widget to use for additional argu- ments, if any are needed. 4mfrom_type24m Specifies the source type. 4mfrom24m Specifies the value to be converted. 4mto_type24m Specifies the destination type. 4mto_return24m Returns the converted value. void XtDirectConvert(4mconverter24m, 4margs24m, 4mnum_args24m, 4mfrom24m, 4mto_return24m) XtConverter 4mconverter24m; XrmValuePtr 4margs24m; Cardinal 4mnum_args24m; XrmValuePtr 4mfrom24m; XrmValuePtr 4mto_return24m; 4mconverter24m Specifies the conversion procedure to be called. 4margs24m Specifies the argument list that contains the additional arguments needed to perform the conver- sion (often NULL). 4mnum_args24m Specifies the number of entries in 4margs24m. 4mfrom24m Specifies the value to be converted. 4mto_return24m Returns the converted value. |__ The 4mXtConvert24m function looks up the type converter regis- tered to convert 4mfrom_type24m to 4mto_type24m, computes any addi- tional arguments needed, and then calls 4mXtDirectConvert24m or 4mXtCallConverter24m. The 4mXtDirectConvert24m function looks in the converter cache to see if this conversion procedure has been called with the specified arguments. If so, it returns a descriptor for information stored in the cache; otherwise, it calls the converter and enters the result in the cache. Before calling the specified converter, 4mXtDirectConvert24m sets the return value size to zero and the return value address to NULL. To determine if the conversion was successful, the 1m3960m 1mX Toolkit Intrinsics X11 Release 6.40m client should check 4mto_return.addr24m for non-NULL. The data returned by 4mXtConvert24m must be copied immediately by the caller, as it may point to static data in the type con- verter. 4mXtConvert24m has been replaced by 4mXtConvertAndStore24m, and 4mXtDi-0m 4mrectConvert24m has been superseded by 4mXtCallConverter24m. To deallocate a shared GC when it is no longer needed, use 4mXtDestroyGC24m. __ | void XtDestroyGC(4mw24m, 4mgc24m) Widget 4mw24m; GC 4mgc24m; 4mw24m Specifies any object on the display for which the shared GC was created. Must be of class Object or any subclass thereof. 4mgc24m Specifies the shared GC to be deallocated. |__ References to sharable GCs are counted and a free request is generated to the server when the last user of a given GC destroys it. Note that some earlier versions of 4mXtDestroyGC0m had only a 4mgc24m argument. Therefore, this function is not very portable, and you are encouraged to use 4mXtReleaseGC0m instead. To declare an action table in the default application con- text and register it with the translation manager, use 4mXtAd-0m 4mdActions24m. __ | void XtAddActions(4mactions24m, 4mnum_actions24m) XtActionList 4mactions24m; Cardinal 4mnum_actions24m; 4mactions24m Specifies the action table to register. 4mnum_actions0m Specifies the number of entries in 4mactions24m. |__ If more than one action is registered with the same name, the most recently registered action is used. If duplicate actions exist in an action table, the first is used. The 1m3970m 1mX Toolkit Intrinsics X11 Release 6.40m Intrinsics register an action table for 4mXtMenuPopup24m and 4mXtMenuPopdown24m as part of X Toolkit initialization. This routine has been replaced by 4mXtAppAddActions24m. 4mXtInitialize0m must be called before using this routine. To set the Intrinsics selection timeout in the default application context, use 4mXtSetSelectionTimeout24m. __ | void XtSetSelectionTimeout(4mtimeout24m) unsigned long 4mtimeout24m; 4mtimeout24m Specifies the selection timeout in milliseconds. This routine has been replaced by 4mXtAppSetSelec-0m 4mtionTimeout24m. 4mXtInitialize24m must be called before using this routine. |__ To get the current selection timeout value in the default application context, use 4mXtGetSelectionTimeout24m. __ | unsigned long XtGetSelectionTimeout() |__ The selection timeout is the time within which the two com- municating applications must respond to one another. If one of them does not respond within this interval, the Intrin- sics abort the selection request. This routine has been replaced by 4mXtAppGetSelectionTimeout24m. 4mXtInitialize24m must be called before using this routine. To obtain the global error database (for example, to merge with an application- or widget-specific database), use 4mXtGetErrorDatabase24m. __ | XrmDatabase *XtGetErrorDatabase() |__ The 4mXtGetErrorDatabase24m function returns the address of the error database. The Intrinsics do a lazy binding of the error database and do not merge in the database file until 1m3980m 1mX Toolkit Intrinsics X11 Release 6.40m the first call to 4mXtGetErrorDatbaseText24m. This routine has been replaced by 4mXtAppGetErrorDatabase24m. An error message handler can obtain the error database text for an error or a warning by calling 4mXtGetErrorDatabaseText24m. __ | void XtGetErrorDatabaseText(4mname24m, 4mtype24m, 4mclass24m, 4mdefault24m, 4mbuffer_return24m, 4mnbytes24m) String 4mname24m, 4mtype24m, 4mclass24m; String 4mdefault24m; String 4mbuffer_return24m; int 4mnbytes24m; 4mname0m 4mtype24m Specify the name and type that are concatenated to form the resource name of the error message. 4mclass24m Specifies the resource class of the error message. 4mdefault24m Specifies the default message to use if an error database entry is not found. 4mbuffer_return0m Specifies the buffer into which the error message is to be returned. 4mnbytes24m Specifies the size of the buffer in bytes. |__ The 4mXtGetErrorDatabaseText24m returns the appropriate message from the error database associated with the default applica- tion context or returns the specified default message if one is not found in the error database. To form the full resource name and class when querying the database, the 4mname0m and 4mtype24m are concatenated with a single ``.'' between them and the 4mclass24m is concatenated with itself with a single ``.'' if it does not already contain a ``.''. This routine has been superseded by 4mXtAppGetErrorDatabaseText24m. To register a procedure to be called on fatal error condi- tions, use 4mXtSetErrorMsgHandler24m. 1m3990m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtSetErrorMsgHandler(4mmsg_handler24m) XtErrorMsgHandler 4mmsg_handler24m; 4mmsg_handler0m Specifies the new fatal error procedure, which should not return. |__ The default error handler provided by the Intrinsics con- structs a string from the error resource database and calls 4mXtError24m. Fatal error message handlers should not return. If one does, subsequent Intrinsics behavior is undefined. This routine has been superseded by 4mXtAppSetErrorMsgHandler24m. To call the high-level error handler, use 4mXtErrorMsg24m. __ | void XtErrorMsg(4mname24m, 4mtype24m, 4mclass24m, 4mdefault24m, 4mparams24m, 4mnum_params24m) String 4mname24m; String 4mtype24m; String 4mclass24m; String 4mdefault24m; String *4mparams24m; Cardinal *4mnum_params24m; 4mname24m Specifies the general kind of error. 4mtype24m Specifies the detailed name of the error. 4mclass24m Specifies the resource class. 4mdefault24m Specifies the default message to use if an error database entry is not found. 4mparams24m Specifies a pointer to a list of values to be stored in the message. 4mnum_params0m Specifies the number of entries in 4mparams24m. |__ This routine has been superseded by 4mXtAppErrorMsg24m. To register a procedure to be called on nonfatal error con- ditions, use 4mXtSetWarningMsgHandler24m. 1m4000m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtSetWarningMsgHandler(4mmsg_handler24m) XtErrorMsgHandler 4mmsg_handler24m; 4mmsg_handler0m Specifies the new nonfatal error procedure, which usually returns. |__ The default warning handler provided by the Intrinsics con- structs a string from the error resource database and calls 4mXtWarning24m. This routine has been superseded by 4mXtAppSet-0m 4mWarningMsgHandler24m. To call the installed high-level warning handler, use 4mXtWarningMsg24m. __ | void XtWarningMsg(4mname24m, 4mtype24m, 4mclass24m, 4mdefault24m, 4mparams24m, 4mnum_params24m) String 4mname24m; String 4mtype24m; String 4mclass24m; String 4mdefault24m; String *4mparams24m; Cardinal *4mnum_params24m; 4mname24m Specifies the general kind of error. 4mtype24m Specifies the detailed name of the error. 4mclass24m Specifies the resource class. 4mdefault24m Specifies the default message to use if an error database entry is not found. 4mparams24m Specifies a pointer to a list of values to be stored in the message. 4mnum_params0m Specifies the number of entries in 4mparams24m. |__ This routine has been superseded by 4mXtAppWarningMsg24m. To register a procedure to be called on fatal error condi- tions, use 4mXtSetErrorHandler24m. 1m4010m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtSetErrorHandler(4mhandler24m) XtErrorHandler 4mhandler24m; 4mhandler24m Specifies the new fatal error procedure, which should not return. |__ The default error handler provided by the Intrinsics is 4m_XtError24m. On POSIX-based systems, it prints the message to standard error and terminates the application. Fatal error message handlers should not return. If one does, subsequent X Toolkit behavior is undefined. This routine has been superseded by 4mXtAppSetErrorHandler24m. To call the installed fatal error procedure, use 4mXtError24m. __ | void XtError(4mmessage24m) String 4mmessage24m; 4mmessage24m Specifies the message to be reported. |__ Most programs should use 4mXtAppErrorMsg24m, not 4mXtError24m, to pro- vide for customization and internationalization of error messages. This routine has been superseded by 4mXtAppError24m. To register a procedure to be called on nonfatal error con- ditions, use 4mXtSetWarningHandler24m. __ | void XtSetWarningHandler(4mhandler24m) XtErrorHandler 4mhandler24m; 4mhandler24m Specifies the new nonfatal error procedure, which usually returns. |__ The default warning handler provided by the Intrinsics is 4m_XtWarning24m. On POSIX-based systems, it prints the message to standard error and returns to the caller. This routine has been superseded by 4mXtAppSetWarningHandler24m. To call the installed nonfatal error procedure, use 4mXtWarn-0m 4ming24m. 1m4020m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtWarning(4mmessage24m) String 4mmessage24m; 4mmessage24m Specifies the nonfatal error message to be reported. |__ Most programs should use 4mXtAppWarningMsg24m, not 4mXtWarning24m, to provide for customization and internationalization of warn- ing messages. This routine has been superseded by 4mXtApp-0m 4mWarning24m. 1m4030m 1mX Toolkit Intrinsics X11 Release 6.40m 1mAppendix D0m 1mIntrinsics Error Messages0m All Intrinsics errors and warnings have class ``XtToolkitEr- ror''. The following two tables summarize the common errors and warnings that can be generated by the Intrinsics. Addi- tional implementation-dependent messages are permitted. 1mError Messages0m ------------------------------------------------------------------------------------- Name Type Default Message ------------------------------------------------------------------------------------- allocError calloc Cannot perform calloc allocError malloc Cannot perform malloc allocError realloc Cannot perform realloc internalError xtMakeGeometryRequest internal error; ShellClassEx- tension is NULL invalidArgCount xtGetValues Argument count > 0 on NULL argument list in XtGetValues invalidArgCount xtSetValues Argument count > 0 on NULL argument list in XtSetValues invalidClass applicationShellInsertChild ApplicationShell does not accept RectObj children; ignored invalidClass constraintSetValue Subclass of Constraint required in CallCon- straintSetValues invalidClass xtAppCreateShell XtAppCreateShell requires non-NULL widget class invalidClass xtCreatePopupShell XtCreatePopupShell requires non-NULL widget class invalidClass xtCreateWidget XtCreateWidget requires non- NULL widget class invalidClass xtPopdown XtPopdown requires a subclass of shellWidgetClass invalidClass xtPopup XtPopup requires a subclass of shellWidgetClass invalidDimension xtCreateWindow Widget %s has zero width and/or height invalidDimension shellRealize Shell widget %s has zero width and/or height invalidDisplay xtInitialize Can't open display: %s invalidGetValues xtGetValues NULL ArgVal in XtGetValues invalidExtension shellClassPartInitialize widget class %s has invalid ShellClassExtension record 1m4040m 1mX Toolkit Intrinsics X11 Release 6.40m invalidExtension xtMakeGeometryRequest widget class %s has invalid ShellClassExtension record invalidGeometryManager xtMakeGeometryRequest XtMakeGeometryRequest - par- ent has no geometry manager invalidParameter xtAddInput invalid condition passed to XtAddInput invalidParameter xtAddInput invalid condition passed to XtAppAddInput invalidParent xtChangeManagedSet Attempt to manage a child when parent is not Composite invalidParent xtChangeManagedSet Attempt to unmanage a child when parent is not Composite invalidParent xtCreatePopupShell XtCreatePopupShell requires non-NULL parent invalidParent xtCreateWidget XtCreateWidget requires non- NULL parent invalidParent xtMakeGeometryRequest non-shell has no parent in XtMakeGeometryRequest invalidParent xtMakeGeometryRequest XtMakeGeometryRequest - par- ent not composite invalidParent xtManageChildren Attempt to manage a child when parent is not Composite invalidParent xtUnmanageChildren Attempt to unmanage a child when parent is not Composite invalidProcedure inheritanceProc Unresolved inheritance opera- tion invalidProcedure realizeProc No realize class procedure defined invalidWindow eventHandler Event with wrong window missingWidget fetchDisplayArg FetchDisplayArg called with- out a widget to reference nonWidget xtCreateWidget attempt to add non-widget child "%s" to parent "%s" which supports only widgets noPerDisplay closeDisplay Couldn't find per display information noPerDisplay getPerDisplay Couldn't find per display information noSelectionProperties freeSelectionProperty internal error: no selection property context for display noWidgetAncestor windowedAncestor Object "%s" does not have windowed ancestor nullDisplay xtRegisterExtensionSelector XtRegisterExtensionSelector requires a non-NULL display nullProc insertChild "%s" parent has NULL insert_child method r2versionMismatch widget Widget class %s must be re- compiled. R3versionMismatch widget Widget class %s must be re- compiled. R4orR5versionMismatch widget Widget class %s must be re- compiled. 1m4050m 1mX Toolkit Intrinsics X11 Release 6.40m rangeError xtRegisterExtensionSelector Attempt to register multiple selectors for one extension event type sessionManagement SmcOpenConnection Tried to connect to session manager, %s subclassMismatch xtCheckSubclass Widget class %s found when subclass of %s expected: %s ------------------------------------------------------------------------------------- 1mWarning Messages0m --------------------------------------------------------------------------- Name Type Default Message --------------------------------------------------------------------------- ambiguousParent xtChangeManagedSet Not all children have same parent ambiguousParent xtManageChildren Not all children have same parent in XtManageChildren ambiguousParent xtUnmanageChildren Not all children have same parent in XtUnmanageChildren badFormat xtGetSelectionValue Selection owner returned type INCR property with format != 32 badGeometry shellRealize Shell widget "%s" has an invalid geometry specifica- tion: "%s" badValue cvtStringToPixel Color name "%s" is not defined communicationError select Select failed; error code %s conversionError string Cannot convert string "%s" to type %s conversionError stringToVisual Cannot find Visual of class %s for display %s conversionFailed xtConvertVarToArgList Type conversion failed conversionFailed xtGetTypedArg Type conversion (%s to %s) failed for widget '%s' displayError invalidDisplay Can't find display structure grabError xtAddGrab XtAddGrab requires exclusive grab if spring_loaded is TRUE grabError xtRemoveGrab XtRemoveGrab asked to remove a widget not on the list initializationError xtInitialize Initializing Resource Lists twice insufficientSpace xtGetTypedArg Insufficient space for con- verted type '%s' in widget '%s' internalError shell Shell's window manager inter- action is broken 1m4060m 1mX Toolkit Intrinsics X11 Release 6.40m invalidAddressMode computeArgs Conversion arguments for wid- get '%s' contain an unsup- ported address mode invalidArgCount getResources argument count > 0 on NULL argument list invalidCallbackList xtAddCallback Cannot find callback list in XtAddCallback invalidCallbackList xtAddCallback Cannot find callback list in XtAddCallbacks invalidCallbackList xtCallCallback Cannot find callback list in XtCallCallbacks invalidCallbackList xtRemoveAllCallback Cannot find callback list in XtRemoveAllCallbacks invalidCallbackList xtRemoveCallback Cannot find callback list in XtRemoveCallbacks invalidChild xtChangeManagedSet Null child passed to Unman- ageChildren invalidChild xtManageChildren null child passed to Man- ageChildren invalidChild xtManageChildren null child passed to XtMan- ageChildren invalidChild xtUnmanageChildren Null child passed to XtUnman- ageChildren invalidChild xtUnmanageChildren Null child found in argument list to unmanage invalidDepth setValues Can't change widget depth invalidExtension xtCreateWidget widget "%s" class %s has invalid CompositeClassExten- sion record invalidExtension xtCreateWidget widget class %s has invalid ConstraintClassExtension record invalidGrab ungrabKeyOrButton Attempt to remove nonexistent passive grab invalidGrabKind xtPopup grab kind argument has invalid value; XtGrabNone assumed invalidParameters freeTranslations Freeing XtTranslations requires no extra arguments invalidParameters mergeTranslations MergeTM to TranslationTable needs no extra arguments invalidParameters xtMenuPopdown XtMenuPopdown called with num_params != 0 or 1 invalidParameters xtMenuPopupAction MenuPopup wants exactly one argument invalidParent xtCopyFromParent CopyFromParent must have non- NULL parent invalidPopup xtMenuPopup Can't find popup widget "%s" in XtMenuPopup invalidPopup xtMenuPopdown Can't find popup in widget "%s" in XtMenuPopdown 1m4070m 1mX Toolkit Intrinsics X11 Release 6.40m invalidPopup unsupportedOperation Pop-up menu creation is only supported on ButtonPress, KeyPress or EnterNotify events. invalidPopup unsupportedOperation Pop-up menu creation is only supported on Button, Key or EnterNotify events. invalidProcedure deleteChild null delete_child procedure for class %s in XtDestroy invalidProcedure inputHandler XtRemoveInput: Input handler not found invalidProcedure set_values_almost set_values_almost procedure shouldn't be NULL invalidResourceCount getResources resource count > 0 on NULL resource list invalidResourceName computeArgs Cannot find resource name %s as argument to conversion invalidShell xtTranslateCoords Widget has no shell ancestor invalidSizeOverride xtDependencies Representation size %d must match superclass's to over- ride %s missingCharsetList cvtStringToFontSet Missing charsets in String to FontSet conversion noActionProc xtCallActionProc No action proc named "%s" is registered for widget "%s" noColormap cvtStringToPixel Cannot allocate colormap entry for "%s" noFont cvtStringToFont Unable to load any usable ISO8859-1 font noFont cvtStringToFontSet Unable to load any usable fontset noFont cvtStringToFontStruct Unable to load any usable ISO8859-1 font notInConvertSelection xtGetSelectionRequest XtGetSelectionRequest or XtGetSelectionParameters called for widget "%s" out- side of ConvertSelection proc notRectObj xtChangeManagedSet child "%s", class %s is not a RectObj notRectObj xtManageChildren child "%s", class %s is not a RectObj nullWidget xtConvertVarToArgList XtVaTypedArg conversion needs non-NULL widget handle r3versionMismatch widget Shell Widget class %s binary compiled for R3 translationError nullTable Can't remove accelerators from NULL table translationError nullTable Tried to remove nonexistent accelerators translationError ambiguousActions Overriding earlier transla- tion manager actions. 1m4080m 1mX Toolkit Intrinsics X11 Release 6.40m translationError newActions New actions are:%s translationError nullTable table to (un)merge must not be null translationError nullTable Can't translate event through NULL table translationError oldActions Previous entry was: %s %s translationError unboundActions Actions not found: %s translationError xtTranslateInitialize Initializing Translation man- ager twice. translationParseError missingComma ... possibly due to missing ',' in event sequence. translationParseError nonLatin1 ... probably due to non- Latin1 character in quoted string translationParseError parseError translation table syntax error: %s translationParseError parseString Missing '"'. translationParseError showLine ... found while parsing '%s' typeConversionError noConverter No type converter registered for '%s' to '%s' conversion. unknownType xtConvertVarToArgList Unable to find type of resource for conversion unknownType xtGetTypedArg Unable to find type of resource for conversion versionMismatch widget Widget class %s version mis- match (recompilation needed):\n widget %d vs. intrinsics %d. wrongParameters cvtIntOrPixelToXColor Pixel to color conversion needs screen and colormap arguments wrongParameters cvtIntToBool Integer to Bool conversion needs no extra arguments wrongParameters cvtIntToBoolean Integer to Boolean conversion needs no extra arguments wrongParameters cvtIntToFloat Integer to Float conversion needs no extra arguments wrongParameters cvtIntToFont Integer to Font conversion needs no extra arguments wrongParameters cvtIntToPixel Integer to Pixel conversion needs no extra arguments wrongParameters cvtIntToPixmap Integer to Pixmap conversion needs no extra arguments wrongParameters cvtIntToShort Integer to Short conversion needs no extra arguments wrongParameters cvtIntToUnsignedChar Integer to UnsignedChar con- version needs no extra argu- ments wrongParameters cvtStringToAcceleratorTable String to AcceleratorTable conversion needs no extra arguments wrongParameters cvtStringToAtom String to Atom conversion needs Display argument 1m4090m 1mX Toolkit Intrinsics X11 Release 6.40m wrongParameters cvtStringToBool String to Bool conversion needs no extra arguments wrongParameters cvtStringToBoolean String to Boolean conversion needs no extra arguments wrongParameters cvtStringToCommandArgArray String to CommandArgArray conversion needs no extra arguments wrongParameters cvtStringToCursor String to cursor conversion needs display argument wrongParameters cvtStringToDimension String to Dimension conver- sion needs no extra arguments wrongParameters cvtStringToDirectoryString String to DirectoryString conversion needs no extra arguments wrongParameters cvtStringToDisplay String to Display conversion needs no extra arguments wrongParameters cvtStringToFile String to File conversion needs no extra arguments wrongParameters cvtStringToFloat String to Float conversion needs no extra arguments wrongParameters cvtStringToFont String to font conversion needs display argument wrongParameters cvtStringToFontSet String to FontSet conversion needs display and locale arguments wrongParameters cvtStringToFontStruct String to font conversion needs display argument wrongParameters cvtStringToGravity String to Gravity conversion needs no extra arguments wrongParameters cvtStringToInitialState String to InitialState con- version needs no extra argu- ments wrongParameters cvtStringToInt String to Integer conversion needs no extra arguments wrongParameters cvtStringToPixel String to pixel conversion needs screen and colormap arguments wrongParameters cvtStringToRestartStyle String to RestartStyle con- version needs no extra argu- ments wrongParameters cvtStringToShort String to Integer conversion needs no extra arguments wrongParameters cvtStringToTranslationTable String to TranslationTable conversion needs no extra arguments wrongParameters cvtStringToUnsignedChar String to Integer conversion needs no extra arguments wrongParameters cvtStringToVisual String to Visual conversion needs screen and depth argu- ments 1m4100m 1mX Toolkit Intrinsics X11 Release 6.40m wrongParameters cvtXColorToPixel Color to Pixel conversion needs no extra arguments wrongParameters freeCursor Free Cursor requires display argument wrongParameters freeDirectoryString Free Directory String requires no extra arguments wrongParameters freeFile Free File requires no extra arguments wrongParameters freeFont Free Font needs display argu- ment wrongParameters freeFontSet FreeFontSet needs display and locale arguments wrongParameters freeFontStruct Free FontStruct requires dis- play argument wrongParameters freePixel Freeing a pixel requires screen and colormap arguments ------------------------------------------------------------------------------ 1m4110m 1mX Toolkit Intrinsics X11 Release 6.40m 1mAppendix E0m 1mDefined Strings0m The 4mStringDefs.h24m header file contains definitions for the following resource name, class, and representation type sym- bolic constants. Resource names: ------------------------------------------------------------- Symbol Definition ------------------------------------------------------------- XtNaccelerators "accelerators" XtNallowHoriz "allowHoriz" XtNallowVert "allowVert" XtNancestorSensitive "ancestorSensitive" XtNbackground "background" XtNbackgroundPixmap "backgroundPixmap" XtNbitmap "bitmap" XtNborder "borderColor" XtNborderColor "borderColor" XtNborderPixmap "borderPixmap" XtNborderWidth "borderWidth" XtNcallback "callback" XtNchangeHook "changeHook" XtNchildren "children" XtNcolormap "colormap" XtNconfigureHook "configureHook" XtNcreateHook "createHook" XtNdepth "depth" XtNdestroyCallback "destroyCallback" XtNdestroyHook "destroyHook" XtNeditType "editType" XtNfile "file" XtNfont "font" XtNfontSet "fontSet" XtNforceBars "forceBars" XtNforeground "foreground" XtNfunction "function" XtNgeometryHook "geometryHook" XtNheight "height" XtNhighlight "highlight" XtNhSpace "hSpace" XtNindex "index" XtNinitialResourcesPersistent "initialResourcesPersistent" XtNinnerHeight "innerHeight" XtNinnerWidth "innerWidth" 1m4120m 1mX Toolkit Intrinsics X11 Release 6.40m XtNinnerWindow "innerWindow" XtNinsertPosition "insertPosition" XtNinternalHeight "internalHeight" XtNinternalWidth "internalWidth" XtNjumpProc "jumpProc" XtNjustify "justify" XtNknobHeight "knobHeight" XtNknobIndent "knobIndent" XtNknobPixel "knobPixel" XtNknobWidth "knobWidth" XtNlabel "label" XtNlength "length" XtNlowerRight "lowerRight" XtNmappedWhenManaged "mappedWhenManaged" XtNmenuEntry "menuEntry" XtNname "name" XtNnotify "notify" XtNnumChildren "numChildren" XtNnumShells "numShells" XtNorientation "orientation" XtNparameter "parameter" XtNpixmap "pixmap" XtNpopupCallback "popupCallback" XtNpopdownCallback "popdownCallback" XtNresize "resize" XtNreverseVideo "reverseVideo" XtNscreen "screen" XtNscrollProc "scrollProc" XtNscrollDCursor "scrollDCursor" XtNscrollHCursor "scrollHCursor" XtNscrollLCursor "scrollLCursor" XtNscrollRCursor "scrollRCursor" XtNscrollUCursor "scrollUCursor" XtNscrollVCursor "scrollVCursor" XtNselection "selection" XtNselectionArray "selectionArray" XtNsensitive "sensitive" XtNsession "session" XtNshells "shells" XtNshown "shown" XtNspace "space" XtNstring "string" XtNtextOptions "textOptions" XtNtextSink "textSink" XtNtextSource "textSource" XtNthickness "thickness" XtNthumb "thumb" XtNthumbProc "thumbProc" XtNtop "top" XtNtranslations "translations" XtNunrealizeCallback "unrealizeCallback" XtNupdate "update" XtNuseBottom "useBottom" 1m4130m 1mX Toolkit Intrinsics X11 Release 6.40m XtNuseRight "useRight" XtNvalue "value" XtNvSpace "vSpace" XtNwidth "width" XtNwindow "window" XtNx "x" XtNy "y" ------------------------------------------------------------- Resource classes: ------------------------------------------------------------- Symbol Definition ------------------------------------------------------------- XtCAccelerators "Accelerators" XtCBackground "Background" XtCBitmap "Bitmap" XtCBoolean "Boolean" XtCBorderColor "BorderColor" XtCBorderWidth "BorderWidth" XtCCallback "Callback" XtCColormap "Colormap" XtCColor "Color" XtCCursor "Cursor" XtCDepth "Depth" XtCEditType "EditType" XtCEventBindings "EventBindings" XtCFile "File" XtCFont "Font" XtCFontSet "FontSet" XtCForeground "Foreground" XtCFraction "Fraction" XtCFunction "Function" XtCHeight "Height" XtCHSpace "HSpace" XtCIndex "Index" XtCInitialResourcesPersistent "InitialResourcesPersistent" XtCInsertPosition "InsertPosition" XtCInterval "Interval" XtCJustify "Justify" XtCKnobIndent "KnobIndent" XtCKnobPixel "KnobPixel" XtCLabel "Label" XtCLength "Length" XtCMappedWhenManaged "MappedWhenManaged" XtCMargin "Margin" XtCMenuEntry "MenuEntry" XtCNotify "Notify" XtCOrientation "Orientation" XtCParameter "Parameter" XtCPixmap "Pixmap" XtCPosition "Position" 1m4140m 1mX Toolkit Intrinsics X11 Release 6.40m XtCReadOnly "ReadOnly" XtCResize "Resize" XtCReverseVideo "ReverseVideo" XtCScreen "Screen" XtCScrollProc "ScrollProc" XtCScrollDCursor "ScrollDCursor" XtCScrollHCursor "ScrollHCursor" XtCScrollLCursor "ScrollLCursor" XtCScrollRCursor "ScrollRCursor" XtCScrollUCursor "ScrollUCursor" XtCScrollVCursor "ScrollVCursor" XtCSelection "Selection" XtCSelectionArray "SelectionArray" XtCSensitive "Sensitive" XtCSession "Session" XtCSpace "Space" XtCString "String" XtCTextOptions "TextOptions" XtCTextPosition "TextPosition" XtCTextSink "TextSink" XtCTextSource "TextSource" XtCThickness "Thickness" XtCThumb "Thumb" XtCTranslations "Translations" XtCValue "Value" XtCVSpace "VSpace" XtCWidth "Width" XtCWindow "Window" XtCX "X" XtCY "Y" ------------------------------------------------------------- Resource representation types: ------------------------------------------------- Symbol Definition ------------------------------------------------- XtRAcceleratorTable "AcceleratorTable" XtRAtom "Atom" XtRBitmap "Bitmap" XtRBool "Bool" XtRBoolean "Boolean" XtRCallback "Callback" XtRCallProc "CallProc" XtRCardinal "Cardinal" XtRColor "Color" XtRColormap "Colormap" XtRCommandArgArray "CommandArgArray" XtRCursor "Cursor" XtRDimension "Dimension" XtRDirectoryString "DirectoryString" XtRDisplay "Display" 1m4150m 1mX Toolkit Intrinsics X11 Release 6.40m XtREditMode "EditMode" XtREnum "Enum" XtREnvironmentArray "EnvironmentArray" XtRFile "File" XtRFloat "Float" XtRFont "Font" XtRFontSet "FontSet" XtRFontStruct "FontStruct" XtRFunction "Function" XtRGeometry "Geometry" XtRGravity "Gravity" XtRImmediate "Immediate" XtRInitialState "InitialState" XtRInt "Int" XtRJustify "Justify" XtRLongBoolean XtRBool XtRObject "Object" XtROrientation "Orientation" XtRPixel "Pixel" XtRPixmap "Pixmap" XtRPointer "Pointer" XtRPosition "Position" XtRRestartStyle "RestartStyle" XtRScreen "Screen" XtRShort "Short" XtRSmcConn "SmcConn" XtRString "String" XtRStringArray "StringArray" XtRStringTable "StringTable" XtRUnsignedChar "UnsignedChar" XtRTranslationTable "TranslationTable" XtRVisual "Visual" XtRWidget "Widget" XtRWidgetClass "WidgetClass" XtRWidgetList "WidgetList" XtRWindow "Window" ------------------------------------------------- Boolean enumeration constants: ------------------------------------------------- Symbol Definition ------------------------------------------------- XtEoff "off" XtEfalse "false" XtEno "no" XtEon "on" XtEtrue "true" XtEyes "yes" ------------------------------------------------- 1m4160m 1mX Toolkit Intrinsics X11 Release 6.40m Orientation enumeration constants: ------------------------------------------------- Symbol Definition ------------------------------------------------- XtEvertical "vertical" XtEhorizontal "horizontal" ------------------------------------------------- Text edit enumeration constants: ------------------------------------------------- Symbol Definition ------------------------------------------------- XtEtextRead "read" XtEtextAppend "append" XtEtextEdit "edit" ------------------------------------------------- Color enumeration constants: --------------------------------------------------- Symbol Definition --------------------------------------------------- XtExtdefaultbackground "xtdefaultbackground" XtExtdefaultforeground "xtdefaultforeground" --------------------------------------------------- Font constant: ------------------------------------------------- Symbol Definition ------------------------------------------------- XtExtdefaultfont "xtdefaultfont" ------------------------------------------------- Hooks for External Agents constants: ----------------------------------------------------- Symbol Definition ----------------------------------------------------- XtHcreate "Xtcreate" XtHsetValues "Xtsetvalues" XtHmanageChildren "XtmanageChildren" XtHunmanageChildren "XtunmanageChildren" XtHmanageSet "XtmanageSet" XtHunmanageSet "XtunmanageSet" XtHrealizeWidget "XtrealizeWidget" XtHunrealizeWidget "XtunrealizeWidget" 1m4170m 1mX Toolkit Intrinsics X11 Release 6.40m XtHaddCallback "XtaddCallback" XtHaddCallbacks "XtaddCallbacks" XtHremoveCallback "XtremoveCallback" XtHremoveCallbacks "XtremoveCallbacks" XtHremoveAllCallbacks "XtremoveAllCallbacks" XtHaugmentTranslations "XtaugmentTranslations" XtHoverrideTranslations "XtoverrideTranslations" XtHuninstallTranslations "XtuninstallTranslations" XtHsetKeyboardFocus "XtsetKeyboardFocus" XtHsetWMColormapWindows "XtsetWMColormapWindows" XtHmapWidget "XtmapWidget" XtHunmapWidget "XtunmapWidget" XtHpopup "Xtpopup" XtHpopupSpringLoaded "XtpopupSpringLoaded" XtHpopdown "Xtpopdown" XtHconfigure "Xtconfigure" XtHpreGeometry "XtpreGeometry" XtHpostGeometry "XtpostGeometry" XtHdestroy "Xtdestroy" ----------------------------------------------------- The 4mShell.h24m header file contains definitions for the follow- ing resource name, class, and representation type symbolic constants. Resource names: ---------------------------------------------------- Symbol Definition ---------------------------------------------------- XtNallowShellResize "allowShellResize" XtNargc "argc" XtNargv "argv" XtNbaseHeight "baseHeight" XtNbaseWidth "baseWidth" XtNcancelCallback "cancelCallback" XtNclientLeader "clientLeader" XtNcloneCommand "cloneCommand" XtNconnection "connection" XtNcreatePopupChildProc "createPopupChildProc" XtNcurrentDirectory "currentDirectory" XtNdieCallback "dieCallback" XtNdiscardCommand "discardCommand" XtNenvironment "environment" XtNerrorCallback "errorCallback" XtNgeometry "geometry" XtNheightInc "heightInc" XtNiconMask "iconMask" XtNiconName "iconName" XtNiconNameEncoding "iconNameEncoding" XtNiconPixmap "iconPixmap" XtNiconWindow "iconWindow" 1m4180m 1mX Toolkit Intrinsics X11 Release 6.40m XtNiconX "iconX" XtNiconY "iconY" XtNiconic "iconic" XtNinitialState "initialState" XtNinput "input" XtNinteractCallback "interactCallback" XtNjoinSession "joinSession" XtNmaxAspectX "maxAspectX" XtNmaxAspectY "maxAspectY" XtNmaxHeight "maxHeight" XtNmaxWidth "maxWidth" XtNminAspectX "minAspectX" XtNminAspectY "minAspectY" XtNminHeight "minHeight" XtNminWidth "minWidth" XtNoverrideRedirect "overrideRedirect" XtNprogramPath "programPath" XtNresignCommand "resignCommand" XtNrestartCommand "restartCommand" XtNrestartStyle "restartStyle" XtNsaveCallback "saveCallback" XtNsaveCompleteCallback "saveCompleteCallback" XtNsaveUnder "saveUnder" XtNsessionID "sessionID" XtNshutdownCommand "shutdownCommand" XtNtitle "title" XtNtitleEncoding "titleEncoding" XtNtransient "transient" XtNtransientFor "transientFor" XtNurgency "urgency" XtNvisual "visual" XtNwaitForWm "waitforwm" XtNwaitforwm "waitforwm" XtNwidthInc "widthInc" XtNwindowGroup "windowGroup" XtNwindowRole "windowRole" XtNwinGravity "winGravity" XtNwmTimeout "wmTimeout" ---------------------------------------------------- Resource classes: ---------------------------------------------------- Symbol Definition ---------------------------------------------------- XtCAllowShellResize "allowShellResize" XtCArgc "Argc" XtCArgv "Argv" XtCBaseHeight "BaseHeight" XtCBaseWidth "BaseWidth" XtCClientLeader "ClientLeader" XtCCloneCommand "CloneCommand" 1m4190m 1mX Toolkit Intrinsics X11 Release 6.40m XtCConnection "Connection" XtCCreatePopupChildProc "CreatePopupChildProc" XtCCurrentDirectory "CurrentDirectory" XtCDiscardCommand "DiscardCommand" XtCEnvironment "Environment" XtCGeometry "Geometry" XtCHeightInc "HeightInc" XtCIconMask "IconMask" XtCIconName "IconName" XtCIconNameEncoding "IconNameEncoding" XtCIconPixmap "IconPixmap" XtCIconWindow "IconWindow" XtCIconX "IconX" XtCIconY "IconY" XtCIconic "Iconic" XtCInitialState "InitialState" XtCInput "Input" XtCJoinSession "JoinSession" XtCMaxAspectX "MaxAspectX" XtCMaxAspectY "MaxAspectY" XtCMaxHeight "MaxHeight" XtCMaxWidth "MaxWidth" XtCMinAspectX "MinAspectX" XtCMinAspectY "MinAspectY" XtCMinHeight "MinHeight" XtCMinWidth "MinWidth" XtCOverrideRedirect "OverrideRedirect" XtCProgramPath "ProgramPath" XtCResignCommand "ResignCommand" XtCRestartCommand "RestartCommand" XtCRestartStyle "RestartStyle" XtCSaveUnder "SaveUnder" XtCSessionID "SessionID" XtCShutdownCommand "ShutdownCommand" XtCTitle "Title" XtCTitleEncoding "TitleEncoding" XtCTransient "Transient" XtCTransientFor "TransientFor" XtCUrgency "Urgency" XtCVisual "Visual" XtCWaitForWm "Waitforwm" XtCWaitforwm "Waitforwm" XtCWidthInc "WidthInc" XtCWindowGroup "WindowGroup" XtCWindowRole "WindowRole" XtCWinGravity "WinGravity" XtCWmTimeout "WmTimeout" ---------------------------------------------------- Resource representation types: 1m4200m 1mX Toolkit Intrinsics X11 Release 6.40m ------------------------------------------------- Symbol Definition ------------------------------------------------- XtRAtom "Atom" ------------------------------------------------- 1m4210m 1mX Toolkit Intrinsics X11 Release 6.40m 1mAppendix F0m 1mResource Configuration Management0m Setting and changing resources in X applications can be dif- ficult for both the application programmer and the end user. 1mResource Configuration Management (RCM) 22maddresses this prob- lem by changing the 1mX Intrinsics 22mto immediately modify a resource for a specified widget and each child widget in the hierarchy. In this context, immediate means: no sourcing of a resource file is required; the application does not need to be restarted for the new resource values to take effect; and the change occurs immediately. The main difference between 1mRCM 22mand the 1mEditres 22mprotocol is that the 1mRCM 22mcustomizing hooks reside in the 1mIntrinsics 22mand thus are linked with other toolkits such as Motif and the Athena widgets. However, the 1mEditRes 22mprotocol requires the application to link with the 1mEditRes 22mroutines in the Xmu library and Xmu is not used by all applications that use Motif. Also, the 1mEditRes 22mprotocol uses ClientMessage, whereas the 1mRCM Intrinsics 22mhooks use 1mPropertyNotify 22mevents. X Properties and the 1mPropertyNotify 22mevents are used to implement 1mRCM 22mand allow on-the-fly resource customization. When the X Toolkit is initialized, two atoms are interned with the strings 4mCustom24m 4mInit24m and 4mCustom24m 4mData24m. Both 4m_XtCre-0m 4matePopupShell24m and 4m_XtAppCreateShell24m register a 1mPropertyNo-0m 1mtify 22mevent handler to handle these properties. A customization tool uses the 4mCustom24m 4mInit24m property to 4mping0m an application to get the application's toplevel window. When the application's property notify event handler is invoked, the handler deletes the property. No data is transferred in this property. A customization tool uses the 4mCustom24m 4mData24m property to tell an application that it should change a resource's value. The data in the property contains the length of the resource name (the number of bytes in the resource name), the resource name and the new value for the resource. This property's type is 1mXA_STRING 22mand the format of the string is: 1. The length of the resource name (the number of bytes in the resource name) 2. One space character 1m4220m 1mX Toolkit Intrinsics X11 Release 6.40m 3. The resource name 4. One space character 5. The resource value When setting the application's resource, the event handler calls functions to walk the application's widget tree, determining which widgets are affected by the resource string, and then applying the value with 4mXtSetValues.24m As the widget tree is recursively descended, at each level in the widget tree a resource part is tested for a match. When the entire resource string has been matched, the value is applied to the widget or widgets. Before a value is set on a widget, it is first determined if the last part of the resource is a valid resource for that widget. It must also add the resource to the application's resource database and then query it using specific resource strings that is builds from the widget information. 1m4230m 1m4240m 1mTable of Contents0m Acknowledgments . . . . . . . . . . . . . . . . . . . . ix About This Manual . . . . . . . . . . . . . . . . . . . xii 1mChapter 1 -- Intrinsics and Widgets 22m. . . . . . . . . . 1 1m1.1. Intrinsics 22m. . . . . . . . . . . . . . . . . . . . 1 1m1.2. Languages 22m. . . . . . . . . . . . . . . . . . . . . 1 1m1.3. Procedures and Macros 22m. . . . . . . . . . . . . . . 2 1m1.4. Widgets 22m. . . . . . . . . . . . . . . . . . . . . . 2 1.4.1. Core Widgets . . . . . . . . . . . . . . . . . . 3 1.4.1.1. CoreClassPart Structure . . . . . . . . . . . . 4 1.4.1.2. CorePart Structure . . . . . . . . . . . . . . 5 1m1.4.1.3. Core Resources 22m. . . . . . . . . . . . . . . . 7 1.4.1.4. CorePart Default Values . . . . . . . . . . . . 7 1.4.2. Composite Widgets . . . . . . . . . . . . . . . . 8 1.4.2.1. CompositeClassPart Structure . . . . . . . . . 8 1.4.2.2. CompositePart Structure . . . . . . . . . . . . 10 1m1.4.2.3. Composite Resources 22m. . . . . . . . . . . . . . 11 1.4.2.4. CompositePart Default Values . . . . . . . . . 11 1.4.3. Constraint Widgets . . . . . . . . . . . . . . . 11 1.4.3.1. ConstraintClassPart Structure . . . . . . . . . 12 1.4.3.2. ConstraintPart Structure . . . . . . . . . . . 13 1m1.4.3.3. Constraint Resources 22m. . . . . . . . . . . . . 14 1m1.5. Implementation-Specific Types 22m. . . . . . . . . . . 14 1m1.6. Widget Classing 22m. . . . . . . . . . . . . . . . . . 15 1m1.6.1. Widget Naming Conventions 22m. . . . . . . . . . . . 16 1.6.2. Widget Subclassing in Public .h Files . . . . . . 18 1.6.3. Widget Subclassing in Private .h Files . . . . . 19 1.6.4. Widget Subclassing in .c Files . . . . . . . . . 21 1.6.5. Widget Class and Superclass Look Up . . . . . . . 24 1.6.6. Widget Subclass Verification . . . . . . . . . . 25 1.6.7. Superclass Chaining . . . . . . . . . . . . . . . 27 1.6.8. Class Initialization: class_initialize and class_part_initialize Procedures . . . . . . . . . . . . 28 1m1.6.9. Initializing a Widget Class 22m. . . . . . . . . . . 30 1.6.10. Inheritance of Superclass Operations . . . . . . 30 1.6.11. Invocation of Superclass Operations . . . . . . 32 1.6.12. Class Extension Records . . . . . . . . . . . . 33 Chapter 2 -- Widget Instantiation . . . . . . . . . . . 36 1m2.1. Initializing the X Toolkit 22m. . . . . . . . . . . . 37 1m2.2. Establishing the Locale 22m. . . . . . . . . . . . . . 43 1m2.3. Loading the Resource Database 22m. . . . . . . . . . . 45 1m2.4. Parsing the Command Line 22m. . . . . . . . . . . . . 50 1m2.5. Creating Widgets 22m. . . . . . . . . . . . . . . . . 53 1m2.5.1. Creating and Merging Argument Lists 22m. . . . . . . 54 1m2.5.2. Creating a Widget Instance 22m. . . . . . . . . . . 57 1m2.5.3. Creating an Application Shell Instance 22m. . . . . 60 1m2.5.4. Convenience Procedure to Initialize an Appli-0m 1mcation 22m. . . . . . . . . . . . . . . . . . . . . . . . . 63 2.5.5. Widget Instance Allocation: The allocate Pro- cedure . . . . . . . . . . . . . . . . . . . . . . . . . 66 2.5.6. Widget Instance Initialization: The initial- 1miii0m ize Procedure . . . . . . . . . . . . . . . . . . . . . 69 2.5.7. Constraint Instance Initialization: The Con- straintClassPart initialize Procedure . . . . . . . . . 72 2.5.8. Nonwidget Data Initialization: The initial- ize_hook Procedure . . . . . . . . . . . . . . . . . . . 72 1m2.6. Realizing Widgets 22m. . . . . . . . . . . . . . . . . 73 2.6.1. Widget Instance Window Creation: The realize Procedure . . . . . . . . . . . . . . . . . . . . . . . 75 2.6.2. Window Creation Convenience Routine . . . . . . . 77 1m2.7. Obtaining Window Information from a Widget 22m. . . . 78 1m2.7.1. Unrealizing Widgets 22m. . . . . . . . . . . . . . . 81 1m2.8. Destroying Widgets 22m. . . . . . . . . . . . . . . . 81 1m2.8.1. Adding and Removing Destroy Callbacks 22m. . . . . . 83 2.8.2. Dynamic Data Deallocation: The destroy Proce- dure . . . . . . . . . . . . . . . . . . . . . . . . . . 84 2.8.3. Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure . . . . . . . . . 85 2.8.4. Widget Instance Deallocation: The deallocate Procedure . . . . . . . . . . . . . . . . . . . . . . . 85 1m2.9. Exiting from an Application 22m. . . . . . . . . . . . 86 Chapter 3 -- Composite Widgets and Their Children . . . 87 3.1. Addition of Children to a Composite Widget: The insert_child Procedure . . . . . . . . . . . . . . . . . 88 1m3.2. Insertion Order of Children: The insert_posi-0m 1mtion Procedure 22m. . . . . . . . . . . . . . . . . . . . . 89 3.3. Deletion of Children: The delete_child Proce- dure . . . . . . . . . . . . . . . . . . . . . . . . . . 90 1m3.4. Adding and Removing Children from the Managed0m 1mSet 22m. . . . . . . . . . . . . . . . . . . . . . . . . . 91 1m3.4.1. Managing Children 22m. . . . . . . . . . . . . . . . 91 1m3.4.2. Unmanaging Children 22m. . . . . . . . . . . . . . . 94 1m3.4.3. Bundling Changes to the Managed Set 22m. . . . . . . 95 1m3.4.4. Determining if a Widget Is Managed 22m. . . . . . . 98 1m3.5. Controlling When Widgets Get Mapped 22m. . . . . . . . 99 3.6. Constrained Composite Widgets . . . . . . . . . . . 100 Chapter 4 -- Shell Widgets . . . . . . . . . . . . . . . 103 4.1. Shell Widget Definitions . . . . . . . . . . . . . 103 4.1.1. ShellClassPart Definitions . . . . . . . . . . . 104 4.1.2. ShellPart Definition . . . . . . . . . . . . . . 109 1m4.1.3. Shell Resources 22m. . . . . . . . . . . . . . . . . 113 1m4.1.4. ShellPart Default Values 22m. . . . . . . . . . . . 116 1m4.2. Session Participation 22m. . . . . . . . . . . . . . . 122 1m4.2.1. Joining a Session 22m. . . . . . . . . . . . . . . . 123 1m4.2.2. Saving Application State 22m. . . . . . . . . . . . 124 1m4.2.2.1. Requesting Interaction 22m. . . . . . . . . . . . 126 1m4.2.2.2. Interacting with the User during a Check-0m 1mpoint 22m. . . . . . . . . . . . . . . . . . . . . . . . . 127 1m4.2.2.3. Responding to a Shutdown Cancellation 22m. . . . . 128 1m4.2.2.4. Completing a Save 22m. . . . . . . . . . . . . . . 128 1m4.2.3. Responding to a Shutdown 22m. . . . . . . . . . . . 129 1m4.2.4. Resigning from a Session 22m. . . . . . . . . . . . 129 Chapter 5 -- Pop-Up Widgets . . . . . . . . . . . . . . 130 1m5.1. Pop-Up Widget Types 22m. . . . . . . . . . . . . . . . 130 1m5.2. Creating a Pop-Up Shell 22m. . . . . . . . . . . . . . 131 1miv0m 1m5.3. Creating Pop-Up Children 22m. . . . . . . . . . . . . 133 1m5.4. Mapping a Pop-Up Widget 22m. . . . . . . . . . . . . . 134 1m5.5. Unmapping a Pop-Up Widget 22m. . . . . . . . . . . . . 138 Chapter 6 -- Geometry Management . . . . . . . . . . . . 142 6.1. Initiating Geometry Changes . . . . . . . . . . . . 142 6.2. General Geometry Manager Requests . . . . . . . . . 143 6.3. Resize Requests . . . . . . . . . . . . . . . . . . 146 6.4. Potential Geometry Changes . . . . . . . . . . . . 147 6.5. Child Geometry Management: The geometry_manager Procedure . . . . . . . . . . . . . . . . . . . . . . . 148 6.6. Widget Placement and Sizing . . . . . . . . . . . . 150 6.7. Preferred Geometry . . . . . . . . . . . . . . . . 153 6.8. Size Change Management: The resize Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Chapter 7 -- Event Management . . . . . . . . . . . . . 157 1m7.1. Adding and Deleting Additional Event Sources0m . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 1m7.1.1. Adding and Removing Input Sources 22m. . . . . . . . 158 1m7.1.2. Adding and Removing Blocking Notifications0m . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 1m7.1.3. Adding and Removing Timeouts 22m. . . . . . . . . . 161 1m7.1.4. Adding and Removing Signal Callbacks 22m. . . . . . 163 1m7.2. Constraining Events to a Cascade of Widgets 22m. . . . 165 1m7.2.1. Requesting Key and Button Grabs 22m. . . . . . . . . 167 1m7.3. Focusing Events on a Child 22m. . . . . . . . . . . . 173 1m7.3.1. Events for Drawables That Are Not a Widget's0m 1mWindow 22m. . . . . . . . . . . . . . . . . . . . . . . . . 175 1m7.4. Querying Event Sources 22m. . . . . . . . . . . . . . 177 1m7.5. Dispatching Events 22m. . . . . . . . . . . . . . . . 178 1m7.6. The Application Input Loop 22m. . . . . . . . . . . . 180 1m7.7. Setting and Checking the Sensitivity State of a0m 1mWidget 22m. . . . . . . . . . . . . . . . . . . . . . . . . 181 1m7.8. Adding Background Work Procedures 22m. . . . . . . . . 183 7.9. X Event Filters . . . . . . . . . . . . . . . . . . 184 7.9.1. Pointer Motion Compression . . . . . . . . . . . 185 7.9.2. Enter/Leave Compression . . . . . . . . . . . . . 185 7.9.3. Exposure Compression . . . . . . . . . . . . . . 185 7.10. Widget Exposure and Visibility . . . . . . . . . . 187 7.10.1. Redisplay of a Widget: The expose Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 7.10.2. Widget Visibility . . . . . . . . . . . . . . . 189 7.11. X Event Handlers . . . . . . . . . . . . . . . . . 189 7.11.1. Event Handlers That Select Events . . . . . . . 190 7.11.2. Event Handlers That Do Not Select Events . . . . 193 7.11.3. Current Event Mask . . . . . . . . . . . . . . . 196 1m7.11.4. Event Handlers for X11 Protocol Extensions0m . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 7.12. Using the Intrinsics in a Multi-Threaded Envi- ronment . . . . . . . . . . . . . . . . . . . . . . . . 204 1m7.12.1. Initializing a Multi-Threaded Intrinsics0m 1mApplication 22m. . . . . . . . . . . . . . . . . . . . . . 204 1m7.12.2. Locking X Toolkit Data Structures 22m. . . . . . . 204 1m7.12.2.1. Locking the Application Context 22m. . . . . . . 206 7.12.2.2. Locking the Process . . . . . . . . . . . . . 206 1mv0m 1m7.12.3. Event Management in a Multi-Threaded Envi-0m 1mronment 22m. . . . . . . . . . . . . . . . . . . . . . . . 207 Chapter 8 -- Callbacks . . . . . . . . . . . . . . . . . 209 1m8.1. Using Callback Procedure and Callback List Def-0m 1minitions 22m. . . . . . . . . . . . . . . . . . . . . . . . 209 1m8.2. Identifying Callback Lists 22m. . . . . . . . . . . . 210 1m8.3. Adding Callback Procedures 22m. . . . . . . . . . . . 211 1m8.4. Removing Callback Procedures 22m. . . . . . . . . . . 212 8.5. Executing Callback Procedures . . . . . . . . . . . 213 8.6. Checking the Status of a Callback List . . . . . . 215 Chapter 9 -- Resource Management . . . . . . . . . . . . 216 9.1. Resource Lists . . . . . . . . . . . . . . . . . . 216 9.2. Byte Offset Calculations . . . . . . . . . . . . . 222 9.3. Superclass-to-Subclass Chaining of Resource Lists . . . . . . . . . . . . . . . . . . . . . . . . . 223 9.4. Subresources . . . . . . . . . . . . . . . . . . . 224 1m9.5. Obtaining Application Resources 22m. . . . . . . . . . 226 9.6. Resource Conversions . . . . . . . . . . . . . . . 228 9.6.1. Predefined Resource Converters . . . . . . . . . 229 9.6.2. New Resource Converters . . . . . . . . . . . . . 232 9.6.3. Issuing Conversion Warnings . . . . . . . . . . . 237 1m9.6.4. Registering a New Resource Converter 22m. . . . . . 238 1m9.6.5. Resource Converter Invocation 22m. . . . . . . . . . 244 1m9.7. Reading and Writing Widget State 22m. . . . . . . . . 249 1m9.7.1. Obtaining Widget State 22m. . . . . . . . . . . . . 249 9.7.1.1. Widget Subpart Resource Data: The get_val- ues_hook Procedure . . . . . . . . . . . . . . . . . . . 252 9.7.1.2. Widget Subpart State . . . . . . . . . . . . . 252 1m9.7.2. Setting Widget State 22m. . . . . . . . . . . . . . 254 9.7.2.1. Widget State: The set_values Procedure . . . . 256 9.7.2.2. Widget State: The set_values_almost Proce- dure . . . . . . . . . . . . . . . . . . . . . . . . . . 259 9.7.2.3. Widget State: The ConstraintClassPart set_values Procedure . . . . . . . . . . . . . . . . . . 260 9.7.2.4. Widget Subpart State . . . . . . . . . . . . . 260 9.7.2.5. Widget Subpart Resource Data: The set_val- ues_hook Procedure . . . . . . . . . . . . . . . . . . . 262 Chapter 10 -- Translation Management . . . . . . . . . . 264 1m10.1. Action Tables 22m. . . . . . . . . . . . . . . . . . 264 1m10.1.1. Action Table Registration 22m. . . . . . . . . . . 266 1m10.1.2. Action Names to Procedure Translations 22m. . . . . 267 1m10.1.3. Action Hook Registration 22m. . . . . . . . . . . . 267 1m10.2. Translation Tables 22m. . . . . . . . . . . . . . . . 269 1m10.2.1. Event Sequences 22m. . . . . . . . . . . . . . . . 270 1m10.2.2. Action Sequences 22m. . . . . . . . . . . . . . . . 271 1m10.2.3. Multi-Click Time 22m. . . . . . . . . . . . . . . . 271 1m10.3. Translation Table Management 22m. . . . . . . . . . . 272 1m10.4. Using Accelerators 22m. . . . . . . . . . . . . . . . 275 10.5. KeyCode-to-KeySym Conversions . . . . . . . . . . 278 1m10.6. Obtaining a KeySym in an Action Procedure 22m. . . . 283 10.7. KeySym-to-KeyCode Conversions . . . . . . . . . . 284 1m10.8. Registering Button and Key Grabs for Actions0m . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 1m10.9. Invoking Actions Directly 22m. . . . . . . . . . . . 287 1mvi0m 10.10. Obtaining a Widget's Action List . . . . . . . . 288 Chapter 11 -- Utility Functions . . . . . . . . . . . . 289 1m11.1. Determining the Number of Elements in an Array0m . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 1m11.2. Translating Strings to Widget Instances 22m. . . . . 290 1m11.3. Managing Memory Usage 22m. . . . . . . . . . . . . . 291 1m11.4. Sharing Graphics Contexts 22m. . . . . . . . . . . . 294 11.5. Managing Selections . . . . . . . . . . . . . . . 297 1m11.5.1. Setting and Getting the Selection Timeout0m 1mValue 22m. . . . . . . . . . . . . . . . . . . . . . . . . 297 11.5.2. Using Atomic Transfers . . . . . . . . . . . . . 298 11.5.2.1. Atomic Transfer Procedures . . . . . . . . . . 298 11.5.2.2. Getting the Selection Value . . . . . . . . . 302 11.5.2.3. Setting the Selection Owner . . . . . . . . . 304 11.5.3. Using Incremental Transfers . . . . . . . . . . 306 11.5.3.1. Incremental Transfer Procedures . . . . . . . 307 11.5.3.2. Getting the Selection Value Incrementally . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 11.5.3.3. Setting the Selection Owner for Incremen- tal Transfers . . . . . . . . . . . . . . . . . . . . . 314 11.5.4. Setting and Retrieving Selection Target Parameters . . . . . . . . . . . . . . . . . . . . . . . 316 11.5.5. Generating MULTIPLE Requests . . . . . . . . . . 319 11.5.6. Auxiliary Selection Properties . . . . . . . . . 320 11.5.7. Retrieving the Most Recent Timestamp . . . . . . 321 11.5.8. Retrieving the Most Recent Event . . . . . . . . 322 11.6. Merging Exposure Events into a Region . . . . . . 322 1m11.7. Translating Widget Coordinates 22m. . . . . . . . . . 323 1m11.8. Translating a Window to a Widget 22m. . . . . . . . . 324 1m11.9. Handling Errors 22m. . . . . . . . . . . . . . . . . 324 1m11.10. Setting WM_COLORMAP_WINDOWS 22m. . . . . . . . . . . 332 1m11.11. Finding File Names 22m. . . . . . . . . . . . . . . 333 1m11.12. Hooks for External Agents 22m. . . . . . . . . . . . 338 1m11.12.1. Hook Object Resources 22m. . . . . . . . . . . . . 339 1m11.12.2. Querying Open Displays 22m. . . . . . . . . . . . 346 Chapter 12 -- Nonwidget Objects . . . . . . . . . . . . 347 12.1. Data Structures . . . . . . . . . . . . . . . . . 347 1m12.2. Object Objects 22m. . . . . . . . . . . . . . . . . . 347 12.2.1. ObjectClassPart Structure . . . . . . . . . . . 347 12.2.2. ObjectPart Structure . . . . . . . . . . . . . . 350 1m12.2.3. Object Resources 22m. . . . . . . . . . . . . . . . 351 1m12.2.4. ObjectPart Default Values 22m. . . . . . . . . . . 351 12.2.5. Object Arguments to Intrinsics Routines . . . . 351 1m12.2.6. Use of Objects 22m. . . . . . . . . . . . . . . . . 352 1m12.3. Rectangle Objects 22m. . . . . . . . . . . . . . . . 353 12.3.1. RectObjClassPart Structure . . . . . . . . . . . 353 12.3.2. RectObjPart Structure . . . . . . . . . . . . . 355 1m12.3.3. RectObj Resources 22m. . . . . . . . . . . . . . . 356 1m12.3.4. RectObjPart Default Values 22m. . . . . . . . . . . 356 1m12.3.5. Widget Arguments to Intrinsics Routines 22m. . . . 356 12.3.6. Use of Rectangle Objects . . . . . . . . . . . . 357 12.4. Undeclared Class . . . . . . . . . . . . . . . . . 359 12.5. Widget Arguments to Intrinsics Routines . . . . . 359 Chapter 13 -- Evolution of the Intrinsics . . . . . . . 362 1mvii0m 1m13.1. Determining Specification Revision Level 22m. . . . . 362 1m13.2. Release 3 to Release 4 Compatibility 22m. . . . . . . 363 13.2.1. Additional Arguments . . . . . . . . . . . . . . 363 13.2.2. set_values_almost Procedures . . . . . . . . . . 363 13.2.3. Query Geometry . . . . . . . . . . . . . . . . . 363 13.2.4. unrealizeCallback Callback List . . . . . . . . 364 13.2.5. Subclasses of WMShell . . . . . . . . . . . . . 364 13.2.6. Resource Type Converters . . . . . . . . . . . . 364 13.2.7. KeySym Case Conversion Procedure . . . . . . . . 365 13.2.8. Nonwidget Objects . . . . . . . . . . . . . . . 365 1m13.3. Release 4 to Release 5 Compatibility 22m. . . . . . . 365 1m13.3.1. baseTranslations Resource 22m. . . . . . . . . . . 366 1m13.3.2. Resource File Search Path 22m. . . . . . . . . . . 366 1m13.3.3. Customization Resource 22m. . . . . . . . . . . . . 366 1m13.3.4. Per-Screen Resource Database 22m. . . . . . . . . . 367 1m13.3.5. Internationalization of Applications 22m. . . . . . 367 13.3.6. Permanently Allocated Strings . . . . . . . . . 368 1m13.3.7. Arguments to Existing Functions 22m. . . . . . . . 368 1m13.4. Release 5 to Release 6 Compatibility 22m. . . . . . . 368 13.4.1. Widget Internals . . . . . . . . . . . . . . . . 369 13.4.2. General Application Development . . . . . . . . 369 13.4.3. Communication with Window and Session Man- agers . . . . . . . . . . . . . . . . . . . . . . . . . 370 13.4.4. Geometry Management . . . . . . . . . . . . . . 370 13.4.5. Event Management . . . . . . . . . . . . . . . . 371 13.4.6. Resource Management . . . . . . . . . . . . . . 371 13.4.7. Translation Management . . . . . . . . . . . . . 372 13.4.8. Selections . . . . . . . . . . . . . . . . . . . 372 13.4.9. External Agent Hooks . . . . . . . . . . . . . . 372 1mAppendix A -- Resource File Format 22m. . . . . . . . . . . 373 1mAppendix B -- Translation Table Syntax 22m. . . . . . . . . 375 1mAppendix C -- Compatibility Functions 22m. . . . . . . . . 385 1mAppendix D -- Intrinsics Error Messages 22m. . . . . . . . 404 1mAppendix E -- Defined Strings 22m. . . . . . . . . . . . . 412 1mAppendix F -- Resource Configuration Management 22m. . . . 422 Index . . . . . . . . . . . . . . . . . . . . . . . . . 425 1mviii0m