diff options
Diffstat (limited to 'specs')
| -rw-r--r-- | specs/CH01 | 2471 | ||||
| -rw-r--r-- | specs/CH02 | 3165 | ||||
| -rw-r--r-- | specs/CH03 | 1031 | ||||
| -rw-r--r-- | specs/CH04 | 1998 | ||||
| -rw-r--r-- | specs/CH05 | 783 | ||||
| -rw-r--r-- | specs/CH06 | 1110 | ||||
| -rw-r--r-- | specs/CH07 | 3555 | ||||
| -rw-r--r-- | specs/CH08 | 452 | ||||
| -rw-r--r-- | specs/CH09 | 3211 | ||||
| -rw-r--r-- | specs/CH10 | 1521 | ||||
| -rw-r--r-- | specs/CH11 | 3566 | ||||
| -rw-r--r-- | specs/CH12 | 1067 | ||||
| -rw-r--r-- | specs/CH13 | 805 | ||||
| -rw-r--r-- | specs/Makefile.am | 24 | ||||
| -rw-r--r-- | specs/Xtk.intr.front | 334 | ||||
| -rw-r--r-- | specs/appA | 107 | ||||
| -rw-r--r-- | specs/appB | 783 | ||||
| -rw-r--r-- | specs/appC | 1204 | ||||
| -rw-r--r-- | specs/appD | 602 | ||||
| -rw-r--r-- | specs/appE | 606 | ||||
| -rw-r--r-- | specs/appF | 125 | ||||
| -rw-r--r-- | specs/intr.idxmac.t | 3 | ||||
| -rw-r--r-- | specs/postproc | 19 | ||||
| -rw-r--r-- | specs/strings.mit | 17 |
24 files changed, 28559 insertions, 0 deletions
diff --git a/specs/CH01 b/specs/CH01 new file mode 100644 index 0000000..78f128b --- /dev/null +++ b/specs/CH01 @@ -0,0 +1,2471 @@ +.\" $Xorg: CH01,v 1.3 2000/08/17 19:42:42 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 1\fP\s-1 + +\s+1\fBIntrinsics and Widgets\fP\s-1 +.sp 2 +.if \n(GS .nr nh*hl 1 +.nr H1 1 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +\fBChapter 1 \(em Intrinsics and Widgets\fP +.XE +The \*(xI are a programming library tailored to the special requirements +of user interface construction within a network window system, +specifically the X Window System. +The \*(xI and a widget set make up an \*(tk. + +.NH 2 +Intrinsics +.XS +\fB\*(SN Intrinsics\fP +.XE +.LP +The \*(xI 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 policy or +style. +.LP +The Intrinsics use object-oriented programming techniques to supply a +consistent architecture for constructing and composing 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 (subclassing) or by writing +entirely new widgets following the established conventions. +.LP +When the \*(xI were first conceived, the root of the object +hierarchy was a widget class named +Core. +.IN "Core" +In Release 4 of the +\*(xI, 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. +.IN "Object" +The remainder of this +specification refers uniformly to \fIwidgets\fP and \fICore\fP +as if they were the +base class for all \*(xI 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 \fIwidget\fP +actually means ``widget'' or ``object.'' + +.NH 2 +Languages +.XS +\fB\*(SN Languages\fP +.XE +.LP +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 +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 programming 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 \fIclient\fP refers to +any module, widget, or application that calls an Intrinsics procedure. +.LP +Applications that use the \*(xI mechanisms +must include the header files +.Pn < X11/Intrinsic.h > +and +.Pn < X11/StringDefs.h >, +or their equivalent, +and they may also include +.Pn < X11/Xatoms.h > +and +.Pn < X11/Shell.h >. +In addition, widget implementations should include +.Pn < X11/IntrinsicP.h > +instead of +.Pn < X11/Intrinsic.h >. +.LP +The applications must also include the additional header files for +each widget class that they are to use (for example, +.Pn < X11/Xaw/Label.h > +or +.Pn < X11/Xaw/Scrollbar.h >). +On a POSIX-based system, +the \*(xI object library file is named +.PN libXt.a +and is usually referenced as \-lXt when linking the application. + +.NH 2 +Procedures and Macros +.LP +.XS +\fB\*(SN Procedures and Macros\fP +.XE +All functions defined in this specification except those specified below +may be implemented as C macros with arguments. C applications may use +``#undef'' to remove a macro definition and ensure that the actual function +is referenced. 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 protected by parentheses, so that +arbitrary expressions may be used as arguments. +.LP +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: +.PN XtCheckSubclass , +.PN XtNew , +.PN XtNumber , +.PN XtOffsetOf , +.PN XtOffset , +and +.PN XtSetArg . + +.NH 2 +Widgets +.LP +.XS +\fB\*(SN Widgets\fP +.XE +.LP +The fundamental abstraction and data type of the \*(tk is the widget, +which is a combination of an X window and its associated +input and display semantics +and which is dynamically allocated and contains state information. +Some 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. +.LP +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. +.LP +The distribution of the declarations and code for a new widget 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. +.LP +A widget instance is composed of two parts: +.IP \(bu 5 +A data structure which contains instance-specific values. +.IP \(bu 5 +A class structure which contains information that is applicable to +all widgets of that class. +.LP +Much of the input/output of a widget (for example, fonts, colors, sizes, +or border widths) is customizable by users. +.LP +This chapter discusses the base widget classes, +Core, Composite, and Constraint, and +ends with a discussion of widget classing. + +.NH 3 +Core Widgets +.XS +\*(SN Core Widgets +.XE +.LP +.IN "Core" "" "@DEF@" +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 +.PN CoreClassPart +and +.PN CorePart +structures. + +.NH 4 +CoreClassPart Structure +.XS +\*(SN CoreClassPart Structure +.XE +.LP +All widget classes contain the fields defined in the +.PN CoreClassPart +structure. +.LP +.IN "CoreClassPart" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3.5i +.ta .5i 3.5i +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; +.De +.LP +.eM +All widget classes have the Core class fields as their first component. +The prototypical +.PN WidgetClass +and +.PN CoreWidgetClass +are defined with only this set of fields. +.LP +.IN "Core" +.IN "WidgetClass" "" "@DEF@" +.IN "CoreWidgetClass" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + CoreClassPart core_class; +} WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass; +.De +.LP +.eM +Various routines can cast widget class pointers, as needed, +to specific widget class types. +.LP +The single occurrences of the class record and pointer for +creating instances of Core are +.LP +In +.PN IntrinsicP.h : +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +extern WidgetClassRec widgetClassRec; +#define coreClassRec widgetClassRec +.De +.LP +.eM +In +.PN Intrinsic.h : +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +extern WidgetClass widgetClass, coreWidgetClass; +.De +.LP +.eM +The opaque types +.PN Widget +and +.PN WidgetClass +and the opaque variable +.PN widgetClass +are defined for generic actions on widgets. +In order to make these types opaque and ensure that the compiler +does not allow applications to access private data, the \*(xI use +incomplete structure definitions in +.PN Intrinsic.h : +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass; +.De +.eM + +.NH 4 +CorePart Structure +.XS +\*(SN CorePart Structure +.XE +.LP +All widget instances contain the fields defined in the +.PN CorePart +structure. +.LP +.IN "CorePart" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +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; +.De +.LP +.eM +All widget instances have the Core fields as their first component. +The prototypical type +.PN Widget +is defined with only this set of fields. +.LP +.IN "Widget" "" "@DEF@" +.IN "CoreWidget" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + CorePart core; +} WidgetRec, *Widget, CoreRec, *CoreWidget; +.De +.LP +.eM +Various routines can cast widget pointers, as needed, +to specific widget types. +.LP +In order to make these types opaque and ensure that the compiler +does not allow applications to access private data, the \*(xI use +incomplete structure definitions in +.PN Intrinsic.h . +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _WidgetRec *Widget, *CoreWidget; +.De +.eM + +.NH 4 +Core Resources +.LP +.XS +\fB\*(SN Core Resources\fP +.XE +.LP +.IN "CoreWidget" "Resources" +The resource names, classes, and representation types specified in the +.PN coreClassRec +resource list are +.LP +.TS +lw(1.5i) lw(1.5i) lw(2.5i) . +_ +.sp 6p +Name Class Representation +.sp 6p +_ +.sp 6p +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 +.sp 6p +_ +.TE +.LP +Additional resources are defined for all widgets via the +.PN objectClassRec +and +.PN rectObjClassRec +resource lists; see Sections 12.2 and 12.3 for details. + +.NH 4 +CorePart Default Values +.XS +\*(SN CorePart Default Values +.XE +.LP +The default values for the Core fields, which are filled in by the \*(xI, +from the resource lists, and by the initialize procedures, are +.LP +.TS +lw(1.5i) lw(4.25i) . +_ +.sp 6p +Field Default Value +.sp 6p +_ +.sp 6p +self Address of the widget structure (may not be changed). +T{ +widget_class +T} T{ +\fIwidget_class\fP argument to +.PN XtCreateWidget +(may not be changed). +T} +T{ +parent +T} T{ +\fIparent\fP argument to +.PN XtCreateWidget +(may not be changed). +T} +being_destroyed Parent's \fIbeing_destroyed\fP value. +destroy_callbacks NULL +constraints NULL +x 0 +y 0 +width 0 +height 0 +border_width 1 +T{ +managed +T} T{ +.PN False +T} +T{ +sensitive +T} T{ +.PN True +T} +ancestor_sensitive T{ +logical AND of parent's \fIsensitive\fP and +\fIancestor_sensitive\fP values. +T} +accelerators NULL +T{ +border_pixel +T} T{ +.PN XtDefaultForeground +T} +border_pixmap T{ +.PN XtUnspecifiedPixmap +T} +popup_list NULL +num_popups 0 +T{ +name +T} T{ +\fIname\fP argument to +.PN XtCreateWidget +(may not be changed). +T} +T{ +screen +T} T{ +Parent's \fIscreen\fP; top-level widget gets screen from display specifier +.br +(may not be changed). +T} +colormap Parent's \fIcolormap\fP value. +window NULL +depth Parent's \fIdepth\fP; top-level widget gets root window depth. +T{ +background_pixel +T} T{ +.PN XtDefaultBackground +T} +background_pixmap T{ +.PN XtUnspecifiedPixmap +T} +T{ +visible +T} T{ +.PN True +T} +T{ +mapped_when_managed +T} T{ +.PN True +T} +.sp 6p +_ +.TE +.LP +.IN XtUnspecifiedPixmap "" "@DEF@" +.PN XtUnspecifiedPixmap +is a symbolic constant guaranteed to be unequal to +any valid Pixmap id, +.PN None , +and +.PN ParentRelative . + +.NH 3 +Composite Widgets +.XS +\*(SN Composite Widgets +.XE +.LP +.IN "Composite" "" "@DEF@" +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 +.PN CompositeClassPart +and +.PN CompositePart +structures. + +.NH 4 +CompositeClassPart Structure +.XS +\*(SN CompositeClassPart Structure +.XE +.LP +In addition to the +Core +class fields, +widgets of the Composite class have the following class fields. +.LP +.IN "CompositeClassPart" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3.5i +.ta .5i 3.5i +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; +.De +.LP +.eM +The extension record defined for +.PN CompositeClassPart +with \fIrecord_type\fP +equal to +.PN \s-1NULLQUARK\s+1 +is +.PN CompositeClassExtensionRec . +.LP +.IN "CompositeClassExtensionRec" "" "@DEF@" +.IN "CompositeClassExtension" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3.5i +.ta .5i 3.5i +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; +.De +.LP +.eM +Composite +classes have the Composite class fields immediately following the +Core class fields. +.LP +.IN "CompositeWidgetClass" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + CoreClassPart core_class; + CompositeClassPart composite_class; +} CompositeClassRec, *CompositeWidgetClass; +.De +.LP +.eM +The single occurrences of the class record and pointer for creating +instances of Composite are +.LP +In +.PN IntrinsicP.h : +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +extern CompositeClassRec compositeClassRec; +.De +.LP +.eM +In +.PN Intrinsic.h : +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +extern WidgetClass compositeWidgetClass; +.De +.LP +.eM +The opaque types +.PN CompositeWidget +and +.PN CompositeWidgetClass +and the opaque variable +.PN compositeWidgetClass +are defined for generic operations on widgets whose class +is Composite or a subclass of Composite. +The symbolic constant for the +.PN CompositeClassExtension +version identifier is +.PN XtCompositeExtensionVersion +(see Section 1.6.12). +.PN Intrinsic.h +uses an incomplete structure +definition to ensure that the compiler catches attempts to access +private data. +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _CompositeClassRec *CompositeWidgetClass; +.De +.eM + +.NH 4 +CompositePart Structure +.XS +\*(SN CompositePart Structure +.XE +.LP +In addition to the +Core instance +fields, +widgets of the Composite class have the following +instance fields defined in the +.PN CompositePart +structure. +.LP +.IN "CompositePart" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +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; +.De +.LP +.eM +Composite +widgets have the Composite instance fields immediately following the Core +instance fields. +.LP +.IN "CompositeWidget" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + CorePart core; + CompositePart composite; +} CompositeRec, *CompositeWidget; +.De +.LP +.eM +.PN Intrinsic.h +uses an incomplete structure definition to ensure that the +compiler catches attempts to access private data. +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _CompositeRec *CompositeWidget; +.De +.eM + +.NH 4 +Composite Resources +.XS +\fB\*(SN Composite Resources\fP +.XE +.LP +.IN "CompositeWidget" "Resources" +The resource names, classes, and representation types +that are specified in +the +.PN compositeClassRec +resource list are +.LP +.TS +lw(1.5i) lw(1.5i) lw(2i) . +_ +.sp 6p +Name Class Representation +.sp 6p +_ +.sp 6p +XtNchildren XtCReadOnly XtRWidgetList +XtNinsertPosition XtCInsertPosition XtRFunction +XtNnumChildren XtCReadOnly XtRCardinal +.sp 6p +_ +.TE + +.NH 4 +CompositePart Default Values +.XS +\*(SN CompositePart Default Values +.XE +.LP +The default values for the Composite fields, +which are filled in from the +Composite +resource list and by the +Composite +initialize procedure, are +.LP +.TS +l l . +_ +.sp 6p +Field Default Value +.sp 6p +_ +.sp 6p +children NULL +num_children 0 +num_slots 0 +insert_position Internal function to insert at end +.sp 6p +_ +.TE +.LP +The \fIchildren\fP, \fInum_children\fP, +and \fIinsert_position\fP fields are declared +as resources; +.IN XtNinsertPosition +XtNinsertPosition +is a settable resource, +.IN XtNchildren +XtNchildren +and +.IN XtNnumChildren +XtNnumChildren +may be read by any client but should only be modified by the composite +widget class procedures. + +.NH 3 +Constraint Widgets +.XS +\*(SN Constraint Widgets +.XE +.LP +.IN "Constraint" "" "@DEF@" +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 +.PN ConstraintClassPart +and +.PN ConstraintPart +structures. + +.NH 4 +ConstraintClassPart Structure +.XS +\*(SN ConstraintClassPart Structure +.XE +.LP +In addition to the +Core +and +Composite +class fields, +widgets of the Constraint class +have the following class fields. +.LP +.IN "ConstraintClassPart" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +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; +.De +.LP +.eM +The extension record defined for +.PN ConstraintClassPart +with \fIrecord_type\fP equal to +.PN \s-1NULLQUARK\s+1 +is +.PN ConstraintClassExtensionRec . +.LP +.IN "ConstraintClassExtensionRec" "" "@DEF@" +.IN "ConstraintClassExtension" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +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; +.De +.LP +.eM +Constraint +classes have the Constraint class fields immediately following the +Composite class fields. +.LP +.IN "ConstraintWidgetClass" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _ConstraintClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ConstraintClassPart constraint_class; +} ConstraintClassRec, *ConstraintWidgetClass; +.De +.LP +.eM +The single occurrences of the class record and pointer for creating +instances of Constraint are +.LP +In +.PN IntrinsicP.h : +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +extern ConstraintClassRec constraintClassRec; +.De +.LP +.eM +In +.PN Intrinsic.h : +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +extern WidgetClass constraintWidgetClass; +.De +.LP +.eM +The opaque types +.PN ConstraintWidget +and +.PN ConstraintWidgetClass +and the opaque variable +.PN constraintWidgetClass +are defined for generic operations on widgets +whose class is Constraint or a subclass +of Constraint. +The symbolic constant for the +.PN ConstraintClassExtension +version identifier is +.PN XtConstraintExtensionVersion +(see Section 1.6.12). +.PN Intrinsic.h +uses an incomplete structure definition to ensure that the +compiler catches attempts to access private data. +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _ConstraintClassRec *ConstraintWidgetClass; +.De +.eM + +.NH 4 +ConstraintPart Structure +.XS +\*(SN ConstraintPart Structure +.XE +.LP +In addition to the +Core +and +Composite instance +fields, +widgets of the Constraint class have the following unused +instance fields defined in the +.PN ConstraintPart +structure +.LP +.IN "ConstraintPart" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int empty; +} ConstraintPart; +.De +.LP +.eM +Constraint +widgets have the Constraint instance fields immediately following the +Composite instance fields. +.LP +.IN "ConstraintWidget" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + CorePart core; + CompositePart composite; + ConstraintPart constraint; +} ConstraintRec, *ConstraintWidget; +.De +.LP +.eM +.PN Intrinsic.h +uses an incomplete structure definition to ensure that the +compiler catches attempts to access private data. +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _ConstraintRec *ConstraintWidget; +.De +.eM + +.NH 4 +Constraint Resources +.XS +\fB\*(SN Constraint Resources\fP +.XE +.LP +The +.PN constraintClassRec +\fIcore_class\fP and \fIconstraint_class resources\fP fields are NULL, +and the \fInum_resources\fP fields are zero; +no additional resources beyond those declared by +the superclasses +are defined for +Constraint. + +.NH 2 +Implementation-Specific Types +.XS +\fB\*(SN Implementation-Specific Types\fP +.XE +.LP +To increase the portability of widget and application source code +between different system environments, the \*(xI define several +types whose precise representation is explicitly dependent upon, +and chosen by, each individual implementation of the \*(xI. +.LP +These implementation-defined types are +.IN "Boolean" "" "@DEF@" +.IP \fBBoolean\fP 11 +A 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 +.PN True . +.IN "Cardinal" "" "@DEF@" +.IP \fBCardinal\fP 11 +An unsigned integer datum with a minimum range of [0..2^16-1]. +.IN "Dimension" "" "@DEF@" +.IP \fBDimension\fP 11 +An unsigned integer datum with a minimum range of [0..2^16-1]. +.IN "Position" "" "@DEF@" +.IP \fBPosition\fP 11 +A signed integer datum with a minimum range of [-2^15..2^15-1]. +.IN "XtPointer" "" "@DEF@" +.IP \fBXtPointer\fP 11 +A datum large enough to contain the largest of a char*, int*, function +pointer, structure pointer, or long value. A pointer +to any type or function, or a long value may be converted +to an +.PN XtPointer +and back again and the result will +compare equal to the original value. In ANSI C +environments it is expected that +.PN XtPointer +will be +defined as void*. +.IN "XtArgVal" "" "@DEF@" +.IP \fBXtArgVal\fP 11 +A datum large enough to contain an +.PN XtPointer , +.PN Cardinal , +.PN Dimension , +or +.PN Position +value. +.IN "XtEnum" "" "@DEF@" +.IP \fBXtEnum\fP 11 +An integer datum large enough to encode at least 128 distinct +values, two of which are the symbolic values +.PN True +and +.PN False . +The symbolic values +.PN \s-1TRUE\s+1 +and +.PN \s-1FALSE\s+1 +are +also defined to be equal to +.PN True +and +.PN False , +respectively. +.LP +In addition to these specific types, the precise order of the +fields within the structure declarations for any of the instance +part records +.PN ObjectPart , +.PN RectObjPart , +.PN CorePart , +.PN CompositePart , +.PN ShellPart , +.PN WMShellPart , +.PN TopLevelShellPart , +and +.PN ApplicationShellPart +is implementation-defined. These +structures may also have additional private +fields internal to the implementation. +The +.PN ObjectPart , +.PN RectObjPart , +and +.PN CorePart +structures must be defined so that any member with the same name +appears at the same offset in +.PN ObjectRec , +.PN RectObjRec , +and +.PN CoreRec +.Pn ( WidgetRec ). +No other relations between the offsets of any two +fields may be assumed. + +.NH 2 +Widget Classing +.LP +.XS +\fB\*(SN Widget Classing\fP +.XE +.IN "widget_class" "" "@DEF@" +The \fIwidget_class\fP 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 methods 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. +.LP +All widget classes are a subclass of +Core +and can be subclassed 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 +.PN XtResourceList . +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). +.LP +Subclassing, however, can be taken too far. +If you create a subclass that inherits none of the procedures of its +superclass, +you should consider whether you have chosen the most +appropriate superclass. +.LP +To make good use of subclassing, +widget declarations and naming conventions are highly stylized. +A widget consists of three files: +.IP \(bu 5 +A public .h file, used by client widgets or applications. +.IP \(bu 5 +A private .h file, used by widgets whose classes +are subclasses of the widget class. +.IP \(bu 5 +A .c file, which implements the widget. + +.NH 3 +Widget Naming Conventions +.XS +\fB\*(SN Widget Naming Conventions\fP +.XE +.LP +The \*(xI 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: +.IP \(bu 5 +Use the X library naming conventions that are applicable. +For example, a record component name is all lowercase +and uses underscores (_) for compound words (for example, background_pixmap). +Type and procedure names start with uppercase and use capitalization for +compound words (for example, +.PN ArgList +or +.PN XtSetValues ). +.IP \(bu 5 +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 symbolic identifier prefixed with +``XtN''. +For example, +the \fIbackground_pixmap\fP field has the corresponding identifier +XtNbackgroundPixmap, +which is defined as the string ``backgroundPixmap''. +Many predefined names are listed in +.Pn < X11/StringDefs.h >. +Before you invent a new name, +you should make sure there is not already a name that you can use. +.IP \(bu 5 +A resource class string starts with a capital letter +and uses capitalization for compound names (for example,``BorderWidth''). +Each resource class string should have a symbolic identifier prefixed with +``XtC'' +(for example, XtCBorderWidth). +Many predefined classes are listed in +.Pn < X11/StringDefs.h >. +.IP \(bu 5 +A resource representation string is spelled identically to the type name +(for example, ``TranslationTable''). +Each representation string should have a symbolic identifier prefixed with +``XtR'' +(for example, XtRTranslationTable). +Many predefined representation types are listed in +.Pn < X11/StringDefs.h >. +.IP \(bu 5 +New widget classes start with a capital and use uppercase for compound +words. +Given a new class name AbcXyz, you should derive several names: +.RS +.IP \- 5 +Additional widget instance structure part name AbcXyzPart. +.IP \- 5 +Complete widget instance structure names AbcXyzRec and _AbcXyzRec. +.IP \- 5 +Widget instance structure pointer type name AbcXyzWidget. +.IP \- 5 +Additional class structure part name AbcXyzClassPart. +.IP \- 5 +Complete class structure names AbcXyzClassRec and _AbcXyzClassRec. +.IP \- 5 +Class structure pointer type name AbcXyzWidgetClass. +.IP \- 5 +Class structure variable abcXyzClassRec. +.IP \- 5 +Class structure pointer variable abcXyzWidgetClass. +.RE +.IP \(bu 5 +Action procedures available to translation specifications should follow the +same naming conventions as procedures. +That is, +they start with a capital letter, and compound names use uppercase +(for example, ``Highlight'' and ``NotifyClient''). +.LP +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 +.PN String . +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 +symbols 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. + +.NH 3 +Widget Subclassing in Public .h Files +.XS +\*(SN Widget Subclassing in Public .h Files +.XE +.LP +The public .h file for a widget class is imported by clients +and contains +.IP \(bu 5 +A reference to the public .h file for the superclass. +.IP \(bu 5 +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. +.IP \(bu 5 +Type declarations for any new resource data types defined by the class. +.IP \(bu 5 +The class record pointer variable used to create widget instances. +.IP \(bu 5 +The C type that corresponds to widget instances of this class. +.IP \(bu 5 +Entry points for new class methods. +.LP +For example, the following is the public .h file for a possible +implementation of a Label widget: +.LP +.Ds +.TA .5i 1.75i +.ta .5i 1.75i +#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 */ + +#endif LABEL_H +.De +.LP +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. +.LP +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 +.PN Constraint.h . + +.NH 3 +Widget Subclassing in Private .h Files +.XS +\*(SN Widget Subclassing in Private .h Files +.XE +.LP +The private .h file for a widget is imported by widget classes that are +subclasses of the widget and contains +.IP \(bu 5 +A reference to the public .h file for the class. +.IP \(bu 5 +A reference to the private .h file for the superclass. +.IP \(bu 5 +Symbolic identifiers for any new resource representation 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. +.IP \(bu 5 +A structure part definition for +the new fields that the widget instance adds to its superclass's +widget structure. +.IP \(bu 5 +The complete widget instance structure definition for this widget. +.IP \(bu 5 +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 +Constraint. +.IP \(bu 5 +The complete +constraint +structure definition if the widget class is a subclass of +Constraint. +.IP \(bu 5 +Type definitions for any new procedure types used by class methods +declared in the widget class part. +.IP \(bu 5 +A structure part definition for +the new fields that this widget class adds to its superclass's widget class +structure. +.IP \(bu 5 +The complete widget class structure definition for this widget. +.IP \(bu 5 +The complete widget class extension structure definition +for this widget, if any. +.IP \(bu 5 +The symbolic constant identifying the class extension version, if any. +.IP \(bu 5 +The name of the global class structure variable containing the generic +class structure for this class. +.IP \(bu 5 +An inherit constant for each new procedure in the widget class part structure. +.LP +For example, the following is the private .h file for a possible Label widget: +.LP +.Ds +.TA .5i 3i +.ta .5i 3i +#ifndef LABELP_H +#define LABELP_H + +#include <X11/Label.h> + +/* 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; +.De +.sp +.Ds +.TA .5i 3i +.ta .5i 3i +/* Full instance record declaration */ +typedef struct _LabelRec { + CorePart core; + LabelPart label; +} LabelRec; + +/* 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 +.De +.LP +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 +.PN ConstrainP.h . + +.NH 3 +Widget Subclassing in .c Files +.XS +\*(SN Widget Subclassing in .c Files +.XE +.LP +The .c file for a widget contains the structure initializer +for the class record variable, +which contains the following parts: +.IP \(bu 5 +Class information (for example, \fIsuperclass\fP, \fIclass_name\fP, +\fIwidget_size\fP, +\fIclass_initialize\fP, and \fIclass_inited\fP). +.IP \(bu 5 +Data constants (for example, \fIresources\fP and \fInum_resources\fP, +\fIactions\fP and \fInum_actions\fP, \fIvisible_interest\fP, +\fIcompress_motion\fP, +\fIcompress_exposure\fP, and \fIversion\fP). +.IP \(bu 5 +Widget operations (for example, \fIinitialize\fP, \fIrealize\fP, \fIdestroy\fP, +\fIresize\fP, \fIexpose\fP, \fIset_values\fP, \fIaccept_focus\fP, +and any new operations specific to +the widget). +.LP +.IN "superclass" "" "@DEF@" +The \fIsuperclass\fP field points to the superclass +global class +record, declared in the superclass private .h file. +For direct subclasses of the generic core widget, +\fIsuperclass\fP should be initialized to the address of the +.PN widgetClassRec +structure. +The superclass is used for class chaining operations and for +inheriting or enveloping a superclass's operations +(see Sections 1.6.7, 1.6.9, and 1.6.10). +.LP +.IN "class_name" "" "@DEF@" +The \fIclass_name\fP 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 +subsequently deallocated. + +.LP +.IN "widget_size" "" "@DEF@" +The \fIwidget_size\fP field is the size of the corresponding widget +instance structure +(not the size of the class structure). +.LP +.IN "version" "" "@DEF@" +The \fIversion\fP field indicates the toolkit +implementation version number and is used for +runtime consistency checking of the \*(tk and widgets in an application. +Widget writers must set it to the +implementation-defined symbolic value +.PN XtVersion +in the widget class structure initialization. +Those widget writers who believe that their widget binaries are compatible +with other implementations of the \*(xI can put the special value +.PN XtVersionDontCheck +in the \fIversion\fP field to disable version checking for those widgets. +If a widget needs to compile alternative code for different +revisions of the \*(xI interface definition, it may use the symbol +.PN XtSpecificationRelease , +as described in Chapter 13. +Use of +.PN XtVersion +allows the \*(xI implementation to recognize widget binaries +that were compiled with older implementations. +.LP +The \fIextension\fP field is for future upward compatibility. +If the widget programmer adds fields to class parts, +all subclass structure layouts change, +requiring complete recompilation. +To allow clients to avoid recompilation, +an extension field at the end of each class part can point to a record +that contains any additional class information required. +.LP +All other fields are described in their respective sections. +.LP +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. +.LP +.Ds +.TA .5i 1.5i 3i +.ta .5i 1.5i 3i + +/* 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(); + . + . + . +.De +.sp +.Ds +.TA .5i 2i 3i +.ta .5i 2i 3i +/* 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, + /* 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; +{ + LabelWidgetClass lwc = (Label WidgetClass)XtClass(w); + XtCheckSubclass(w, labelWidgetClass, NULL); + *(lwc->label_class.set_text)(w, text) +} +/* Private procedures */ + . + . + . +.De + +.NH 3 +Widget Class and Superclass Look Up +.XS +\*(SN Widget Class and Superclass Look Up +.XE +.LP +To obtain the class of a widget, use +.PN XtClass . +.IN "XtClass" "" "@DEF@" +.LP +.sM +.FD 0 +WidgetClass XtClass(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(oI +.LP +.eM +The +.PN XtClass +function returns a pointer to the widget's class structure. +.sp +.LP +To obtain the superclass of a widget, use +.PN XtSuperclass . +.IN "XtSuperclass" "" "@DEF@" +.LP +.sM +.FD 0 +WidgetClass XtSuperclass(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(oI +.LP +.eM +The +.PN XtSuperclass +function returns a pointer to the widget's superclass class structure. + +.NH 3 +Widget Subclass Verification +.XS +\*(SN Widget Subclass Verification +.XE +.LP +To check the subclass to which a widget belongs, use +.PN XtIsSubclass . +.IN "XtIsSubclass" "" "@DEF@" +.LP +.sM +.FD 0 +Boolean XtIsSubclass(\fIw\fP, \fIwidget_class\fP) +.br + Widget \fIw\fP; +.br + WidgetClass \fIwidget_class\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget or object instance whose class is to be checked. \*(oI +.IP \fIwidget_class\fP 1i +Specifies the widget class for which to test. \*(oC +.LP +.eM +The +.PN XtIsSubclass +function returns +.PN True +if the class of the specified widget is equal to +or is a subclass of the specified class. +The widget's class can be any number of subclasses 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 +.PN XtIsSubclass +to find out if a widget belongs to the desired class of objects. +.sp +.LP +To test if a given widget belongs to a subclass of an \*(xI-defined +class, the \*(xI define macros or functions equivalent to +.PN XtIsSubclass +for each of the built-in classes. These procedures are +.PN XtIsObject , +.PN XtIsRectObj , +.PN XtIsWidget , +.PN XtIsComposite , +.PN XtIsConstraint , +.PN XtIsShell , +.PN XtIsOverrideShell , +.PN XtIsWMShell , +.PN XtIsVendorShell , +.PN XtIsTransientShell , +.PN XtIsTopLevelShell , +.PN XtIsApplicationShell , +and +.PN XtIsSessionShell . +.IN "XtIsObject" "" "@DEF@" +.IN "XtIsRectObj" "" "@DEF@" +.IN "XtIsWidget" "" "@DEF@" +.IN "XtIsComposite" "" "@DEF@" +.IN "XtIsConstraint" "" "@DEF@" +.IN "XtIsShell" "" "@DEF@" +.IN "XtIsOverrideShell" "" "@DEF@" +.IN "XtIsWMShell" "" "@DEF@" +.IN "XtIsVendorShell" "" "@DEF@" +.IN "XtIsTransientShell" "" "@DEF@" +.IN "XtIsTopLevelShell" "" "@DEF@" +.IN "XtIsApplicationShell" "" "@DEF@" +.IN "XtIsSessionShell" "" "@DEF@" +.LP +All these macros and functions have the same argument description. +.LP +.sM +.FD 0 +Boolean XtIs\fI<class>\fP (\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget or object instance whose class is to be checked. \*(oI +.LP +.eM +These procedures may be faster than calling +.PN XtIsSubclass +directly for the built-in classes. +.sp +.LP +To check a widget's class +and to generate a debugging error message, use +.PN XtCheckSubclass , +defined in +.Pn < X11/IntrinsicP.h >: +.IN "XtCheckSubclass" "" "@DEF@" +.LP +.sM +.FD 0 +void XtCheckSubclass(\fIw\fP, \fIwidget_class\fP, \fImessage\fP) +.br + Widget \fIw\fP; +.br + WidgetClass \fIwidget_class\fP; +.br + String \fImessage\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget or object whose class is to be checked. \*(oI +.IP \fIwidget_class\fP 1i +Specifies the widget class for which to test. \*(oC +.ds Me used +.IP \fImessage\fP 1i +Specifies the message to be used. +.LP +.eM +The +.PN XtCheckSubclass +macro determines if the class of the specified widget is equal to +or is a subclass of the specified class. +The widget's class can be any number of subclasses down the chain +and need not be an immediate subclass of the specified class. +If the specified widget's class is not a subclass, +.PN XtCheckSubclass +constructs an error message from the supplied message, +the widget's actual class, and the expected class and calls +.PN XtErrorMsg . +.PN XtCheckSubclass +should be used at the entry point of exported routines to ensure +that the client has passed in a valid widget class for the exported operation. +.LP +.PN XtCheckSubclass +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. + +.NH 3 +Superclass Chaining +.XS +\*(SN Superclass Chaining +.XE +.LP +.IN "Chaining" "superclass" +.IN "Chaining" "Subclass" +.IN "Superclass Chaining" "" "@DEF@" +.IN "Subclass Chaining" "" "@DEF@" +.IN "Inheritance" +While most fields in a widget class structure are self-contained, +some fields are linked to their corresponding fields in their superclass +structures. +With a linked field, +the \*(xI 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-contained fields are +.sp +.ta 2i +In all widget classes: \fIclass_name\fP +.br + \fIclass_initialize\fP +.br + \fIwidget_size\fP +.br + \fIrealize\fP +.br + \fIvisible_interest\fP +.br + \fIresize\fP +.br + \fIexpose\fP +.br + \fIaccept_focus\fP +.br + \fIcompress_motion\fP +.br + \fIcompress_exposure\fP +.br + \fIcompress_enterleave\fP +.br + \fIset_values_almost\fP +.br + \fItm_table\fP +.br + \fIversion\fP +.br + \fIallocate\fP +.br + \fIdeallocate\fP +.sp +In Composite widget classes: \fIgeometry_manager\fP +.br + \fIchange_managed\fP +.br + \fIinsert_child\fP +.br + \fIdelete_child\fP +.br + \fIaccepts_objects\fP +.br + \fIallows_change_managed_set\fP +.sp +In Constraint widget classes: \fIconstraint_size\fP +.sp +In Shell widget classes: \fIroot_geometry_manager\fP +.sp +.LP +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 structure. These superclass-to-subclass fields are +.sp +.ta 1i +.br + \fIclass_part_initialize\fP +.br + \fIget_values_hook\fP +.br + \fIinitialize\fP +.br + \fIinitialize_hook\fP +.br + \fIset_values\fP +.br + \fIset_values_hook\fP +.br + \fIresources\fP +.sp +.LP +In addition, for subclasses of +Constraint, +the following fields of the +.PN ConstraintClassPart +and +.PN ConstraintClassExtensionRec +structures are chained from the +Constraint +class down to the subclass: +.ta 1i +.br + \fIresources\fP +.br + \fIinitialize\fP +.br + \fIset_values\fP +.br + \fIget_values_hook\fP +.sp +.LP +With upward superclass chaining, +the invocation of an operation first accesses the field from the widget +class structure, then from the superclass structure, +and so on up the class chain to the +Core, +RectObj, +and +Object +class structures. +The subclass-to-superclass fields are +.sp +.ta 1i +.br + \fIdestroy\fP +.br + \fIactions\fP +.sp +.LP +For subclasses of +Constraint, +the following field of +.PN ConstraintClassPart +is chained from the subclass up to the +Constraint class: +.sp +.ta 1i +.br + \fIdestroy\fP + +.NH 3 +Class Initialization: class_initialize and class_part_initialize Procedures +.XS +\*(SN Class Initialization: class_initialize and class_part_initialize Procedures +.XE +.LP +.IN "Class Initialization" +.IN "Initialization" +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. +.LP +Because the C language does not have initialization procedures +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 \*(xI. +A class initialization procedure pointer is of type +.PN XtProc : +.IN "class_initialize procedure" "" "@DEF@" +.IN "XtProc" "" "@DEF@" +.LP +.sM +.FD 0 +typedef void (*XtProc)(void); +.FN +.LP +.eM +A widget class indicates that it has no class initialization procedure by +specifying NULL in the \fIclass_initialize\fP field. +.LP +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 procedure, +a pointer to which is stored in the \fIclass_part_initialize\fP field. +The class_part_initialize procedure pointer is of type +.PN XtWidgetClassProc . +.IN "XtWidgetClassProc" "" "@DEF@" +.LP +.sM +.FD 0 +typedef void (*XtWidgetClassProc)(WidgetClass); +.br + WidgetClass \fIwidget_class\fP; +.FN +.IP \fIwidget_class\fP 1i +Points to the class structure for the class being initialized. +.LP +.eM +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 initializations +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 procedure. +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, Composite's +class_part_initialize procedure is called to initialize 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 \fIclass_part_initialize\fP field. +.LP +All widget classes, whether they have a class initialization procedure or not, +must start with their \fIclass_inited\fP field +.PN False . +.LP +The first time a widget of a class is created, +.PN XtCreateWidget +ensures that the widget class and all superclasses are initialized, in +superclass-to-subclass order, by checking each \fIclass_inited\fP field and, +if it is +.PN False , +by calling the class_initialize and the class_part_initialize procedures +for the class and all its superclasses. +The \*(xI then set the \fIclass_inited\fP field to a nonzero value. +After the one-time initialization, +a class structure is constant. +.LP +The following example provides the class initialization procedure for a Label class. +.LP +.Ds +.TA .5i 2i +.ta .5i 2i +static void ClassInitialize() +{ + XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify, + NULL, 0, XtCacheNone, NULL); +} +.De + +.NH 3 +Initializing a Widget Class +.XS +\fB\*(SN Initializing a Widget Class\fP +.XE +.IN "Widget" "class initialization" +.LP +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 +.PN XtInitializeWidgetClass . +.IN "XtInitializeWidgetClass" "" "@DEF@" +.LP +.sM +.FD 0 +void XtInitializeWidgetClass(\fIobject_class\fP) +.br + WidgetClass \fIobject_class\fP; +.br +.FN +.IP \fIobject_class\fP 1i +Specifies the object class to initialize. May be +.PN objectClass +or any subclass thereof. +.LP +.eM +If the specified widget class is already initialized, +.PN XtInitializeWidgetClass +returns immediately. +.LP +If the class initialization procedure registers type converters, +these type converters are not available until the first object +of the class or subclass is created or +.PN XtInitializeWidgetClass +is called +(see Section 9.6). + +.NH 3 +Inheritance of Superclass Operations +.XS +\*(SN Inheritance of Superclass Operations +.XE +.LP +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 +.IP +expose +.IP +realize +.IP +insert_child +.IP +delete_child +.IP +geometry_manager +.IP +set_values_almost +.LP +To inherit an operation \fIxyz\fP, +specify the constant +.PN XtInherit \fIXyz\fP +in your class record. +.LP +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. +.LP +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 \*(xI internal value +.PN _XtInherit +cast to the appropriate type. +.PN _XtInherit +is a procedure that issues an error message if it is actually called. +.LP +For example, +.PN CompositeP.h +contains these definitions: +.LP +.Ds +.TA .25i 1.5i 3i +.ta .25i 1.5i 3i +#define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit) +#define XtInheritChangeManaged ((XtWidgetProc) _XtInherit) +#define XtInheritInsertChild ((XtArgsProc) _XtInherit) +#define XtInheritDeleteChild ((XtWidgetProc) _XtInherit) +.De +.LP +Composite's class_part_initialize procedure begins as follows: +.LP +.Ds +.TA .2i 1.5i 3i +.ta .2i 1.5i 3i +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; + } + . + . + . +.De +.LP +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: +.LP +For Object: +.IP +.PN XtInheritAllocate +.IP +.PN XtInheritDeallocate +.LP +For Core: +.IP +.PN XtInheritRealize +.IP +.PN XtInheritResize +.IP +.PN XtInheritExpose +.IP +.PN XtInheritSetValuesAlmost +.IP +.PN XtInheritAcceptFocus +.IP +.PN XtInheritQueryGeometry +.IP +.PN XtInheritTranslations +.IP +.PN XtInheritDisplayAccelerator +.LP +For Composite: +.IP +.PN XtInheritGeometryManager +.IP +.PN XtInheritChangeManaged +.IP +.PN XtInheritInsertChild +.IP +.PN XtInheritDeleteChild +.LP +For Shell: +.IP +.PN XtInheritRootGeometryManager + +.NH 3 +Invocation of Superclass Operations +.XS +\*(SN Invocation of Superclass Operations +.XE +.LP +A widget sometimes needs to call a superclass operation +that is not chained. +For example, +a widget's expose procedure might call its superclass's \fIexpose\fP +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 \fIinsert_child\fP +.IN "insert_child procedure" +and then calling +.PN XtManageChild +to add the child to the managed set. +.LP +.NT +A class method should not use +.PN XtSuperclass +but should instead call the class method of its own specific superclass +directly through the superclass record. +That is, it should use its own class pointers only, +not the widget's class pointers, +as the widget's class may be a subclass of the +class whose implementation is being referenced. +.NE +This technique is referred to as \fIenveloping\fP the superclass's operation. + +.NH 3 +Class Extension Records +.XS +\*(SN Class Extension Records +.XE +.IN "Widget" "class extension records" +.LP +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. +.LP +If extension fields exist, as is the case with the +Composite, +Constraint, +and +Shell +classes, subclasses can provide values for these fields by setting the +\fIextension\fP pointer for the appropriate part in their class structure to +point to a statically declared extension record containing the +additional fields. +Setting the \fIextension\fP field is never mandatory; code that uses fields +in the extension record must always check the \fIextension\fP field and take +some appropriate default action if it is NULL. +.LP +In order to permit multiple subclasses and libraries to chain extension +records from a single \fIextension\fP field, extension records should be +declared as a linked list, and each extension record definition should +contain the following four fields at the beginning of the structure +declaration: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +struct { + XtPointer next_extension; + XrmQuark record_type; + long version; + Cardinal record_size; +}; +.De +.IP \fInext_extension\fP 1.25i +Specifies the next record in the list, or NULL. +.IP \fIrecord_type\fP 1.25i +Specifies the particular structure declaration to which +each extension record instance conforms. +.IP \fIversion\fP 1.25i +Specifies a version id symbolic constant supplied by +the definer of the structure. +.IP \fIrecord_size\fP 1.25i +Specifies the total number of bytes allocated for the +extension record. +.LP +.eM +The \fIrecord_type\fP field identifies the contents of the extension record +and is used by the definer of the record to locate its particular +extension record in the list. The +\fIrecord_type\fP field is normally assigned the +result of +.PN XrmStringToQuark +for a registered string constant. The +\*(xI reserve all record type strings beginning with the two +characters ``XT'' for future standard uses. The value +.PN \s-1NULLQUARK\s+1 +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. +.LP +The \fIversion\fP 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 \fIrecord_size\fP field value includes the four common header fields and +should normally be initialized with +.PN sizeof (). +.LP +Any value stored in the class part extension fields of +.PN CompositeClassPart , +.PN ConstraintClassPart , +or +.PN ShellClassPart +must point to an extension record conforming to this definition. +.LP +The \*(xI 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 \fIextension\fP field in the class record. +.LP +To locate a class extension record, use +.PN XtGetClassExtension . +.IN "XtGetClassExtension" "" "@DEF@" +.LP +.sM +.FD 0 +XtPointer XtGetClassExtension(\fIobject_class\fP, \fIbyte_offset\fP, \ +\fItype\fP, \fIversion\fP, \fIrecord_size\fP) +.br + WidgetClass \fIobject_class\fP; +.br + Cardinal \fIbyte_offset\fP; +.br + XrmQuark \fItype\fP; +.br + long \fIversion\fP; +.br + Cardinal \fIrecord_size\fP; +.FN +.IP \fIobject_class\fP 1i +Specifies the object class containing the extension list to be searched. +.IP \fIbyte_offset\fP 1i +Specifies the offset in bytes from the base of the +class record of the extension field to be searched. +.IP \fItype\fP 1i +Specifies the record_type of the class extension to be located. +.IP \fIversion\fP 1i +Specifies the minimum acceptable version of the class +extension required for a match. +.IP \fIrecord_size\fP 1i +Specifies the minimum acceptable length of the class +extension record required for a match, or 0. +.LP +.eM +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 specified version, and a record +size greater than or equal the specified record_size if it is nonzero. +.PN XtGetClassExtension +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. +.bp diff --git a/specs/CH02 b/specs/CH02 new file mode 100644 index 0000000..cbb4bb8 --- /dev/null +++ b/specs/CH02 @@ -0,0 +1,3165 @@ +.\" $Xorg: CH02,v 1.3 2000/08/17 19:42:42 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 2\fP\s-1 + +\s+1\fBWidget Instantiation\fP\s-1 +.sp 2 +.nr H1 2 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 2 \(em Widget Instantiation +.XE +A hierarchy of widget instances constitutes a widget tree. +The shell widget returned by +.PN XtAppCreateShell +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. +.LP +Widgets can be either composite or primitive. +Both kinds of widgets can contain children, +but the \*(xI provide a set of management mechanisms for constructing +and interfacing between composite widgets, their children, and +other clients. +.LP +Composite widgets, that is, members of the class +.PN compositeWidgetClass , +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 management methods. +.LP +In addition, +the \*(xI recursively perform many operations +(for example, realization and destruction) +on composite widgets and all their children. +Primitive widgets that have children must be prepared +to perform the recursive operations themselves on behalf of their children. +.LP +A widget tree is manipulated by several \*(xI functions. +For example, +.PN XtRealizeWidget +traverses the tree downward and recursively realizes all +pop-up widgets and children of composite widgets. +.PN XtDestroyWidget +traverses the tree downward and destroys all pop-up widgets +and children 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. +.PN XtMakeGeometryRequest +traverses the tree up one level and calls the geometry manager +that is responsible for a widget child's geometry. +.LP +To facilitate upward traversal of the widget tree, +each widget has a pointer to its parent widget. +The +Shell +widget that +.PN XtAppCreateShell +returns has a \fIparent\fP pointer of NULL. +.LP +To facilitate downward traversal of the widget tree, +the \fIchildren\fP 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. + +.NH 2 +Initializing the \*(tk +.XS +\fB\*(SN Initializing the \*(tk\fP +.XE +.LP +Before an application can call any \*(xI function +other than +.PN XtSetLanguageProc +and +.PN XtToolkitThreadInitialize , +it must initialize the \*(xI by using +.IP \(bu 5 +.PN XtToolkitInitialize , +which initializes the \*(xI internals +.IP \(bu 5 +.PN XtCreateApplicationContext , +which initializes the per-application state +.IP \(bu 5 +.PN XtDisplayInitialize +or +.PN XtOpenDisplay , +which initializes the per-display state +.IP \(bu 5 +.PN XtAppCreateShell , +which creates the root of a widget tree +.LP +Or an application can call the convenience procedure +.PN XtOpenApplication , +which combines the functions of the preceding procedures. +An application wishing to use the ANSI C locale mechanism should call +.PN XtSetLanguageProc +prior to calling +.PN XtDisplayInitialize , +.PN XtOpenDisplay , +.PN XtOpenApplication , +or +.PN XtAppInitialize . +.LP +Multiple instances of \*(tk applications may be implemented +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. +.IN "application context" "" "@DEF@" +To accommodate both requirements, +the \*(xI 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 +.PN Display +pointers for that application. +The \*(xI handle all display connections within a single application +context simultaneously, handling input in a round-robin fashion. +The application context type +.PN XtAppContext +.IN "XtAppContext" "" "@DEF@" +is opaque to clients. +.sp +.LP +To initialize the \*(xI internals, use +.PN XtToolkitInitialize . +.LP +.IN "XtToolkitInitialize" "" "@DEF@" +.sM +.FD 0 +void XtToolkitInitialize() +.FN +.LP +.eM +If +.PN XtToolkitInitialize +was previously called, it returns immediately. +When +.PN XtToolkitThreadInitialize +is called before +.PN XtToolkitInitialize , +the latter is protected against +simultaneous activation by multiple threads. +.sp +.LP +To create an application context, use +.PN XtCreateApplicationContext . +.LP +.IN "XtCreateApplicationContext" "" "@DEF@" +.sM +.FD 0 +XtAppContext XtCreateApplicationContext() +.FN +.LP +.eM +The +.PN XtCreateApplicationContext +function returns an application context, +which is an opaque type. +Every application must have at least one application context. +.sp +.LP +To destroy an application context and close any +remaining display connections in it, use +.PN XtDestroyApplicationContext . +.LP +.IN "XtDestroyApplicationContext" "" "@DEF@" +.sM +.FD 0 +void XtDestroyApplicationContext(\fIapp_context\fP) +.br + XtAppContext \fIapp_context\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.LP +.eM +The +.PN XtDestroyApplicationContext +function destroys the specified application context. +If called from within an event dispatch (for example, in a callback procedure), +.PN XtDestroyApplicationContext +does not destroy the application context until the dispatch is complete. +.sp +.LP +To get the application context in which a given widget was created, use +.PN XtWidgetToApplicationContext . +.LP +.IN "XtWidgetToApplicationContext" "" "@DEF@" +.sM +.FD 0 +XtAppContext XtWidgetToApplicationContext(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget for which you want the application context. \*(oI +.LP +.eM +The +.PN XtWidgetToApplicationContext +function returns the application context for the specified widget. +.sp +.LP +To initialize a display and add it to an application context, use +.PN XtDisplayInitialize . +.LP +.IN "XtDisplayInitialize" "" "@DEF@" +.sM +.FD 0 +void XtDisplayInitialize(\fIapp_context\fP, \fIdisplay\fP, \ +\fIapplication_name\fP, \fIapplication_class\fP, +.br + \fIoptions\fP, \fInum_options\fP, \fIargc\fP, \fIargv\fP) +.br + XtAppContext \fIapp_context\fP; +.br + Display *\fIdisplay\fP; +.br + String \fIapplication_name\fP; +.br + String \fIapplication_class\fP; +.br + XrmOptionDescRec *\fIoptions\fP; +.br + Cardinal \fInum_options\fP; +.br + int *\fIargc\fP; +.br + String *\fIargv\fP; +.FN +.IP \fIapp_context\fP 1.4i +Specifies the application context. +.IP \fIdisplay\fP 1.4i +Specifies a previously opened display connection. Note that a single +display connection can be in at most one application context. +.IP \fIapplication_name\fP 1.4i +Specifies the name of the application instance. +.IP \fIapplication_class\fP 1.4i +Specifies the class name of this application, +which is usually the generic name for all instances of this application. +.IP \fIoptions\fP 1.4i +Specifies how to parse the command line for any application-specific resources. +The \fIoptions\fP argument is passed as a parameter to +.PN XrmParseCommand . +For further information, +see Section 15.9 in \fI\*(xL\fP and Section 2.4 of this specification. +.IP \fInum_options\fP 1.4i +Specifies the number of entries in the options list. +.IP \fIargc\fP 1.4i +Specifies a pointer to the number of command line parameters. +.IP \fIargv\fP 1.4i +Specifies the list of command line parameters. +.LP +.eM +The +.PN XtDisplayInitialize +function retrieves the language string to be +used for the specified display (see Section 11.11), +calls the language procedure (if set) with that language string, +builds the resource database for the default screen, calls the Xlib +.PN XrmParseCommand +function to parse the command line, +and performs other per-display initialization. +After +.PN XrmParseCommand +has been called, +\fIargc\fP and \fIargv\fP contain only those parameters that +were not in the standard option table or in the table specified by the +\fIoptions\fP argument. +If the modified \fIargc\fP is not zero, +most applications simply print out the modified \fIargv\fP along with a message +listing the allowable options. +On POSIX-based systems, +the application name is usually the final component of \fIargv\fP[0]. +If the synchronous resource is +.PN True , +.PN XtDisplayInitialize +calls the Xlib +.PN XSynchronize +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 \fIapplication_name\fP, +\fIapplication_class\fP, \fIoptions\fP, and \fInum_options\fP arguments. +.LP +.PN XtDisplayInitialize +calls +.PN XrmSetDatabase +to associate the resource database of the default screen with the +display before returning. + +.KS +.LP +To open a display, initialize it, and then +add it to an application context, use +.PN XtOpenDisplay . +.LP +.IN "XtOpenDisplay" "" "@DEF@" +.sM +.FD 0 +Display *XtOpenDisplay(\fIapp_context\fP, \fIdisplay_string\fP, \ +\fIapplication_name\fP, \fIapplication_class\fP, +.br + \fIoptions\fP, \fInum_options\fP, \fIargc\fP, \fIargv\fP) +.br + XtAppContext \fIapp_context\fP; +.br + String \fIdisplay_string\fP; +.br + String \fIapplication_name\fP; +.br + String \fIapplication_class\fP; +.br + XrmOptionDescRec *\fIoptions\fP; +.br + Cardinal \fInum_options\fP; +.br + int *\fIargc\fP; +.br + String *\fIargv\fP; +.FN +.IP \fIapp_context\fP 1.4i +Specifies the application context. +.IP \fIdisplay_string\fP 1.4i +Specifies the display string, or NULL. +.IP \fIapplication_name\fP 1.4i +Specifies the name of the application instance, or NULL. +.IP \fIapplication_class\fP 1.4i +Specifies the class name of this application, +which is usually the generic name for all instances of this application. +.IP \fIoptions\fP 1.4i +Specifies how to parse the command line for any application-specific resources. +The options argument is passed as a parameter to +.PN XrmParseCommand . +.IP \fInum_options\fP 1.4i +Specifies the number of entries in the options list. +.IP \fIargc\fP 1.4i +Specifies a pointer to the number of command line parameters. +.IP \fIargv\fP 1.4i +Specifies the list of command line parameters. +.KE +.LP +.eM +The +.PN XtOpenDisplay +function calls +.PN XOpenDisplay +with the specified \fIdisplay_string\fP. +If \fIdisplay_string\fP is NULL, +.PN XtOpenDisplay +uses the current value of the \-display option specified in \fIargv\fP. +If no display is specified in \fIargv\fP, +the user's default display is retrieved from the environment. +On POSIX-based systems, +this is the value of the +.PN \s-1DISPLAY\s+1 +environment variable. +.LP +If this succeeds, +.PN XtOpenDisplay +then calls +.PN XtDisplayInitialize +and passes it the opened display and +the value of the \-name option specified in \fIargv\fP as the application name. +If no \-name option is specified +and \fIapplication_name\fP is +non-NULL, \fIapplication_name\fP is passed to +.PN XtDisplayInitialize . +If \fIapplication_name\fP is NULL and if the environment variable +.PN \s-1RESOURCE_NAME\s+1 +is set, the value of +.PN \s-1RESOURCE_NAME\s+1 +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 \fIargv\fP[0] less any directory and file type components, that is, the +final component of \fIargv\fP[0], if specified. If \fIargv\fP[0] does not exist or +is the empty string, the application name is ``main''. +.PN XtOpenDisplay +returns the newly opened display or NULL if it failed. +.LP +See Section 7.12 for information regarding the use of +.PN XtOpenDisplay +in multiple threads. +.sp +.LP +To close a display and remove it from an application context, use +.PN XtCloseDisplay . +.LP +.IN "XtCloseDisplay" "" "@DEF@" +.sM +.FD 0 +void XtCloseDisplay(\fIdisplay\fP) +.br + Display *\fIdisplay\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display. +.LP +.eM +The +.PN XtCloseDisplay +function calls +.PN XCloseDisplay +with the specified \fIdisplay\fP as soon as it is safe to do so. +If called from within an event dispatch (for example, a callback procedure), +.PN XtCloseDisplay +does not close the display until the dispatch is complete. +Note that applications need only call +.PN XtCloseDisplay +if they are to continue executing after closing the display; +otherwise, they should call +.PN XtDestroyApplicationContext . +.LP +See Section 7.12 for information regarding the use of +.PN XtCloseDisplay +in multiple threads. + +.NH 2 +Establishing the Locale +.XS +\fB\*(SN Establishing the Locale\fP +.XE +.LP +Resource databases are specified to be created in the current process +locale. During display initialization prior to creating the +per-screen resource database, the \*(xI 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. +.LP +The callout procedure provided by the application is of type +.PN XtLanguageProc . +.LP +.IN "XtLanguageProc" "" "@DEF@" +.sM +.FD 0 +typedef String (*XtLanguageProc)(Display*, String, XtPointer); +.br + Display *\fIdisplay\fP; +.br + String \fIlanguage\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIdisplay\fP 1i +Passes the display. +.IP \fIlanguage\fP +Passes the initial language value obtained from the command line +or server per-display resource specifications. +.IP \fIclient_data\fP +Passes the additional client data specified in the call to +.PN XtSetLanguageProc . +.LP +.eM +The language procedure allows an application to set the locale to +the value of the language resource determined by +.PN XtDisplayInitialize . +The function returns a new language string that +will be subsequently used by +.PN XtDisplayInitialize +to establish the path for loading resource files. The returned +string will be copied by the \*(xI into new memory. +.LP +Initially, no language procedure is set by the \*(xI. +To set the language procedure for use by +.PN XtDisplayInitialize , +use +.PN XtSetLanguageProc . +.LP +.IN XtSetLanguageProc "" "@DEF@" +.IN "language procedure" "" "@DEF@" +.sM +.FD 0 +XtLanguageProc XtSetLanguageProc(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP) +.br + XtAppContext \fIapp_context\fP; +.br + XtLanguageProc \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context in which the language procedure is +to be used, or NULL. +.IP \fIproc\fP 1i +Specifies the language procedure. +.IP \fIclient_data\fP 1i +Specifies additional client data to be passed to the language +procedure when it is called. +.LP +.eM +.PN XtSetLanguageProc +sets the language procedure that will be called from +.PN XtDisplayInitialize +for all subsequent Displays initialized in the specified application +context. If \fIapp_context\fP is NULL, the specified language +procedure is registered in all application contexts created by the +calling process, including any future application contexts that may +be created. If \fIproc\fP is NULL, a default language procedure is +registered. +.PN XtSetLanguageProc +returns the previously registered language procedure. +If a language procedure has not yet been registered, the return value +is unspecified, but if this return value is used in a subsequent call to +.PN XtSetLanguageProc , +it will cause the default language procedure to be registered. +.LP +The default language procedure does the following: +.IP \(bu 5 +Sets the locale according to the environment. On ANSI C-based +systems this is done by calling +.PN setlocale ( +.PN LC_ALL , +\fIlanguage\fP ). +If an error is encountered, a warning message is issued with +.PN XtWarning . +.IP \(bu 5 +Calls +.PN XSupportsLocale +to verify that the current locale is supported. +If the locale is not supported, a warning message is issued with +.PN XtWarning +and the locale is set to ``C''. +.IP \(bu 5 +Calls +.PN XSetLocaleModifiers +specifying the empty string. +.IP \(bu 5 +Returns the value of the current locale. On ANSI C-based systems this +is the return value from a final call to +.PN setlocale ( +.PN LC_ALL , +NULL ). +.LP +A client wishing to use this mechanism to establish locale can do so +by calling +.PN XtSetLanguageProc +prior to +.PN XtDisplayInitialize , +as in the following example. +.LP +.Ds 0 +.TA .5i + Widget top; + XtSetLanguageProc(NULL, NULL, NULL); + top = XtOpenApplication(...); + ... +.De + +.NH 2 +Loading the Resource Database +.XS +\fB\*(SN Loading the Resource Database\fP +.XE +.LP +The +.PN XtDisplayInitialize +function first determines the language +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 precedence: + +.IP \(bu 5 +Application command line (\fIargc\fP, \fIargv\fP). +.IP \(bu 5 +Per-host user environment resource file on the local host. +.IP \(bu 5 +Per-screen resource specifications from the server. +.IP \(bu 5 +Per-display resource specifications from the server or from +.br +the user preference file on the local host. +.IP \(bu 5 +Application-specific user resource file on the local host. +.IP \(bu 5 +Application-specific class resource file on the local host. + +.LP +When the resource database for a particular screen on the display +is needed (either internally, or when +.PN XtScreenDatabase +is called), +it is created in the following manner using the sources listed +above in the same order: + +.IP \(bu 5 +A temporary database, the ``server resource database'', is +created from the string returned by +.PN XResourceManagerString +or, if +.PN XResourceManagerString +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/\fB.Xdefaults\fP. +.IN ".Xdefaults" "" "@DEF@" + +.IP \(bu 5 +If a language procedure has been set, +.PN XtDisplayInitialize +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 Character Set. If neither option is +specified on the command line, +.PN XtDisplayInitialize +queries the server resource database (which is assumed to be entirely +in XPCS) for the resource +\fIname\fP\fB.xnlLanguage\fP, class \fIClass\fP\fB.XnlLanguage\fP +where \fIname\fP +.IN "xnlLanguage" "" "@DEF@" +.IN "Resources" "xnlLanguage" +and \fIClass\fP are the \fIapplication_name\fP and +\fIapplication_class\fP specified to +.PN XtDisplayInitialize . +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 \*(xI that require the per-display language string. + +.IP \(bu 5 +The screen resource database is initialized by parsing the command +line in the manner specified by Section 2.4. + +.IP \(bu 5 +If a language procedure has not been set, +the initial database is then queried for the resource +\fIname\fP\fB.xnlLanguage\fP, class \fIClass\fP\fB.XnlLanguage\fP +as 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 systems, this is done by retrieving the +value of the +.PN \s-1LANG\s+1 +environment variable. If no language string is +found, the empty string is used. +This language string is saved for all future references in the \*(xI +that require the per-display language string. + +.IP \(bu 5 +After determining the language string, the user's environment 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 environment resource file name is +specified by the value of the +.PN \s-1XENVIRONMENT\s+1 +environment variable. +If this environment variable does not exist, the user's home directory +is searched for a file named +.PN \&.Xdefaults-\fIhost\fP , +where \fIhost\fP is the host name of the machine on which the +application is running. + +.IP \(bu 5 +The per-screen resource specifications are then merged into the screen +resource database, if they exist. These specifications are the string +returned by +.PN XScreenResourceString +for the respective screen and are owned entirely by the user. + +.IP \(bu 5 +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. + +.IP \(bu 5 +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 +.PN XrmSetDatabase +with the current screen resource database, after preserving the +original display-associated database, then calling +.PN XtResolvePathname +with the parameters +(\fIdisplay\fP, NULL, NULL, NULL, \fIpath\fP, NULL, 0, NULL), +where \fIpath\fP is defined in an operating-system-specific way. +On POSIX-based systems, \fIpath\fP is defined to be the value +of the environment variable +.PN \s-1XUSERFILESEARCHPATH\s+1 +if this is defined. If +.PN \s-1XUSERFILESEARCHPATH\s+1 +is not defined, an implementation-dependent default value is used. +This default value is constrained in the following manner: + +.RS +.IP \- 3 +If the environment variable +.PN \s-1XAPPLRESDIR\s+1 +is not defined, the default +.PN \s-1XUSERFILESEARCHPATH\s+1 +must contain at least six entries. These entries must contain +.IN "XUSERFILESEARCHPATH" "" "@DEF@" +.IN "XAPPLRESDIR" "" "@DEF@" +.IN "$HOME" +$HOME as the directory prefix, plus the following substitutions: + +.nf +.ta .3i 1.5i 2i +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 +.fi + +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. + +.IP \- 3 +If +.PN \s-1XAPPLRESDIR\s+1 +is defined, the default +.PN \s-1XUSERFILESEARCHPATH\s+1 +must contain at least seven entries. These entries must contain the +following directory prefixes and substitutions: + +.ne 1.1 +.nf +.ta .3i 1.6i 2.2i 3.3i 3.7i +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 +.fi + +The order of these seven entries within the path must be as given above. +The order and use of substitutions within a given entry are +implementation-dependent. +.RE + +.IP \(bu 5 +Last, the application-specific class resource file from the local +host is merged into the screen resource database. +This file is owned by the application and is usually installed in +a system directory when the application is installed. +It may contain sitewide customizations specified by the system manager. +The name of the application class resource file is found by calling +.PN XtResolvePathname +with the parameters +(\fIdisplay\fP, ``app-defaults'', NULL, NULL, NULL, NULL, 0, NULL). +This file is expected to be provided by the developer of the application +and may be required for the application 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 +.PN XtAppSetFallbackResources . +Note that the customization substitution string is retrieved +dynamically by +.PN XtResolvePathname +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 +database, even though the contents of the class resource file have +lowest precedence. After calling +.PN XtResolvePathname , +the original display-associated database is restored. +.sp +.LP +To obtain the resource database for a particular screen, use +.PN XtScreenDatabase . +.LP +.IN "XtScreenDatabase" "" "@DEF@" +.sM +.FD 0 +XrmDatabase XtScreenDatabase(\fIscreen\fP) +.br + Screen *\fIscreen\fP; +.FN +.IP \fIscreen\fP 1i +Specifies the screen whose resource database is to be returned. +.LP +.eM +The +.PN XtScreenDatabase +function returns the fully merged resource database as specified above, +associated with the specified screen. If the specified \fIscreen\fP +does not belong to a +.PN Display +initialized by +.PN XtDisplayInitialize , +the results are undefined. +.sp +.LP +To obtain the default resource database associated with a particular display, use +.PN XtDatabase . +.LP +.IN "XtDatabase" "" "@DEF@" +.sM +.FD 0 +XrmDatabase XtDatabase(\fIdisplay\fP) +.br + Display *\fIdisplay\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display. +.LP +.eM +The +.PN XtDatabase +function is equivalent to +.PN XrmGetDatabase . +It returns the database associated with the specified display, or +NULL if a database has not been set. +.sp +.LP +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 +.PN XtAppSetFallbackResources . +.LP +.IN "XtAppSetFallbackResources" "" "@DEF@" +.sM +.FD 0 +void XtAppSetFallbackResources(\fIapp_context\fP, \fIspecification_list\fP) +.br + XtAppContext \fIapp_context\fP; +.br + String *\fIspecification_list\fP; +.FN +.IP \fIapp_context\fP 1.25i +Specifies the application context in which +the fallback specifications will be used. +.IP \fIspecification_list\fP 1.25i +Specifies a NULL-terminated list of +resource specifications to preload +the database, or NULL. +.LP +.eM +Each entry in \fIspecification_list\fP points to a string in the format of +.PN XrmPutLineResource . +Following a call to +.PN XtAppSetFallbackResources , +when a resource database is being created for a particular screen and +the \*(xI are not able +to find or read an application-specific class resource file according to the +rules given above and if \fIspecification_list\fP is not NULL, the +resource specifications in \fIspecification_list\fP will be merged +into the screen resource database in place of the application-specific +class resource file. +.PN XtAppSetFallbackResources +is not +required to copy \fIspecification_list\fP; 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 +.PN XtAppSetFallbackResources +is called again. The value NULL for +\fIspecification_list\fP removes any previous fallback resource specification +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 problem +exists in finding and loading the application defaults file. + +.NH 2 +Parsing the Command Line +.XS +\fB\*(SN Parsing the Command Line\fP +.XE +.LP +The +.PN XtOpenDisplay +function first parses the command line for the following options: +.IP \-display 1i +Specifies the display name for +.PN XOpenDisplay . +.IP \-name 1i +Sets the resource name prefix, +which overrides the application name passed to +.PN XtOpenDisplay . +.IP \-xnllanguage 1i +Specifies the initial language string for establishing locale +and for finding application class resource files. +.LP +.PN XtDisplayInitialize +has a table of standard command line options that are passed to +.PN XrmParseCommand +for adding resources to the resource database, +and it takes as a parameter additional +application-specific resource abbreviations. +.IN "XrmOptionDescRec" "" "@DEF@" +The format of this table is described in Section 15.9 in \fI\*(xL\fP. +.LP +.sM +.Ds 0 +.TA .5i 2.75i +.ta .5i 2.75i +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; + +.De +.LP +.eM +The standard table contains the following entries: +.TS H +l l l l . +_ +.sp 6p +.TH +Option String Resource Name Argument Kind Resource Value +.sp 6p +_ +.sp 6p +\-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 +\-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 +.sp 6p +_ +.TE +.LP +Note that any unique abbreviation for an option name in the standard table +or in the application table is accepted. +.LP +If reverseVideo is +.PN True , +the values of +.PN XtDefaultForeground +and +.PN XtDefaultBackground +are exchanged for all screens on the Display. +.LP +.IN "synchronous" "" "@DEF@" +.IN "Resources" "synchronous" +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, +.PN XtDisplayInitialize +makes a call to +.PN XSynchronize +for all display +connections currently open in the application context. Therefore, +when multiple displays are initialized in the same application +context, the most recent value specified for the synchronous resource +is used for all displays in the application context. +.LP +.IN "selectionTimeout" "" "@DEF@" +.IN "Resources" "selectionTimeout" +The value of the selectionTimeout resource applies to all displays +opened in the same application context. When multiple displays are +initialized in the same application context, the most recent value +specified is used for all displays in the application context. +.LP +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 +.PN xmh , +you can start it up as +.LP +.Ds +xmh \-xrm 'xmh*Command.background: red' +.DE +.LP +When it parses the command line, +.PN XtDisplayInitialize +merges the application option table with the standard option table +before calling the Xlib +.PN XrmParseCommand +function. +An entry in the application table with the same name as an entry +in the standard table overrides the standard table entry. +If an option name is a prefix of another option name, +both names are kept in the merged table. +The \*(xI reserve all option names +beginning with the characters ``-xt'' for future standard uses. + +.NH 2 +Creating Widgets +.XS +\fB\*(SN Creating Widgets\fP +.XE +.LP +The creation of widget instances is a three-phase process: +.IP 1. 5 +The widgets are allocated and initialized with resources +and are optionally added to the managed subset of their parent. +.IP 2. 5 +All composite widgets are notified of their managed children +in a bottom-up traversal of the widget tree. +.IP 3. 5 +The widgets create X windows, which then are mapped. +.LP +.EQ +delim $$ +.EN +To start the first phase, +the application calls +.PN XtCreateWidget +for all its widgets and adds some (usually, most or all) of its widgets +to their respective parents' managed set by calling +.PN XtManageChild . +To avoid an $O( n sup 2 )$ creation process where each composite widget +lays itself out each time a widget is created and managed, +parent widgets are not notified of changes in their managed set +during this phase. +.EQ +delim off +.EN +.LP +After all widgets have been created, +the application calls +.PN XtRealizeWidget +with the top-level widget to execute the second and third phases. +.PN XtRealizeWidget +first recursively traverses the widget tree in a postorder (bottom-up) +traversal and then notifies each composite widget with one +or more managed children by means of its change_managed procedure. +.LP +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 example, 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 directions through the widget tree. +The parent may force some of its children to change size and position +and may issue geometry requests to its own parent in order to better +accommodate all its children. +You cannot predict where anything will go on the screen +until this process finishes. +.LP +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. +.LP +Finally, +.PN XtRealizeWidget +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 procedure, and finally maps the widgets that are managed. + +.NH 3 +Creating and Merging Argument Lists +.XS +\fB\*(SN Creating and Merging Argument Lists\fP +.XE +.LP +Many \*(xI functions may be passed pairs of resource names and +values. +These are passed as an arglist, a pointer to an array of +.PN Arg +structures, which contains +.IN "ArgList" "" "@DEF@" +.IN "Arg" "" "@DEF@" +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + String name; + XtArgVal value; +} Arg, *ArgList; +.De +.LP +.eM +where +.PN XtArgVal +is as defined in Section 1.5. +.LP +If the size of the resource is less than or equal to the size of an +.PN XtArgVal , +the resource value is stored directly in \fIvalue\fP; +otherwise, a pointer to it is stored in \fIvalue\fP. +.LP +To set values in an +.PN ArgList , +use +.PN XtSetArg . +.LP +.IN "XtSetArg" "" "@DEF@" +.sM +.FD 0 +void XtSetArg(\fIarg\fP, \fIname\fP, \fIvalue\fP) +.br + Arg \fIarg\fP; +.br + String \fIname\fP; +.br + XtArgVal \fIvalue\fP; +.FN +.IP \fIarg\fP 1i +Specifies the \fIname/value\fP pair to set. +.IP \fIname\fP 1i +Specifies the name of the resource. +.IP \fIvalue\fP 1i +Specifies the value of the resource if it will fit in an +.PN XtArgVal , +else the address. +.LP +.eM +The +.PN XtSetArg +function is usually used in a highly stylized manner to +minimize the probability of making a mistake; for example: +.LP +.Ds +.TA .5i 3i +.ta .5i 3i +Arg args[20]; +int n; + +n = 0; +XtSetArg(args[n], XtNheight, 100); n++; +XtSetArg(args[n], XtNwidth, 200); n++; +XtSetValues(widget, args, n); +.De +.LP +Alternatively, an application can statically declare the argument list +and use +.PN XtNumber : +.LP +.Ds +.TA .5i 3i +.ta .5i 3i +static Args args[] = { + {XtNheight, (XtArgVal) 100}, + {XtNwidth, (XtArgVal) 200}, +}; +XtSetValues(Widget, args, XtNumber(args)); +.De +.LP +Note that you should not use expressions with side effects such as +auto-increment or auto-decrement +within the first argument to +.PN XtSetArg . +.PN XtSetArg +can be implemented as a macro that evaluates the first argument twice. +.sp +.LP +To merge two +arglist arrays, use +.PN XtMergeArgLists . +.LP +.IN "XtMergeArgLists" "" "@DEF@" +.sM +.FD 0 +ArgList XtMergeArgLists(\fIargs1\fP, \fInum_args1\fP, \fIargs2\fP, \ +\fInum_args2\fP) +.br + ArgList \fIargs1\fP; +.br + Cardinal \fInum_args1\fP; +.br + ArgList \fIargs2\fP; +.br + Cardinal \fInum_args2\fP; +.FN +.IP \fIargs1\fP 1i +Specifies the first argument list. +.IP \fInum_args1\fP 1i +Specifies the number of entries in the first argument list. +.IP \fIargs2\fP 1i +Specifies the second argument list. +.IP \fInum_args2\fP 1i +Specifies the number of entries in the second argument list. +.LP +.eM +The +.PN XtMergeArgLists +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 +.PN XtFree . +.sp +.LP +.IN "varargs" "" "@DEF@" +All \*(xI interfaces that require +.PN ArgList +arguments have analogs +conforming to the ANSI C variable argument list +(traditionally called ``varargs'') +calling convention. The name of the analog is formed by prefixing +``Va'' to the name of the corresponding +.PN ArgList +procedure; e.g., +.PN XtVaCreateWidget . +Each procedure named \fBXtVa\fP\fIsomething\fP takes as its +last arguments, in place of the corresponding +.PN ArgList / +.PN Cardinal +parameters, a variable parameter list of resource name and +value pairs where each name is of type +.PN String +and each value is of type +.PN XtArgVal . +The end of the list is identified by a \fIname\fP 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 +.PN ArgList +and varargs forms interchangeably. +.LP +Two special names are defined for use only in varargs lists: +.PN XtVaTypedArg +and +.PN XtVaNestedList . +.sp +.LP +.IN "XtVaTypedArg" "" "@DEF@" +.sM +.Ds 0 +#define XtVaTypedArg "XtVaTypedArg" +.De +.LP +.eM +If the name +.PN XtVaTypedArg +is specified in place of a resource +name, then the following four arguments are interpreted as a +\fIname/type/value/size\fP tuple \fIwhere\fP name is of type +.PN String , +\fItype\fP is of type +.PN String , +\fIvalue\fP is of type +.PN XtArgVal , +and \fIsize\fP is of type int. When a varargs list containing +.PN XtVaTypedArg +is processed, a resource type +conversion (see Section 9.6) is performed if necessary to convert the +value into the format required by the associated resource. If \fItype\fP is +XtRString, then \fIvalue\fP contains a pointer to the string and \fIsize\fP +contains the number of bytes allocated, including the trailing null +byte. If \fItype\fP is not XtRString, then \fIif\fP size is +less than or equal to +\fBsizeof\fP(\fBXtArgVal\fP), the value should be the data cast to the type +.PN XtArgVal , +otherwise \fIvalue\fP 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. +.sp +.LP +.IN "XtVaNestedList" "" "@DEF@" +.sM +.Ds 0 +#define XtVaNestedList "XtVaNestedList" +.De +.LP +.eM +If the name +.PN XtVaNestedList +is specified in place of a resource name, +then the following argument is interpreted as an +.PN XtVarArgsList +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 identified with a +name entry containing NULL. Varargs lists may nest to any depth. +.sp +.LP +To dynamically allocate a varargs list for use with +.PN XtVaNestedList +in multiple calls, use +.PN XtVaCreateArgsList . +.IN "XtVaCreateArgsList" "" "@DEF@" +.sp +.LP +.sM +.Ds 0 +typedef XtPointer XtVarArgsList; +.De +.LP +.FD 0 +XtVarArgsList XtVaCreateArgsList(\fIunused\fP, ...) +.br + XtPointer \fIunused\fP; +.FN +.IP \fIunused\fP 1i +This argument is not currently used and must be specified as NULL. +.IP ... 1i +Specifies a variable parameter list of resource +name and value pairs. +.LP +.eM +The +.PN XtVaCreateArgsList +function allocates memory and copies its arguments into a +single list pointer, which may be used with +.PN XtVaNestedList . +The end of +both lists is identified by a \fIname\fP entry containing NULL. Any entries +of type +.PN XtVaTypedArg +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 +.PN XtFree +when no longer needed. +.LP +Use of resource files and of the resource database is generally +encouraged over lengthy arglist or varargs lists whenever possible in +order to permit modification without recompilation. + +.NH 3 +Creating a Widget Instance +.XS +\fB\*(SN Creating a Widget Instance\fP +.XE +.LP +To create an instance of a widget, use +.PN XtCreateWidget . +.LP +.IN "XtCreateWidget" "" "@DEF@" +.sM +.FD 0 +Widget XtCreateWidget(\fIname\fP, \fIobject_class\fP, \fIparent\fP, \ +\fIargs\fP, \fInum_args\fP) +.br + String \fIname\fP; +.br + WidgetClass \fIobject_class\fP; +.br + Widget \fIparent\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIname\fP 1i +Specifies the resource instance name for the created 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. +.IP \fIobject_class\fP 1i +Specifies the widget class pointer for the created object. \*(oC +.IP \fIparent\fP 1i +Specifies the parent widget. \*(oI +.IP \fIargs\fP 1i +Specifies the argument list to override any other resource specifications. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtCreateWidget +function performs all the boilerplate operations of widget +creation, doing the following in order: +.IP \(bu 5 +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. +.IP \(bu 5 +If the specified class is not +.PN coreWidgetClass +or a subclass thereof, +and the parent's class is a subclass of +.PN compositeWidgetClass +and either no extension record in +the parent's composite class part extension field exists with the +\fIrecord_type\fP +.PN \s-1NULLQUARK\s+1 +or the \fIaccepts_objects\fP field in the extension +record is +.PN False , +.PN XtCreateWidget +issues a fatal error; see Section 3.1 and Chapter 12. +.IP \(bu 5 +If the specified class contains an extension record in the object class +part \fIextension\fP field with \fIrecord_type\fP +.PN \s-1NULLQUARK\s+1 +and the \fIallocate\fP field is not NULL, +the procedure is invoked to allocate memory +for the widget instance. If the parent is a member of the class +.PN constraintWidgetClass , +the procedure also allocates memory for the +parent's constraints and stores the address of this memory into the +\fIconstraints\fP field. If no allocate procedure is found, the \*(xI +allocate memory for the widget and, when applicable, the constraints, +and initializes the \fIconstraints\fP field. +.IP \(bu 5 +Initializes the Core nonresource data fields +\fIself\fP, \fIparent\fP, \fIwidget_class\fP, \fIbeing_destroyed\fP, +\fIname\fP, \fImanaged\fP, \fIwindow\fP, \fIvisible\fP, +\fIpopup_list\fP, and \fInum_popups\fP. +.IP \(bu 5 +Initializes the resource fields (for example, \fIbackground_pixel\fP) +by using the +.PN CoreClassPart +resource lists specified for this class and all superclasses. +.IP \(bu 5 +If the parent is a member of the class +.PN constraintWidgetClass , +initializes the resource fields of the constraints record +by using the +.PN ConstraintClassPart +resource lists specified for the parent's class +and all superclasses up to +.PN constraintWidgetClass . +.IP \(bu 5 +Calls the initialize procedures for the widget starting at the +Object +initialize procedure on down to the widget's initialize procedure. +.IP \(bu 5 +If the parent is a member of the class +.PN constraintWidgetClass , +calls the +.PN ConstraintClassPart +initialize procedures, +starting at +.PN constraintWidgetClass +on down to the parent's +.PN ConstraintClassPart +initialize procedure. +.IP \(bu 5 +If the parent is a member of the class +.PN compositeWidgetClass , +puts the widget into its parent's children list by calling its parent's +insert_child procedure. +For further information, +see Section 3.1. +.sp +.LP +To create an instance of a widget using varargs lists, use +.PN XtVaCreateWidget . +.LP +.IN "XtVaCreateWidget" "" "@DEF@" +.sM +.FD 0 +Widget XtVaCreateWidget(\fIname\fP, \fIobject_class\fP, \fIparent\fP, ...) +.br + String \fIname\fP; +.br + WidgetClass \fIobject_class\fP; +.br + Widget \fIparent\fP; +.FN +.IP \fIname\fP 1i +Specifies the resource name for the created widget. +.IP \fIobject_class\fP 1i +Specifies the widget class pointer for the created object. \*(oC +.IP \fIparent\fP 1i +Specifies the parent widget. \*(oI +.IP ... 1i +Specifies the variable argument list to override any other +resource specifications. +.LP +.eM +The +.PN XtVaCreateWidget +procedure is identical in function to +.PN XtCreateWidget +with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, +as described +in Section 2.5.1. + +.NH 3 +Creating an Application Shell Instance +.XS +\fB\*(SN Creating an Application Shell Instance\fP +.XE +.LP +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 +.PN XtAppCreateShell +to create independent widget trees. +.LP +.IN "XtAppCreateShell" "" "@DEF@" +.sM +.FD 0 +Widget XtAppCreateShell(\fIname\fP, \ +\fIapplication_class\fP, \fIwidget_class\fP, \fIdisplay\fP, \ +\fIargs\fP, \fInum_args\fP) +.br + String \fIname\fP; +.br + String \fIapplication_class\fP; +.br + WidgetClass \fIwidget_class\fP; +.br + Display *\fIdisplay\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIname\fP 1.25i +Specifies the instance name of the shell widget. +If \fIname\fP is NULL, +the application name passed to +.PN XtDisplayInitialize +is used. +.IP \fIapplication_class\fP 1.25i +Specifies the resource class string to be used in +place of the widget \fIclass_name\fP string when +\fIwidget_class\fP is +.PN applicationShellWidgetClass +or a subclass thereof. +.IP \fIwidget_class\fP 1.25i +Specifies the widget class for the top-level widget (e.g., +.PN applicationShellWidgetClass ). +.IP \fIdisplay\fP 1.25i +Specifies the display for the default screen +and for the resource database used to retrieve +the shell widget resources. +.IP \fIargs\fP 1.25i +Specifies the argument list to override any other resource specifications. +.IP \fInum_args\fP 1.25i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtAppCreateShell +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 +\fIargs\fP 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 \fIname\fP.screen, +class \fIClass\fP.Screen where \fIClass\fP is the specified +\fIapplication_class\fP if \fIwidget_class\fP is +.PN applicationShellWidgetClass +or a subclass thereof. If \fIwidget_class\fP is not +.PN application\%Shell\%Widget\%Class +or a subclass, \fIClass\fP is the \fIclass_name\fP +field from the +.PN CoreClassPart +of the specified \fIwidget_class\fP. +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 +\fIargs\fP. The widget name and \fIClass\fP as determined above are +used as the leftmost (i.e., root) components in all fully qualified +resource names for objects within this widget tree. + +.LP +If the specified widget class is a subclass of WMShell, the name and +\fIClass\fP as determined above will be stored into the +.PN \s-1WM_CLASS\s+1 +property on the widget's window when it becomes realized. +If the specified \fIwidget_class\fP is +.PN applicationShellWidgetClass +or a subclass thereof, the +.PN \s-1WM_COMMAND\s+1 +property will also be set from the values of the XtNargv and +XtNargc resources. + +.LP +To create multiple top-level shells within a single (logical) +application, +you can use one of two methods: +.IP \(bu 5 +Designate one shell as the real top-level shell and +create the others as pop-up children of it by using +.PN XtCreatePopupShell . +.IP \(bu 5 +Have all shells as pop-up children of an unrealized top-level shell. +.LP +The first method, +which is best used when there is a clear choice for what is the main window, +leads to resource specifications like the following: +.LP +.Ds +.TA 2i +.ta 2i +xmail.geometry:... (the main window) +xmail.read.geometry:... (the read window) +xmail.compose.geometry:... (the compose window) +.De +.LP +The second method, +which is best if there is no main window, +leads to resource specifications like the following: +.LP +.Ds +.TA 2i +.ta 2i +xmail.headers.geometry:... (the headers window) +xmail.read.geometry:... (the read window) +xmail.compose.geometry:... (the compose window) +.De +.sp +.LP +To create a top-level widget that is the root of a widget tree using +varargs lists, use +.PN XtVaAppCreateShell . +.LP +.IN "XtVaAppCreateShell" "" "@DEF@" +.sM +.FD 0 +Widget XtVaAppCreateShell(\fIname\fP, \fIapplication_class\fP, \ +\fIwidget_class\fP, \fIdisplay\fP, ...) +.br + String \fIname\fP; +.br + String \fIapplication_class\fP; +.br + WidgetClass \fIwidget_class\fP; +.br + Display *\fIdisplay\fP; +.FN +.IP \fIname\fP 1.5i +Specifies the instance name of the shell widget. +If \fIname\fP is NULL, +the application name passed to +.PN XtDisplayInitialize +is used. +.IP \fIapplication_class\fP 1.5i +Specifies the resource class string to be used in +place of the widget \fIclass_name\fP string when +\fIwidget_class\fP is +.PN applicationShellWidgetClass +or a subclass thereof. +.IP \fIwidget_class\fP 1.5i +Specifies the widget class for the top-level widget. +.IP \fIdisplay\fP 1.5i +Specifies the display for the default screen +and for the resource database used to retrieve +the shell widget resources. +.IP ... 1.5i +Specifies the variable argument list to override any other +resource specifications. +.LP +.eM +The +.PN XtVaAppCreateShell +procedure is identical in function to +.PN XtAppCreateShell +with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as +described in Section 2.5.1. + +.NH 3 +Convenience Procedure to Initialize an Application +.XS +\fB\*(SN Convenience Procedure to Initialize an Application\fP +.XE +.LP +To initialize the \*(xI internals, create an application context, +open and initialize a display, and create the initial root shell +instance, an application may use +.PN XtOpenApplication +or +.PN XtVaOpenApplication . +.LP +.IN "XtOpenApplication" "" "@DEF@" +.sM +.FD 0 +Widget XtOpenApplication(\fIapp_context_return\fP, \fIapplication_class\fP, \ +\fIoptions\fP, \fInum_options\fP, +.br + \fIargc_in_out\fP, \fIargv_in_out\fP, \ +\fIfallback_resources\fP, \fIwidget_class\fP, \fIargs\fP, \fInum_args\fP) +.br + XtAppContext *\fIapp_context_return\fP; +.br + String \fIapplication_class\fP; +.br + XrmOptionDescList \fIoptions\fP; +.br + Cardinal \fInum_options\fP; +.br + int *\fIargc_in_out\fP; +.br + String *\fIargv_in_out\fP; +.br + String *\fIfallback_resources\fP; +.br + WidgetClass \fIwidget_class\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIapp_context_return\fP 1.5i +Returns the application context, if non-NULL. +.IP \fIapplication_class\fP 1.5i +Specifies the class name of the application. +.IP \fIoptions\fP 1.5i +Specifies the command line options table. +.IP \fInum_options\fP 1.5i +Specifies the number of entries in \fIoptions\fP. +.IP \fIargc_in_out\fP 1.5i +Specifies a pointer to the number of command line arguments. +.IP \fIargv_in_out\fP 1.5i +Specifies a pointer to the command line arguments. +.IP \fIfallback_resources\fP 1.5i +Specifies resource values to be used if the application class resource +file cannot be opened or read, or NULL. +.IP \fIwidget_class\fP 1.5i +Specifies the class of the widget to be created. Must be shellWidgetClass +or a subclass. +.br +.IP \fIargs\fP 1.5i +Specifies the argument list to override any +other resource specifications for the created shell widget. +.IP \fInum_args\fP 1.5i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtOpenApplication +function calls +.PN XtToolkitInitialize +followed by +.PN XtCreateApplicationContext , +then calls +.PN XtOpenDisplay +with \fIdisplay_string\fP NULL and +\fIapplication_name\fP NULL, and finally calls +.PN XtAppCreateShell +with \fIname\fP NULL, the specified \fIwidget_class\fP, +an argument list and count, +and returns the created shell. +The recommended \fIwidget_class\fP is +.PN sessionShellWidgetClass . +The argument list and count are created by merging +the specified \fIargs\fP and \fInum_args\fP with a list +containing the specified \fIargc\fP and \fIargv\fP. +The modified \fIargc\fP and \fIargv\fP returned by +.PN XtDisplayInitialize +are returned in \fIargc_in_out\fP and \fIargv_in_out\fP. If +\fIapp_context_return\fP 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 +.PN XtOpenApplication +terminates the application. If \fIfallback_resources\fP is non-NULL, +.PN XtAppSetFallbackResources +is called with the value prior to calling +.PN XtOpenDisplay . +.sp +.LP +.IN "XtVaOpenApplication" "" "@DEF@" +.sM +.FD 0 +Widget XtVaOpenApplication(\fIapp_context_return\fP, \fIapplication_class\fP, \ +\fIoptions\fP, \fInum_options\fP, +.br + \fIargc_in_out\fP, \fIargv_in_out\fP, \ +\fIfallback_resources\fP, \fIwidget_class\fP, ...) +.br + XtAppContext *\fIapp_context_return\fP; +.br + String \fIapplication_class\fP; +.br + XrmOptionDescList \fIoptions\fP; +.br + Cardinal \fInum_options\fP; +.br + int *\fIargc_in_out\fP; +.br + String *\fIargv_in_out\fP; +.br + String *\fIfallback_resources\fP; +.br + WidgetClass \fIwidget_class\fP; +.FN +.IP \fIapp_context_return\fP 1.5i +Returns the application context, if non-NULL. +.IP \fIapplication_class\fP 1.5i +Specifies the class name of the application. +.IP \fIoptions\fP 1.5i +Specifies the command line options table. +.IP \fInum_options\fP 1.5i +Specifies the number of entries in \fIoptions\fP. +.IP \fIargc_in_out\fP 1.5i +Specifies a pointer to the number of command line arguments. +.IP \fIargv_in_out\fP 1.5i +Specifies the command line arguments array. +.IP \fIfallback_resources\fP 1.5i +Specifies resource values to be used if the application class +resource file cannot be opened, or NULL. +.IP \fIwidget_class\fP 1.5i +Specifies the class of the widget to be created. Must be shellWidgetClass +or a subclass. +.IP ... 1.5i +Specifies the variable argument list to override any other +resource specifications for the created shell. +.LP +.eM +The +.PN XtVaOpenApplication +procedure is identical in function to +.PN XtOpenApplication +with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, +as described +in Section 2.5.1. + +.NH 3 +Widget Instance Allocation: The allocate Procedure +.XS +\*(SN Widget Instance Allocation: The allocate Procedure +.XE +.IN "Widget Allocation" +.LP +A widget class may optionally provide an instance allocation procedure +in the +.PN ObjectClassExtension +record. +.LP +When the call to create a widget includes a varargs list containing +.PN XtVaTypedArg , +these arguments will be passed to the allocation procedure in an +.PN XtTypedArgList . +.LP +.IN "XtTypedArgList" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + String name; + String type; + XtArgVal value; + int size; +} XtTypedArg, *XtTypedArgList; +.De +.LP +.eM +.IN "allocate procedure" "" "@DEF@" +The allocate procedure pointer in the +.PN ObjectClassExtension +record is of type +.PN XtAllocateProc . +.LP +.IN "XtAllocateProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtAllocateProc)(WidgetClass, Cardinal*, Cardinal*, ArgList, \ +Cardinal*, + XtTypedArgList, Cardinal*, \ +Widget*, XtPointer*); +.br + WidgetClass \fIwidget_class\fP; +.br + Cardinal* \fIconstraint_size\fP; +.br + Cardinal* \fImore_bytes\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal* \fInum_args\fP; +.br + XtTypedArgList \fItyped_args\fP, +.br + Cardinal* \fInum_typed_args\fP; +.br + Widget* \fInew_return\fP; +.br + XtPointer* \fImore_bytes_return\fP; +.FN +.IP \fIwidget_class\fP 1.5i +Specifies the widget class of the instance to allocate. +.IP \fIconstraint_size\fP 1.5i +Specifies the size of the constraint record to allocate, or 0. +.IP \fImore_bytes\fP 1.5i +Specifies the number of auxiliary bytes of memory to allocate. +.IP \fIargs\fP 1.5i +Specifies the argument list as given in the call to create the widget. +.IP \fInum_args\fP 1.5i +Specifies the number of arguments. +.IP \fItyped_args\fP 1.5i +Specifies the list of typed arguments given in the call to create the widget. +.IP \fInum_typed_args\fP 1.5i +Specifies the number of typed arguments. +.IP \fInew_return\fP 1.5i +Returns a pointer to the newly allocated instance, or NULL in case of error. +.IP \fImore_bytes_return\fP 1.5i +Returns the auxiliary memory if it was requested, or NULL +if requested and an error occurred; otherwise, unchanged. +.LP +.eM +At widget allocation time, if an extension record with \fIrecord_type\fP +equal to +.PN \s-1NULLQUARK\s+1 +is located through the object class part \fIextension\fP field +and the \fIallocate\fP field is not NULL, the +.PN XtAllocateProc +will be invoked to allocate memory for the widget. If no ObjectClassPart +extension record is declared with \fIrecord_type equal\fP to +.PN \s-1NULLQUARK\s+1 , +then +.PN XtInheritAllocate +and +.PN XtInheritDeallocate +are assumed. +If no +.PN XtAllocateProc +is found, the \*(xI will allocate memory for the widget. +.LP +An +.PN XtAllocateProc +must perform the following: +.IP \(bu 5 +Allocate memory for the widget instance and return it in \fInew_return\fP. +The memory must be at least \fIwc->core_class.widget_size\fP bytes in length, +double-word aligned. +.IP \(bu 5 +Initialize the \fIcore.constraints\fP field in the instance record to NULL +or to point to a constraint record. If \fIconstraint_size\fP +is not 0, the procedure must allocate memory for the constraint record. +The memory must be double-word aligned. +.IP \(bu 5 +If \fImore_bytes\fP is not 0, then the address of a block of memory +at least \fImore_bytes\fP in size, double-word aligned, must be +returned in the \fImore_bytes_return\fP parameter, +or NULL to indicate an error. +.LP +A class allocation procedure that envelops the allocation procedure of a +superclass must rely on the enveloped procedure 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. + +.NH 3 +Widget Instance Initialization: The initialize Procedure +.XS +\*(SN Widget Instance Initialization: The initialize Procedure +.XE +.IN "Initialization" +.IN "Chaining" +.IN "Superclass Chaining" +.IN "Inheritance" +.LP +The initialize procedure pointer in a widget class is of type +.PN XtInitProc . +.LP +.IN "XtInitProc" "" "@DEF@" +.IN "initialize procedure" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtInitProc)(Widget, Widget, ArgList, Cardinal*); +.br + Widget \fIrequest\fP; +.br + Widget \fInew\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal *\fInum_args\fP; +.FN +.IP \fIrequest\fP 1i +Specifies a copy of the widget with resource values as requested by the +argument list, the resource database, and the widget defaults. +.IP \fInew\fP 1i +Specifies the widget with the new values, both resource and nonresource, +that are actually allowed. +.IP \fIargs\fP 1i +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 +.PN XtVaTypedArg +are converted to the widget representation and the list is transformed +into the +.PN ArgList +format. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +An initialization procedure performs the following: +.IP \(bu 5 +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 +.PN String , +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. +.NT +It is not necessary to allocate space for or to copy callback lists. +.NE +.IP \(bu 5 +Computes values for unspecified resource fields. +For example, if \fIwidth\fP and \fIheight\fP are zero, +the widget should compute an appropriate width and height +based on its other resources. +.NT +A widget may directly assign only +its own \fIwidth\fP and \fIheight\fP within the initialize, initialize_hook, +set_values, and +set_values_hook procedures; see Chapter 6. +.NE +.IP \(bu 5 +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. +.LP +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. +.LP +Initialization procedures are called in superclass-to-subclass order +after all fields specified in the resource lists have been +initialized. The initialize procedure does not need to examine +\fIargs\fP and \fInum_args\fP +if all public resources are declared in the resource list. +Most of the initialization code for a specific widget class deals with fields +defined in that class and not with fields defined in its superclasses. +.LP +If a subclass does not need an initialization procedure +because it does not need to perform any of the above operations, +it can specify NULL for the \fIinitialize\fP field in the class record. +.LP +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. +.LP +As an example, +a subclass can visually surround its superclass display. +In this case, the width and height calculated by the superclass initialize +procedure are too small and need to be incremented by the size of the surround. +The subclass needs to know if its superclass's size was calculated by the +superclass or was specified explicitly. +All widgets must place themselves into whatever size is explicitly given, +but they should compute a reasonable size if no size is requested. +.LP +The \fIrequest\fP and \fInew\fP arguments provide the necessary information for +a subclass to determine the difference between an explicitly specified field +and a field computed by a superclass. +The \fIrequest\fP widget is a copy of the widget as initialized by the +arglist and resource database. +The \fInew\fP 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. +.LP +In the above example, +the subclass with the visual surround can see +if the \fIwidth\fP and \fIheight\fP in the \fIrequest\fP widget are zero. +If so, +it adds its surround size to the \fIwidth\fP and \fIheight\fP +fields in the \fInew\fP widget. +If not, it must make do with the size originally specified. +.LP +The \fInew\fP widget will become the actual widget instance record. +Therefore, +the initialization procedure should do all its work on the \fInew\fP widget; +the \fIrequest\fP widget should never be modified. +If the initialize procedure +needs to call any routines that operate on a widget, +it should specify \fInew\fP as the widget instance. + +.NH 3 +Constraint Instance Initialization: The ConstraintClassPart initialize Procedure +.XS +\*(SN Constraint Instance Initialization: The ConstraintClassPart initialize Procedure +.XE +.IN "Initialization" +.IN "XtInitProc" +.IN "initialize procedure" +.IN "Chaining" +.IN "Superclass Chaining" +.IN "Inheritance" +.LP +The constraint initialization procedure pointer, found in the +.PN ConstraintClassPart +\fIinitialize\fP field of the widget class record, is of type +.PN XtInitProc . +The values passed to the parent constraint initialization procedures +are the same as those passed to the child's class widget initialization +procedures. +.LP +The \fIconstraints\fP field of the \fIrequest\fP widget points to a copy of the +constraints record as initialized by the arglist and resource database. +.LP +The constraint initialization procedure should compute any constraint fields +derived from constraint resources. +It can make further changes to the \fInew\fP widget to make the widget +and any other constraint fields +conform to the specified constraints, for example, +changing the widget's size or position. +.LP +If a constraint class does not need a constraint initialization procedure, +it can specify NULL for the \fIinitialize\fP field of the +.PN ConstraintClassPart +in the class record. + +.NH 3 +Nonwidget Data Initialization: The initialize_hook Procedure +.XS +\*(SN Nonwidget Data Initialization: The initialize_hook Procedure +.XE +.IN "Initialization" +.LP +.NT +The initialize_hook procedure is obsolete, as the same information +is now available to the initialize procedure. The procedure has been +retained for those widgets that used it in previous releases. +.NE +.LP +The initialize_hook procedure pointer is of type +.PN XtArgsProc : +.LP +.IN "initialize_hook procedure" "" "@DEF@" +.IN "XtArgsProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtArgsProc)(Widget, ArgList, Cardinal*); +.br + Widget \fIw\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal *\fInum_args\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. +.IP \fIargs\fP 1i +Specifies the argument list passed by the client. +If the client created the widget using a varargs form, any resources +specified via +.PN XtVaTypedArg +are converted to the widget representation and the list is transformed +into the +.PN ArgList +format. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +If this procedure is not NULL, +it is called immediately after the corresponding initialize +procedure or in its place if the \fIinitialize\fP field is NULL. +.LP +The initialize_hook procedure allows a widget instance to initialize +nonresource data using information from the specified argument list +as if it were a resource. + +.NH 2 +Realizing Widgets +.XS +\fB\*(SN Realizing Widgets\fP +.XE +.LP +To realize a widget instance, use +.PN XtRealizeWidget . +.LP +.IN "XtRealizeWidget" "" "@DEF@" +.sM +.FD 0 +void XtRealizeWidget(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(cI +.eM +.LP +If the widget is already realized, +.PN XtRealizeWidget +simply returns. +Otherwise it performs the following: +.IP \(bu 5 +Binds all action names in the widget's +translation table to procedures (see Section 10.1.2). +.IP \(bu 5 +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. +.IP \(bu 5 +Constructs an +.PN XSetWindowAttributes +structure filled in with information derived from the +Core +widget fields and calls the realize procedure for the widget, +which adds any widget-specific attributes and creates the X window. +.IP \(bu 5 +If the widget is +not a subclass of +.PN compositeWidgetClass , +.PN XtRealizeWidget +returns; otherwise it continues and performs the following: +.RS +.IP \- 5 +Descends recursively to each of the widget's +managed children and calls the realize procedures. +Primitive widgets that instantiate children are responsible for realizing +those children themselves. +.IP \- 5 +Maps all of the managed children windows that have \fImapped_when_managed\fP +.PN True . +If a widget is managed but \fImapped_when_managed\fP is +.PN False , +the widget is allocated visual space but is not displayed. +.RE +.LP +If the widget is a top-level shell widget (that is, it has no parent), and +\fImapped_when_managed\fP is +.PN True , +.PN XtRealizeWidget +maps the widget window. +.LP +.PN XtCreateWidget , +.PN XtVaCreateWidget , +.PN XtRealizeWidget , +.PN XtManageChildren , +.PN XtUnmanage\%Children , +.PN XtUnrealizeWidget , +.PN XtSetMappedWhenManaged , +and +.PN XtDestroy\%Widget +maintain the following invariants: +.IP \(bu 5 +If a composite widget is realized, then all its managed children are realized. +.IP \(bu 5 +If a composite widget is realized, then all its managed children that have +\fImapped_when_managed\fP +.PN True +are mapped. +.LP +All \*(xI 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, +.PN XtRealizeWidget +calls the procedures in reverse order of +appearance in the +.PN CompositePart +\fIchildren\fP list. By default, this +ordering of the realize procedures will +result in the stacking order of any newly created subwindows being +top-to-bottom in the order of appearance on the list, and the most +recently created child will be at the bottom. +.sp +.LP +To check whether or not a widget has been realized, use +.PN XtIsRealized . +.LP +.IN "XtIsRealized" "" "@DEF@" +.sM +.FD 0 +Boolean XtIsRealized(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(oI +.LP +.eM +The +.PN XtIsRealized +function returns +.PN True +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. +.LP +Some widget procedures (for example, set_values) might wish to +operate differently +after the widget has been realized. + +.NH 3 +Widget Instance Window Creation: The realize Procedure +.XS +\*(SN Widget Instance Window Creation: The realize Procedure +.XE +.LP +The realize procedure pointer in a widget class is of type +.PN XtRealizeProc . +.LP +.IN "XtRealizeProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtRealizeProc)(Widget, XtValueMask*, XSetWindowAttributes*); +.br + Widget \fIw\fP; +.br + XtValueMask *\fIvalue_mask\fP; +.br + XSetWindowAttributes *\fIattributes\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. +.IP \fIvalue_mask\fP 1i +Specifies which fields in the \fIattributes\fP structure are used. +.IP \fIattributes\fP 1i +Specifies the window attributes to use in the +.PN XCreateWindow +call. +.LP +.eM +The realize procedure must create the widget's window. +.LP +Before calling the class realize procedure, the generic +.PN XtRealizeWidget +function fills in a mask and a corresponding +.PN XSetWindowAttributes +structure. +It sets the following fields in \fIattributes\fP and +corresponding bits in \fIvalue_mask\fP +based on information in the widget +core +structure: +.IP \(bu 5 +The \fIbackground_pixmap\fP (or \fIbackground_pixel\fP if \fIbackground_pixmap\fP is +.PN XtUnspecifiedPixmap ) +is filled in from the corresponding field. +.IP \(bu 5 +The \fIborder_pixmap\fP (or \fIborder_pixel\fP if \fIborder_pixmap\fP is +.PN XtUnspecifiedPixmap ) +is filled in from the corresponding field. +.IP \(bu 5 +The \fIcolormap\fP is filled in from the corresponding field. +.IP \(bu 5 +The \fIevent_mask\fP is filled in based on the event handlers registered, +the event translations specified, whether the \fIexpose\fP field is non-NULL, +and whether \fIvisible_interest\fP is +.PN True . +.IP \(bu 5 +The \fIbit_gravity\fP is set to +.PN NorthWestGravity +if the \fIexpose\fP field is NULL. +.LP +These or any other fields in attributes and the corresponding bits in +\fIvalue_mask\fP can be set by the realize procedure. +.LP +Note that because realize is not a chained operation, +the widget class realize procedure must update the +.PN XSetWindowAttributes +structure with all the appropriate fields from +non-Core +superclasses. +.LP +.IN "Inheritance" +A widget class can inherit its realize procedure from its superclass +during class initialization. +The realize procedure defined for +.PN coreWidgetClass +calls +.PN XtCreateWindow +with the passed \fIvalue_mask\fP and \fIattributes\fP +and with \fIwindow_class\fP and \fIvisual\fP set to +.PN CopyFromParent . +Both +.PN compositeWidgetClass +and +.PN constraintWidgetClass +inherit this realize procedure, and most new widget subclasses +can do the same (see Section 1.6.10). +.LP +The most common noninherited realize procedures set \fIbit_gravity\fP in the mask +and attributes to the appropriate value and then create the window. +For example, depending on its justification, Label might set \fIbit_gravity\fP to +.PN WestGravity , +.PN CenterGravity , +or +.PN EastGravity . +Consequently, shrinking it would just move the bits appropriately, +and no +exposure +event is needed for repainting. +.LP +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 +.PN XtRealizeWidget +on its children itself in the appropriate order from within its own +realize procedure. +.LP +Widgets that have children and whose class is not a subclass of +.PN compositeWidgetClass +are responsible for calling +.PN XtRealizeWidget +on their children, usually from within the realize procedure. +.LP +Realize procedures cannot manage or unmanage their descendants. + +.NH 3 +Window Creation Convenience Routine +.XS +\*(SN Window Creation Convenience Routine +.XE +.LP +Rather than call the Xlib +.PN XCreateWindow +.IN "realize procedure" +function explicitly, a realize procedure should normally call the \*(xI analog +.PN XtCreateWindow , +which simplifies the creation of windows for widgets. +.LP +.IN "XtCreateWindow" "" "@DEF@" +.sM +.FD 0 +void XtCreateWindow(\fIw\fP, \fIwindow_class\fP, \fIvisual\fP, \ +\fIvalue_mask\fP, \fIattributes\fP) +.br + Widget \fIw\fP; +.br + unsigned int \fIwindow_class\fP; +.br + Visual *\fIvisual\fP; +.br + XtValueMask \fIvalue_mask\fP; +.br + XSetWindowAttributes *\fIattributes\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget that defines the additional window attributed. \*(cI +.IP \fIwindow_class\fP 1i +Specifies the Xlib window class (for example, +.PN InputOutput , +.PN InputOnly , +or +.PN CopyFromParent ). +.IP \fIvisual\fP 1i +Specifies the visual type (usually +.PN CopyFromParent ). +.ds Vm attribute fields to use +.IP \fIvalue_mask\fP 1i +Specifies which fields in the \fIattributes\fP structure are used. +.IP \fIattributes\fP 1i +Specifies the window attributes to use in the +.PN XCreateWindow +call. +.LP +.eM +The +.PN XtCreateWindow +function calls the Xlib +.PN XCreateWindow +function with values from the widget structure and the passed parameters. +Then, it assigns the created window to the widget's \fIwindow\fP field. +.LP +.PN XtCreateWindow +evaluates the following fields of the widget core +structure: \fIdepth\fP, \fIscreen\fP, \fIparent->core.window\fP, \fIx\fP, +\fIy\fP, \fIwidth\fP, \fIheight\fP, and +\fIborder_width\fP. + +.NH 2 +Obtaining Window Information from a Widget +.XS +\fB\*(SN Obtaining Window Information from a Widget\fP +.XE +.LP +The +Core +widget class definition contains the screen and window ids. +The \fIwindow\fP field may be NULL for a while +(see Sections 2.5 and 2.6). +.LP +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. +.LP +.IN "XtDisplay" "" "@DEF@" +.sM +.FD 0 +Display *XtDisplay(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(cI +.LP +.eM +.PN XtDisplay +returns the display pointer for the specified widget. +.sp +.LP +.IN "XtParent" "" "@DEF@" +.sM +.FD 0 +Widget XtParent(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(oI +.LP +.eM +.PN XtParent +returns the parent object for the specified widget. The returned object +will be of class Object or a subclass. +.sp +.LP +.IN "XtScreen" "" "@DEF@" +.sM +.FD 0 +Screen *XtScreen(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(cI +.LP +.eM +.PN XtScreen +returns the screen pointer for the specified widget. +.sp +.LP +.IN "XtWindow" "" "@DEF@" +.sM +.FD 0 +Window XtWindow(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(cI +.LP +.eM +.PN XtWindow +returns the window of the specified widget. +.sp +.LP +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 +.PN XtDisplayOfObject , +.PN XtScreenOfObject , +and +.PN XtWindowOfObject . +.IN "XtDisplayOfObject" "" "@DEF@" +.sp +.LP +.sM +.FD 0 +Display *XtDisplayOfObject(\fIobject\fP) +.br + Widget \fIobject\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object. \*(oI +.LP +.eM +.PN XtDisplayOfObject +is identical in function to +.PN XtDisplay +if the object is a widget; otherwise +.PN XtDisplayOfObject +returns the display +pointer for the nearest ancestor of \fIobject\fP that is of class +Widget or a subclass thereof. +.LP +.IN "XtScreenOfObject" "" "@DEF@" +.sM +.FD 0 +Screen *XtScreenOfObject(\fIobject\fP) +.br + Widget \fIobject\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object. \*(oI +.LP +.eM +.PN XtScreenOfObject +is identical in function to +.PN XtScreen +if the object is a widget; otherwise +.PN XtScreenOfObject +returns the screen pointer +for the nearest ancestor of \fIobject\fP that is of class +Widget or a subclass thereof. +.LP +.IN "XtWindowOfObject" "" "@DEF@" +.sM +.FD 0 +Window XtWindowOfObject(\fIobject\fP) +.br + Widget \fIobject\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object. \*(oI +.LP +.eM +.PN XtWindowOfObject +is identical in function to +.PN XtWindow +if the object is a widget; otherwise +.PN XtWindowOfObject +returns the window for the nearest ancestor of \fIobject\fP that is of class +Widget or a subclass thereof. +.sp +.LP +To retrieve the instance name of an object, use +.PN XtName . +.LP +.IN "XtName" "" "@DEF@" +.sM +.FD 0 +String XtName(\fIobject\fP) +.br + Widget \fIobject\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object whose name is desired. \*(oI +.LP +.eM +.PN XtName +returns a pointer to the instance name of the specified object. +The storage is owned by the \*(xI and must not be modified. The +name is not qualified by the names of any of the object's ancestors. +.LP +Several window attributes are locally cached in the widget instance. +Thus, they can be set by the resource manager and +.PN XtSetValues +as well as used by routines that derive structures from these values +(for example, \fIdepth\fP for deriving pixmaps, +\fIbackground_pixel\fP for deriving GCs, and so on) or in the +.PN XtCreateWindow +call. +.LP +The \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, and \fIborder_width\fP +window attributes are available to +geometry managers. +These fields are maintained synchronously inside the \*(xI. +When an +.PN XConfigureWindow +is issued by the \*(xI on the widget's window (on request of its parent), +these values are updated immediately rather than some time later +when the server generates a +.PN ConfigureNotify +event. +(In fact, most widgets do not select +.PN SubstructureNotify +events.) +This ensures that all geometry calculations are based on the internally +consistent toolkit world rather than on either +an inconsistent world updated by asynchronous +.PN ConfigureNotify +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). + +.NH 3 +Unrealizing Widgets +.XS +\fB\*(SN Unrealizing Widgets\fP +.XE +.LP +To destroy the windows associated with a widget and its +non-pop-up descendants, use +.PN XtUnrealizeWidget . +.LP +.IN "XtUnrealizeWidget" "" "@DEF@" +.sM +.FD 0 +void XtUnrealizeWidget(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(cI +.LP +.eM +If the widget is currently unrealized, +.PN XtUnrealizeWidget +simply returns. Otherwise it performs the following: +.IP \(bu 5 +Unmanages the widget if the widget is managed. +.IP \(bu 5 +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 +.IN XtNunrealizeCallback +XtNunrealizeCallback +list. +.IN "unrealizeCallback" "" "@DEF@" +.IP \(bu 5 +Destroys the widget's window and any subwindows by calling +.PN XDestroyWindow +with the specified widget's \fIwindow\fP field. +.LP +Any events in the queue or which arrive following a call to +.PN XtUnrealizeWidget +will be dispatched as if the window(s) of the +unrealized widget(s) had never existed. + +.NH 2 +Destroying Widgets +.XS +\fB\*(SN Destroying Widgets\fP +.XE +.LP +The \*(xI provide support +.IP \(bu 5 +To destroy all the pop-up children of the widget being destroyed +and destroy all children of composite widgets. +.IP \(bu 5 +To remove (and unmap) the widget from its parent. +.IP \(bu 5 +To call the callback procedures that have been registered to trigger +when the widget is destroyed. +.IP \(bu 5 +To minimize the number of things a widget has to deallocate when destroyed. +.IP \(bu 5 +To minimize the number of +.PN XDestroyWindow +calls when destroying a widget tree. +.sp +.LP +To destroy a widget instance, use +.PN XtDestroyWidget . +.LP +.IN "XtDestroyWidget" "" "@DEF@" +.sM +.FD 0 +void XtDestroyWidget(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(oI +.LP +.eM +The +.PN XtDestroyWidget +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. +.LP +In phase 1, +.PN XtDestroyWidget +performs the following: +.IP \(bu 5 +If the \fIbeing_destroyed\fP field of the widget is +.PN True , +it returns immediately. +.IP \(bu 5 +Recursively descends the widget tree and +sets the \fIbeing_destroyed\fP field to +.PN True +for the widget and all normal and pop-up children. +.IP \(bu 5 +Adds the widget to a list of widgets (the destroy list) that should be +destroyed when it is safe to do so. +.LP +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. +.LP +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 managers, +that is, when the current invocation of +.PN XtDispatchEvent +is about to return, or immediately if not in +.PN XtDispatchEvent . +.LP +In phase 2, +.PN XtDestroyWidget +performs the following on each entry in the destroy list in the order +specified: +.IP \(bu 5 +If the widget is not a pop-up child and the widget's parent is a subclass of +.PN composite\%WidgetClass , +and if the parent is not being destroyed, +it calls +.PN XtUnmanageChild +on the widget and then calls the widget's parent's delete_child procedure +(see Section 3.3). +.IP \(bu 5 +Calls the destroy callback procedures registered on the widget +and all normal and pop-up descendants in postorder (it calls child +callbacks before parent callbacks). +.LP +The +.PN XtDestroyWidget +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: +.IP \(bu 5 +If the widget is not a pop-up child and the widget's parent is a subclass of +.PN constraint\%WidgetClass , +it calls the +.PN ConstraintClassPart +destroy procedure for the parent, +then for the parent's superclass, +until finally it calls the +.PN ConstraintClassPart +destroy procedure for +.PN constraintWidgetClass . +.IP \(bu 5 +Calls the +.PN CoreClassPart +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. Callback lists are deallocated. +.IP \(bu 5 +If the widget class object class part contains an +.PN ObjectClassExtension +record with the record_type +.PN \s-1NULLQUARK\s+1 +and the \fIdeallocate\fP field is not NULL, +calls the deallocate procedure to deallocate the instance and if one +exists, the constraint record. Otherwise, the \*(xI will deallocate +the widget instance record and if one exists, the constraint record. +.IP \(bu 5 +Calls +.PN XDestroyWindow +if the specified widget is realized (that is, has an X window). +The server recursively destroys all normal descendant windows. +(Windows of realized pop-up Shell children, and their +descendants, are destroyed by a shell class destroy procedure.) + +.NH 3 +Adding and Removing Destroy Callbacks +.XS +\fB\*(SN Adding and Removing Destroy Callbacks\fP +.XE +.LP +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. +.IN "Destroy Callbacks" +The destroy callback list is identified by the resource name +XtNdestroyCallback. +.LP +For example, the following adds an application-supplied destroy callback +procedure \fIClientDestroy\fP with client data to a widget by calling +.PN XtAddCallback . +.IN "XtAddCallback" +.Ds +XtAddCallback(\fIw\fP, XtNdestroyCallback, \fIClientDestroy\fP, \fIclient_data\fP) +.De +.LP +Similarly, the following removes the application-supplied destroy callback +procedure \fIClientDestroy\fP by calling +.PN XtRemoveCallback . +.IN "XtRemoveCallback" +.Ds +XtRemoveCallback(\fIw\fP, XtNdestroyCallback, \fIClientDestroy\fP, \fIclient_data\fP) +.De +.LP +The \fIClientDestroy\fP argument is of type +.PN XtCallbackProc ; +see Section 8.1. + +.NH 3 +Dynamic Data Deallocation: The destroy Procedure +.XS +\*(SN Dynamic Data Deallocation: The destroy Procedure +.XE +.LP +.IN "destroy procedure" "" "@DEF@" +The destroy procedure pointers in the +.PN ObjectClassPart , +.PN RectObjClassPart , +and +.PN CoreClassPart +structures are of type +.PN XtWidgetProc . +.LP +.IN "XtWidgetProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtWidgetProc)(Widget); +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget being destroyed. +.LP +.eM +The destroy procedures are called in subclass-to-superclass order. +Therefore, a widget's destroy procedure should deallocate only storage +that is specific to the subclass and should ignore the storage +allocated by any of its superclasses. +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. +.LP +Deallocating storage includes, but is not limited to, +the following steps: +.IP \(bu 5 +Calling +.PN XtFree +on dynamic storage allocated with +.PN XtMalloc , +.PN XtCalloc , +and so on. +.IP \(bu 5 +Calling +.PN XFreePixmap +on pixmaps created with direct X calls. +.IP \(bu 5 +Calling +.PN XtReleaseGC +on GCs allocated with +.PN XtGetGC . +.IP \(bu 5 +Calling +.PN XFreeGC +on GCs allocated with direct X calls. +.IP \(bu 5 +Calling +.PN XtRemoveEventHandler +on event handlers added to other widgets. +.IP \(bu 5 +Calling +.PN XtRemoveTimeOut +on timers created with +.PN XtAppAddTimeOut . +.IP \(bu 5 +Calling +.PN XtDestroyWidget +for each child if the widget has children +and is not a subclass of +.PN compositeWidgetClass . +.LP +During destroy phase 2 for each widget, the \*(xI 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. + +.NH 3 +Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure +.XS +\*(SN Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure +.XE +.LP +The constraint destroy procedure identified in the +.PN ConstraintClassPart +structure is called for a widget whose parent is a subclass of +.PN constraintWidgetClass . +This constraint destroy procedure pointer is of type +.PN XtWidgetProc . +The constraint destroy procedures are called in subclass-to-superclass order, +starting at the class of the widget's parent and ending at +.PN constraint\%WidgetClass . +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. +.LP +If a parent does not need to deallocate any constraint storage, +the constraint destroy procedure entry +in its class record can be NULL. + +.NH 3 +Widget Instance Deallocation: The deallocate Procedure +.XS +\*(SN Widget Instance Deallocation: The deallocate Procedure +.XE +.LP +.IN "deallocate procedure" "" "@DEF@" +The deallocate procedure pointer in the +.PN ObjectClassExtension +record is of type +.PN XtDeallocateProc . +.LP +.IN "XtDeallocateProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtDeallocateProc)(Widget, XtPointer); +.br + Widget \fIwidget\fP; +.br + XtPointer \fImore_bytes\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget being destroyed. +.IP \fImore_bytes\fP 1i +Specifies the auxiliary memory received from the corresponding allocator +along with the widget, or NULL. +.LP +.eM +When a widget is destroyed, if an +.PN ObjectClassExtension +record exists in the object class part \fIextension\fP field +with \fIrecord_type\fP +.PN \s-1NULLQUARK\s+1 +and the \fIdeallocate\fP field is not NULL, the +.PN XtDeallocateProc +will be called. +If no ObjectClassPart extension record is declared with \fIrecord_type\fP +equal to +.PN \s-1NULLQUARK\s+1 , +then +.PN XtInheritAllocate +and +.PN XtInheritDeallocate +are assumed. +The responsibilities of the deallocate procedure are to deallocate the +memory specified by \fImore_bytes\fP if it is not NULL, +to deallocate the constraints record as specified by the +widget's \fIcore.constraints\fP field if it is +not NULL, and to deallocate the widget instance itself. +.LP +If no +.PN XtDeallocateProc +is found, it is assumed that the \*(xI +originally allocated the memory and is responsible for freeing it. + +.NH 2 +Exiting from an Application +.XS +\fB\*(SN Exiting from an Application\fP +.XE +.LP +All \*(tk applications should terminate +by calling +.PN XtDestroyApplicationContext +and then exiting +using the +standard method for their operating system (typically, by calling +.PN exit +for POSIX-based systems). +The quickest way to make the windows disappear while exiting is to call +.PN XtUnmapWidget +on each top-level shell widget. +The \*(xI 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. +.LP +Depending upon the widget set in use, it may be necessary to explicitly +destroy individual widgets or widget trees with +.PN XtDestroyWidget +before calling +.PN XtDestroyApplicationContext +in order to ensure that any +required widget cleanup is properly 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. +.bp diff --git a/specs/CH03 b/specs/CH03 new file mode 100644 index 0000000..f96a797 --- /dev/null +++ b/specs/CH03 @@ -0,0 +1,1031 @@ +.\" $Xorg: CH03,v 1.3 2000/08/17 19:42:44 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 3\fP\s-1 + +\s+1\fBComposite Widgets and Their Children\fP\s-1 +.sp 2 +.nr H1 3 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 3 \(em Composite Widgets and Their Children +.XE +.IN "Composite widgets" +Composite widgets (widgets whose class is a subclass of +.PN compositeWidgetClass ) +can have an arbitrary number of children. +Consequently, they are responsible for much more than primitive widgets. +Their responsibilities (either implemented directly by the widget class +or indirectly by \*(xI functions) include: +.IP \(bu 5 +Overall management of children from creation to destruction. +.IP \(bu 5 +Destruction of descendants when the composite widget is destroyed. +.IP \(bu 5 +Physical arrangement (geometry management) of a displayable subset of +children (that is, the managed children). +.IP \(bu 5 +Mapping and unmapping of a subset of the managed children. +.LP +Overall management is handled by the generic procedures +.PN XtCreateWidget +and +.PN XtDestroyWidget . +.PN XtCreateWidget +adds children to their parent by calling the parent's insert_child +procedure. +.PN XtDestroyWidget +removes children from their parent by calling the parent's delete_child +procedure and ensures that all children of a destroyed composite widget +also get destroyed. +.LP +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 subset are called managed widgets +and enter into geometry manager calculations. +The other children are called unmanaged widgets +and, by definition, are not mapped by the \*(xI. +.LP +Children are added to and removed from their parent's managed set by using +.PN XtManageChild , +.PN XtManageChildren , +.PN XtUnmanageChild , +.PN XtUnmanageChildren , +and +.PN XtChangeManagedSet , +which notify the parent to recalculate the physical layout of its children +by calling the parent's change_managed procedure. +The +.PN XtCreateManagedWidget +convenience function calls +.PN XtCreateWidget +and +.PN XtManageChild +on the result. +.LP +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 \fImap_when_managed\fP field is +.PN False . +The default is +.PN True +and is changed by using +.PN XtSetMappedWhenManaged . +.LP +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: +.IP "Fixed boxes" 1.6i +Fixed boxes have a fixed number of children created by the parent. +All these children are managed, +and none ever makes geometry manager requests. +.IP "Homogeneous boxes" 1.6i +Homogeneous boxes treat all children equally and apply the same geometry +constraints to each child. +Many clients insert and delete widgets freely. +.IP "Heterogeneous boxes" 1.6i +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. +.IP "Shell boxes" 1.6i +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 +.PN ConfigureNotify +events when the window size is changed by the window manager. + +.NH 2 +Addition of Children to a Composite Widget: The insert_child Procedure +.XS +\*(SN Addition of Children to a Composite Widget: The insert_child Procedure +.XE +.LP +.IN "insert_child procedure" +To add a child to +the parent's list of children, the +.PN XtCreateWidget +function calls the parent's class routine insert_child. +The insert_child procedure pointer in a composite widget is of type +.PN XtWidgetProc . +.LP +.IN "insert_child procedure" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtWidgetProc)(Widget); +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Passes the newly created child. +.LP +.eM +Most composite widgets inherit their superclass's operation. +The insert_child routine in +.PN CompositeWidgetClass calls the insert_position procedure +and inserts the child at the specified position +in the \fIchildren\fP list, expanding it if necessary. +.LP +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 composite widget class that wishes +to allow nonwidget children (see Chapter 12) must specify a +.PN CompositeClassExtension +extension record as described +in Section 1.4.2.1 and set the \fIaccepts_objects\fP field in this record to +.PN True . +If the +.PN CompositeClassExtension +record is not specified or the +\fIaccepts_objects\fP field is +.PN False , +the composite widget can assume that all its children are of a subclass of Core +without an explicit subclass test in the insert_child procedure. +.LP +If there is not enough room to insert a new child in the \fIchildren\fP array +(that is, \fInum_children\fP is equal to \fInum_slots\fP), +the insert_child procedure must first reallocate the array +and update \fInum_slots\fP. +The insert_child procedure then places the child at the appropriate position +in the array and increments the \fInum_children\fP field. + +.NH 2 +Insertion Order of Children: The insert_position Procedure +.XS +\fB\*(SN Insertion Order of Children: The insert_position Procedure\fP +.XE +.LP +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 buttons that represent file names to be kept +in alphabetical order without constraining the order in which the +buttons are created. +.LP +An application controls the presentation order of a set of children by +supplying an +.IN XtNinsertPosition +XtNinsertPosition +resource. +The insert_position procedure pointer in a composite widget instance is of type +.PN XtOrderProc . +.LP +.IN "XtOrderProc" "" "@DEF@" +.sM +.FD 0 +typedef Cardinal (*XtOrderProc)(Widget); +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Passes the newly created widget. +.LP +.eM +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 procedure to determine where a new +child should go in its \fIchildren\fP 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. +.LP +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 \fInum_children\fP indicates that it should go after all other children. +The default insert_position function returns \fInum_children\fP +and can be overridden by a specific composite widget's resource list +or by the argument list provided when the composite widget is created. + +.NH 2 +Deletion of Children: The delete_child Procedure +.XS +\*(SN Deletion of Children: The delete_child Procedure +.XE +.LP +.IN "delete_child procedure" +.LP +To remove the child from the parent's \fIchildren\fP list, the +.PN XtDestroyWidget +function eventually causes a call to the Composite parent's class delete_child +procedure. +The delete_child procedure pointer is of type +.PN XtWidgetProc . +.LP +.IN "delete_child procedure" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtWidgetProc)(Widget); +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP +Passes the child being deleted. +.LP +.eM +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 companion widgets. + +.NH 2 +Adding and Removing Children from the Managed Set +.XS +\fB\*(SN Adding and Removing Children from the Managed Set\fP +.XE +.LP +The \*(xI 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. +.IN "change_managed procedure" +These generic routines eventually call the composite widget's change_managed +procedure if the procedure pointer is non-NULL. +The change_managed procedure pointer is of type +.PN XtWidgetProc . +The widget argument specifies the composite widget whose managed child +set has been modified. + +.NH 3 +Managing Children +.XS +\fB\*(SN Managing Children\fP +.XE +.LP +To add a list of widgets to the geometry-managed (and hence displayable) +subset of their Composite parent, use +.PN XtManageChildren . +.LP +.IN "XtManageChildren" "" "@DEF@" +.sM +.FD 0 +typedef Widget *WidgetList; +.sp +void XtManageChildren(\fIchildren\fP, \fInum_children\fP) +.br + WidgetList \fIchildren\fP; +.br + Cardinal \fInum_children\fP; +.FN +.IP \fIchildren\fP 1i +Specifies a list of child widgets. Each child must be of class +RectObj or any subclass thereof. +.IP \fInum_children\fP 1i +Specifies the number of children in the list. +.LP +.eM +The +.PN XtManageChildren +function performs the following: +.IP \(bu 5 +Issues an error if the children do not all have the same parent or +if the parent's class is not a subclass of +.PN compositeWidgetClass . +.IP \(bu 5 +Returns immediately if the common parent is being destroyed; +otherwise, for each unique child on the list, +.PN XtManageChildren +ignores the child if it already is managed or is being destroyed, +and marks it if not. +.IP \(bu 5 +If the parent is realized and after all children have been marked, +it makes some of the newly managed children viewable: +.RS +.IP \- 5 +Calls the change_managed routine of the widgets' parent. +.IP \- 5 +Calls +.PN XtRealizeWidget +on each previously unmanaged child that is unrealized. +.IP \- 5 +Maps each previously unmanaged child that has \fImap_when_managed\fP +.PN True . +.RE +.LP +Managing children is independent of the ordering of children and +independent of creating and deleting children. +The layout routine of the parent +should consider children whose \fImanaged\fP field is +.PN True +and should ignore all other children. +Note that some composite widgets, especially fixed boxes, call +.PN XtManageChild +from their insert_child procedure. +.LP +If the parent widget is realized, +its change_managed procedure 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 +.PN XtMoveWidget , +which first updates the \fIx\fP and \fIy\fP fields and which then calls +.PN XMoveWindow . +.LP +If the composite widget wishes to change the size or border width of any of +its children, it calls +.PN XtResizeWidget , +which first updates the +\fIwidth\fP, \fIheight\fP, and \fIborder_width\fP +fields and then calls +.PN XConfigureWindow . +Simultaneous repositioning and resizing may be done with +.PN XtConfigureWidget ; +see Section 6.6. +.sp +.LP +To add a single child to its parent widget's set of managed children, use +.PN XtManageChild . +.LP +.IN "XtManageChild" "" "@DEF@" +.sM +.FD 0 +void XtManageChild(\fIchild\fP) +.br + Widget \fIchild\fP; +.FN +.IP \fIchild\fP 1i +Specifies the child. \*(rI +.LP +.eM +The +.PN XtManageChild +function constructs a +.PN WidgetList +of length 1 and calls +.PN XtManageChildren . +.sp +.LP +To create and manage a child widget in a single procedure, use +.PN XtCreateManagedWidget +or +.PN XtVaCreateManagedWidget . +.LP +.IN "XtCreateManagedWidget" "" "@DEF@" +.sM +.FD 0 +Widget XtCreateManagedWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, \ +\fIargs\fP, \fInum_args\fP) +.br + String \fIname\fP; +.br + WidgetClass \fIwidget_class\fP; +.br + Widget \fIparent\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIname\fP 1i +Specifies the resource instance name for the created widget. +.IP \fIwidget_class\fP 1i +Specifies the widget class pointer for the created widget. \*(rC +.IP \fIparent\fP 1i +Specifies the parent widget. Must be of class Composite or any +subclass thereof. +.IP \fIargs\fP 1i +Specifies the argument list to override any other resource specifications. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtCreateManagedWidget +function is a convenience routine that calls +.PN XtCreateWidget +and +.PN XtManageChild . +.sp +.LP +.IN "XtVaCreateManagedWidget" "" "@DEF@" +.sM +.FD 0 +Widget XtVaCreateManagedWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, ...) +.br + String \fIname\fP; +.br + WidgetClass \fIwidget_class\fP; +.br + Widget \fIparent\fP; +.FN +.IP \fIname\fP 1i +Specifies the resource instance name for the created widget. +.IP \fIwidget_class\fP 1i +Specifies the widget class pointer for the created widget. \*(rC +.IP \fIparent\fP 1i +Specifies the parent widget. Must be of class Composite or any +subclass thereof. +.IP ... 1i +Specifies the variable argument list to override any other +resource specifications. +.LP +.eM +.PN XtVaCreateManagedWidget +is identical in function to +.PN XtCreateManagedWidget +with the \fIargs\fP and \fInum_args\fP parameters replaced +by a varargs list, as described in Section 2.5.1. + +.NH 3 +Unmanaging Children +.XS +\fB\*(SN Unmanaging Children\fP +.XE +.LP +To remove a list of children from a parent widget's managed list, use +.PN XtUnmanageChildren . +.LP +.IN "XtUnmanageChildren" "" "@DEF@" +.sM +.FD 0 +void XtUnmanageChildren(\fIchildren\fP, \fInum_children\fP) +.br + WidgetList \fIchildren\fP; +.br + Cardinal \fInum_children\fP; +.FN +.IP \fIchildren\fP 1i +Specifies a list of child widgets. Each child must be of class +RectObj or any subclass thereof. +.IP \fInum_children\fP 1i +Specifies the number of children. +.LP +.eM +The +.PN XtUnmanageChildren +function performs the following: +.IP \(bu 5 +Returns immediately if the common parent is being destroyed. +.IP \(bu 5 +Issues an error if the children do not all have the same parent +or if the parent is not a subclass of +.PN compositeWidgetClass . +.IP \(bu 5 +For each unique child on the list, +.PN XtUnmanageChildren +ignores the child if it is unmanaged; otherwise it performs the following: +.RS +.IP \- 5 +Marks the child as unmanaged. +.IP \- 5 +If the child is realized and the \fImap_when_managed\fP field is +.PN True , +it is unmapped. +.RE +.IP \(bu 5 +If the parent is realized and if any children have become unmanaged, +calls the change_managed routine of the widgets' parent. +.LP +.PN XtUnmanageChildren +does not destroy the child widgets. +Removing widgets from a parent's managed set is often a temporary banishment, +and some time later the client may manage the children again. +To destroy widgets entirely, +.PN XtDestroyWidget +should be called instead; +see Section 2.9. +.sp +.LP +To remove a single child from its parent widget's managed set, use +.PN XtUnmanageChild . +.LP +.IN "XtUnmanageChild" "" "@DEF@" +.sM +.FD 0 +void XtUnmanageChild(\fIchild\fP) +.br + Widget \fIchild\fP; +.FN +.IP \fIchild\fP 1i +Specifies the child. \*(rI +.LP +.eM +The +.PN XtUnmanageChild +function constructs a widget list +of length 1 and calls +.PN XtUnmanageChildren . +.LP +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. + +.NH 3 +Bundling Changes to the Managed Set +.XS +\fB\*(SN Bundling Changes to the Managed Set\fP +.XE +.LP +A client may simultaneously unmanage and manage children +with a single call to the \*(xI. 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 invocation. +.\" .LP +.\" The composite widget class specifies how its change_managed method +.\" should be invoked by declaring a +.\" .PN CompositeClassExtension +.\" structure as described in section 1.4.2.1. If the +.\" \fIallows_change_managed_set\fP field in the +.\" .PN CompositeClassExtension +.\" record is +.\" .PN False , +.\" the change_managed method will be invoked twice; once before any +.\" geometry changes are requested by the client callback and once +.\" after. If the \fIallows_change_managed_set\fP field is +.\" .PN True , +.\" the change_managed method will be invoked just once after the +.\" specified children have been marked as unmanaged or managed and +.\" the client's callback has been invoked. +.\" If no +.\" .PN CompositeClassExtension +.\" record is found in the extension field of the +.\" composite class part with record type +.\" .PN \s-1NULLQUARK\s+1 +.\" and version greater +.\" than 1 and if +.\" .PN XtInheritChangeManaged +.\" was specified in the class record during class initialization, the +.\" value of the \fIallows_change_managed_set\fP +.\" field will be inherited from the superclass. +.LP +To simultaneously remove from and add to the geometry-managed +set of children of a composite parent, use +.PN XtChangeManagedSet . +.LP +.IN "XtChangeManagedSet" "" "@DEF@" +.sM +.FD 0 +void XtChangeManagedSet(\fIunmanage_children\fP, \fInum_unmanage_children\fP, + \fIdo_change_proc\fP, \fIclient_data\fP, + \fImanage_children\fP, \fInum_manage_children\fP) +.br + WidgetList \fIunmanage_children\fP; +.br + Cardinal \fInum_unmanage_children\fP; +.br + XtDoChangeProc \fIdo_change_proc\fP; +.br + XtPointer \fIclient_data\fP; +.br + WidgetList \fImanage_children\fP; +.br + Cardinal \fInum_manage_children\fP; +.FN +.IP \fIunmanage_children\fP 1.8i +Specifies the list of widget children to initially remove from the managed set. +.IP \fInum_unmanage_children\fP 1.8i +Specifies the number of entries in the \fIunmanage_children\fP list. +.IP \fIdo_change_proc\fP 1.8i +Specifies a procedure to invoke between unmanaging +and managing the children, or NULL. +.IP \fIclient_data\fP 1.8i +Specifies client data to be passed to the do_change_proc. +.IP \fImanage_children\fP 1.8i +Specifies the list of widget children to finally add to the managed set. +.IP \fInum_manage_children\fP 1.8i +Specifies the number of entries in the \fImanage_children\fP list. +.LP +.eM +The +.PN XtChangeManagedSet +function performs the following: +.IP \(bu 5 +Returns immediately if \fInum_unmanage_children\fP and +\fInum_manage_children\fP are both 0. +.IP \(bu 5 +Issues a warning and returns if the widgets specified in the +\fImanage_children\fP and +the \fIunmanage_children\fP lists do not all have the same parent or if +that parent is not a subclass of +.PN compositeWidgetClass . +.IP \(bu 5 +Returns immediately if the common parent is being destroyed. +.IP \(bu 5 +If \fIdo_change_proc\fP is not NULL and the parent's +.PN CompositeClassExtension +\fIallows_change_managed_set\fP field is +.PN False , +then +.PN XtChangeManagedSet +performs the following: +.RS +.IP \- 5 +Calls +.PN XtUnmanageChildren +(\fIunmanage_children\fP, \fInum_unmanage_children\fP). +.IP \- 5 +Calls the \fIdo_change_proc\fP. +.IP \- 5 +Calls +.PN XtManageChildren +(\fImanage_children\fP, \fInum_manage_children\fP). +.RE +.IP \(bu 5 +Otherwise, the following is performed: +.RS +.IP \- 5 +For each child on the \fIunmanage_children\fP list; if the child is +already unmanaged it is ignored, otherwise it is marked as unmanaged, +and if it is realized and its \fImap_when_managed\fP field is +.PN True , +it is unmapped. +.IP \- 5 +If \fIdo_change_proc\fP is non-NULL, the procedure is invoked. +.IP \- 5 +For each child on the \fImanage_children\fP list; if the child is already +managed or is being destroyed, it is ignored; otherwise it is +marked as managed. +.IP \- 5 +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 calling +.PN XtRealizeWidget +on each previously unmanaged child that is unrealized and +mapping each previously unmanaged child that has \fImap_when_managed\fP +.PN True . +.RE +.LP +If no +.PN CompositeClassExtension +record is found in the parent's composite class part \fIextension\fP field +with record type +.PN \s-1NULLQUARK\s+1 +and version greater than 1, and if +.PN XtInheritChangeManaged +was specified in the parent's class record during class initialization, +the value of the \fIallows_change_managed_set\fP +field is inherited from the superclass. The value inherited from +.PN compositeWidgetClass +for the \fIallows_change_managed_set\fP field is +.PN False . +.LP +It is not an error to include a child in both the \fIunmanage_children\fP +and the \fImanage_children\fP lists. The effect of such a call is that +the child remains managed following the call, but the \fIdo_change_proc\fP is +able to affect the child while it is in an unmanaged state. +.sp +.LP +The \fIdo_change_proc\fP is of type +.PN XtDoChangeProc . +.LP +.IN "XtDoChangeProc" "" "@DEF" +.sM +.FD 0 +typedef void (*XtDoChangeProc)(Widget, WidgetList, Cardinal*, WidgetList, Cardinal*, XtPointer); +.br + Widget \fIcomposite_parent\fP; +.br + WidgetList \fIunmange_children\fP; +.br + Cardinal *\fInum_unmanage_children\fP; +.br + WidgetList \fImanage_children\fP; +.br + Cardinal *\fInum_manage_children\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIcomposite_parent\fP 1.8i +Passes the composite parent whose managed set is being altered. +.IP \fIunmanage_children\fP 1.8i +Passes the list of children just removed from the managed set. +.IP \fInum_unmanage_children\fP 1.8i +Passes the number of entries in the \fIunmanage_children\fP list. +.IP \fImanage_children\fP 1.8i +Passes the list of children about to be added to the managed set. +.IP \fInum_manage_children\fP 1.8i +Passes the number of entries in the \fImanage_children\fP list. +.IP \fIclient_data\fP 1.8i +Passes the client data passed to +.PN XtChangeManagedSet . +.LP +.eM +The \fIdo_change_proc\fP procedure is used by the caller of +.PN XtChangeManagedSet +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 +.PN XtChangeManagedSet +may take advantage of the fact that the \*(xI internally grant +geometry requests made by unmanaged children without invoking +the parent's geometry manager. To achieve this advantage, if +the \fIdo_change_proc\fP procedure +changes the geometry of a child or of a descendant of a child, then +that child should be included in the \fIunmanage_children\fP and +\fImanage_children\fP lists. + +.NH 3 +Determining if a Widget Is Managed +.XS +\fB\*(SN Determining if a Widget Is Managed\fP +.XE +.LP +To determine the managed state of a given child widget, use +.PN XtIsManaged . +.LP +.IN "XtIsManaged" "" "@DEF@" +.sM +.FD 0 +Boolean XtIsManaged(\fIw\fP) +.br + Widget \fIw\fP\^; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(oI +.LP +.eM +The +.PN XtIsManaged +function returns +.PN True +if the specified widget is of class RectObj or any subclass thereof +and is managed, or +.PN False +otherwise. + +.NH 2 +Controlling When Widgets Get Mapped +.XS +\fB\*(SN Controlling When Widgets Get Mapped\fP +.XE +.LP +A widget is normally mapped if it is managed. +However, +this behavior can be overridden by setting the XtNmappedWhenManaged resource +for the widget when it is created +or by setting the \fImap_when_managed\fP field to +.PN False . +.sp +.LP +To change the value of a given widget's \fImap_when_managed\fP field, use +.PN XtSetMappedWhenManaged . +.LP +.IN "XtSetMappedWhenManaged" "" "@DEF@" +.sM +.FD 0 +void XtSetMappedWhenManaged(\fIw\fP, \fImap_when_managed\fP) +.br + Widget \fIw\fP; +.br + Boolean \fImap_when_managed\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(cI +.IP \fImap_when_managed\fP 1i +Specifies a Boolean value that indicates the new value +that is stored into the widget's \fImap_when_managed\fP +field. +.LP +.eM +If the widget is realized and managed, +and if \fImap_when_managed\fP is +.PN True , +.PN XtSetMappedWhenManaged +maps the window. +If the widget is realized and managed, +and if \fImap_when_managed\fP is +.PN False , +it unmaps the window. +.PN XtSetMappedWhenManaged +is a convenience function that is equivalent to (but slightly faster than) +calling +.PN XtSetValues +and setting the new value for the XtNmappedWhenManaged resource +then mapping the widget as appropriate. +As an alternative to using +.PN XtSetMappedWhenManaged +to control mapping, +a client may set \fImapped_when_managed\fP to +.PN False +and use +.PN XtMapWidget +and +.PN XtUnmapWidget +explicitly. +.sp +.LP +To map a widget explicitly, use +.PN XtMapWidget . +.LP +.IN "XtMapWidget" "" "@DEF@" +.sM +.FD 0 +XtMapWidget(\fIw\fP) +.br + Widget \fIw\fP\^; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(cI +.LP +.eM +To unmap a widget explicitly, use +.PN XtUnmapWidget . +.LP +.IN "XtUnmapWidget" "" "@DEF@" +.sM +.FD 0 +XtUnmapWidget(\fIw\fP) +.br + Widget \fIw\fP\^; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(cI +.LP +.eM + +.NH 2 +Constrained Composite Widgets +.XS +\*(SN Constrained Composite Widgets +.XE +.LP +The Constraint +widget class is a subclass of +.PN compositeWidgetClass . +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. +.LP +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. +.LP +To make it easy for widgets and the \*(xI to keep track of the +constraints associated with a child, +every widget has a \fIconstraints\fP field, +which is the address of a parent-specific structure that contains +constraint information about the child. +If a child's parent does not belong to a subclass of +.PN constraintWidgetClass , +then the child's \fIconstraints\fP field is NULL. +.LP +Subclasses of +Constraint +can add constraint data to the constraint 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: +.LP +.Ds +.TA .5i 3i +.ta .5i 3i +typedef struct { + Dimension max_width, max_height; +} MaxConstraintPart; + +typedef struct { + MaxConstraintPart max; +} MaxConstraintRecord, *MaxConstraint; +.De +.LP +A subclass of this widget class that also needs to maintain a minimum size would +define its constraint record as follows: +.LP +.Ds +.TA .5i 3i +.ta .5i 3i +typedef struct { + Dimension min_width, min_height; +} MinConstraintPart; + +typedef struct { + MaxConstraintPart max; + MinConstraintPart min; +} MaxMinConstraintRecord, *MaxMinConstraint; +.De +.LP +Constraints are allocated, initialized, deallocated, and otherwise maintained +insofar as possible by the \*(xI. +The Constraint class record part has several entries that facilitate this. +All entries in +.PN ConstraintClassPart +are fields and procedures that are defined and implemented by the parent, +but they are called whenever actions are performed on the parent's children. +.LP +The +.PN XtCreateWidget +function uses the \fIconstraint_size\fP field in the parent's class record +to allocate a constraint record when a child is created. +.PN XtCreateWidget +also uses the constraint resources to fill in resource fields in the +constraint record associated with a child. +It then calls the constraint initialize procedure so that the parent +can compute constraint fields that are derived from constraint resources +and can possibly move or resize the child to conform to the given constraints. +.LP +When the +.PN XtGetValues +and +.PN XtSetValues +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. +.PN XtSetValues +then calls the constraint set_values procedures so that the parent can +recompute derived constraint fields and move or resize the child +as appropriate. +If a +Constraint +widget class or any of its superclasses have declared a +.PN ConstraintClassExtension +record in the +.PN ConstraintClassPart +\fIextension\fP +fields with a record type of +.PN \s-1NULLQUARK\s+1 +and the \fIget_values_hook\fP field in +.IN "get_values_hook procedure" +.IN "Constraint" "get_values_hook" +the extension record is non-NULL, +.PN XtGetValues +calls the get_values_hook +procedure(s) to allow the parent to return derived constraint fields. +.LP +The +.PN XtDestroyWidget +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; +.PN XtDestroyWidget +does this automatically. +.bp diff --git a/specs/CH04 b/specs/CH04 new file mode 100644 index 0000000..0291aa3 --- /dev/null +++ b/specs/CH04 @@ -0,0 +1,1998 @@ +.\" $Xorg: CH04,v 1.3 2000/08/17 19:42:44 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 4\fP\s-1 + +\s+1\fBShell Widgets\fP\s-1 +.sp 2 +.nr H1 4 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 4 \(em Shell Widgets +.XE +.IN "Shell" "" "@DEF@" +.LP +Shell widgets hold an application's top-level widgets to allow them to +communicate with the window manager and session 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. +.LP +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. +.LP +The five types of public shells are: +.TS +lw(1.5i) lw(4.25i). +T{ +.PN OverrideShell +T} T{ +Used for shell windows that completely bypass the window manager +(for example, pop-up menu shells). +T} +.sp +T{ +.PN TransientShell +T} T{ +Used for shell windows that have the +.PN \s-1WM_TRANSIENT_FOR\s+1 +property set. The effect of this property is dependent upon the +window manager being used. +T} +.sp +T{ +.PN TopLevelShell +T} T{ +Used for normal top-level windows +(for example, any additional top-level widgets an application needs). +T} +.sp +T{ +.PN ApplicationShell +T} T{ +Formerly used for the single main top-level window that +the window manager identifies as an application instance and +made obsolete by SessionShell. +T} +.IN "ApplicationShell" "" "@DEF@" +.sp +T{ +.PN SessionShell +T} T{ +Used for the single main top-level window that +the window manager identifies as an application instance and +that interacts with the session manager. +T} +.IN "SessionShell" "" "@DEF@" +.TE + +.NH 2 +Shell Widget Definitions +.XS +\*(SN Shell Widget Definitions +.XE +.LP +Widgets negotiate their size and position with their parent widget, +that is, the widget that directly contains them. +Widgets at the top of the hierarchy do not have parent widgets. +Instead, they must deal with the outside world. +To provide for this, +each top-level widget is encapsulated in a special widget, called a +shell widget. +.LP +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 window relationship. +They also can provide a layer of communication with the window manager. +.LP +The eight different types of shells are: +.TS +lw(1.5i) lw(4.5i). +T{ +.PN Shell +T} T{ +The base class for shell widgets; provides the +fields needed for all types of shells. +Shell +is a direct subclass of +.PN compositeWidgetClass . +T} +.sp 6p +T{ +.PN OverrideShell +T} T{ +A subclass of Shell; used for shell windows that completely +bypass the window manager. +T} +.sp 6p +T{ +.PN WMShell +T} T{ +A subclass of Shell; contains fields needed by the +common window manager protocol. +T} +.sp 6p +T{ +.PN VendorShell +T} T{ +A subclass of WMShell; contains fields used by +vendor-specific window managers. +T} +.sp 6p +T{ +.PN TransientShell +T} T{ +A subclass of VendorShell; used for shell windows that +desire the +.PN \s-1WM_TRANSIENT_FOR\s+1 +property. +T} +.sp 6p +T{ +.PN TopLevelShell +T} T{ +A subclass of VendorShell; used for normal top-level windows. +T} +.sp 6p +T{ +.PN ApplicationShell +T} T{ +A subclass of TopLevelShell; may be used for an application's additional +root windows. +T} +.sp 6p +T{ +.PN SessionShell +T} T{ +A subclass of ApplicationShell; used for an application's +main root window. +T} +.TE +.LP +Note that the classes +Shell, +WMShell, +and +VendorShell +are internal and should not be instantiated or subclassed. +Only +OverrrideShell, +TransientShell, +TopLevelShell, +ApplicationShell, +and +SessionShell +are intended for public use. + +.NH 3 +ShellClassPart Definitions +.XS +\*(SN ShellClassPart Definitions +.XE +.LP +Only the +Shell +class has additional class fields, which are all contained in the +.PN ShellClassExtensionRec . +None of the other Shell classes have any additional class fields: +.LP +.KS +.sM +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct { + XtPointer extension; +} ShellClassPart, OverrideShellClassPart, +WMShellClassPart, VendorShellClassPart, TransientShellClassPart, +TopLevelShellClassPart, ApplicationShellClassPart, SessionShellClassPart; +.De +.LP +.eM +.KE +The full Shell class record definitions are: +.IN "ShellClassExtension" "" "@DEF@" +.IN "ShellClassExtensionRec" "" "@DEF@" +.LP +.KS +.sM +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct _ShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; +} ShellClassRec; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +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; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct _OverrideShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + OverrideShellClassPart override_shell_class; +} OverrideShellClassRec; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct _WMShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + WMShellClassPart wm_shell_class; +} WMShellClassRec; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct _VendorShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + WMShellClassPart wm_shell_class; + VendorShellClassPart vendor_shell_class; +} VendorShellClassRec; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +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; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +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; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +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; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +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; +.De +.LP +.eM +.KE +.KS +The single occurrences of the class records and pointers for creating +instances of shells are: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +extern ShellClassRec shellClassRec; +extern OverrideShellClassRec overrideShellClassRec; +extern WMShellClassRec wmShellClassRec; +extern VendorShellClassRec vendorShellClassRec; +extern TransientShellClassRec transientShellClassRec; +extern TopLevelShellClassRec topLevelShellClassRec; +extern ApplicationShellClassRec applicationShellClassRec; +extern SessionShellClassRec sessionShellClassRec; +.sp +extern WidgetClass shellWidgetClass; +extern WidgetClass overrideShellWidgetClass; +extern WidgetClass wmShellWidgetClass; +extern WidgetClass vendorShellWidgetClass; +extern WidgetClass transientShellWidgetClass; +extern WidgetClass topLevelShellWidgetClass; +extern WidgetClass applicationShellWidgetClass; +extern WidgetClass sessionShellWidgetClass; +.De +.LP +.eM +.KE +.KS +The following opaque types and opaque variables are defined +for generic operations on widgets whose class is a subclass of +Shell. +.TS +lw(2.75i) lw(2.75i). +_ +.sp 6p +Types Variables +.sp 6p +_ +.sp 6p +T{ +.PN ShellWidget +T} T{ +.PN shellWidgetClass +T} +T{ +.PN OverrideShellWidget +T} T{ +.PN overrideShellWidgetClass +T} +T{ +.PN WMShellWidget +T} T{ +.PN wmShellWidgetClass +T} +T{ +.PN VendorShellWidget +T} T{ +.PN vendorShellWidgetClass +T} +T{ +.PN TransientShellWidget +T} T{ +.PN transientShellWidgetClass +T} +T{ +.PN TopLevelShellWidget +T} T{ +.PN topLevelShellWidgetClass +T} +T{ +.PN ApplicationShellWidget +T} T{ +.PN applicationShellWidgetClass +T} +T{ +.PN SessionShellWidget +T} T{ +.PN sessionShellWidgetClass +T} +.PN ShellWidgetClass +.PN OverrideShellWidgetClass +.PN WMShellWidgetClass +.PN VendorShellWidgetClass +.PN TransientShellWidgetClass +.PN TopLevelShellWidgetClass +.PN ApplicationShellWidgetClass +.PN SessionShellWidgetClass +.sp 6p +_ +.TE +.KE +.LP +The declarations for all Intrinsics-defined shells except +VendorShell appear in +.PN Shell.h +and +.PN ShellP.h . +VendorShell has separate public and private .h files which are included by +.PN Shell.h +and +.PN ShellP.h . +.LP +.PN Shell.h +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. +.LP +The symbolic constant for the +.PN ShellClassExtension +version identifier is +.PN XtShellExtensionVersion +(see Section 1.6.12). +.IN "XtShellExtensionVersion" "" "@DEF@" +.LP +.IN "Shell" "root_geometry_manager" +.IN "root_geometry_manager procedure" +The root_geometry_manager procedure acts as +the parent geometry manager for geometry requests made by shell +widgets. When a shell widget calls either +.PN XtMakeGeometryRequest +or +.PN XtMakeResizeRequest , +the root_geometry_manager procedure is invoked to +negotiate the new geometry with the window manager. If the window +manager permits the new geometry, the root_geometry_manager +procedure should +return +.PN XtGeometryYes ; +if the window manager denies the geometry +request or does not change the window geometry within some timeout +interval (equal to \fIwm_timeout\fP in the case of WMShells), the +.IN "Shell" "wm_timeout" "@DEF@" +.IN "wm_timeout" "" "@DEF@" +root_geometry_manager procedure should return +.PN XtGeometryNo . +If the window manager makes some alternative geometry change, the +root_geometry_manager procedure may return either +.PN XtGeometryNo +and handle the new geometry as a resize or +.PN XtGeometryAlmost +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_manager 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. +.LP +If no +.PN ShellClassPart +extension record is declared with \fIrecord_type\fP +equal to +.PN \s-1NULLQUARK\s+1 , +then +.PN XtInheritRootGeometryManager +is assumed. + +.NH 3 +ShellPart Definition +.XS +\*(SN ShellPart Definition +.XE +.LP +The various shell widgets have the following additional instance +fields defined in +their widget records: +.LP +.IN "ShellPart" "" "@DEF@" +.KS +.sM +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +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; +.De +.KE +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct { + int empty; +} OverrideShellPart; +.De +.Ds 0 +.TA .5i 1i 1.5i 2.5i +.ta .5i 1i 1.5i 2.5i +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; +.De +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct { + int vendor_specific; +} VendorShellPart; +.De +.KE +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct { + Widget transient_for; +} TransientShellPart; + +typedef struct { + String icon_name; + Boolean iconic; + Atom icon_name_encoding; +} TopLevelShellPart; +.De +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct { + char * class; + XrmClass xrm_class; + int argc; + char ** argv; +} ApplicationShellPart; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +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; +.De +.LP +.eM +.KE +.KS +The full shell widget instance record definitions are: +.LP +.IN "ShellWidget" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; +} ShellRec, *ShellWidget; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + OverrideShellPart override; +} OverrideShellRec, *OverrideShellWidget; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; +} WMShellRec, *WMShellWidget; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; +} VendorShellRec, *VendorShellWidget; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; + TransientShellPart transient; +} TransientShellRec, *TransientShellWidget; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; + TopLevelShellPart topLevel; +} TopLevelShellRec, *TopLevelShellWidget; +.De +.KE +.KS +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +.IN "ApplicationShellWidget" "" "@DEF@" +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; + TopLevelShellPart topLevel; + ApplicationShellPart application; +} ApplicationShellRec, *ApplicationShellWidget; +.De +.KE +.KS +.IN "SessionShellWidget" "" "@DEF@" +.Ds 0 +.TA .5i 2.5i 4.5i +.ta .5i 2.5i 4.5i +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; + TopLevelShellPart topLevel; + ApplicationShellPart application; + SessionShellPart session; +} SessionShellRec, *SessionShellWidget; +.De +.LP +.eM +.KE + +.NH 3 +Shell Resources +.XS +\fB\*(SN Shell Resources\fP +.XE +.LP +.IN "ShellWidget" "Resources" +The resource names, classes, and representation types specified in +the +.PN shellClassRec +resource list are: +.LP +.TS +lw(1.7i) lw(1.7i) lw(1.2i) . +_ +.sp 6p +Name Class Representation +.sp 6p +_ +.sp 6p +XtNallowShellResize XtCAllowShellResize XtRBoolean +XtNcreatePopupChildProc XtCCreatePopupChildProc XtRFunction +XtNgeometry XtCGeometry XtRString +XtNoverrideRedirect XtCOverrideRedirect XtRBoolean +XtNpopdownCallback XtCCallback XtRCallback +XtNpopupCallback XtCCallback XtRCallback +XtNsaveUnder XtCSaveUnder XtRBoolean +XtNvisual XtCVisual XtRVisual +.sp 6p +_ +.TE +.LP +OverrideShell +declares no additional resources beyond those defined by +Shell. +.LP +The resource names, classes, and representation types specified in +the +.PN wmShellClassRec +.IN "WMShell" "resources" +resource list are: +.LP +.TS +lw(2.1i) lw(2.1i) lw(1.2i) . +_ +.sp 6p +Name Class Representation +.sp 6p +_ +.sp 6p +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 +.sp 6p +_ +.TE +.LP +The class resource list for +VendorShell +is implementation-defined. +.LP +The resource names, classes, and representation types that are specified in the +.PN transient\%ShellClassRec +.IN "TransientShell" "resources" +resource list are: +.LP +.TS +lw(1.7i) lw(1.7i) lw(1.2i) . +_ +.sp 6p +Name Class Representation +.sp 6p +_ +.sp 6p +XtNtransientFor XtCTransientFor XtRWidget +.sp 6p +_ +.TE +.LP +The resource names, classes, and representation types that are specified in the +.PN topLevelShellClassRec +.IN "TopLevelShell" "resources" +resource list are: +.LP +.TS +lw(1.7i) lw(1.7i) lw(1.2i) . +_ +.sp 6p +Name Class Representation +.sp 6p +_ +.sp 6p +XtNiconName XtCIconName XtRString +XtNiconNameEncoding XtCIconNameEncoding XtRAtom +XtNiconic XtCIconic XtRBoolean +.sp 6p +_ +.TE +.LP +The resource names, classes, and representation types that are specified in the +.PN application\%ShellClassRec +resource list are: +.LP +.TS +lw(1.7i) lw(1.7i) lw(1.2i) . +_ +.sp 6p +Name Class Representation +.sp 6p +_ +.sp 6p +XtNargc XtCArgc XtRInt +XtNargv XtCArgv XtRStringArray +.sp 6p +_ +.TE +.LP +.KS +The resource names, classes, and representation types that are specified +in the +.PN sessionShellClassRec +resource list are: +.LP +.TS +lw(1.7i) lw(1.7i) lw(1.2i) . +_ +.sp 6p +Name Class Representation +.sp 6p +_ +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 +.sp 6p +_ +.TE +.KE +.NH 3 +ShellPart Default Values +.XS +\fB\*(SN ShellPart Default Values\fP +.XE +.LP +The default values for fields common to all classes of public shells +(filled in by the +Shell +resource lists and the +Shell +initialize procedures) are: +.TS +lw(1.75i) lw(3i). +_ +.sp 6p +Field Default Value +.sp 6p +_ +.sp 6p +geometry NULL +create_popup_child_proc NULL +grab_kind (none) +spring_loaded (none) +popped_up T{ +.PN False +T} +allow_shell_resize T{ +.PN False +T} +client_specified (internal) +save_under T{ +.PN True +for +OverrideShell +and +TransientShell, +.PN False +otherwise +T} +override_redirect T{ +.PN True +for +OverrideShell, +.PN False +otherwise +T} +popup_callback NULL +popdown_callback NULL +visual T{ +.PN CopyFromParent +T} +.sp 6p +_ +.TE +.LP +The \fIgeometry\fP field specifies the size and position +and is usually given only on a command line or in a defaults file. +If the \fIgeometry\fP field is non-NULL when +a widget of class WMShell +is realized, the geometry specification is parsed using +.PN XWMGeometry +with a default geometry +string constructed from the values of \fIx\fP, \fIy\fP, \fIwidth\fP, +\fIheight\fP, \fIwidth_inc\fP, +and \fIheight_inc\fP and the size and position flags in the window manager +size hints are set. If the geometry specifies an x or y position, +then +.PN USPosition +is set. If the geometry specifies a width or height, then +.PN USSize +is set. Any fields in the geometry specification +override the corresponding values in the +Core \fIx\fP, \fIy\fP, \fIwidth\fP, and \fIheight\fP fields. +If \fIgeometry\fP is NULL or contains only a partial specification, then the +Core \fIx\fP, \fIy\fP, \fIwidth\fP, and \fIheight\fP fields are used and +.PN PPosition +and +.PN PSize +are set as appropriate. +The geometry string is not copied by any of the \*(xI +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 \fI\*(xL\fP. +.LP +The \fIcreate_popup_child_proc\fP procedure is called by the +.PN XtPopup +procedure and may remain NULL. +The \fIgrab_kind\fP, \fIspring_loaded\fP, +and \fIpopped_up\fP fields maintain widget +state information as described under +.PN XtPopup , +.PN XtMenuPopup , +.PN XtPopdown , +and +.PN XtMenuPopdown . +.IN "allowShellResize" "" "@DEF@" +The \fIallow_shell_resize\fP field controls whether the widget contained +by the shell is allowed to try to resize itself. +If allow_shell_resize is +.PN False , +any geometry requests made by the child will always return +.PN XtGeometryNo +without interacting with the window manager. +Setting \fIsave_under\fP +.PN True +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. +Setting \fIoverride_redirect\fP +.PN True +determines +whether the window manager can intercede when the shell window +is mapped. +For further information on override_redirect, +see Section 3.2 in \fI\*(xL\fP and Sections 4.1.10 and 4.2.2 in the +\fI\*(xC\fP. +The pop-up and pop-down callbacks are called during +.PN XtPopup +and +.PN XtPopdown . +The default value of the \fIvisual\fP resource is the symbolic value +.PN CopyFromParent . +The \*(xI do not need to query the parent's visual type when the +default value is used; if a client using +.PN XtGetValues +to examine the visual type receives the value +.PN CopyFromParent , +it must then use +.PN XGetWindowAttributes +if it needs the actual visual type. + +.LP +The default values for Shell fields in +WMShell +and its subclasses are: +.LP +.IN "XtUnspecifiedShellInt" "" "@DEF@" +.IN "XtUnspecifiedWindow" +.TS +lw(1i) lw(4i). +_ +.sp 6p +Field Default Value +.sp 6p +_ +.sp 6p +title T{ +Icon name, if specified, otherwise the application's name +T} +wm_timeout Five seconds, in units of milliseconds +wait_for_wm T{ +.PN True +T} +transient T{ +.PN True +for +TransientShell, +.PN False +otherwise +T} +urgency T{ +.PN False +T} +client_leader NULL +window_role NULL +min_width \fBXtUnspecifiedShellInt\fP +min_height \fBXtUnspecifiedShellInt\fP +max_width \fBXtUnspecifiedShellInt\fP +max_height \fBXtUnspecifiedShellInt\fP +width_inc \fBXtUnspecifiedShellInt\fP +height_inc \fBXtUnspecifiedShellInt\fP +min_aspect_x \fBXtUnspecifiedShellInt\fP +min_aspect_y \fBXtUnspecifiedShellInt\fP +max_aspect_x \fBXtUnspecifiedShellInt\fP +max_aspect_y \fBXtUnspecifiedShellInt\fP +input T{ +.PN False +T} +initial_state Normal +icon_pixmap None +icon_window None +icon_x \fBXtUnspecifiedShellInt\fP +icon_y \fBXtUnspecifiedShellInt\fP +icon_mask None +window_group \fBXtUnspecifiedWindow\fP +base_width \fBXtUnspecifiedShellInt\fP +base_height \fBXtUnspecifiedShellInt\fP +win_gravity \fBXtUnspecifiedShellInt\fP +title_encoding See text +.sp 6p +_ +.TE +.LP +The \fItitle\fP and +\fItitle_encoding\fP fields are stored in the +.PN \s-1WM_NAME\s+1 +property on the shell's window by the WMShell realize procedure. +If the \fItitle_encoding\fP field is +.PN None , +the \fItitle\fP string is assumed to be in the encoding of the current +locale and the encoding of the +.PN \s-1WM_NAME\s+1 +property is set to +.PN XStdICCTextStyle . +If a language procedure has not been set +the default value of \fItitle_encoding\fP is +\fB\s-1XA_STRING\s+1\fP, otherwise the default value is +.PN None . +The \fIwm_timeout\fP 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 \fIwait_for_wm\fP to +.PN False +(later events may reset this value). +When \fIwait_for_wm\fP is +.PN False , +the shell does not wait for a response, but relies on asynchronous +notification. +If \fItransient\fP is +.PN True , +the +.PN \s-1WM_TRANSIENT_FOR\s+1 +property +will be stored on the shell window with a value as specified below. +The interpretation of this property is specific to the window manager +under which the application is run; see the \fI\*(xC\fP for more details. +.LP +The realize and set_values procedures of WMShell store the +.PN \s-1WM_CLIENT_LEADER\s+1 +property on the shell window. +When \fIclient_leader\fP 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 \fIclient_leader\fP is NULL and the shell widget has a NULL parent, +the widget's window is used as the value of the +property. +When \fIclient_leader\fP is NULL and the shell widget has a non-NULL parent, +a search is made for the closest shell ancestor +with a non-NULL \fIclient_leader\fP, +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. +.LP +When the value of \fIwindow_role\fP is not NULL, the +realize and set_values procedures store the +.PN \s-1WM_WINDOW_ROLE\s+1 +property on the shell's window with the value of the resource. +.LP +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 +.PN XtUnspecifiedShellInt , +the value of the field is modified as follows: +.br +.sp +.TS +lw(2i) lw(3i). +_ +.sp 6p +Field Replacement +.sp 6p +_ +.sp 6p +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 T{ +Value returned by +.PN XWMGeometry +if called, +else \fBNorthWestGravity\fP +T} +.sp 6p +_ +.TE + +.IN "XWMGeometry" +.LP +If the shell widget has a non-NULL parent, then the +realize and set_values procedures replace the value +.PN XtUnspecifiedWindow +.IN "XtUnspecifiedWindow" "" "@DEF@" +in the \fIwindow_group\fP field with the window id of the root widget +of the widget tree if the +root widget is realized. The symbolic constant +.PN XtUnspecifiedWindowGroup +.IN "XtUnspecifiedWindowGroup" "" "@DEF@" +may be used to indicate that the \fIwindow_group\fP hint flag bit is not +to be set. If \fItransient\fP is +.PN True , +the shell's class is not a subclass of +TransientShell, +and \fIwindow_group\fP is not +.PN XtUnspecifiedWindowGroup , +the WMShell realize and set_values procedures then store the +.PN \s-1WM_TRANSIENT_FOR\s+1 +property with the value of \fIwindow_group\fP. +.LP +.KS +Transient +shells have the following additional resource: +.TS +l l. +_ +.sp 6p +Field Default Value +.sp 6p +_ +.sp 6p +transient_for NULL +.sp 6p +_ +.TE +.KE +.LP +The realize and set_values procedures of +TransientShell +store the +.PN \s-1WM_TRANSIENT_FOR\s+1 +property on the shell window if \fItransient\fP is +.PN True . +If \fItransient_for\fP is non-NULL and the widget specified by +\fItransient_for\fP is realized, then its window is used as the value of the +.PN \s-1WM_TRANSIENT_FOR\s+1 +property; otherwise, the value of \fIwindow_group\fP is used. +.LP +.PN TopLevel +shells have the the following additional resources: +.TS +l l. +_ +.sp 6p +Field Default Value +.sp 6p +_ +.sp 6p +icon_name Shell widget's name +iconic T{ +.PN False +T} +icon_name_encoding See text +.sp 6p +_ +.TE +.LP +The \fIicon_name\fP +and \fIicon_name_encoding\fP fields are stored in the +.PN \s-1WM_ICON_NAME\s+1 +property on the shell's window by the TopLevelShell realize +procedure. +If the \fIicon_name_encoding\fP field is +.PN None , +the \fIicon_name\fP string is assumed to be in the encoding of the +current locale and the encoding of the +.PN \s-1WM_ICON_NAME\s+1 +property is set to +.PN XStdICCTextStyle . +If a language procedure has not been set, +the default value of \fIicon_name_encoding\fP is +\fB\s-1XA_STRING\s+1\fP, otherwise the default value is +.PN None . +The \fIiconic\fP 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 +.PN \s-1WM_CHANGE_STATE\s+1 +message (as specified by the \fI\*(xC\fP) +if this resource is changed from +.PN False +to +.PN True +and will call +.PN XtPopup +specifying \fIgrab_kind\fP as +.PN XtGrabNone +if \fIiconic\fP is changed from +.PN True +to +.PN False . +The XtNiconic resource is also an alternative way to set +the XtNinitialState resource +to indicate that a shell should be initially displayed as an icon; the +TopLevelShell +initialize procedure will set \fIinitial_state\fP to +.PN IconicState +if \fIiconic\fP is +.PN True . +.LP +Application +shells have the following additional resources: +.br +.ne 4 +.TS +l l. +_ +.sp 6p +Field Default Value +.sp 6p +_ +.sp 6p +argc 0 +argv NULL +.sp 6p +_ +.TE +.LP +The \fIargc\fP and \fIargv\fP fields are used to initialize +the standard property +.PN \s-1WM_COMMAND\s+1 . +See the \fI\*(xC\fP for more information. +.LP +The default values for the SessionShell instance fields, +which are filled in from the resource lists and by the +initialize procedure, are +.TS +l l. +_ +.sp 6p +Field Default Value +.sp 6p +_ +.sp 6p +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 T{ +.PN True +T} +program_path See text +resign_command NULL +restart_command See text +restart_style T{ +.PN SmRestartIfRunning +T} +save_callbacks NULL +save_complete_callbacks NULL +session_id NULL +shutdown_command NULL +.sp 6p +_ +.TE +.LP +The \fIconnection\fP field contains the session connection object or NULL +if a session connection is not being managed by this widget. +.LP +The \fIsession_id\fP is an identification assigned to the session +participant by the session manager. +The \fIsession_id\fP 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 \fIsession_id\fP field. +When not NULL, the \fIsession_id\fP of the Session shell widget that +is at the root of the widget tree of the client leader widget will be +used to create the +.PN \s-1SM_CLIENT_ID\s+1 +property on the client leader's window. +.LP +If \fIjoin_session\fP is +.PN False , +the widget will not attempt to establish a +connection to the session manager at shell creation time. +See Sections 4.2.1 and 4.2.4 +for more information on the functionality of this resource. +.LP +The \fIrestart_command\fP, \fIclone_command\fP, \fIdiscard_command\fP, +\fIresign_command\fP, \fIshutdown_command\fP, \fIenvironment\fP, +\fIcurrent_dir\fP, \fIprogram_path\fP, and +\fIrestart_style\fP fields contain standard session properties. +.LP +When a session connection is established or newly managed by the shell, +the shell initialize and set_values methods check the values of the +\fIrestart_command\fP, \fIclone_command\fP, and \fIprogram_path\fP +resources. At that time, if \fIrestart_command\fP is NULL, the value +of the \fIargv\fP resource will be copied to \fIrestart_command\fP. +Whether or not \fIrestart_command\fP was NULL, +if \*Q\fR-xtsessionID\fP\*U \*Q\fR<session id>\*U does not +already appear in the \fIrestart_command\fP, it will be added by the +initialize and set_values methods at the beginning of the command arguments; +if the \*Q\fR-xtsessionID\fP\*U argument already appears with an incorrect +\fRsession id\fP in the following argument, that argument +will be replaced with the current \fRsession id\fP. +.LP +After this, the shell initialize and set_values procedures check the +\fIclone_command\fP. If \fIclone_command\fP is NULL, +\fIrestart_command\fP will be copied to \fIclone_command\fP, +except the \*Q\fR-xtsessionID\fP\*U and following argument will not be copied. +.LP +Finally, the shell initialize and set_values procedures check the +\fIprogram_path\fP. If \fIprogram_path\fP is NULL, the +first element of \fIrestart_command\fP is copied to \fIprogram_path\fP. +.LP +The possible values of \fIrestart_style\fP are +.PN SmRestartIfRunning , +.PN SmRestartAnyway , +.PN SmRestartImmediately , +and +.PN SmRestartNever . +A resource converter is registered for this resource; +for the strings that it recognizes, +see Section 9.6.1. +.LP +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. + +.NH 2 +Session Participation +.XS +\fB\*(SN Session Participation\fP +.XE +.LP +Applications can participate in a user's session, exchanging messages +with the session manager as described in the \fIX Session Management +Protocol\fP and the \fIX Session Management Library\fP. +.LP +When a widget of +.PN sessionShellWidgetClass +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. + +.NH 3 +Joining a Session +.XS +\fB\*(SN Joining a Session\fP +.XE +.LP +When a Session shell is created, +if \fIconnection\fP is NULL, +and if \fIjoin_session\fP is +.PN True , +and if \fIargv\fP or \fIrestart_command\fP is not NULL, +and if in POSIX environments the +.PN \s-1SESSION_MANAGER\s+1 +environment variable is defined, +the shell will attempt to establish a new connection with the session manager. +.LP +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 \fIconnection\fP 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 session manager. +The application must ensure that only one +Session shell manages the connection. +.LP +In the Session shell set_values procedure, +if \fIjoin_session\fP changes from +.PN False +to +.PN True +and \fIconnection\fP is NULL and when in POSIX environments the +.PN \s-1SESSION_MANAGER\s+1 +environment variable is defined, +the shell will attempt to open a connection to the session manager. +If \fIconnection\fP changes from NULL to non-NULL, the +Session shell +will take over management of that session connection and will set +\fIjoin_session\fP to +.PN True . +If \fIjoin_session\fP changes from +.PN False +to +.PN True +and \fIconnection\fP is not NULL, the +Session shell will take over management of the session connection. +.LP +When a successful connection has been established, \fIconnection\fP +contains the session connection ID for the session participant. +When the shell begins to manage the connection, it will call +.PN XtAppAddInput +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 \fIconnection\fP is set to NULL. +.LP +While the connection is being managed, if a +.PN SaveYourself , +.PN SaveYourselfPhase2 , +.PN Interact , +.PN ShutdownCancelled , +.PN SaveComplete , +or +.PN Die +message is received from the session manager, the Session shell will +call out to application callback procedures registered +on the respective callback list of the Session shell and will +send +.PN SaveYourselfPhase2Request , +.PN InteractRequest , +.PN InteractDone , +.PN SaveYourselfDone , +and +.PN ConnectionClosed +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 +.PN SetProperties +or a +.PN DeleteProperties +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. + +.NH 3 +Saving Application State +.XS +\fB\*(SN Saving Application State\fP +.XE +.LP +The session manager instigates an application checkpoint by sending a +.PN SaveYourself +request. +Applications are responsible for saving their state in response to the +request. +.LP +When the +.PN SaveYourself +request arrives, the procedures registered on the +Session shell's save callback list are called. +If the application does not register any save callback procedures 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 \fIcall_data\fP parameter. +.sp +.LP +.KS +The checkpoint token in the \fIcall_data\fP parameter is of type +.PN XtCheckpointToken . +.LP +.IN "XtCheckpointToken" "" "@DEF@" +.IN "XtCheckpointTokenRec" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2i 4i +.ta .5i 2i 4i +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; +.De +.LP +.eM +.KE +The \fIsave_type\fP, \fIinteract_style\fP, \fIshutdown\fP, and \fIfast\fP +fields of the token contain the parameters of the +.PN SaveYourself +message. +The possible values of \fIsave_type\fP are +.PN SmSaveLocal , +.PN SmSaveGlobal , +and +.PN SmSaveBoth ; +these indicate the type of information to be saved. +The possible values of \fIinteract_style\fP are +.PN SmInteractStyleNone , +.PN SmInteractStyleErrors , +and +.PN SmInteractStyleAny ; +these indicate whether user interaction would be permitted +and, if so, what kind of interaction. +If \fIshutdown\fP is +.PN True , +the checkpoint is being performed in preparation for the end of the session. +If \fIfast\fP is +.PN True , +the client should perform the checkpoint as quickly as possible. +If \fIcancel_shutdown\fP is +.PN True , +a +.PN ShutdownCancelled +message has been received for the current save operation. (See Section 4.4.4.) +The \fIphase\fP is used by manager clients, such as a window manager, +to distinguish between the first and second phase of a save operation. +The \fIphase\fP will be either 1 or 2. +The remaining fields in the checkpoint token structure are provided for +the application to communicate with the shell. +.LP +Upon entry to the first application save callback procedure, the return +fields in the token have the following initial values: +\fIinteract_dialog_type\fP is +.PN SmDialogNormal ; +\fIrequest_cancel\fP is +.PN False ; +\fIrequest_next_phase\fP is +.PN False ; +and \fIsave_success\fP is +.PN True . +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 application during the current save operation +will always contain the noninitial value. +.LP +The purpose of the token's \fIsave_success\fP field is to +indicate the outcome of the entire operation to the +session manager and ultimately, to the user. +Returning +.PN False +indicates some portion of the application state +could not be successfully saved. If any token is returned +to the shell with \fIsave_success\fP +.PN False , +tokens subsequently received +by the application for the current save operation will show +\fIsave_success\fP as +.PN False . +When the shell sends the final status of the checkpoint to the +session manager, it will indicate failure to save application state +if any token was returned with \fIsave_success\fP +.PN False . +.LP +Session participants that manage and save the state of other clients +should structure their save or interact callbacks to +set \fIrequest_next_phase\fP to +.PN True +when phase is 1, which will cause the shell to send the +.PN SaveYourselfPhase2Request +when the first phase is complete. When the +.PN SaveYourselfPhase2 +message is received, the shell will invoke the save callbacks a +second time with \fIphase\fP equal to 2. +Manager clients should save the state of other clients +when the callbacks are invoked the second time and \fIphase\fP equal to 2. +.LP +The application may request additional tokens while a checkpoint is under way, +and these additional tokens must be returned by an explicit call. +.sp +.LP +.KS +To request an additional token for a save callback response that has a +deferred outcome, use +.PN XtSessionGetToken . +.LP +.IN "XtSessionGetToken" "" "@DEF@" +.sM +.FD 0 +XtCheckpointToken XtSessionGetToken(\fIwidget\fP) +.br + Widget \fIwidget\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the Session shell widget which manages session participation. +.LP +.eM +The +.PN XtSessionGetToken +function will return NULL if no checkpoint operation is currently under way. +.KE +.sp +.LP +.KS +To indicate the completion of checkpoint processing including user +interaction, the application must signal the Session shell +by returning all tokens. +(See Sections 4.2.2.2 and 4.2.2.4). +To return a token, use +.PN XtSessionReturnToken . +.LP +.IN "XtSessionReturnToken" "" "@DEF@" +.sM +.FD 0 +void XtSessionReturnToken(\fItoken\fP) +.br + XtCheckpointToken \fItoken\fP; +.FN +.IP \fItoken\fP 1i +Specifies a token that was received as the \fIcall_data\fP by a procedure +on the interact callback list or a token that was received by a call to +.PN XtSessionGetToken . +.LP +.eM +.KE +.LP +Tokens passed as \fIcall_data\fP to save callbacks are implicitly +returned when the save callback procedure returns. +A save callback procedure should not call +.PN XtSessionReturnToken +on the token passed in its \fIcall_data\fP. + +.NH 4 +Requesting Interaction +.XS +\fB\*(SN Requesting Interaction\fP +.XE +.LP +When the token \fIinteract_style\fP allows user interaction, +the application may +interact with the user during the checkpoint, but must wait for permission +to interact. +Applications 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 +.PN XtSessionGetToken +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 +.PN InteractRequest +to the session manager when an interact request is not already outstanding +for the application. +.LP +The type of interaction dialog that will be requested is specified by +the \fIinteract_dialog_type\fP field in the checkpoint token. +The possible values for \fIinteract_dialog_type\fP are +.PN SmDialogError +and +.PN SmDialogNormal . +If a token is returned with \fIinteract_dialog_type\fP containing +.PN SmDialogError , +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. +.LP +When a token is returned with \fIsave_success\fP +.PN False +or \fIinteract_dialog_type\fP +.PN SmDialogError , +tokens subsequently passed to callbacks during the same active +.PN SaveYourself +response will reflect these changed values, indicating that +an error condition has occurred during the checkpoint. +.LP +The \fIrequest_cancel\fP 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 \fIrequest_cancel\fP field is not examined by the shell. +This is also true of tokens received through a call to +.PN XtSessionGetToken . + +.NH 4 +Interacting with the User during a Checkpoint +.XS +\fB\*(SN Interacting with the User during a Checkpoint\fP +.XE +.LP +When the session manager grants the application's request for user interaction, +the Session shell receives an +.PN Interact +message. +The procedures registered on the interact callback list are executed, +but not as if executing a typical callback 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 \fIcall_data\fP. +The interact callback will typically pop up a dialog box and return. +When the user interaction and associated application checkpointing has +completed, the application must return the token by calling +.PN XtSessionReturnToken . +Returning the token completes the current step and triggers the next step +in the sequence. +.LP +During interaction the client may request cancellation of a shutdown. +When a token passed as \fIcall_data\fP to an interact procedure is returned, +if \fIshutdown\fP is +.PN True +and \fIcancel_shutdown\fP is +.PN False , +\fIrequest_cancel\fP indicates whether the +application requests that the pending shutdown be cancelled. +If \fIrequest_cancel\fP is +.PN True , +the field will also be +.PN True +in any tokens subsequently granted during the checkpoint operation. +When a token is returned requesting cancellation of +the session 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, and the final interact token returned to the shell, an +.PN InteractDone +message is sent to the session manager, indicating whether +a pending session shutdown is requested to be cancelled. + +.NH 4 +Responding to a Shutdown Cancellation +.XS +\fB\*(SN Responding to a Shutdown Cancellation\fP +.XE +.LP +Callbacks registered on the cancel callback list are invoked when the +Session shell processes a +.PN ShutdownCancelled +message from the session manager. This may occur during the +processing of save callbacks, while waiting for interact permission, +during user interaction, or after the save operation is complete and +the application is expecting a +.PN SaveComplete +or a +.PN Die +message. +The \fIcall_data\fP for these callbacks is NULL. +.LP +When the shell notices that a pending shutdown has been cancelled, +the token \fIcancel_shutdown\fP field will be +.PN True +in tokens subsequently given to the application. +.LP +Receiving notice of a shutdown cancellation does not cancel the +pending execution of save callbacks or interact callbacks. +After the cancel callbacks execute, if \fIinteract_style\fP is not +.PN SmInteractStyleNone +and the interact list is not empty, +the procedures on the interact callback list will be executed +and passed a token with \fIinteract_style\fP +.PN SmInteractStyleNone . +The application should not interact with the user, and the Session shell +will not send an +.PN InteractDone +message. + +.NH 4 +Completing a Save +.XS +\fB\*(SN Completing a Save\fP +.XE +.LP +When there is no user interaction, the shell regards the application +as having finished saving state when all callback procedures +on the save callback list have returned, and any additional tokens +passed out by +.PN XtSessionGetToken +have been returned by corresponding calls to +.PN XtSessionReturnToken . +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 +.PN XtSessionReturnToken . +If the save operation involved a manager client that requested the +second phase, the above conditions apply to both the first and second +phase of the save operation. +.br +.LP +When the application has finished saving state, +the Session shell will report the result to the session manager by +sending the +.PN SaveYourselfDone +message. +If the session is continuing, the shell will receive the +.PN SaveComplete +message when all applications have completed saving state. +This message indicates that applications may again allow changes +to their state. The shell will execute the save_complete callbacks. +The \fIcall_data\fP for these callbacks is NULL. + +.NH 3 +Responding to a Shutdown +.XS +\fB\*(SN Responding to a Shutdown\fP +.XE +.LP +Callbacks registered on the die callback list are invoked when the +session manager sends a +.PN Die +message. +The callbacks on this list should do whatever is appropriate to quit +the application. +Before executing procedures on the die callback list, +the Session shell will close the connection to the session manager +and will remove the handler that watches for protocol messages. +The \fIcall_data\fP for these callbacks is NULL. + +.NH 3 +Resigning from a Session +.XS +\fB\*(SN Resigning from a Session\fP +.XE +.LP +When the Session shell widget is destroyed, the destroy method will +close the connection to the session manager by sending a +.PN ConnectionClosed +protocol message and will remove the input callback +that was watching for session protocol messages. +.LP +When +.PN XtSetValues +is used to set \fIjoin_session\fP to +.PN False , +the set_values method of the Session shell will close the +connection to the session manager if one exists by sending a +.PN ConnectionClosed +message, and \fIconnection\fP will be set to NULL. +.LP +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 \fIjoin_session\fP to +.PN False +before exiting. +.LP +When +.PN XtSetValues +is used to set \fIconnection\fP to NULL, +the Session shell will stop managing the connection, if one exists. +However, that session connection will not be closed. +.LP +Applications that wish to ensure continuation of a session connection +beyond the destruction of the shell should first retrieve the +\fIconnection\fP resource value, +then set the \fIconnection\fP resource to NULL, +and then they may safely destroy the widget without losing control +of the session connection. +.LP +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 \fIconnection\fP to NULL, +remove the input callback, and +call the procedures registered on the error callback list. +The \fIcall_data\fP for these callbacks is NULL. +.bp diff --git a/specs/CH05 b/specs/CH05 new file mode 100644 index 0000000..4f15bea --- /dev/null +++ b/specs/CH05 @@ -0,0 +1,783 @@ +.\" $Xorg: CH05,v 1.3 2000/08/17 19:42:44 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 5\fP\s-1 + +\s+1\fBPop-Up Widgets\fP\s-1 +.sp 2 +.nr H1 5 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 5 \(em Pop-Up Widgets +.XE +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 widget's parent window. +.\"One thing that all pop-ups in common is that they break +.\"the widget/window hierarchy. +.\"Pop-ups windows are not geometry constrained by their parent widget. +.\"Instead, they are window children of the root. +Therefore, pop-ups are created and attached differently to their widget parent +than normal widget children. +.LP +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 \fIpopup_list\fP field in the +.PN CorePart +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 provide a place for +.PN XtDestroyWidget +to look for all extant children. +.LP +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 \fIchild\fP always refers to a normal, geometry-managed widget +on the composite widget's list of children, and the term +\fIpop-up child\fP always refers to a +widget on the pop-up list. +.IN "pop-up" "" "@DEF@" +.IN "pop-up" "list" +.IN "pop-up" "child" + +.NH 2 +Pop-Up Widget Types +.LP +.XS +\fB\*(SN Pop-Up Widget Types\fP +.XE +There are three kinds of pop-up widgets: +.IP \(bu 5 +Modeless pop-ups +.IP +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. +.IP \(bu 5 +Modal pop-ups +.IP +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. +.IP \(bu 5 +Spring-loaded pop-ups +.IP +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 applications. +.LP +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 different processing by the \*(xI. +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 appropriate descendant, so +that, for example, button-up can take down a spring-loaded pop-up no +matter where the +button-up occurs. +.LP +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 dispatched +to any of the modal or spring-loaded pop-ups +currently mapped. +.LP +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. + +.NH 2 +Creating a Pop-Up Shell +.XS +\fB\*(SN Creating a Pop-Up Shell\fP +.XE +.LP +.IN "pop-up" "shell" +.IN "pop-up" "child" +For a widget to be popped up, +it must be the child of a pop-up shell widget. +None of the \*(xI-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. +.sp +.LP +To create a pop-up shell, use +.PN XtCreatePopupShell . +.LP +.IN "XtCreatePopupShell" "" "@DEF@" +.sM +.FD 0 +Widget XtCreatePopupShell(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, \ +\fIargs\fP, \fInum_args\fP) +.br + String \fIname\fP; +.br + WidgetClass \fIwidget_class\fP; +.br + Widget \fIparent\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIname\fP 1i +Specifies the instance name for the created shell widget. +.IP \fIwidget_class\fP 1i +Specifies the widget class pointer for the created shell widget. +.IP \fIparent\fP 1i +Specifies the parent widget. \*(cI +.IP \fIargs\fP 1i +Specifies the argument list to override any other resource specifications. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtCreatePopupShell +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 +.IN "insert_child procedure" +\fIchildren\fP list, +attaches the shell to the parent's \fIpopup_list\fP directly. +.LP +The screen resource for this widget is determined by first scanning +\fIargs\fP for the XtNscreen argument. If no XtNscreen argument is +found, the resource database associated with the parent's screen +is queried for the resource \fIname\fP.screen, class +\fIClass\fP.Screen where \fIClass\fP is the \fIclass_name\fP +field from the +.PN CoreClassPart +of the specified \fIwidget_class\fP. +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 +\fIargs\fP. + +.LP +A spring-loaded pop-up invoked from a translation table via +.PN XtMenuPopup +must already exist +at the time that the translation 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. +.sp +.LP +To create a pop-up shell using varargs lists, use +.PN XtVaCreatePopupShell . +.LP +.IN "XtVaCreatePopupShell" "" "@DEF@" +.sM +.FD 0 +Widget XtVaCreatePopupShell(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, ...) +.br + String \fIname\fP; +.br + WidgetClass \fIwidget_class\fP; +.br + Widget \fIparent\fP; +.FN +.IP \fIname\fP 1i +Specifies the instance name for the created shell widget. +.IP \fIwidget_class\fP 1i +Specifies the widget class pointer for the created shell widget. +.IP \fIparent\fP 1i +Specifies the parent widget. \*(cI +.IP ... 1i +Specifies the variable argument list to override any other +resource specifications. +.LP +.eM +.PN XtVaCreatePopupShell +is identical in function to +.PN XtCreatePopupShell +with \fIthe\fP args and \fInum_args\fP parameters replaced by a varargs list as +described in Section 2.5.1. + +.NH 2 +Creating Pop-Up Children +.XS +\fB\*(SN Creating Pop-Up Children\fP +.XE +.LP +Once a pop-up shell is created, +the single child of the pop-up shell can be created +either statically or dynamically. +.LP +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 +.PN XtSetSensitive +(or, in general, +.PN XtSetValues ) +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 +.PN XtRealizeWidget +on the pop-up shell at startup. +When the menu is needed, +all the widgets that make up the menu already exist and need only be mapped. +The menu should pop up as quickly as the X server can respond. +.LP +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 out if it should change the sensitivity of any of its subparts. +.LP +Pop-up child creation does not map the pop-up, +even if you create the child and call +.PN XtRealizeWidget +on the pop-up shell. +.LP +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. + +.NH 2 +Mapping a Pop-Up Widget +.XS +\fB\*(SN Mapping a Pop-Up Widget\fP +.XE +.LP +Pop-ups can be popped up through several mechanisms: +.IP \(bu 5 +A call to +.PN XtPopup +or +.PN XtPopupSpringLoaded . +.IP \(bu 5 +One of the supplied callback procedures +.PN XtCallbackNone , +.PN XtCallbackNonexclusive , +or +.PN XtCallbackExclusive . +.IP \(bu 5 +The standard translation action +.PN XtMenuPopup . +.LP +Some of these routines take an argument of type +.PN XtGrabKind , +which is defined as +.sp +.sM +.Ds 0 +typedef enum {XtGrabNone, XtGrabNonexclusive, XtGrabExclusive} XtGrabKind; +.De +.sp +.eM +.LP +The create_popup_child_proc procedure pointer +in the shell widget instance record is of type +.PN XtCreatePopupChildProc . +.LP +.IN "create_popup_child_proc" +.IN "Shell" "create_popup_child_proc" +.IN "XtCreatePopupChildProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtCreatePopupChildProc)(Widget); +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the shell widget being popped up. +.LP +.eM +To map a pop-up from within an application, use +.PN XtPopup . +.LP +.IN "XtPopup" "" "@DEF@" +.sM +.FD 0 +void XtPopup(\fIpopup_shell\fP, \fIgrab_kind\fP) +.br + Widget \fIpopup_shell\fP; +.br + XtGrabKind \fIgrab_kind\fP; +.FN +.IP \fIpopup_shell\fP 1i +Specifies the shell widget. +.IP \fIgrab_kind\fP 1i +Specifies the way in which user events should be constrained. +.LP +.eM +The +.PN XtPopup +function performs the following: +.IP \(bu 5 +Calls +.PN XtCheckSubclass +to ensure \fIpopup_shell\fP's class is a subclass of +.PN shellWidgetClass . +.IP \(bu 5 +Raises the window and returns if the shell's \fIpopped_up\fP field is already +.PN True . +.IP \(bu 5 +Calls the callback procedures on the shell's \fIpopup_callback\fP list, +specifying a pointer to the value of \fIgrab_kind\fP as the \fIcall_data\fP +argument. +.IP \(bu 5 +Sets the shell \fIpopped_up\fP field to +.PN True , +the shell \fIspring_loaded\fP field to +.PN False , +and the shell \fIgrab_kind\fP field from \fIgrab_kind\fP. +.IP \(bu 5 +If the shell's \fIcreate_popup_child_proc\fP field is non-NULL, +.PN XtPopup +calls it with \fIpopup_shell\fP as the parameter. +.IP \(bu 5 +If \fIgrab_kind\fP is either +.PN XtGrabNonexclusive +or +.PN XtGrabExclusive , +it calls +.LP +.Ds +XtAddGrab(\fIpopup_shell\fP, (\fIgrab_kind\fP == XtGrabExclusive), False) +.De +.IP \(bu 5 +Calls +.PN XtRealizeWidget +with \fIpopup_shell\fP specified. +.IP \(bu 5 +Calls +.PN XMapRaised +with the window of \fIpopup_shell\fP. +.sp +.LP +To map a spring-loaded pop-up from within an application, use +.PN XtPopupSpringLoaded . +.LP +.IN "XtPopupSpringLoaded" "" @DEF@" +.sM +.FD 0 +void XtPopupSpringLoaded(\fIpopup_shell\fP) +.br + Widget \fIpopup_shell\fP; +.FN +.IP \fIpopup_shell\fP 1i +Specifies the shell widget to be popped up. +.LP +.eM +The +.PN XtPopupSpringLoaded +function performs exactly as +.PN XtPopup +except that it sets the shell \fIspring_loaded\fP field to +.PN True +and always calls +.PN XtAddGrab +with \fIexclusive\fP +.PN True +and \fIspring-loaded\fP +.PN True . +.sp +.LP +To map a pop-up from a given widget's callback list, +you also can register one of the +.PN XtCallbackNone , +.PN XtCallbackNonexclusive , +or +.PN XtCallbackExclusive +convenience routines as callbacks, using the pop-up shell widget as the +client data. +.LP +.IN "XtCallbackNone" "" "@DEF@" +.sM +.FD 0 +void XtCallbackNone(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP) +.br + Widget \fIw\fP; +.br + XtPointer \fIclient_data\fP; +.br + XtPointer \fIcall_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. +.IP \fIclient_data\fP 1i +Specifies the pop-up shell. +.IP \fIcall_data\fP 1i +Specifies the callback data argument, +which is not used by this procedure. +.sp +.LP +.IN "XtCallbackNonexclusive" "" "@DEF@" +.FD 0 +void XtCallbackNonexclusive(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP) +.br + Widget \fIw\fP; +.br + XtPointer \fIclient_data\fP; +.br + XtPointer \fIcall_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. +.IP \fIclient_data\fP 1i +Specifies the pop-up shell. +.IP \fIcall_data\fP 1i +Specifies the callback data argument, +which is not used by this procedure. +.sp +.LP +.IN "XtCallbackExclusive" "" "@DEF@" +.FD 0 +void XtCallbackExclusive(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP) +.br + Widget \fIw\fP; +.br + XtPointer \fIclient_data\fP; +.br + XtPointer \fIcall_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. +.IP \fIclient_data\fP 1i +Specifies the pop-up shell. +.IP \fIcall_data\fP 1i +Specifies the callback data argument, +which is not used by this procedure. +.LP +.eM +The +.PN XtCallbackNone , +.PN XtCallbackNonexclusive , +and +.PN XtCallbackExclusive +functions call +.PN XtPopup +with the shell specified by the \fIclient_data\fP argument +and \fIgrab_kind\fP set as the name specifies. +.PN XtCallbackNone , +.PN XtCallbackNonexclusive , +and +.PN XtCallbackExclusive +specify +.PN XtGrabNone , +.PN XtGrabNonexclusive , +and +.PN XtGrabExclusive , +respectively. +Each function then sets the widget that executed the callback list +to be insensitive by calling +.PN XtSetSensitive . +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 button. +.sp +.LP +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 +.PN XtMenuPopup , +or its synonym, +.PN MenuPopup . +From a translation writer's point of view, +the definition for this translation action is +.LP +.IN "MenuPopup" "" "@DEF@" +.IN "XtMenuPopup" "" "@DEF@" +.sM +.FD 0 +void XtMenuPopup(\fIshell_name\fP) +.br + String \fIshell_name\fP; +.FN +.IP \fIshell_name\fP 1i +Specifies the name of the shell widget to pop up. +.LP +.eM +.PN XtMenuPopup +is known to the translation manager, +which registers the corresponding built-in action procedure +.PN XtMenuPopupAction +using +.PN XtRegisterGrabAction +specifying \fIowner_events\fP +.PN True , +\fIevent_mask\fP +.PN ButtonPressMask +\fB|\fP +.PN ButtonReleaseMask , +and \fIpointer_mode\fP and \fIkeyboard_mode\fP +.PN GrabModeAsync . +.LP +If +.PN XtMenuPopup +is invoked on +.PN ButtonPress , +it calls +.PN XtPopupSpringLoaded +on the specified shell widget. +If +.PN XtMenuPopup +is invoked on +.PN KeyPress +or +.PN EnterWindow , +it calls +.PN XtPopup +on the specified shell widget with \fIgrab_kind\fP set to +.PN XtGrabNonexclusive . +Otherwise, the translation manager generates a +warning message and ignores the action. +.LP +.PN XtMenuPopup +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 +.PN XtMenuPopup +gets to the application top-level shell widget and has not +found a matching shell, it generates a warning and returns immediately. + +.NH 2 +Unmapping a Pop-Up Widget +.XS +\fB\*(SN Unmapping a Pop-Up Widget\fP +.XE +.LP +Pop-ups can be popped down through several mechanisms: +.IP \(bu 5 +A call to +.PN XtPopdown +.IP \(bu 5 +The supplied callback procedure +.PN XtCallbackPopdown +.IP \(bu 5 +The standard translation action +.PN XtMenuPopdown +.sp +.LP +To unmap a pop-up from within an application, use +.PN XtPopdown . +.LP +.IN "XtPopdown" "" "@DEF@" +.sM +.FD 0 +void XtPopdown(\fIpopup_shell\fP) +.br + Widget \fIpopup_shell\fP; +.FN +.IP \fIpopup_shell\fP 1i +Specifies the shell widget to pop down. +.LP +.eM +The +.PN XtPopdown +function performs the following: +.IP \(bu 5 +Calls +.PN XtCheckSubclass +.\".PN XtCheckSubclass(popup_shell, popupShellWidgetClass) +to ensure \fIpopup_shell\fP's class is a subclass of +.PN shellWidgetClass . +.IP \(bu 5 +Checks that the \fIpopped_up\fP field of \fIpopup_shell\fP is +.PN True ; +otherwise, it returns immediately. +.IP \(bu 5 +Unmaps \fIpopup_shell\fP's window and, if \fIoverride_redirect\fP is +.PN False , +sends a synthetic +.PN UnmapNotify +event as specified by the \fI\*(xC\fP. +.IP \(bu 5 +If \fIpopup_shell\fP's \fIgrab_kind\fP is either +.PN XtGrabNonexclusive +or +.PN XtGrabExclusive , +it calls +.PN XtRemoveGrab . +.\".PN XtRemoveGrab(popup_shell) +.IP \(bu 5 +Sets \fIpopup_shell\fP's \fIpopped_up\fP field to +.PN False . +.IP \(bu 5 +Calls the callback procedures on the shell's \fIpopdown_callback\fP list, +specifying a pointer to the value of the shell's \fIgrab_kind\fP field +as the \fIcall_data\fP argument. +.sp +.LP +To pop down a pop-up from a callback list, you may use the callback +.PN XtCallbackPopdown . +.LP +.IN "XtCallbackPopdown" "" "@DEF@" +.sM +.FD 0 +void XtCallbackPopdown(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP) +.br + Widget \fIw\fP; +.br + XtPointer \fIclient_data\fP; +.br + XtPointer \fIcall_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. +.IP \fIclient_data\fP 1i +Specifies a pointer to the +.PN XtPopdownID +structure. +.IP \fIcall_data\fP 1i +Specifies the callback data argument, +which is not used by this procedure. +.LP +.eM +The +.PN XtCallbackPopdown +function casts the \fIclient_data\fP parameter to a pointer of type +.PN XtPopdownID . +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + Widget shell_widget; + Widget enable_widget; +} XtPopdownIDRec, *XtPopdownID; +.De +.LP +.eM +The \fIshell_widget\fP is the pop-up shell to pop down, +and the \fIenable_widget\fP is usually the widget that was used to pop it up +in one of the pop-up callback convenience procedures. +.LP +.PN XtCallbackPopdown +calls +.PN XtPopdown +with the specified \fIshell_widget\fP +and then calls +.PN XtSetSensitive +to resensitize \fIenable_widget\fP. +.sp +.LP +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 +.PN XtMenuPopdown +or its synonym, +.PN MenuPopdown . +From a translation writer's point of view, +the definition for this translation action is +.LP +.IN "XtMenuPopdown" "" "@DEF@" +.IN "MenuPopdown" "" "@DEF@" +.sM +.FD 0 +void XtMenuPopdown(\fIshell_name\fP) +.br + String \fIshell_name\fP; +.FN +.IP \fIshell_name\fP 1i +Specifies the name of the shell widget to pop down. +.LP +.eM +If a shell name is not given, +.PN XtMenuPopdown +calls +.PN XtPopdown +with the widget for which the translation is specified. +If \fIshell_name\fP is specified in the translation table, +.PN XtMenuPopdown +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 +.PN XtMenuPopdown +gets to the application top-level shell widget +and cannot find a matching shell, +it generates a warning and returns immediately. +.bp diff --git a/specs/CH06 b/specs/CH06 new file mode 100644 index 0000000..34c2861 --- /dev/null +++ b/specs/CH06 @@ -0,0 +1,1110 @@ +.\" $Xorg: CH06,v 1.3 2000/08/17 19:42:45 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 6\fP\s-1 + +\s+1\fBGeometry Management\fP\s-1 +.sp 2 +.nr H1 6 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 6 \(em Geometry Management +.XE +.LP +.IN "geometry_manager procedure" +.IN "Geometry Management" +.IN "Configure Window" +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 locations. +.LP +To resolve physical layout conflicts between sibling widgets and between +a widget and its parent, the \*(xI provide the geometry management mechanism. +Almost all +composite +widgets have a geometry manager specified in the \fIgeometry_manager\fP field +in the widget class record that is responsible for the size, position, and +stacking order of the widget'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. + +.NH 2 +Initiating Geometry Changes +.LP +.XS +\*(SN Initiating Geometry Changes +.XE +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 +.PN XtMove\%Widget , +.PN XtResizeWidget , +or +.PN XtConfigureWidget . +A child must ask its parent for a geometry change by calling +.PN XtMakeGeometryRequest +or +.PN XtMakeResizeRequest . +An application or other client code initiates a geometry change by calling +.PN XtSetValues +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. +.LP +When a widget that needs to change its size, position, border width, +or stacking depth asks its parent's geometry manager to make the desired +changes, +the geometry manager can allow the request, disallow the request, or +suggest a compromise. +.LP +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 +.PN XtMoveWidget . +When it resizes a child (that is, changes the width, height, or +border width) other than the one making the request, +it should do so by calling +.PN XtResizeWidget . +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 +.PN XtConfigureWidget . +.LP +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. +.LP +Because such cascaded arbitration of widget geometry can involve extended +negotiation, +windows are not actually allocated to widgets at application +startup until all widgets are satisfied with their geometry; +see Sections 2.5 and 2.6. +.NT Notes +.IP 1. 5 +The \*(xI 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 +.PN XtSetValues +that will generate a stacking geometry request. +.IP 2. 5 +After a successful geometry request (one that returned +.PN XtGeometryYes ), +a widget does not know whether its resize procedure has been called. +Widgets should have resize procedures that can be called more than once +without ill effects. +.NE + +.NH 2 +General Geometry Manager Requests +.XS +\*(SN General Geometry Manager Requests +.XE +.LP +When making a geometry request, the child specifies an +.PN XtWidgetGeometry +structure. +.LP +.IN "XtGeometryMask" +.KS +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef unsigned long XtGeometryMask; + +typedef struct { + XtGeometryMask request_mode; + Position x, y; + Dimension width, height; + Dimension border_width; + Widget sibling; + int stack_mode; +} XtWidgetGeometry; +.De +.eM +.KE +.LP +To make a general geometry manager request from a widget, use +.PN XtMakeGeometryRequest . +.LP +.IN "XtMakeGeometryRequest" "" "@DEF@" +.sM +.FD 0 +XtGeometryResult XtMakeGeometryRequest(\fIw\fP, \fIrequest\fP, \ +\fIreply_return\fP) +.br + Widget \fIw\fP; +.br + XtWidgetGeometry *\fIrequest\fP; +.br + XtWidgetGeometry *\fIreply_return\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget making the request. \*(rI +.IP \fIrequest\fP 1i +Specifies the desired widget geometry (size, position, border width, +and stacking order). +.IP \fIreply_return\fP 1i +Returns the allowed widget size, or may be NULL +if the requesting widget is not interested in handling +.PN XtGeometryAlmost . +.LP +.eM +Depending on the condition, +.PN XtMakeGeometryRequest +performs the following: +.IP \(bu 5 +If the widget is unmanaged or the widget's parent is not realized, +it makes the changes and returns +.PN XtGeometryYes . +.IP \(bu 5 +If the parent's class is not a subclass of +.PN compositeWidgetClass +or the parent's \fIgeometry_manager\fP field is NULL, +it issues an error. +.IP \(bu 5 +If the widget's \fIbeing_destroyed\fP field is +.PN True , +it returns +.PN XtGeometryNo . +.IP \(bu 5 +If the widget \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, and +\fIborder_width\fP fields are +all equal to the requested values, +it returns +.PN XtGeometryYes ; +otherwise, it calls the parent's geometry_manager procedure +with the given parameters. +.IP \(bu 5 +If the parent's geometry manager returns +.PN XtGeometryYes +and if +.PN XtCWQueryOnly +is not set in \fIrequest->request_mode\fP +and if the widget is realized, +.PN XtMakeGeometryRequest +calls the +.PN XConfigureWindow +Xlib function to reconfigure the widget's window (set its size, location, +and stacking order as appropriate). +.IP \(bu 5 +If the geometry manager returns +.PN XtGeometryDone , +the change has been approved and actually has been done. +In this case, +.PN XtMakeGeometryRequest +does no configuring and returns +.PN XtGeometryYes . +.PN XtMakeGeometryRequest +never returns +.PN XtGeometryDone . +.IP \(bu 5 +Otherwise, +.PN XtMakeGeometryRequest +just returns the resulting value from the parent's geometry manager. +.LP +Children of primitive widgets are always unmanaged; therefore, +.PN XtMakeGeometryRequest +always returns +.PN XtGeometryYes +when called by a child of a primitive widget. +.LP +The return codes from geometry managers are +.IN "XtGeometryResult" +.LP +.KS +.sM +.Ds 0 +.TA .5i 1.75i +.ta .5i 1.75i +typedef enum { + XtGeometryYes, + XtGeometryNo, + XtGeometryAlmost, + XtGeometryDone +} XtGeometryResult; +.De +.eM +.KE +.LP +The \fIrequest_mode\fP definitions are from +.Pn < X11/X.h >. +.LP +.sM +.TS +lw(.5i) lw(2.5i) lw(.75i). +T{ +#define +T} T{ +.PN CWX +T} T{ +(1<<0) +T} +T{ +#define +T} T{ +.PN CWY +T} T{ +(1<<1) +T} +T{ +#define +T} T{ +.PN CWWidth +T} T{ +(1<<2) +T} +T{ +#define +T} T{ +.PN CWHeight +T} T{ +(1<<3) +T} +T{ +#define +T} T{ +.PN CWBorderWidth +T} T{ +(1<<4) +T} +T{ +#define +T} T{ +.PN CWSibling +T} T{ +(1<<5) +T} +T{ +#define +T} T{ +.PN CWStackMode +T} T{ +(1<<6) +T} +.TE +.LP +.eM +The \*(xI also support the following value. +.LP +.sM +.TS +lw(.5i) lw(2.5i) lw(.75i). +T{ +#define +T} T{ +.PN XtCWQueryOnly +T} T{ +(1<<7) +T} +.TE +.LP +.eM +.PN XtCWQueryOnly +indicates that the corresponding geometry request is only a query +as to what would happen if this geometry request were made +and that no widgets should actually be changed. +.LP +.PN XtMakeGeometryRequest , +like the +.PN XConfigureWindow +Xlib function, uses \fIrequest_mode\fP to determine which fields in the +.PN XtWidgetGeometry +structure the caller wants to specify. +.LP +The \fIstack_mode\fP definitions are from +.Pn < X11/X.h >: +.LP +.sM +.TS +lw(.5i) lw(2.5i) lw(.75i). +T{ +#define +T} T{ +.PN Above +T} T{ +0 +T} +T{ +#define +T} T{ +.PN Below +T} T{ +1 +T} +T{ +#define +T} T{ +.PN TopIf +T} T{ +2 +T} +T{ +#define +T} T{ +.PN BottomIf +T} T{ +3 +T} +T{ +#define +T} T{ +.PN Opposite +T} T{ +4 +T} +.TE +.LP +.eM +The \*(xI also support the following value. +.LP +.sM +.TS +lw(.5i) lw(2.5i) lw(.75i). +T{ +#define +T} T{ +.PN XtSMDontChange +T} T{ +5 +T} +.TE +.LP +.eM +For definition and behavior of +.PN Above , +.PN Below , +.PN TopIf , +.PN BottomIf , +and +.PN Opposite , +see Section 3.7 in \fI\*(xL\fP. +.PN XtSMDontChange +indicates that the widget wants its current stacking order preserved. + +.NH 2 +Resize Requests +.XS +\*(SN Resize Requests +.XE +.LP +To make a simple resize request from a widget, you can use +.PN XtMakeResizeRequest +as an alternative to +.PN XtMakeGeometryRequest . +.LP +.IN "XtMakeResizeRequest" "" "@DEF@" +.sM +.FD 0 +XtGeometryResult XtMakeResizeRequest(\fIw\fP, \fIwidth\fP, \fIheight\fP, \ +\fIwidth_return\fP, \fIheight_return\fP) +.br + Widget \fIw\fP; +.br + Dimension \fIwidth\fP, \fIheight\fP; +.br + Dimension *\fIwidth_return\fP, *\fIheight_return\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget making the request. \*(rI +.IP \fIwidth\fP 1i +Specify the desired widget width and height. +.br +.ns +.IP \fIheight\fP 1i +.IP \fIwidth_return\fP 1i +Return the allowed widget width and height. +.br +.ns +.IP \fIheight_return\fP 1i +.LP +.eM +The +.PN XtMakeResizeRequest +function, a simple interface to +.PN XtMakeGeometryRequest , +creates an +.PN XtWidgetGeometry +structure and specifies that width and height should change +by setting \fIrequest_mode\fP to +.PN CWWidth +\fB|\fP +.PN CWHeight . +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 +.PN XtGeometryAlmost , +\fIwidth_return\fP and \fIheight_return\fP contain a compromise width and height. +If these are acceptable, +the widget should immediately call +.PN XtMakeResizeRequest +again and request that the compromise width and height be applied. +If the widget is not interested in +.PN XtGeometryAlmost +replies, +it can pass NULL for \fIwidth_return\fP and \fIheight_return\fP. + +.NH 2 +Potential Geometry Changes +.XS +\*(SN Potential Geometry Changes +.XE +.LP +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 grandparent). +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 +position 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 +.PN XtCWQueryOnly +in the intermediate request. +.LP +When +.PN XtCWQueryOnly +is used, the geometry manager needs to cache +enough information to exactly reconstruct the intermediate request. +If the grandparent's response to the intermediate query was +.PN XtGeometryAlmost , +the geometry manager needs to cache the entire +reply geometry in the event the child accepts the parent's compromise. +.LP +If the grandparent's response was +.PN XtGeometryAlmost , +it may also be necessary to cache the entire reply geometry from +the grandparent when +.PN XtCWQueryOnly +is not used. +If the geometry manager is still able to satisfy the original request, +it may immediately accept the grandparent's compromise +and then act on the child's request. +If the grandparent'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. +.LP +Note that a compromise geometry returned with +.PN XtGeometryAlmost +is guaranteed only for the next call to the same widget; +therefore, a cache of size 1 is sufficient. + +.NH 2 +Child Geometry Management: The geometry_manager Procedure +.XS +\*(SN Child Geometry Management: The geometry_manager Procedure +.XE +.LP +The geometry_manager procedure pointer in a composite widget class is of type +.PN XtGeometryHandler . +.LP +.IN "XtGeometryHandler" "" "@DEF@" +.sM +.FD 0 +typedef XtGeometryResult (*XtGeometryHandler)(Widget, XtWidgetGeometry*, \ +XtWidgetGeometry*); +.br + Widget \fIw\fP; +.br + XtWidgetGeometry *\fIrequest\fP; +.br + XtWidgetGeometry *\fIgeometry_return\fP; +.FN +.IP \fIw\fP 1.2i +Passes the widget making the request. +.IP \fIrequest\fP 1.2i +Passes the new geometry the child desires. +.IP \fIgeometry_return\fP 1.2i +Passes a geometry structure in which the geometry manager may store a +compromise. +.LP +.eM +A class can inherit its superclass's geometry manager during class +initialization. +.LP +A bit set to zero in the request's \fIrequest_mode\fP +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 corresponding field. +.LP +If the geometry manager can satisfy all changes requested +and if +.PN XtCWQueryOnly +is not specified, +it updates the widget's \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, +and \fIborder_width\fP fields +appropriately. +Then, it returns +.PN XtGeometryYes , +and the values pointed to by the \fIgeometry_return\fP argument are undefined. +The widget's window is moved and resized automatically by +.PN XtMakeGeometryRequest . +.LP +Homogeneous composite widgets often find it convenient to treat the widget +making the request the same as any other widget, including reconfiguring +it using +.PN XtConfigureWidget +or +.PN XtResizeWidget +as part of its layout process, unless +.PN XtCWQueryOnly +is specified. +If it does this, +it should return +.PN XtGeometryDone +to inform +.PN XtMakeGeometryRequest +that it does not need to do the configuration itself. +.NT +To remain +compatible with layout techniques used in older widgets (before +.PN XtGeometryDone +was added to the \*(xI), a geometry manager should avoid using +.PN XtResizeWidget +or +.PN XtConfigureWidget +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 management scheme, however, provided that it +clearly warns widget developers of the compatibility consequences. +.NE +.LP +Although +.PN XtMakeGeometryRequest +resizes the widget's window +(if the geometry +manager returns +.PN XtGeometryYes ), +it does not call the widget class's resize procedure. +The requesting widget must perform whatever +resizing calculations are needed explicitly. +.LP +If the geometry manager disallows the request, +the widget cannot change its geometry. +The values pointed to by \fIgeometry_return\fP are undefined, +and the geometry manager returns +.PN XtGeometryNo . +.LP +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 +\fIgeometry_return\fP with the actual changes +it is willing to make, including an appropriate \fIrequest_mode\fP mask, and returns +.PN XtGeometryAlmost . +If a bit in \fIgeometry_return->request_mode\fP is zero, +the geometry manager agrees not to change the corresponding value +if \fIgeometry_return\fP is used immediately +in a new request. +If a bit is 1, +the geometry manager does change that element to the corresponding +value in \fIgeometry_return\fP. +More bits may be set in \fIgeometry_return->request_mode\fP +than in the original request if +the geometry manager intends to change other fields should the +child accept the compromise. +.LP +When +.PN XtGeometryAlmost +is returned, +the widget must decide if the compromise suggested in \fIgeometry_return\fP +is acceptable. +If it is, the widget must not change its geometry directly; +rather, it must make another call to +.PN XtMakeGeometryRequest . +.LP +If the next geometry request from this child uses the +\fIgeometry_return\fP values filled in by the geometry manager with an +.PN XtGeometryAlmost +return and if there have been no intervening geometry requests on +either its parent or any of its other children, +the geometry manager must grant the request, if possible. +That is, if the child asks immediately with the returned geometry, +it should get an answer of +.PN XtGeometryYes . +However, +dynamic behavior in +the user's window manager may affect the final outcome. +.LP +To return +.PN XtGeometryYes , +the geometry manager frequently rearranges the position of other managed +children by calling +.PN XtMoveWidget . +However, a few geometry managers may sometimes change the +size of other managed children by calling +.PN XtResizeWidget +or +.PN XtConfigureWidget . +If +.PN XtCWQueryOnly +is specified, +the geometry manager must return data describing +how it would react to this geometry +request without actually moving or resizing any widgets. +.LP +Geometry managers must not assume that the \fIrequest\fP +and \fIgeometry_return\fP 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. + +.NH 2 +Widget Placement and Sizing +.XS +\*(SN Widget Placement and Sizing +.XE +.LP +To move a sibling widget of the child making the geometry request, +the parent uses +.PN XtMoveWidget . +.LP +.IN "XtMoveWidget" "" "@DEF@" +.sM +.FD 0 +void XtMoveWidget(\fIw\fP, \fIx\fP, \fIy\fP) +.br + Widget \fIw\fP; +.br + Position \fIx\fP; +.br + Position \fIy\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(rI +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the new widget x and y coordinates. +.LP +.eM +The +.PN XtMoveWidget +function returns immediately if the specified geometry fields +are the same as the old values. +Otherwise, +.PN XtMoveWidget +writes the new \fIx\fP and \fIy\fP values into the object +and, if the object is a widget and is realized, issues an Xlib +.PN XMoveWindow +call on the widget's window. +.sp +.LP +To resize a sibling widget of the child making the geometry request, +the parent uses +.PN XtResizeWidget . +.LP +.IN "XtResizeWidget" "" "@DEF@" +.sM +.FD 0 +void XtResizeWidget(\fIw\fP, \fIwidth\fP, \fIheight\fP, \fIborder_width\fP) +.br + Widget \fIw\fP; +.br + Dimension \fIwidth\fP; +.br + Dimension \fIheight\fP; +.br + Dimension \fIborder_width\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(rI +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +.br +.ns +.IP \fIborder_width\fP 1i +Specify the new widget size. +.LP +.eM +The +.PN XtResizeWidget +function returns immediately if the specified geometry fields +are the same as the old values. +Otherwise, +.PN XtResizeWidget +writes the new \fIwidth\fP, \fIheight\fP, and \fIborder_width\fP values into +the object and, if the object is a widget and is realized, issues an +.PN XConfigureWindow +call on the widget's window. +.LP +If the new width or height is different from the old values, +.PN XtResizeWidget +calls the object's resize procedure to notify it of the size change. +.sp +.LP +To move and resize the sibling widget of the child making the geometry request, +the parent uses +.PN XtConfigureWidget . +.LP +.IN "XtConfigureWidget" "" "@DEF@" +.sM +.FD 0 +void XtConfigureWidget(\fIw\fP, \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, \ +\fIborder_width\fP) +.br + Widget \fIw\fP; +.br + Position \fIx\fP; +.br + Position \fIy\fP; +.br + Dimension \fIwidth\fP; +.br + Dimension \fIheight\fP; +.br + Dimension \fIborder_width\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(rI +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the new widget x and y coordinates. +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +.br +.ns +.IP \fIborder_width\fP 1i +Specify the new widget size. +.LP +.eM +The +.PN XtConfigureWidget +function returns immediately if the specified new geometry fields +are all equal to the current values. +Otherwise, +.PN XtConfigureWidget +writes the new \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, +and \fIborder_width\fP values +into the object and, if the object is a widget and is realized, makes an Xlib +.PN XConfigureWindow +call on the widget's window. +.LP +If the new width or height is different from its old value, +.PN XtConfigureWidget +calls the object's resize procedure to notify it of the size change; +otherwise, it simply returns. +.sp +.LP +To resize a child widget that already has the new values of its width, +height, and border width, the parent uses +.PN XtResizeWindow . +.LP +.IN "XtResizeWindow" "" "@DEF@" +.sM +.FD 0 +void XtResizeWindow(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(cI +.LP +.eM +The +.PN XtResizeWindow +function calls the +.PN XConfigureWindow +Xlib function to make the window of the specified widget match 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. +.LP +There are very few times to use +.PN XtResizeWindow ; +instead, the parent should use +.PN XtResizeWidget . + +.NH 2 +Preferred Geometry +.XS +\*(SN Preferred Geometry +.XE +.LP +Some parents may be willing to adjust their layouts to accommodate the +preferred geometries of their children. +They can use +.PN XtQueryGeometry +to obtain the preferred geometry +and, as they see fit, can use or ignore any portion of the response. +.sp +.LP +To query a child widget's preferred geometry, use +.PN XtQueryGeometry . +.LP +.IN "XtQueryGeometry" "" "@DEF@" +.sM +.FD 0 +XtGeometryResult XtQueryGeometry(\fIw\fP, \fIintended\fP, \ +\fIpreferred_return\fP) +.br + Widget \fIw\fP; +.br + XtWidgetGeometry *\fIintended\fP; +.br + XtWidgetGeometry *\fIpreferred_return\fP; +.FN +.IP \fIw\fP 1.1i +Specifies the widget. \*(rI +.IP \fIintended\fP 1.1i +Specifies the new geometry the parent plans to give to the child, or +NULL. +.IP \fIpreferred_return\fP 1.1i +Returns the child widget's preferred geometry. +.LP +.eM +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 \fIintended.request_mode\fP, +and calls +.PN XtQueryGeometry . +The parent 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. +.LP +.PN XtQueryGeometry +clears all bits in the \fIpreferred_return->request_mode\fP +field and checks the +\fIquery_geometry\fP field of the specified widget's class record. +If \fIquery_geometry\fP is not NULL, +.PN XtQueryGeometry +calls the query_geometry procedure and passes as arguments the +specified widget, \fIintended\fP, and \fIpreferred_return\fP structures. +If the \fIintended\fP argument is NULL, +.PN XtQueryGeometry +replaces it with a pointer to an +.PN XtWidgetGeometry +structure with \fIrequest_mode\fP equal to zero before calling the +query_geometry procedure. +.NT +If +.PN XtQueryGeometry +is called from within a geometry_manager +procedure for the widget that issued +.PN XtMakeGeometryRequest +or +.PN XtMakeResizeRequest , +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. +.NE +.sp +.LP +The query_geometry procedure pointer is of type +.PN XtGeometryHandler . +.LP +.IN "query_geometry procedure" "" "@DEF@" +.sM +.FD 0 +typedef XtGeometryResult (*XtGeometryHandler)(Widget, XtWidgetGeometry*, \ +XtWidgetGeometry*); +.br + Widget \fIw\fP; +.br + XtWidgetGeometry *\fIrequest\fP; +.br + XtWidgetGeometry *\fIpreferred_return\fP; +.FN +.IP \fIw\fP 1.2i +Passes the child widget whose preferred geometry is required. +.IP \fIrequest\fP 1.2i +Passes the geometry changes that the parent plans to make. +.IP \fIpreferred_return\fP 1.2i +Passes a structure in which the child returns its preferred geometry. +.LP +.eM +.IN "query_geometry procedure" +The query_geometry procedure is expected to examine the bits set in +\fIrequest->request_mode\fP, evaluate the preferred geometry of the widget, +and store the result in \fIpreferred_return\fP +(setting the bits in \fIpreferred_return->request_mode\fP corresponding +to those geometry fields that it cares about). +If the proposed geometry change is acceptable without modification, +the query_geometry procedure should return +.PN XtGeometryYes . +If at least one field in \fIpreferred_return\fP +with a bit set in \fIpreferred_return->request_mode\fP +is different +from the corresponding field in \fIrequest\fP +or if a bit was set in \fIpreferred_return->request_mode\fP +that was not set in the request, +the query_geometry procedure should return +.PN XtGeometryAlmost . +If the preferred geometry is identical to the current geometry, +the query_geometry procedure should return +.PN XtGeometryNo . +.NT +The query_geometry procedure may assume +that no +.PN XtMakeResizeRequest +or +.PN XtMakeGeometryRequest +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. +.NE +.LP +After calling the query_geometry procedure +or if the \fIquery_geometry\fP field is NULL, +.PN XtQueryGeometry +examines all the unset bits in \fIpreferred_return->request_mode\fP +and sets the corresponding fields in \fIpreferred_return\fP +to the current values from the widget instance. +If +.PN CWStackMode +is not set, +the \fIstack_mode\fP field is set to +.PN XtSMDontChange . +.PN XtQueryGeometry +returns the value returned by the query_geometry procedure or +.PN XtGeometryYes +if the \fIquery_geometry\fP field is NULL. +.LP +Therefore, the caller can interpret a return of +.PN XtGeometryYes +as not needing to evaluate the contents of the reply and, more important, +not needing to modify its layout plans. +A return of +.PN XtGeometryAlmost +means either that both the parent and the child expressed interest +in at least one common field and the child's preference does not match +the parent's intentions or that the child expressed interest in a field that +the parent might need to consider. +A return value of +.PN XtGeometryNo +means that both the parent and the child expressed interest in a field and +that the child suggests that the field's current value 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 \fIpreferred_return\fP structure contains complete +geometry information for the child. +.LP +Parents are expected to call +.PN XtQueryGeometry +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. + +.NH 2 +Size Change Management: The resize Procedure +.XS +\*(SN Size Change Management: The resize Procedure +.XE +.LP +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 +.PN XtResizeWidget , +which updates the geometry fields in the widget, +configures the window if the widget is realized, +and calls the child's resize procedure to notify the child. +The resize procedure pointer is of type +.PN XtWidgetProc . +.IN "resize procedure" "" "@DEF@" +.LP +If a class need not recalculate anything when a widget is resized, +it can specify NULL for the \fIresize\fP 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 \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, +and \fIborder_width\fP 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 +.PN XtMakeGeometryRequest +or +.PN XtMakeResizeRequest +call from its resize procedure. +.bp diff --git a/specs/CH07 b/specs/CH07 new file mode 100644 index 0000000..07b3674 --- /dev/null +++ b/specs/CH07 @@ -0,0 +1,3555 @@ +.\" $Xorg: CH07,v 1.4 2000/08/17 19:42:45 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 7\fP\s-1 + +\s+1\fBEvent Management\fP\s-1 +.sp 2 +.nr H1 7 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 7 \(em Event Management +.XE +While Xlib allows the reading and processing of events anywhere in an application, +widgets in the \*(tk neither directly read events +nor grab the server or pointer. +Widgets register procedures that are to be called +when an event or class of events occurs in that widget. +.LP +A typical application consists of startup code followed by an event loop +that reads events and dispatches them by calling +the procedures that widgets have registered. +The default event loop provided by the \*(xI is +.PN XtAppMainLoop . +.LP +The event manager is a collection of functions to perform the following tasks: +.IP \(bu 5 +Add or remove event sources other than X server events (in particular, +timer interrupts, file input, or POSIX signals). +.IP \(bu 5 +Query the status of event sources. +.IP \(bu 5 +Add or remove procedures to be called when an event occurs for a particular +widget. +.IP \(bu 5 +Enable and +disable the dispatching of user-initiated events (keyboard and pointer events) +for a particular widget. +.IP \(bu 5 +Constrain the dispatching of events to a cascade of pop-up widgets. +.IP \(bu 5 +Register procedures to be called when specific events arrive. +.IP \(bu 5 +Register procedures to be called when the \*(xI will block. +.IP \(bu 5 +Enable safe operation in a multi-threaded environment. +.LP +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 +.PN XtAppMainLoop . + +.NH 2 +Adding and Deleting Additional Event Sources +.XS +\fB\*(SN Adding and Deleting Additional Event Sources\fP +.XE +.LP +While most applications are driven only by X events, +some applications need to incorporate other sources of input +into the \*(xI event-handling mechanism. +The event manager provides routines to integrate notification of timer events +and file data pending into this mechanism. +.LP +The next section describes functions that provide input gathering from files. +The application registers the files with the \*(xI read routine. +When input is pending on one of the files, +the registered callback procedures are invoked. + +.NH 3 +Adding and Removing Input Sources +.XS +\fB\*(SN Adding and Removing Input Sources\fP +.XE +.LP +To register a new file as an input source for a given application context, use +.PN XtAppAddInput . +.LP +.IN "XtAppAddInput" "" "@DEF@" +.sM +.FD 0 +XtInputId XtAppAddInput(\fIapp_context\fP, \fIsource\fP, \fIcondition\fP, \ +\fIproc\fP, \fIclient_data\fP) +.br + XtAppContext \fIapp_context\fP; +.br + int \fIsource\fP; +.br + XtPointer \fIcondition\fP; +.br + XtInputCallbackProc \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context that identifies the application. +.IP \fIsource\fP 1i +Specifies the source file descriptor on a POSIX-based system +or other operating-system-dependent device specification. +.IP \fIcondition\fP 1i +Specifies the mask that indicates a read, write, or exception condition +or some other operating-system-dependent condition. +.IP \fIproc\fP 1i +Specifies the procedure to be called when the condition is found. +.IP \fIclient_data\fP 1i +Specifies an argument passed to the specified procedure +when it is called. +.LP +.eM +The +.PN XtAppAddInput +function registers with the \*(xI read routine a new source of events, +which is usually file input but can also be file output. +Note that \fIfile\fP should be loosely interpreted to mean any sink +or source of data. +.PN XtAppAddInput +also specifies the conditions under which the source can generate events. +When an event is pending on this source, +the callback procedure is called. +.LP +The legal values for the \fIcondition\fP argument are operating-system-dependent. +On a POSIX-based system, +\fIsource\fP is a file number and the condition is some union of the following: +.IN "XtInputReadMask" "" "@DEF@" +.IP \fBXtInputReadMask\fR 1.5i +Specifies that \fIproc\fP is to be called when \fIsource\fP has data to be read. +.IN "XtInputWriteMask" "" "@DEF@" +.IP \fBXtInputWriteMask\fR 1.5i +Specifies that \fIproc\fP is to be called when \fIsource\fP is ready +for writing. +.IN "XtInputExceptMask" "" "@DEF@" +.IP \fBXtInputExceptMask\fR 1.5i +Specifies that \fIproc\fP is to be called when \fIsource\fP has +exception data. +.LP +Callback procedure pointers used to handle file events are of +type +.PN XtInputCallbackProc . +.LP +.IN "XtInputCallbackProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtInputCallbackProc)(XtPointer, int*, XtInputId*); +.br + XtPointer \fIclient_data\fP; +.br + int *\fIsource\fP; +.br + XtInputId *\fIid\fP; +.FN +.IP \fIclient_data\fP 1i +Passes the client data argument that was registered for this procedure in +.PN XtApp\%AddInput . +.IP \fIsource\fP 1i +Passes the source file descriptor generating the event. +.IP \fIid\fP 1i +Passes the id returned from the corresponding +.PN XtAppAddInput +call. +.LP +.eM +See Section 7.12 for information regarding the use of +.PN XtAppAddInput +in multiple threads. +.sp +.LP +To discontinue a source of input, use +.PN XtRemoveInput . +.LP +.IN "XtRemoveInput" "" "@DEF@" +.sM +.FD 0 +void XtRemoveInput(\fIid\fP) +.br + XtInputId \fIid\fP; +.FN +.IP \fIid\fP 1i +Specifies the id returned from the corresponding +.PN XtAppAddInput +call. +.LP +.eM +The +.PN XtRemoveInput +function causes the \*(xI read routine to stop watching for events +from the file source specified by \fIid\fP. +.LP +See Section 7.12 for information regarding the use of +.PN XtRemoveInput +in multiple threads. + +.NH 3 +Adding and Removing Blocking Notifications +.XS +\fB\*(SN Adding and Removing Blocking Notifications\fP +.XE +.LP +Occasionally it is desirable for an application to receive notification +when the \*(xI 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. +.sp +.LP +To register a hook that is called immediately prior to event blocking, use +.PN XtAppAddBlockHook . +.LP +.IN "XtAppAddBlockHook" "" "@DEF@" +.sM +.FD 0 +XtBlockHookId XtAppAddBlockHook(\fIapp_context\fP, \fIproc\fP, \ +\fIclient_data\fP) +.br + XtAppContext \fIapp_context\fP; +.br + XtBlockHookProc \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context that identifies the application. +.IP \fIproc\fP 1i +Specifies the procedure to be called before blocking. +.IP \fIclient_data\fP 1i +Specifies an argument passed to the specified procedure when it is called. +.LP +.eM +The +.PN XtAppAddBlockHook +function registers the specified procedure and returns an identifier for it. +The hook procedure \fIproc\fP is called at any time in the future when +the \*(xI are about to block pending some input. +.LP +The procedure pointers used to provide notification of event blocking +are of type +.PN XtBlockHookProc . +.LP +.IN "XtBlockHookProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtBlockHookProc)(XtPointer); +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIclient_data\fP 1i +Passes the client data argument that was registered for this procedure in +.PN XtApp\%AddBlockHook . +.LP +.eM +To discontinue the use of a procedure for blocking notification, use +.PN XtRemoveBlockHook . +.LP +.IN "XtRemoveBlockHook" "" "@DEF@" +.sM +.FD 0 +void XtRemoveBlockHook(\fIid\fP) +.br + XtBlockHookId \fIid\fP; +.FN +.IP \fIid\fP 1i +Specifies the identifier returned from the corresponding call to +.PN XtAppAddBlockHook . +.LP +.eM +The +.PN XtRemoveBlockHook +function removes the specified procedure from the list of procedures +that are called by the \*(xI read routine before blocking on event sources. + +.NH 3 +Adding and Removing Timeouts +.XS +\fB\*(SN Adding and Removing Timeouts\fP +.XE +.LP +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. +.sp +.LP +To register a timeout callback, use +.PN XtAppAddTimeOut . +.LP +.IN "XtAppAddTimeOut" "" "@DEF@" +.sM +.FD 0 +XtIntervalId XtAppAddTimeOut(\fIapp_context\fP, \fIinterval\fP, \fIproc\fP, \ +\fIclient_data\fP) +.br + XtAppContext \fIapp_context\fP; +.br + unsigned long \fIinterval\fP; +.br + XtTimerCallbackProc \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context for which the timer is to be set. +.IP \fIinterval\fP 1i +Specifies the time interval in milliseconds. +.IP \fIproc\fP 1i +Specifies the procedure to be called when the time expires. +.IP \fIclient_data\fP 1i +Specifies an argument passed to the specified procedure +when it is called. +.LP +.eM +The +.PN XtAppAddTimeOut +function creates a timeout and returns an identifier for it. +The timeout value is set to \fIinterval\fP. +The callback procedure \fIproc\fP is called when +.PN XtAppNextEvent +or +.PN XtAppProcessEvent +is next called after the time interval elapses, +and then the timeout is removed. +.LP +Callback procedure pointers used with timeouts are of +type +.PN XtTimerCallbackProc . +.LP +.IN "XtTimerCallbackProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtTimerCallbackProc)(XtPointer, XtIntervalId*); +.br + XtPointer \fIclient_data\fP; +.br + XtIntervalId *\fItimer\fP; +.FN +.IP \fIclient_data\fP 1i +Passes the client data argument that was registered for this procedure in +.PN XtApp\%AddTimeOut . +.IP \fItimer\fP 1i +Passes the id returned from the corresponding +.PN XtAppAddTimeOut +call. +.LP +.eM +See Section 7.12 for information regarding the use of +.PN XtAppAddTimeOut +in multiple threads. +.sp +.LP +To clear a timeout value, use +.PN XtRemoveTimeOut . +.LP +.IN "XtRemoveTimeOut" "" "@DEF@" +.sM +.FD 0 +void XtRemoveTimeOut(\fItimer\fP) +.br + XtIntervalId \fItimer\fP; +.FN +.IP \fItimer\fP 1i +Specifies the id for the timeout request to be cleared. +.LP +.eM +The +.PN XtRemoveTimeOut +function removes the pending timeout. +Note that timeouts are automatically removed once they trigger. +.LP +Please refer to Section 7.12 for information regarding the use of +.PN XtRemoveTimeOut +in multiple threads. + +.NH 3 +Adding and Removing Signal Callbacks +.XS +\fB\*(SN Adding and Removing Signal Callbacks\fP +.XE +.LP +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. +.sp +.LP +Prior to establishing a signal handler, the application or widget should +call +.PN XtAppAddSignal +and store the resulting identifier in a place accessible to the signal +handler. When a signal arrives, the signal handler should call +.PN XtNoticeSignal +to notify the \*(xI that a signal has occured. To register a signal +callback use +.PN XtAppAddSignal . +.LP +.IN "XtAppAddSignal" "" "@DEF@" +.sM +.FD 0 +XtSignalId XtAppAddSignal(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP) +.br + XtAppContext \fIapp_context\fP; +.br + XtSignalCallbackProc \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context that identifies the application. +.IP \fIproc\fP 1i +Specifies the procedure to be called when the signal is noticed. +.IP \fIclient_data\fP 1i +Specifies an argument passed to the specified procedure when it is called. +.LP +.eM +The callback procedure pointers used to handle signal events are of type +.PN XtSignalCallbackProc . +.LP +.IN "XtSignalCallbackProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtSignalCallbackProc)(XtPointer, XtSignalId*); +.br + XtPointer \fIclient_data\fP; +.br + XtSignalId *\fIid\fP; +.FN +.IP \fIclient_data\fP 1i +Passes the client data argument that was registered for this procedure in +.PN XtAppAddSignal . +.IP \fIid\fP 1i +Passes the id returned from the corresponding +.PN XtAppAddSignal +call. +.LP +.eM +To notify the \*(xI that a signal has occured, use +.PN XtNoticeSignal . +.LP +.IN "XtNoticeSignal" "" "@DEF@" +.sp +.sM +.FD 0 +void XtNoticeSignal(\fIid\fP) +.br + XtSignalId \fIid\fP; +.FN +.IP \fIid\fP 1i +Specifies the id returned from the corresponding +.PN XtAppAddSignal +call. +.LP +.eM +On a POSIX-based system, +.PN XtNoticeSignal +is the only \*(xI function that can safely be called from a signal handler. +If +.PN XtNoticeSignal +is invoked multiple times before the \*(xI are able to invoke the +registered callback, the callback is only called once. +Logically, the \*(xI maintain ``pending'' flag for each registered callback. +This flag is initially +.PN False +and is set to +.PN True +by +.PN XtNoticeSignal . +When +.PN XtAppNextEvent +or +.PN XtAppProcessEvent +(with a mask including +.PN XtIMSignal ) +is called, all registered callbacks with ``pending'' +.PN True +are invoked and the flags are reset to +.PN False . +.LP +If the signal handler wants to track how many times the signal has been +raised, it can keep its own private counter. Typically the handler would +not do any other work; the callback does the actual processing for the +signal. The \*(xI never block signals from being raised, so if a given +signal can be raised multiple times before the \*(xI 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 \*(xI +sets the pending flag to +.PN False +but before the callback can get control, in which case the pending flag +will still be +.PN True +after the callback returns, and the \*(xI will invoke the callback +again, even though all of the signal raises have been handled. The +callback must also be prepared to handle this case. +.LP +To remove a registered signal callback, call +.PN XtRemoveSignal . +.LP +.IN "XtRemoveSignal" "" "@DEF@" +.sM +.FD 0 +void XtRemoveSignal(\fIid\fP) +.br + XtSignalId \fIid\fP; +.FN +.IP \fIid\fP 1i +Specifies the id returned by the corresponding call to +.PN XtAppAddSignal . +.LP +.eM +The client should typically disable the source of the signal before calling +.PN XtRemoveSignal . +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 +.PN XtRemoveSignal +the client can test for signals with +.PN XtAppPending +and process them by calling +.PN XtAppProcessEvent +with the mask +.PN XtIMSignal . + +.NH 2 +Constraining Events to a Cascade of Widgets +.XS +\fB\*(SN Constraining Events to a Cascade of Widgets\fP +.XE +.LP +.IN "Grabbing Input" +.IN "Input Grabbing" +Modal widgets are widgets that, except for the input directed to them, +lock out user input to the application. +.LP +When a modal menu or modal dialog box is popped up using +.PN XtPopup , +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. +.LP +Menus can pop up submenus, and dialog boxes can pop up further dialog +boxes to create a pop-up cascade. +In this case, +user events may be delivered to one of several modal widgets in the cascade. +.LP +Display-related events should be delivered outside the modal cascade so that +exposure events and the like keep the application's display up-to-date. +Any event that occurs within the cascade is delivered as usual. +The user events delivered to the most recent spring-loaded shell +in the cascade when they occur outside the cascade are called remap events +and are +.PN KeyPress , +.PN KeyRelease , +.PN ButtonPress , +and +.PN ButtonRelease . +The user events ignored when they occur outside the cascade are +.PN MotionNotify +and +.PN EnterNotify . +All other events are delivered normally. +In particular, note that this is one +way in which widgets can receive +.PN LeaveNotify +events without first receiving +.PN EnterNotify +events; they should be prepared to deal with +this, typically by ignoring any unmatched +.PN LeaveNotify +events. +.LP +.PN XtPopup +uses the +.PN XtAddGrab +and +.PN XtRemoveGrab +functions to constrain user events to a modal cascade +and subsequently to remove a grab when the modal widget is popped down. + +.sp +.LP +To constrain or redirect user input to a modal widget, use +.PN XtAddGrab . +.LP +.IN "XtAddGrab" "" "@DEF@" +.sM +.FD 0 +void XtAddGrab(\fIw\fP, \fIexclusive\fP, \fIspring_loaded\fP) +.br + Widget \fIw\fP; +.br + Boolean \fIexclusive\fP; +.br + Boolean \fIspring_loaded\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget to add to the modal cascade. \*(cI +.IP \fIexclusive\fP 1i +Specifies whether user events should be dispatched exclusively to this widget +or also to previous widgets in the cascade. +.IP \fIspring_loaded\fP 1i +Specifies whether this widget was popped up because the user pressed +a pointer button. +.LP +.eM +The +.PN XtAddGrab +function appends the widget to the modal cascade +and checks that \fIexclusive\fP is +.PN True +if \fIspring_loaded\fP is +.PN True . +If this condition is not met, +.PN XtAddGrab +generates a warning message. +.LP +The modal cascade is used by +.PN XtDispatchEvent +when it tries to dispatch a user event. +When at least one modal widget is in the widget cascade, +.PN XtDispatchEvent +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 \fIexclusive\fP parameter +.PN True . +.LP +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 \fIexclusive\fP +.PN False . +Modal dialog boxes that need to restrict user input to the most deeply nested +dialog box add a subdialog widget to the cascade with \fIexclusive\fP +.PN True . +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. +.LP +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 \fIspring_loaded\fP +.PN True , +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 +delivered also to the spring-loaded widget. +Regardless of where it is dispatched, the \*(xI do not modify +the contents of the event. +.sp +.LP +To remove the redirection of user input to a modal widget, use +.PN XtRemoveGrab . +.LP +.IN "XtRemoveGrab" "" "@DEF@" +.sM +.FD 0 +void XtRemoveGrab(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget to remove from the modal cascade. +.LP +.eM +The +.PN XtRemoveGrab +function removes widgets from the modal cascade starting +at the most recent widget up to and including the specified widget. +It issues a warning if the specified widget is not on the modal cascade. + +.NH 3 +Requesting Key and Button Grabs +.XS +\fB\*(SN Requesting Key and Button Grabs\fP +.XE +.LP +The \*(xI provide a set of key and button grab interfaces that +are parallel to those provided by Xlib and that allow the \*(xI +to modify event dispatching when necessary. \*(tk applications and +widgets that need to passively grab keys or buttons or actively grab +the keyboard or pointer should use the +following \*(xI routines rather than the corresponding Xlib +routines. +.sp +.LP +To passively grab a single key of the keyboard, use +.PN XtGrabKey . +.LP +.IN "XtGrabKey" "" "@DEF@" +.sM +.FD 0 +void XtGrabKey(\fIwidget\fP, \fIkeycode\fP, \fImodifiers\fP, \ +\fIowner_events\fP, \fIpointer_mode\fP, \fIkeyboard_mode\fP) +.br + Widget \fIwidget\fP; +.br + KeyCode \fIkeycode\fP; +.br + Modifiers \fImodifiers\fP; +.br + Boolean \fIowner_events\fP; +.br + int \fIpointer_mode\fP, \fIkeyboard_mode\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget in whose window the key is to be grabbed. \*(cI +.sp 6p +.IP \fIkeycode\fP +.br +.ns +.IP \fImodifiers\fP +.br +.ns +.IP \fIowner_events\fP +.br +.ns +.IP \fIpointer_mode\fP +.br +.ns +.IP \fIkeyboard_mode\fP 1i +Specify arguments to +.PN XGrabKey ; +see Section 12.2 in \fI\*(xL\fP. +.LP +.eM +.PN XtGrabKey +calls +.PN XGrabKey +specifying the widget's window as the grab +window if the widget is realized. The remaining arguments are exactly +as for +.PN XGrabKey . +If the widget is not realized, or is later unrealized, the call to +.PN XGrabKey +is performed (again) when +the widget is realized and its window becomes mapped. In the future, +if +.PN XtDispatchEvent +is called with a +.PN KeyPress +event matching the specified keycode and modifiers (which may be +.PN AnyKey +or +.PN AnyModifier , +respectively) for the +widget's window, the \*(xI will call +.PN XtUngrabKeyboard +with the timestamp from the +.PN KeyPress +event if either of the following conditions is true: +.IP \(bu 3 +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 +.IP \(bu 3 +.PN XFilterEvent +returns +.PN True . + +.sp +.LP +To cancel a passive key grab, use +.PN XtUngrabKey . +.LP +.IN "XtUngrabKey" "" "@DEF@" +.sM +.FD 0 +void XtUngrabKey(\fIwidget\fP, \fIkeycode\fP\fI, modifiers\fP) +.br + Widget \fIwidget\fP; +.br + KeyCode \fIkeycode\fP; +.br + Modifiers \fImodifiers\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget in whose window the key was grabbed. +.sp 6p +.IP \fIkeycode\fP +.br +.ns +.IP \fImodifiers\fP 1i +Specify arguments to +.PN XUngrabKey ; +see Section 12.2 in \fI\*(xL\fP. +.LP +.eM +The +.PN XtUngrabKey +procedure calls +.PN XUngrabKey +specifying the widget's +window as the ungrab window if the widget is realized. The remaining +arguments are exactly as for +.PN XUngrabKey . +If the widget is not realized, +.PN XtUngrabKey +removes a deferred +.PN XtGrabKey +request, if any, for the specified widget, keycode, and modifiers. +.sp +.LP +To actively grab the keyboard, use +.PN XtGrabKeyboard . +.LP +.IN "XtGrabKeyboard" "" "@DEF@" +.sM +.FD 0 +int XtGrabKeyboard(\fIwidget\fP, \fIowner_events\fP, \fIpointer_mode\fP, \ +\fIkeyboard_mode\fP, \fItime\fP) +.br + Widget \fIwidget\fP; +.br + Boolean \fIowner_events\fP; +.br + int \fIpointer_mode\fP, \fIkeyboard_mode\fP; +.br + Time \fItime\fP; +.br +.FN +.IP \fIwidget\fP 1i +Specifies the widget for whose window the keyboard is to be grabbed. +\*(cI +.sp 6p +.IP \fIowner_events\fP +.br +.ns +.IP \fIpointer_mode\fP +.br +.ns +.IP \fIkeyboard_mode\fP +.br +.ns +.IP \fItime\fP 1i +Specify arguments to +.PN XGrabKeyboard ; +see Section 12.2 in \fI\*(xL\fP. +.LP +.eM +If the specified widget is realized, +.PN XtGrabKeyboard +calls +.PN XGrabKeyboard +specifying the widget's window as the grab window. The remaining +arguments and return value are exactly as for +.PN XGrabKeyboard . +If the widget is not realized, +.PN XtGrabKeyboard +immediately returns +.PN GrabNotViewable . +No future automatic ungrab is implied by +.PN XtGrabKeyboard . +.sp +.LP +To cancel an active keyboard grab, use +.PN XtUngrabKeyboard . +.LP +.IN "XtUngrabKeyboard" "" "@DEF@" +.sM +.FD 0 +void XtUngrabKeyboard(\fIwidget\fP, \fItime\fP) +.br + Widget \fIwidget\fP; +.br + Time \fItime\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget that has the active keyboard grab. +.IP \fItime\fP 1i +Specifies the additional argument to +.PN XUngrabKeyboard ; +see Section 12.2 in \fI\*(xL\fP. +.LP +.eM +.PN XtUngrabKeyboard +calls +.PN XUngrabKeyboard +with the specified time. +.sp +.LP +To passively grab a single pointer button, use +.PN XtGrabButton . +.LP +.IN "XtGrabButton" "" "@DEF@" +.sM +.FD 0 +void XtGrabButton(\fIwidget\fP, \fIbutton\fP, \fImodifiers\fP, \ +\fIowner_events\fP, \fIevent_mask\fP, \fIpointer_mode\fP, + \fIkeyboard_mode\fP, \fIconfine_to\fP, \fIcursor\fP) +.br + Widget \fIwidget\fP; +.br + int \fIbutton\fP; +.br + Modifiers \fImodifiers\fP; +.br + Boolean \fIowner_events\fP; +.br + unsigned int \fIevent_mask\fP; +.br + int \fIpointer_mode\fP, \fIkeyboard_mode\fP; +.br + Window \fIconfine_to\fP; +.br + Cursor \fIcursor\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget in whose window the button is to be grabbed. \*(cI +.sp 6p +.IP \fIbutton\fP +.br +.ns +.IP \fImodifiers\fP +.br +.ns +.IP \fIowner_events\fP +.br +.ns +.IP \fIevent_mask\fP +.br +.ns +.IP \fIpointer_mode\fP +.br +.ns +.IP \fIkeyboard_mode\fP +.br +.ns +.IP \fIconfine_to\fP +.br +.ns +.IP \fIcursor\fP 1i +Specify arguments to +.PN XGrabButton ; +see Section 12.1 in \fI\*(xL\fP. +.LP +.eM +.PN XtGrabButton +calls +.PN XGrabButton +specifying the widget's window as the +grab window if the widget is realized. The remaining arguments are +exactly as for +.PN XGrabButton . +If the widget is not realized, or is later unrealized, the call to +.PN XGrabButton +is performed (again) +when the widget is realized and its window becomes mapped. In the +future, if +.PN XtDispatchEvent +is called with a +.PN ButtonPress +event matching the specified button and modifiers (which may be +.PN AnyButton +or +.PN AnyModifier , +respectively) +for the widget's window, the \*(xI will call +.PN XtUngrabPointer +with the timestamp from the +.PN ButtonPress +event if either of the following conditions is true: +.IP \(bu 3 +There is a modal cascade and the +widget is not in the active subset of the cascade and the pointer was +not previously grabbed, or +.IP \(bu 3 +.PN XFilterEvent +returns +.PN True . + +.sp +.LP +To cancel a passive button grab, use +.PN XtUngrabButton . +.LP +.IN "XtUngrabButton" "" "@DEF@" +.sM +.FD 0 +void XtUngrabButton(\fIwidget\fP, \fIbutton\fP, \fImodifiers\fP) +.br + Widget \fIwidget\fP; +.br + unsigned int \fIbutton\fP; +.br + Modifiers \fImodifiers\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget in whose window the button was grabbed. +.IP \fIbutton\fP +.br +.ns +.IP \fImodifiers\fP 1i +Specify arguments to +.PN XUngrabButton ; +see Section 12.1 in \fI\*(xL\fP. +.LP +.eM +The +.PN XtUngrabButton +procedure calls +.PN XUngrabButton +specifying the +widget's window as the ungrab window if the widget is realized. The +remaining arguments are exactly as for +.PN XUngrabButton . +If the widget is not realized, +.PN XtUngrabButton +removes a deferred +.PN XtGrabButton +request, if any, for the specified widget, button, and modifiers. +.sp +.LP +To actively grab the pointer, use +.PN XtGrabPointer . +.LP +.IN "XtGrabPointer" "" "@DEF@" +.sM +.FD 0 +int XtGrabPointer(\fIwidget\fP, \fIowner_events\fP, \fIevent_mask\fP, \ +\fIpointer_mode\fP, \fIkeyboard_mode\fP, + \fIconfine_to\fP, \fIcursor\fP, \fItime\fP) +.br + Widget \fIwidget\fP; +.br + Boolean \fIowner_events\fP; +.br + unsigned int \fIevent_mask\fP; +.br + int \fIpointer_mode\fP, \fIkeyboard_mode\fP; +.br + Window \fIconfine_to\fP; +.br + Cursor \fIcursor\fP; +.br + Time \fItime\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget for whose window the pointer is to be grabbed. \*(cI +.sp 6p +.IP \fIowner_events\fP +.br +.ns +.IP \fIevent_mask\fP +.br +.ns +.IP \fIpointer_mode\fP +.br +.ns +.IP \fIkeyboard_mode\fP +.br +.ns +.IP \fIconfine_to\fP +.br +.ns +.IP \fIcursor\fP +.br +.ns +.IP \fItime\fP 1i +Specify arguments to +.PN XGrabPointer ; +see Section 12.1 in \fI\*(xL\fP. +.LP +.eM +If the specified widget is realized, +.PN XtGrabPointer +calls +.PN XGrabPointer , +specifying the widget's window as the grab window. The remaining +arguments and return value are exactly as for +.PN XGrabPointer . +If the widget is not realized, +.PN XtGrabPointer +immediately returns +.PN GrabNotViewable . +No future automatic ungrab is implied by +.PN XtGrabPointer . +.sp +.LP +To cancel an active pointer grab, use +.PN XtUngrabPointer . +.LP +.IN "XtUngrabPointer" "" "@DEF@" +.sM +.FD 0 +void XtUngrabPointer(\fIwidget\fP, \fItime\fP) +.br + Widget \fIwidget\fP; +.br + Time \fItime\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget that has the active pointer grab. +.IP \fItime\fP 1i +Specifies the time argument to +.PN XUngrabPointer ; +see Section 12.1 in \fI\*(xL\fP. +.LP +.eM +.PN XtUngrabPointer +calls +.PN XUngrabPointer +with the specified time. + +.NH 2 +Focusing Events on a Child +.XS +\fB\*(SN Focusing Events on a Child\fP +.XE +.LP +To redirect keyboard input to a normal descendant of a +widget without calling +.PN XSetInputFocus , +use +.PN XtSetKeyboardFocus . +.LP +.IN "XtSetKeyboardFocus" "" "@DEF@" +.sM +.FD 0 +void XtSetKeyboardFocus(\fIsubtree\fP\, \fIdescendant\fP) +.br + Widget \fIsubtree\fP, \fIdescendant\fP; +.FN +.IP \fIsubtree\fP 1i +Specifies the subtree of the hierarchy for which the keyboard focus is +to be set. \*(cI +.IP \fIdescendant\fP 1i +Specifies either the normal (non-pop-up) descendant of \fIsubtree\fP to which +keyboard events are logically directed, or +.PN None . +It is not an error to specify +.PN None +when no input focus was previously set. \*(oI +.LP +.eM +.PN XtSetKeyboardFocus +causes +.PN XtDispatchEvent +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. +.LP +When there is no modal cascade, keyboard events can be dispatched +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). +.IP \(bu 3 +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 +.PN XtGrabKey +with any value of \fIowner_events\fP, or +if the keyboard is actively grabbed by E with \fIowner_events\fP +.PN False +via +.PN XtGrabKeyboard +or +.PN XtGrabKey +on a previous key press, the event is dispatched to E. +.IP \(bu 3 +Beginning with the ancestor of E closest to the root that has +redirected the keyboard focus or E if no such ancestor 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 redirected focus. +.RS +.IP \- 3 +If E is the final focus target widget F or a descendant of F, the +event is dispatched to E. +.IP \- 3 +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 call to +.PN XtGrabKey +for E, +.PN XtUngrabKeyboard +is called. +.IP \- 3 +If E is an ancestor of F, and the event is a key press, and either +.RS +.IP + 3 +E has grabbed the key with +.PN XtGrabKey +and \fIowner_events\fP +.PN False , +or +.IP + 3 +E has grabbed the key with +.PN XtGrabKey +and \fIowner_events\fP +.PN True , +and the coordinates of the event are outside the rectangle specified +by E's geometry, +.RE +then the event is dispatched to E. +.IP \- 3 +Otherwise, define A as the closest common ancestor of E and F: +.RS +.IP + 3 +If there is an active keyboard grab for any widget via either +.PN XtGrabKeyboard +or +.PN XtGrabKey +on a previous key press, or +if no widget between F and A (noninclusive) has grabbed +the key and modifier combination with +.PN XtGrabKey +and any value of \fIowner_events\fP, the event is dispatched to F. +.IP + 3 +Else, the event is dispatched to the ancestor of F closest to A +that has grabbed the key and modifier combination with +.PN XtGrabKey . +.RE +.RE +.LP +When there is a modal cascade, if the final destination widget as +identified above is in the active subset of the cascade, the event is +dispatched; otherwise the event is remapped to a spring-loaded shell +or discarded. +Regardless of where it is dispatched, the \*(xI do not modify +the contents of the event. +.LP +When \fIsubtree\fP or one of its descendants acquires the X input focus +or the pointer moves into the subtree such that keyboard events would +now be delivered to the subtree, a +.PN FocusIn +event is generated for the descendant if +.PN FocusChange +events have been selected by the descendant. +Similarly, when \fIsubtree\fP loses the X input focus +or the keyboard focus for one of its ancestors, a +.PN FocusOut +event is generated for descendant if +.PN FocusChange +events have been selected by the descendant. +.sp +.LP +A widget tree may also actively manage the X server input focus. To +do so, a widget class specifies an accept_focus procedure. +.LP +.IN "accept_focus procedure" +The accept_focus procedure pointer is of type +.PN XtAcceptFocusProc . +.LP +.IN "XtAcceptFocusProc" "" "@DEF@" +.sM +.FD 0 +typedef Boolean (*XtAcceptFocusProc)(Widget, Time*); +.br + Widget \fIw\fP; +.br + Time *\fItime\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. +.IP \fItime\fP 1i +Specifies the X time of the event causing the accept focus. +.LP +.eM +Widgets that need the input focus can call +.PN XSetInputFocus +explicitly, pursuant to the restrictions of the \fI\*(xC\fP. +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 mechanism explicitly +(typically by specifying translations for +.PN FocusIn +and +.PN FocusOut +events). +Widgets classes that never want the input focus should set the +\fIaccept_focus\fP field to NULL. +.sp +.LP +To call a widget's accept_focus procedure, use +.PN XtCallAcceptFocus . +.LP +.IN "XtCallAcceptFocus" "" "@DEF@" +.sM +.FD 0 +Boolean XtCallAcceptFocus(\fIw\fP, \fItime\fP) +.br + Widget \fIw\fP; +.br + Time *\fItime\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(cI +.IP \fItime\fP 1i +Specifies the X time of the event that is causing the focus change. +.LP +.eM +The +.PN XtCallAcceptFocus +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 \fIaccept_focus\fP is NULL, +.PN XtCallAcceptFocus +returns +.PN False . + +.NH 3 +Events for Drawables That Are Not a Widget's Window +.XS +\fB\*(SN Events for Drawables That Are Not a Widget's Window\fP +.XE +.LP +Sometimes an application must handle events for drawables that are not +associated with widgets in its widget tree. Examples include handling +.PN GraphicsExpose +and +.PN NoExpose +events on Pixmaps, and handling +.PN PropertyNotify +events on the root window. +.LP +To register a drawable with the \*(xI event dispatching, use +.PN XtRegisterDrawable . +.LP +.IN "XtRegisterDrawable" "" "@DEF@" +.sM +.FD 0 +void XtRegisterDrawable(\fIdisplay\fP, \fIdrawable\fP, \fIwidget\fP) +.br + Display *\fIdisplay\fP; +.br + Drawable \fIdrawable\fP; +.br + Widget \fIwidget\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the drawable's display. +.IP \fIdrawable\fP 1i +Specifies the drawable to register. +.IP \fIwidget\fP 1i +Specifies the widget to register the drawable for. +.LP +.eM +.PN XtRegisterDrawable +associates the specified drawable with the specified widget +so that future calls to +.PN XtWindowToWidget +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. +.LP +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 +.PN XtRegisterDrawable +are undefined. + +.LP +To unregister a drawable with the Intrinsics event dispatching, use +.PN XtUnregisterDrawable . +.LP +.IN "XtUnregisterDrawable" "" "@DEF@" +.sM +.FD 0 +void XtUnregisterDrawable(\fIdisplay\fP, \fIdrawable\fP) +.br + Display *\fIdisplay\fP; +.br + Drawable \fIdrawable\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the drawable's display. +.IP \fIdrawable\fP 1i +Specifies the drawable to unregister. +.LP +.eM +.PN XtUnregisterDrawable +removes an association created with +.PN XtRegisterDrawable . +If the drawable is the window of a widget in the client's widget tree +the results of calling +.PN XtUnregisterDrawable +are undefined. + +.NH 2 +Querying Event Sources +.XS +\fB\*(SN Querying Event Sources\fP +.XE +.LP +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 \*(xI equivalents of the +.PN XPending , +.PN XPeekEvent , +and +.PN XNextEvent +Xlib calls. +.sp +.LP +.IN "Events" +To determine if there are any events on the input queue for a given application, +use +.PN XtAppPending . +.LP +.IN "XtAppPending" "" "@DEF@" +.sM +.FD 0 +XtInputMask XtAppPending(\fIapp_context\fP) +.br + XtAppContext \fIapp_context\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context that identifies the application to check. +.LP +.eM +The +.PN XtAppPending +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 +.PN XtIMXEvent , +.PN XtIMTimer , +.PN XtIMAlternateInput , +and +.PN XtIMSignal +(see +.PN XtAppProcessEvent ). +If there are no events pending, +.PN XtAppPending +flushes the output buffers of each Display in the application context +and returns zero. +.sp +.LP +To return the event from the head of a given application's input queue +without removing input from the queue, use +.PN XtAppPeekEvent . +.LP +.IN "XtAppPeekEvent" "" "@DEF@" +.sM +.FD 0 +Boolean XtAppPeekEvent(\fIapp_context\fP, \fIevent_return\fP) +.br + XtAppContext \fIapp_context\fP; +.br + XEvent *\fIevent_return\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context that identifies the application. +.IP \fIevent_return\fP 1i +Returns the event information to the specified event structure. +.LP +.eM +If there is an X event in the queue, +.PN XtAppPeekEvent +copies it into \fIevent_return\fP and returns +.PN True . +If no X input is on the queue, +.PN XtAppPeekEvent +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, +.PN XtAppPeekEvent +fills in \fIevent_return\fP and returns +.PN True . +Otherwise, the input is for an input source +registered with +.PN XtAppAddInput , +and +.PN XtAppPeekEvent +returns +.PN False . +.FS +The sample implementations provides XtAppPeekEvent as described. Timeout callbacks +are called while blocking for input. If some input for an input source is +available, +.PN XtAppPeekEvent +will return +.PN True +without returning an event. +.FE +.sp +.LP +To remove and return the event +from the head of a given application's X event queue, +use +.PN XtAppNextEvent . +.LP +.IN "XtAppNextEvent" "" "@DEF@" +.sM +.FD 0 +void XtAppNextEvent(\fIapp_context\fP, \fIevent_return\fP) +.br + XtAppContext \fIapp_context\fP; +.br + XEvent *\fIevent_return\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context that identifies the application. +.IP \fIevent_return\fP 1i +Returns the event information to the specified event structure. +.LP +.eM +If the X event queue is empty, +.PN XtAppNextEvent +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 procedures triggered by them. +This wait time can be used for background processing; +see Section 7.8. + +.NH 2 +Dispatching Events +.XS +\fB\*(SN Dispatching Events\fP +.XE +.LP +The \*(xI provide functions that dispatch events +to widgets or other application code. +Every client interested in X events on a widget uses +.PN XtAddEventHandler +to register which events it is +interested in and a procedure (event handler) to be called +when the event happens in that window. +The translation manager automatically registers event handlers for widgets +that use translation tables; see Chapter 10. +.sp +.LP +Applications that need direct control of the processing of different types +of input should use +.PN XtAppProcessEvent . +.LP +.IN "XtAppProcessEvent" "" "@DEF@" +.sM +.FD 0 +void XtAppProcessEvent(\fIapp_context\fP, \fImask\fP) +.br + XtAppContext \fIapp_context\fP; +.br + XtInputMask \fImask\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context that identifies the +application for which to process input. +.IP \fImask\fP 1i +Specifies what types of events to process. +The mask is the bitwise inclusive OR of any combination of +.PN XtIMXEvent , +.PN XtIMTimer , +.PN XtIMAlternateInput , +and +.PN XtIMSignal . +As a convenience, +.PN Intrinsic.h +defines the symbolic name +.PN XtIMAll +to be the bitwise inclusive OR of these four event types. +.LP +.eM +The +.PN XtAppProcessEvent +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 +.PN XtAppProcessEvent +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 +.PN XtAppMainLoop . +.PN XtAppProcessEvent +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 +.PN XtDispatchEvent . +.LP +When an X event is received, +it is passed to +.PN XtDispatchEvent , +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 dispatcher simply returns. + +.sp +.LP +To dispatch an event returned by +.PN XtAppNextEvent , +retrieved directly from the Xlib queue, or synthetically constructed, +to any registered event filters or event handlers, call +.PN XtDispatchEvent . +.LP +.IN "XtDispatchEvent" "" "@DEF@" +.sM +.FD 0 +Boolean XtDispatchEvent(\fIevent\fP) +.br + XEvent *\fIevent\fP; +.FN +.IP \fIevent\fP 1i +Specifies a pointer to the event structure to be dispatched +to the appropriate event handlers. +.LP +.eM +The +.PN XtDispatchEvent +function first calls +.PN XFilterEvent +with the \fIevent\fP and the window of the widget to which the +\*(xI intend to dispatch the event, or the event window if +the \*(xI would not dispatch the event to any handlers. +If +.PN XFilterEvent +returns +.PN True +and the event activated a server grab as identified +by a previous call to +.PN XtGrabKey +or +.PN XtGrabButton , +.PN XtDispatchEvent +calls +.PN XtUngrabKeyboard +or +.PN XtUngrabPointer +with the timestamp from the event and immediately returns +.PN True . +If +.PN XFilterEvent +returns +.PN True +and a grab was not activated, +.PN XtDispatchEvent +just immediately returns +.PN True . +Otherwise, +.PN XtDispatchEvent +sends the event to the event handler functions that +have been previously registered with the dispatch routine. +.PN XtDispatchEvent +returns +.PN True +if +.PN XFilterEvent +returned +.PN True , +or if the event was dispatched to some handler, and +.PN False +if it found no handler to which to dispatch the event. +.PN XtDispatchEvent +records the last timestamp in any event that +contains a timestamp (see +.PN XtLastTimestampProcessed ), +regardless of whether it was filtered or dispatched. +If a modal cascade is active with \fIspring_loaded\fP +.PN True , +and if the event is a remap event as defined by +.PN XtAddGrab , +.PN XtDispatchEvent +may dispatch the event a second time. If it does so, +.PN XtDispatchEvent +will call +.PN XFilterEvent +again with the window of the spring-loaded widget prior to the second +dispatch, and if +.PN XFilterEvent +returns +.PN True , +the second dispatch will not be performed. + +.NH 2 +The Application Input Loop +.XS +\fB\*(SN The Application Input Loop\fP +.XE +.LP +To process all input from a given application in a continuous loop, +use the convenience procedure +.PN XtAppMainLoop . +.LP +.IN "XtAppMainLoop" "" "@DEF@" +.sM +.FD 0 +void XtAppMainLoop(\fIapp_context\fP) +.br + XtAppContext \fIapp_context\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context that identifies the application. +.LP +.eM +The +.PN XtAppMainLoop +function first reads the next incoming X event by calling +.PN XtAppNextEvent +and then dispatches the event to the appropriate registered procedure +by calling +.PN XtDispatchEvent . +This constitutes the main loop of \*(tk applications. +There is nothing special about +.PN XtAppMainLoop ; +it simply calls +.PN XtAppNextEvent +and then +.PN XtDispatchEvent +in a conditional loop. +At the bottom of the loop, it checks to see if the specified +application context's destroy flag is set. +If the flag is set, the loop breaks. +The whole loop is enclosed between a matching +.PN XtAppLock +and +.PN XtAppUnlock . +.LP +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 circling back to the call to +.PN XtAppNextEvent . + +.NH 2 +Setting and Checking the Sensitivity State of a Widget +.XS +\fB\*(SN Setting and Checking the Sensitivity State of a Widget\fP +.XE +.LP +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. +.LP +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 +.PN KeyPress , +.PN KeyRelease , +.PN ButtonPress , +.PN ButtonRelease , +.PN MotionNotify , +.PN EnterNotify , +.PN LeaveNotify , +.PN FocusIn , +or +.PN FocusOut . +.LP +A widget can be insensitive because its \fIsensitive\fP field is +.PN False +or because one of its ancestors is insensitive and thus the widget's +\fIancestor_sensitive\fP field also is +.PN False . +A widget can but does not need to distinguish these two cases visually. +.NT +Pop-up shells will have +\fIancestor_sensitive\fP +.PN False +if the parent was insensitive when the shell +was created. Since +.PN XtSetSensitive +on the parent will not +modify the resource of the pop-up child, clients are advised to include +a resource specification of the form +``*TransientShell.ancestorSensitive: True'' +in the application defaults resource file or to +otherwise ensure that the parent is +sensitive when creating pop-up shells. +.NE +.sp +.LP +To set the sensitivity state of a widget, use +.PN XtSetSensitive . +.LP +.IN "XtSetSensitive" "" "@DEF@" +.sM +.FD 0 +void XtSetSensitive(\fIw\fP, \fIsensitive\fP) +.br + Widget \fIw\fP; +.br + Boolean \fIsensitive\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(rI +.IP \fIsensitive\fP 1i +Specifies whether the widget should receive +keyboard, pointer, and focus events. +.LP +.eM +The +.PN XtSetSensitive +function first calls +.PN XtSetValues +on the current widget with an argument list specifying the +XtNsensitive resource and the new value. +If \fIsensitive\fP is +.PN False +and the widget's class is a subclass of +Composite, +.PN XtSetSensitive +recursively propagates the new value +down the child tree by calling +.PN XtSetValues +on each child to set \fIancestor_sensitive\fP to +.PN False . +If \fIsensitive\fP is +.PN True +and the widget's class is a subclass of +Composite +and the widget's \fIancestor_sensitive\fP field is +.PN True , +.PN XtSetSensitive +sets the \fIancestor_sensitive\fP of each child to +.PN True +and then recursively calls +.PN XtSetValues +on each normal descendant that is now sensitive to set +\fIancestor_sensitive\fP to +.PN True . +.LP +.PN XtSetSensitive +calls +.PN XtSetValues +to change the \fIsensitive\fP and \fIancestor_sensitive\fP fields +of each affected widget. +Therefore, 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). +.LP +.PN XtSetSensitive +maintains the invariant that, if the parent has either \fIsensitive\fP +or \fIancestor_sensitive\fP +.PN False , +then all children have \fIancestor_sensitive\fP +.PN False . +.sp +.LP +To check the current sensitivity state of a widget, +use +.PN XtIsSensitive . +.LP +.IN "XtIsSensitive" "" "@DEF@" +.sM +.FD 0 +Boolean XtIsSensitive(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the object. \*(oI +.LP +.eM +The +.PN XtIsSensitive +function returns +.PN True +or +.PN False +to indicate whether user input events are being dispatched. +If object's class is a subclass of RectObj and +both \fIsensitive\fP and \fIancestor_sensitive\fP are +.PN True , +.PN XtIsSensitive +returns +.PN True ; +otherwise, it returns +.PN False . + +.NH 2 +Adding Background Work Procedures +.XS +\fB\*(SN Adding Background Work Procedures\fP +.XE +.LP +The \*(xI have some limited support for background processing. +Because most applications spend most of their time waiting for input, +you can register an idle-time work procedure +that is called when the toolkit would otherwise block in +.PN XtAppNextEvent +or +.PN XtAppProcessEvent . +Work procedure pointers are of type +.PN XtWorkProc . +.LP +.IN "XtWorkProc" "" "@DEF@" +.sM +.FD 0 +typedef Boolean (*XtWorkProc)(XtPointer); +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIclient_data\fP 1i +Passes the client data specified when the work procedure was registered. +.LP +.eM +This procedure should return +.PN True +when it is done to indicate that it +should be removed. +If the procedure returns +.PN False , +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 suffer. +.sp +.LP +To register a work procedure for a given application, use +.PN XtAppAddWorkProc . +.LP +.IN "XtAppAddWorkProc" "" "@DEF@" +.sM +.FD 0 +XtWorkProcId XtAppAddWorkProc(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP) +.br + XtAppContext \fIapp_context\fP; +.br + XtWorkProc \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context that identifies the application. +.IP \fIproc\fP 1i +Specifies the procedure to be called when the application is idle. +.IP \fIclient_data\fP 1i +Specifies the argument passed to the specified procedure +when it is called. +.LP +.eM +The +.PN XtAppAddWorkProc +function adds the specified work procedure for the application identified +by \fIapp_context\fP +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. +However, if a work procedure adds another work procedure, +the newly added one has lower priority than the current one. +.sp +.LP +To remove a work procedure, either return +.PN True +from the procedure when it is called or use +.PN XtRemoveWorkProc +outside of the procedure. +.LP +.IN "XtRemoveWorkProc" "" "@DEF@" +.sM +.FD 0 +void XtRemoveWorkProc(\fIid\fP) +.br + XtWorkProcId \fIid\fP; +.FN +.IP \fIid\fP 1i +Specifies which work procedure to remove. +.LP +.eM +The +.PN XtRemoveWorkProc +function explicitly removes the specified background work procedure. + +.NH 2 +X Event Filters +.XS +\*(SN X Event Filters +.XE +.LP +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. + +.NH 3 +Pointer Motion Compression +.XS +\*(SN Pointer Motion Compression +.XE +.LP +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 \fIcompress_motion\fP should be +.PN True . +.IN "compress_motion field" +When a request for an event would return a motion event, +the \*(xI 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. + +.NH 3 +Enter/Leave Compression +.XS +\*(SN Enter/Leave Compression +.XE +.LP +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 \fIcompress_enterleave\fP should be +.PN True . +.IN "compress_enterleave field" +These enter and leave events are not delivered to the client +if they are found together in the input queue. + +.NH 3 +Exposure Compression +.XS +\*(SN Exposure Compression +.XE +.LP +.IN "compress_expose field" +Many widgets prefer to process a series of exposure events as a +single expose region rather than as individual rectangles. 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. +.LP +In either case, these widgets do not care about getting partial exposure events. +The \fIcompress_exposure\fP 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: +.sp +.sM +.Ds 0 +.TA 3i +.ta 3i +#define XtExposeNoCompress ((XtEnum)False) +#define XtExposeCompressSeries ((XtEnum)True) +#define XtExposeCompressMultiple <implementation-defined> +#define XtExposeCompressMaximal <implementation-defined> +.De +.LP +.eM +optionally ORed with any combination of the following flags (all with +implementation-defined values): +.PN XtExposeGraphicsExpose , +.PN XtExposeGraphicsExposeMerged , +.PN XtExposeNoExpose , +and +.PN XtExposeNoRegion . + +.LP +If the \fIcompress_exposure\fP field in the widget class structure does not +specify +.PN XtExposeNoCompress , +the event manager calls the widget's expose procedure only +once for a series of exposure events. +In this case, all +.PN Expose +or +.PN GraphicsExpose +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 +.PN XtExposeNoRegion +is specified) the region. +For more information on regions, see Section 16.5 in \fI\*(xL\fP.) +.LP +The values have the following interpretation: +.sp +.LP +.PN XtExposeNoCompress +.IN "XtExposeNoCompress" "" "@DEF@" +.IP +No exposure compression is performed; every selected event is +individually dispatched to the expose procedure with a \fIregion\fP +argument of NULL. +.sp +.LP +.PN XtExposeCompressSeries +.IN "XtExposeCompressSeries" "" "@DEF@" +.IP +Each series of exposure events is coalesced into a single event, +which is dispatched +when an exposure event with count equal to zero is reached. +.sp +.LP +.PN XtExposeCompressMultiple +.IN "XtExposeCompressMultiple" "" "@DEF@" +.IP +Consecutive series of exposure events are coalesced into a single +event, which is dispatched +when an exposure 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. +.sp +.LP +.PN XtExposeCompressMaximal +.IN "XtExposeCompressMaximal" "" "@DEF" +.IP +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 \*(xI will +block until the end of the series is received. +.sp +.LP +The additional flags have the following meaning: +.sp +.LP +.PN XtExposeGraphicsExpose +.IN "XtExposeGraphicsExpose" "" "@DEF@" +.IP +Specifies that +.PN GraphicsExpose +events are also to be dispatched to +the expose procedure. +.PN GraphicsExpose +events are compressed, if specified, in the same manner as +.PN Expose +events. +.sp +.LP +.PN XtExposeGraphicsExposeMerged +.IN "XtExposeGraphicsExposeMerged" "" "@DEF@" +.IP +Specifies in the case of +.PN XtExposeCompressMultiple +and +.PN XtExposeCompressMaximal +that series of +.PN GraphicsExpose +and +.PN Expose +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 +.PN XtExposeGraphicsExpose . +.sp +.LP +.PN XtExposeNoExpose +.IN "XtExposeNoExpose" "" "@DEF@" +.IP +Specifies that +.PN NoExpose +events are also to be dispatched to the expose procedure. +.PN NoExpose +events are never coalesced with +other exposure events or with each other. +.sp +.LP +.PN XtExposeNoRegion +.IN "XtExposeNoRegion" "" "@DEF" +.IP +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. + +.NH 2 +Widget Exposure and Visibility +.XS +\*(SN Widget Exposure and Visibility +.XE +.LP +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. + +.NH 3 +Redisplay of a Widget: The expose Procedure +.XS +\*(SN Redisplay of a Widget: The expose Procedure +.XE +.IN "expose procedure" +.LP +The expose procedure pointer in a widget class is of type +.PN XtExposeProc . +.LP +.IN "XtExposeProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtExposeProc)(Widget, XEvent*, Region); +.br + Widget \fIw\fP; +.br + XEvent *\fIevent\fP; +.br + Region \fIregion\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget instance requiring redisplay. +.IP \fIevent\fP 1i +Specifies the exposure event giving the rectangle requiring redisplay. +.IP \fIregion\fP 1i +Specifies the union of all rectangles in this exposure sequence. +.LP +.eM +The redisplay of a widget upon exposure is the responsibility of the +expose procedure in the widget's class record. +If a widget has no display semantics, +it can specify NULL for the \fIexpose\fP field. +Many composite widgets serve only as containers for their children +and have no expose procedure. +.NT +If the \fIexpose\fP procedure is NULL, +.PN XtRealizeWidget +fills in a default bit gravity of +.PN NorthWestGravity +before it calls the widget's realize procedure. +.NE +.LP +If the widget's \fIcompress_exposure\fP class field specifies +.PN XtExposeNoCompress +or +.PN XtExposeNoRegion , +or if the event type is +.PN NoExpose +(see Section 7.9.3), +\fIregion\fP is NULL. If +.PN XtExposeNoCompress +is not specified and the event type is not +.PN NoExpose , +the event is the final event in the compressed series +but \fIx\fP, \fIy\fP, \fIwidth\fP, and \fIheight\fP contain +the bounding box for all the compressed events. +The region is created and destroyed by the \*(xI, but +the widget is permitted to modify the region contents. +.LP +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. +.LP +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 display routine in Label that uses display state +fields like +.LP +.DS +Boolean invert; +Boolean highlight; +Dimension highlight_width; +.DE +Label would have \fIinvert\fP and \fIhighlight\fP always +.PN False +and \fIhighlight_width\fP zero. +Pushbutton would dynamically set \fIhighlight\fP and \fIhighlight_width\fP, +but it would leave \fIinvert\fP always +.PN False . +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. + +.NH 3 +Widget Visibility +.XS +\*(SN Widget Visibility +.XE +.LP +Some widgets may use substantial computing resources to produce 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. +.LP +.IN "Visibility" +The \fIvisible\fP 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 +.PN True +by the time an +exposure +event is processed if any part of the widget is visible, +but is +.PN False +if the widget is fully obscured. +.LP +Widgets can use or ignore the \fIvisible\fP hint. +If they ignore it, +they should have \fIvisible_interest\fP in their widget class record set +.PN False . +In such cases, +the \fIvisible\fP field is initialized +.PN True +and never changes. +If \fIvisible_interest\fP is +.PN True , +the event manager asks for +.PN VisibilityNotify +events for the widget and sets \fIvisible\fP to +.PN True +on +.PN VisibilityUnobscured +or +.PN VisibilityPartiallyObscured +.IN VisibilityNotify +events and +.PN False +on +.PN VisibilityFullyObscured +events. + +.NH 2 +X Event Handlers +.XS +\*(SN X Event Handlers +.XE +.LP +Event handlers are procedures called when specified events +occur in a widget. +Most widgets need not use event handlers explicitly. +Instead, they use the \*(xI translation manager. +Event handler procedure pointers are of the type +.PN XtEventHandler . +.LP +.IN "XtEventHandler" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtEventHandler)(Widget, XtPointer, XEvent*, Boolean*); +.br + Widget \fIw\fP; +.br + XtPointer \fIclient_data\fP; +.br + XEvent *\fIevent\fP; +.br + Boolean *\fIcontinue_to_dispatch\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget for which the event arrived. +.IP \fIclient_data\fP 1i +Specifies any client-specific information registered with the event handler. +.IP \fIevent\fP 1i +Specifies the triggering event. +.IP \fIcontinue_to_dispatch\fP 1i +Specifies whether the remaining event +handlers registered for the current event +should be called. +.LP +.eM +After receiving an event and before calling any event handlers, the +Boolean pointed to by \fIcontinue_to_dispatch\fP is initialized to +.PN True . +When an event handler is called, it may decide that further processing +of the event is not desirable and may store +.PN False +in this Boolean, in +which case any handlers remaining to be called for the event are +ignored. +.LP +The circumstances under which the \*(xI may add event handlers +to a widget are currently implementation-dependent. Clients must +therefore be aware that storing +.PN False +into the \fIcontinue_to_dispatch\fP argument can lead to portability problems. + +.NH 3 +Event Handlers That Select Events +.XS +\*(SN Event Handlers That Select Events +.XE +.LP +To register an event handler procedure with the dispatch mechanism, use +.PN XtAddEventHandler . +.LP +.IN "XtAddEventHandler" "" "@DEF@" +.sM +.FD 0 +void XtAddEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \ +\fIproc\fP, \fIclient_data\fP) +.br + Widget \fIw\fP; +.br + EventMask \fIevent_mask\fP; +.br + Boolean \fInonmaskable\fP; +.br + XtEventHandler \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget for which this event handler is being registered. \*(cI +.IP \fIevent_mask\fP 1i +Specifies the event mask for which to call this procedure. +.IP \fInonmaskable\fP 1i +Specifies whether this procedure should be +called on the nonmaskable events +.Pn ( GraphicsExpose , +.PN NoExpose , +.PN SelectionClear , +.PN SelectionRequest , +.PN SelectionNotify , +.PN ClientMessage , +and +.PN MappingNotify ). +.IP \fIproc\fP 1i +Specifies the procedure to be called. +.IP \fIclient_data\fP 1i +Specifies additional data to be passed to the event handler. +.LP +.eM +The +.PN XtAddEventHandler +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 \fIclient_data\fP +value, +the specified mask augments the existing mask. +If the widget is realized, +.PN XtAddEventHandler +calls +.PN XSelectInput , +if necessary. +The order in which this procedure is called relative to other handlers +registered for the same event is not defined. +.sp +.LP +To remove a previously registered event handler, use +.PN XtRemoveEventHandler . +.LP +.IN "XtRemoveEventHandler" "" "@DEF@" +.sM +.FD 0 +void XtRemoveEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \ +\fIproc\fP, \fIclient_data\fP) +.br + Widget \fIw\fP; +.br + EventMask \fIevent_mask\fP; +.br + Boolean \fInonmaskable\fP; +.br + XtEventHandler \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget for which this procedure is registered. \*(cI +.IP \fIevent_mask\fP 1i +Specifies the event mask for which to unregister this procedure. +.IP \fInonmaskable\fP 1i +Specifies whether this procedure should be +removed on the nonmaskable events +.Pn ( GraphicsExpose , +.PN NoExpose , +.PN SelectionClear , +.PN SelectionRequest , +.PN SelectionNotify , +.PN ClientMessage , +and +.PN MappingNotify ). +.IP \fIproc\fP 1i +Specifies the procedure to be removed. +.IP \fIclient_data\fP 1i +Specifies the registered client data. +.LP +.eM +The +.PN XtRemoveEventHandler +function unregisters an event handler registered with +.PN XtAddEventHandler +or +.PN XtInsertEventHandler +for the specified events. +The request is ignored if \fIclient_data\fP does not match the value given +when the handler was registered. +If the widget is realized and no other event handler requires the event, +.PN XtRemoveEventHandler +calls +.PN XSelectInput . +If the specified procedure has not been registered +or if it has been registered with a different value of \fIclient_data\fP, +.PN XtRemoveEventHandler +returns without reporting an error. +.LP +To stop a procedure registered with +.PN XtAddEventHandler +or +.PN XtInsertEventHandler +from receiving all selected events, call +.PN XtRemoveEventHandler +with an \fIevent_mask\fP of +.PN XtAllEvents +and \fInonmaskable\fP +.PN True . +The procedure will continue to receive any events +that have been specified in calls to +.PN XtAddRawEventHandler +or +.PN XtInsertRawEventHandler . +.sp +.LP +To register an event handler procedure that receives events before or +after all previously registered event handlers, use +.PN XtInsertEventHandler . +.LP +.IN "XtListPosition" "" "@DEF@" +.IN "XtInsertEventHandler" "" "@DEF@" +.sM +.Ds 0 +typedef enum {XtListHead, XtListTail} XtListPosition; +.De +.LP +.FD 0 +void XtInsertEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \ +\fIproc\fP, \fIclient_data\fP, \fIposition\fP) +.br + Widget \fIw\fP; +.br + EventMask \fIevent_mask\fP; +.br + Boolean \fInonmaskable\fP; +.br + XtEventHandler \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.br + XtListPosition \fIposition\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget for which this event handler is being registered. \*(cI +.IP \fIevent_mask\fP 1i +Specifies the event mask for which to call this procedure. +.IP \fInonmaskable\fP 1i +Specifies whether this procedure should be +called on the nonmaskable events +.Pn ( GraphicsExpose , +.PN NoExpose , +.PN SelectionClear , +.PN SelectionRequest , +.PN SelectionNotify , +.PN ClientMessage , +and +.PN MappingNotify ). +.IP \fIproc\fP 1i +Specifies the procedure to be called. +.IP \fIclient_data\fP 1i +Specifies additional data to be passed to the client's event handler. +.IP \fIposition\fP 1i +Specifies when the event handler is to be called +relative to other previously registered handlers. +.LP +.eM +.PN XtInsertEventHandler +is identical to +.PN XtAddEventHandler +with the additional \fIposition\fP argument. If \fIposition\fP is +.PN XtListHead , +the event +handler is registered so that it is called before any event +handlers that were previously registered for the same widget. If +\fIposition\fP is +.PN XtListTail , +the event handler is registered to be called +after any previously registered event handlers. If the procedure is +already registered with the same \fIclient_data\fP value, the specified mask +augments the existing mask and the procedure is repositioned in +the list. + +.NH 3 +Event Handlers That Do Not Select Events +.XS +\*(SN Event Handlers That Do Not Select Events +.XE +.LP +On occasion, +clients need to register an event handler procedure with the +dispatch mechanism without explicitly +causing the X server to select for that event. +To do this, use +.PN XtAddRawEventHandler . +.LP +.IN "XtAddRawEventHandler" "" "@DEF@" +.sM +.FD 0 +void XtAddRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \ +\fIproc\fP, \fIclient_data\fP) +.br + Widget \fIw\fP; +.br + EventMask \fIevent_mask\fP; +.br + Boolean \fInonmaskable\fP; +.br + XtEventHandler \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget for which this event handler is being registered. \*(cI +.IP \fIevent_mask\fP 1i +Specifies the event mask for which to call this procedure. +.IP \fInonmaskable\fP 1i +Specifies whether this procedure should be +called on the nonmaskable events +.Pn ( GraphicsExpose , +.PN NoExpose , +.PN SelectionClear , +.PN SelectionRequest , +.PN SelectionNotify , +.PN ClientMessage , +and +.PN MappingNotify ). +.IP \fIproc\fP 1i +Specifies the procedure to be called. +.IP \fIclient_data\fP 1i +Specifies additional data to be passed to the client's event handler. +.LP +.eM +The +.PN XtAddRawEventHandler +function is similar to +.PN XtAddEventHandler +except that it does not affect the widget's event mask and never causes an +.PN XSelectInput +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 \fIclient_data\fP, +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. +.sp +.LP +To remove a previously registered raw event handler, use +.PN XtRemoveRawEventHandler . +.LP +.IN "XtRemoveRawEventHandler" "" "@DEF@" +.sM +.FD 0 +void XtRemoveRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \ +\fIproc\fP, \fIclient_data\fP) +.br + Widget \fIw\fP; +.br + EventMask \fIevent_mask\fP; +.br + Boolean \fInonmaskable\fP; +.br + XtEventHandler \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget for which this procedure is registered. \*(cI +.IP \fIevent_mask\fP 1i +Specifies the event mask for which to unregister this procedure. +.IP \fInonmaskable\fP 1i +Specifies whether this procedure should be +removed on the nonmaskable events +.Pn ( GraphicsExpose , +.PN NoExpose , +.PN SelectionClear , +.PN SelectionRequest , +.PN SelectionNotify , +.PN ClientMessage , +and +.PN MappingNotify ). +.IP \fIproc\fP 1i +Specifies the procedure to be registered. +.IP \fIclient_data\fP 1i +Specifies the registered client data. +.LP +.eM +The +.PN XtRemoveRawEventHandler +function unregisters an event handler registered with +.PN XtAddRawEventHandler +or +.PN XtInsertRawEventHandler +for the specified events without changing +the window event mask. +The request is ignored if \fIclient_data\fP does not match the value given +when the handler was registered. +If the specified procedure has not been registered +or if it has been registered with a different value of \fIclient_data\fP, +.PN XtRemoveRawEventHandler +returns without reporting an error. +.LP +To stop a procedure +registered with +.PN XtAddRawEventHandler +or +.PN XtInsertRawEventHandler +from receiving all nonselected events, call +.PN XtRemoveRawEventHandler +with an \fIevent_mask\fP of +.PN XtAllEvents +and \fInonmaskable\fP +.PN True . +The procedure +will continue to receive any events that have been specified in calls to +.PN XtAddEventHandler +or +.PN XtInsertEventHandler . +.sp +.LP +To register an event handler procedure that receives events before or +after all previously registered event handlers without selecting for +the events, use +.PN XtInsertRawEventHandler . +.LP +.IN "XtInsertRawEventHandler" "" "@DEF@" +.sM +.FD 0 +void XtInsertRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \ +\fIproc\fP, \fIclient_data\fP, \fIposition\fP) +.br + Widget \fIw\fP; +.br + EventMask \fIevent_mask\fP; +.br + Boolean \fInonmaskable\fP; +.br + XtEventHandler \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.br + XtListPosition \fIposition\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget for which this event handler is being registered. \*(cI +.IP \fIevent_mask\fP 1i +Specifies the event mask for which to call this procedure. +.IP \fInonmaskable\fP 1i +Specifies whether this procedure should be +called on the nonmaskable events +.Pn ( GraphicsExpose , +.PN NoExpose , +.PN SelectionClear , +.PN SelectionRequest , +.PN SelectionNotify , +.PN ClientMessage , +and +.PN MappingNotify ). +.IP \fIproc\fP 1i +Specifies the procedure to be registered. +.IP \fIclient_data\fP 1i +Specifies additional data to be passed to the client's event handler. +.IP \fIposition\fP 1i +Specifies when the event handler is to be called +relative to other previously registered handlers. +.LP +.eM +The +.PN XtInsertRawEventHandler +function is similar to +.PN XtInsertEventHandler +except that it does not modify the widget's event +mask and never causes an +.PN XSelectInput +for the specified events. If +the procedure is already registered with the same \fIclient_data\fP +value, the +specified mask augments the existing mask and the procedure is +repositioned in the list. + +.NH 3 +Current Event Mask +.XS +\*(SN Current Event Mask +.XE +.LP +To retrieve the event mask for a given widget, use +.PN XtBuildEventMask . +.LP +.IN "XtBuildEventMask" "" "@DEF@" +.sM +.FD 0 +EventMask XtBuildEventMask(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(cI +.LP +.eM +The +.PN XtBuildEventMask +function returns the event mask representing the logical OR +of all event masks for event handlers registered on the widget with +.PN XtAddEventHandler +and +.PN XtInsertEventHandler +and all event translations, including accelerators, +installed on the widget. +This is the same event mask stored into the +.PN XSetWindowAttributes +structure by +.PN XtRealizeWidget +and sent to the server when event handlers and translations are installed or +removed on the realized widget. + +.NH 3 +Event Handlers for X11 Protocol Extensions +.XS +\fB\*(SN Event Handlers for X11 Protocol Extensions\fP +.XE +.LP +To register an event handler procedure with the \*(xI dispatch +mechanism according to an event type, use +.PN XtInsertEventTypeHandler . +.LP +.IN "XtInsertEventTypeHandler" "" "@DEF" +.sM +.FD 0 +void XtInsertEventTypeHandler(\fIwidget\fP, \fIevent_type\fP, \ +\fIselect_data\fP, \fIproc\fP, \fIclient_data\fP, \fIposition\fP) +.br + Widget \fIwidget\fP; +.br + int \fIevent_type\fP; +.br + XtPointer \fIselect_data\fP; +.br + XtEventHandler \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.br + XtListPosition \fIposition\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget for which this event handler is being registered. \*(cI +.IP \fIevent_type\fP 1i +Specifies the event type for which to call this event handler. +.IP \fIselect_data\fP 1i +Specifies data used to request events of the specified type from the server, +or NULL. +.IP \fIproc\fP 1i +Specifies the event handler to be called. +.IP \fIclient_data\fP 1i +Specifies additional data to be passed to the event handler. +.IP \fIposition\fP 1i +Specifies when the event handler is to be called relative to other +previously registered handlers. +.LP +.eM +.PN XtInsertEventTypeHandler +registers a procedure with the +dispatch mechanism that is to be called when an event that matches the +specified \fIevent_type\fP is dispatched to the specified \fIwidget\fP. +.LP +If \fIevent_type\fP specifies one of the core X protocol events, then +\fIselect_data\fP must be a pointer to a value of type +.PN EventMask , +indicating +the event mask to be used to select for the desired event. This event +mask is included in the value returned by +.PN XtBuildEventMask . +If the widget is realized, +.PN XtInsertEventTypeHandler +calls +.PN XSelectInput +if necessary. Specifying NULL for \fIselect_data\fP is equivalent to +specifying a pointer to an event mask containing 0. This is similar +to the +.PN XtInsertRawEventHandler +function. +.LP +If \fIevent_type\fP specifies an extension event type, then the semantics of +the data pointed to by \fIselect_data\fP are defined by the extension +selector registered for the specified event type. +.LP +In either case the \*(xI are not required to copy the data +pointed to by \fIselect_data\fP, so the caller must ensure that it remains +valid as long as the event handler remains registered with this value +of \fIselect_data\fP. +.LP +The \fIposition\fP 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 +.PN XtListTail , +which registers this event handler after any previously +registered handlers for this event type. +.LP +Each widget has a single registered event handler list, which will +contain any procedure/client_data pair exactly once if it is +registered with +.PN XtInsertEventTypeHandler , +regardless of the manner +in which it is registered and regardless of the value(s) +of \fIselect_data\fP. If the procedure is already registered with the +same \fIclient_data\fP value, the specified mask augments the existing +mask and the procedure is repositioned in the list. +.sp +.LP +To remove an event handler registered with +.PN XtInsertEventTypeHandler , +use +.PN XtRemoveEventTypeHandler . +.LP +.IN "XtRemoveEventTypeHandler" "" "@DEF" +.sM +.FD 0 +void XtRemoveEventTypeHandler(\fIwidget\fP, \fIevent_type\fP, \ +\fIselect_data\fP, \fIproc\fP, \fIclient_data\fP) +.br + Widget \fIwidget\fP; +.br + int \fIevent_type\fP; +.br + XtPointer \fIselect_data\fP; +.br + XtEventHandler \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget for which the event handler was registered. \*(cI +.IP \fIevent_type\fP 1i +Specifies the event type for which the handler was registered. +.IP \fIselect_data\fP 1i +Specifies data used to deselect events of the specified type +from the server, or NULL. +.IP \fIproc\fP 1i +Specifies the event handler to be removed. +.IP \fIclient_data\fP 1i +Specifies the additional client data with which the procedure was registered. +.LP +.eM +The +.PN XtRemoveEventTypeHandler +function unregisters an event handler +registered with +.PN XtInsertEventTypeHandler +for the specified event type. +The request is ignored if \fIclient_data\fP does not match the value given +when the handler was registered. +.LP +If \fIevent_type\fP specifies one of the core X protocol events, +\fIselect_data\fP must be a pointer to a value of type +.PN EventMask, indicating the event +mask to be used to deselect for the appropriate event. If the widget +is realized, +.PN XtRemoveEventTypeHandler +calls +.PN XSelectInput +if necessary. +Specifying NULL for \fIselect_data\fP is equivalent to specifying a pointer +to an event mask containing 0. This is similar to the +.PN XtRemoveRawEventHandler +function. +.LP +If \fIevent_type\fP specifies an extension event type, then the semantics of +the data pointed to by \fIselect_data\fP are defined by the extension +selector registered for the specified event type. +.sp +.LP +To register a procedure to select extension events for a widget, use +.PN XtRegisterExtensionSelector . +.LP +.IN "XtRegisterExtensionSelector" "" "@DEF@" +.sM +.FD 0 +void XtRegisterExtensionSelector(\fIdisplay\fP, \fImin_event_type\fP, \ +\fImax_event_type\fP, \fIproc\fP, + \fIclient_data\fP) +.br + Display \fI*display\fP; +.br + int \fImin_event_type\fP; +.br + int \fImax_event_type\fP; +.br + XtExtensionSelectProc \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIdisplay\fP 1.5i +Specifies the display for which the extension selector is to be registered. +.IP \fImin_event_type\fP +.IP \fImax_event_type\fP 1.5i +Specifies the range of event types for the extension. +.IP \fIproc\fP 1.5i +Specifies the extension selector procedure. +.IP \fIclient_data\fP 1.5i +Specifies additional data to be passed to the extension selector. +.LP +.eM +The +.PN XtRegisterExtensionSelector +function registers a procedure to arrange +for the delivery of extension events to widgets. +.LP +If \fImin_event_type\fP and \fImax_event_type\fP match the parameters +to a previous call to +.PN XtRegisterExtensionSelector +for the same \fIdisplay\fP, then \fIproc\fP and \fIclient_data\fP +replace the previously +registered values. If the range specified by \fImin_event_type\fP +and \fImax_event_type\fP overlaps the range of the parameters to a +previous call for the same display in any other way, an error results. +.LP +When a widget is realized, +after the \fIcore.realize\fP method is called, +the \*(xI check to see if any event +handler specifies an event type within the range of a registered +extension selector. If so, the \*(xI call each such selector. +If an event type handler is added or removed, the \*(xI 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 \*(xI +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 delivery of extension events +required by the widget. +.sp +.LP +An extension selector is of type +.PN XtExtensionSelectProc . +.LP +.IN "XtExtensionSelectProc" "" "@DEF" +.sM +.FD 0 +typedef void (*XtExtensionSelectProc)(Widget, int *, XtPointer *, int, \ +XtPointer); +.br + Widget \fIwidget\fP; +.br + int *\fIevent_types\fP; +.br + XtPointer *\fIselect_data\fP; +.br + int \fIcount\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget that is being realized or is having +an event handler added or removed. +.IP \fIevent_types\fP 1i +Specifies a list of event types that the widget has +registered event handlers for. +.IP \fIselect_data\fP 1i +Specifies a list of the select_data parameters specified in +.PN XtInsertEventTypeHandler . +.IP \fIcount\fP 1i +Specifies the number of entries in the \fIevent_types\fP and \fIselect_data\fP +lists. +.IP \fIclient_data\fP 1i +Specifies the additional client data with which the procedure was registered. +.LP +.eM +The \fIevent_types\fP and \fIselect_data\fP lists will always have the +same number of elements, specified by \fIcount\fP. +Each event type/select data pair represents one call to +.PN XtInsertEventTypeHandler . +.sp +.LP +To register a procedure to dispatch events of a specific type within +.PN XtDispatchEvent , +use +.PN XtSetEventDispatcher . +.LP +.IN "XtSetEventDispatcher" "" "@DEF@" +.sM +.FD 0 +XtEventDispatchProc XtSetEventDispatcher(\fIdisplay\fP, \fIevent_type\fP, \ +\fIproc\fP) +.br + Display *\fIdisplay\fP; +.br + int \fIevent_type\fP; +.br + XtEventDispatchProc \fIproc\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display for which the event dispatcher is to be registered. +.IP \fIevent_type\fP 1i +Specifies the event type for which the dispatcher should be invoked. +.IP \fIproc\fP 1i +Specifies the event dispatcher procedure. +.LP +.eM +The +.PN XtSetEventDispatcher +function registers the event dispatcher procedure specified by \fIproc\fP +for events with the type \fIevent_type\fP. The previously registered +dispatcher (or the default dispatcher if there was no previously registered +dispatcher) is returned. If \fIproc\fP is NULL, the default procedure is +restored for the specified type. +.LP +In the future, when +.PN XtDispatchEvent +is called with an event type of \fIevent_type\fP, the specified \fIproc\fP +(or the default dispatcher) is invoked to determine a widget +to which to dispatch the event. +.LP +The default dispatcher handles the \*(xI modal cascade and keyboard +focus mechanisms, handles the semantics of \fIcompress_enterleave\fP +and \fIcompress_motion\fP, and discards all extension events. +.sp +.LP +An event dispatcher procedure pointer is of type +.PN XtEventDispatchProc . +.LP +.IN "XtEventDispatchProc" "" "@DEF@" +.sM +.FD 0 +typedef Boolean (*XtEventDispatchProc)(XEvent*) +.br + XEvent *\fIevent\fP; +.FN +.IP \fIevent\fP 1i +Passes the event to be dispatched. +.LP +.eM +The event dispatcher procedure should determine whether this event is of +a type that should be dispatched to a widget. +.LP +If the event should be dispatched to a widget, the event dispatcher +procedure should determine the appropriate widget to receive the +event, call +.PN XFilterEvent +with the window of this widget, or +.PN None +if the event is to be discarded, and if +.PN XFilterEvent +returns +.PN False , +dispatch the event to the widget using +.PN XtDispatchEventToWidget . +The procedure should return +.PN True +if either +.PN XFilterEvent +or +.PN XtDispatchEventToWidget +returned +.PN True +and +.PN False +otherwise. +.LP +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 +.PN True +if it successfully dispatched the event and +.PN False +otherwise. +.sp +.LP +Some dispatchers for extension events may wish to forward events +according to the Intrinsics' keyboard focus mechanism. To determine +which widget is the end result of keyboard event forwarding, use +.PN XtGetKeyboardFocusWidget . +.LP +.IN "XtGetKeyboardFocusWidget" "" "@DEF@" +.sM +.FD 0 +Widget XtGetKeyboardFocusWidget(\fIwidget\fP) +.br + Widget \fIwidget\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget to get forwarding information for. +.LP +.eM +The +.PN XtGetKeyboardFocusWidget +function returns the widget that would be the end result of keyboard +event forwarding for a keyboard event for the specified widget. +.sp +.LP +To dispatch an event to a specified widget, use +.PN XtDispatchEventToWidget . +.LP +.IN "XtDispatchEventToWidget" "" "@DEF@" +.sM +.FD 0 +Boolean XtDispatchEventToWidget(\fIwidget\fP, \fIevent\fP) +.br + Widget \fIwidget\fP; +.br + XEvent *\fIevent\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget to which to dispatch the event. +.IP \fIevent\fP 1i +Specifies a pointer to the event to be dispatched. +.LP +.eM +The +.PN XtDispatchEventToWidget +function scans the list of registered event handlers for the +specified widget and calls each handler that has been registered +for the specified event type, subject to the \fIcontinue_to_dispatch\fP +value returned by each handler. +The \*(xI behave as if event handlers were registered at the head +of the list for +.PN Expose , +.PN NoExpose , +.PN GraphicsExpose , +and +.PN VisibilityNotify +events to invoke the widget's expose procedure according to the exposure +compression rules and to update the widget's \fIvisible\fP field +if \fIvisible_interest\fP is +.PN True . +These internal event handlers never set \fIcontinue_to_dispatch\fP to +.PN False . +.LP +.PN XtDispatchEventToWidget +returns +.PN True +if any event handler was called and +.PN False +otherwise. + +.NH 2 +Using the \*(xI in a Multi-Threaded Environment +.XS +\*(SN Using the \*(xI in a Multi-Threaded Environment +.XE +.LP +The \*(xI may be used in environments that offer multiple threads +of execution within the context of a single process. A multi-threaded +application using the \*(xI must explicitly initialize the toolkit +for mutually exclusive access by calling +.PN XtToolkitThreadInitialize . + +.NH 3 +Initializing a Multi-Threaded \*(xI Application +.XS +\fB\*(SN Initializing a Multi-Threaded \*(xI Application\fP +.XE +.LP +To test and initialize \*(xI support for mutually exclusive thread +access, call +.PN XtToolkitThreadInitialize . +.LP +.IN "XtToolkitThreadInitialize" "" "@DEF@" +.sM +.FD 0 +Boolean XtToolkitThreadInitialize() +.FN +.LP +.eM +.PN XtToolkitThreadInitialize +returns \fBTrue\fP if the \*(xI support mutually exclusive thread +access, otherwise it returns \fBFalse\fP. \fBXtToolkitThreadInitialize\fP +must be called before +.PN XtCreateApplicationContext , +.PN XtAppInitialize , +.PN XtOpenApplication , +or +.PN XtSetLanguageProc +is called. \fBXtToolkitThreadInitialize\fP may be called more than once; +however, the application writer must ensure that it is not called +simultaneously by two or more threads. + +.NH 3 +Locking \*(tk Data Structures +.XS +\fB\*(SN Locking \*(tk Data Structures\fP +.XE +.LP +The \*(xI employs two levels of locking: application context and +process. Locking an application context ensures mutually exclusive +access by a thread to the state associated with the application context, +including all displays and widgets associated with it. Locking a +process ensures mutually exclusive access by a thread to \*(xI process +global data. +.LP +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. +.LP +Most application writers will have little need to use locking as the +\*(xI performs the necessary locking internally. +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: +.LP +.KS +.Ds +.TA .5i 2i +.ta .5i 2i + ... + XtAppLock(app_context); + XtCvtStringToPixel(dpy, args, num_args, fromVal, toVal, closure_ret); + XtAppUnlock(app_context); + ... +.De +.KE +.LP +When the application relies upon +.PN XtConvertAndStore +or a converter to provide the storage for the results of a +conversion, the application should acquire the process lock before +calling out and hold the lock until the results have been copied. +.LP +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: +.LP +.KS +.Ds +.TA .5i 2i +.ta .5i 2i +#include <X11/CoreP.h> +Boolean BeingDestroyed (widget) + Widget widget; +{ + Boolean ret; + XtAppLock(XtWidgetToApplicationContext(widget)); + ret = widget->core.being_destroyed; + XtAppUnlock(XtWidgetToApplicationContext(widget)); + return ret; +} +.De +.KE +A client that wishes to atomically call two or more \*(xI functions +must lock the application context. For example: +.LP +.KS +.Ds +.TA .5i 2i +.ta .5i 2i + ... + XtAppLock(XtWidgetToApplicationContext(widget)); + XtUnmanageChild (widget1); + XtManageChild (widget2); + XtAppUnlock(XtWidgetToApplicationContext(widget)); + ... +.De +.KE + +.NH 4 +Locking the Application Context +.XS +\fB\*(SN Locking the Application Context\fP +.XE +.LP +To ensure mutual exclusion of application context, display, or +widget internal state, use +.PN XtAppLock. +.LP +.IN "XtAppLock" "" "@DEF@" +.sM +.FD 0 +void XtAppLock(\fIapp_context\fP) +.br + XtAppContext \fIapp_context\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context to lock. +.LP +.eM +\fBXtAppLock\fP blocks 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. +.LP +To unlock a locked application context, use +.PN XtAppUnlock. +.LP +.IN "XtAppUnlock" "" "@DEF@" +.sM +.FD 0 +void XtAppUnlock(\fIapp_context\fP) +.br + XtAppContext \fIapp_context\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context that was previously locked. +.LP +.eM + +.NH 4 +Locking the Process +.XS +\*(SN Locking the Process +.XE +.LP +To ensure mutual exclusion of \*(tk process global data, a +widget writer must use +.PN XtProcessLock. +.LP +.IN "XtProcessLock" "" "@DEF@" +.sM +.FD 0 +void XtProcessLock() +.FN +.LP +.eM +\fBXtProcessLock\fP blocks until it is able to acquire the lock. +Widget writers may use XtProcessLock to guarantee mutually exclusive +access to widget static data. +.LP +To unlock a locked process, use +.PN XtProcessUnlock . +.LP +.IN "XtProcessUnlock" "" "@DEF@" +.sM +.FD 0 +void XtProcessUnlock() +.FN +.LP +.eM +To lock both an application context and the process at the same +time, call +.PN XtAppLock +first and then +.PN XtProcessLock . +To release both locks, call +.PN XtProcessUnlock +first and then +.PN XtAppUnlock . +The order is important to avoid deadlock. + +.NH 3 +Event Management in a Multi-Threaded Environment +.XS +\fB\*(SN Event Management in a Multi-Threaded Environment\fP +.XE +.LP +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 desirable to provide a mechanism to terminate an +event-processing loop without necessarily terminating its thread. +.LP +To indicate that the event loop should terminate after the current +event dispatch has completed, use +.PN XtAppSetExitFlag . +.LP +.IN "XtAppSetExitFlag" "" "@DEF@" +.sM +.FD 0 +void XtAppSetExitFlag(\fIapp_context\fP) +.br + XtAppContext \fIapp_context\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.LP +.eM +.PN XtAppMainLoop +tests the value of the flag and will return if the flag is \fBTrue\fP. +.LP +Application writers who implement their own main loop may test the +value of the exit flag with +.PN XtAppGetExitFlag . +.LP +.IN "XtAppGetExitFlag" "" "@DEF@" +.sM +.FD 0 +Boolean XtAppGetExitFlag(\fIapp_context\fP) +.br + XtAppContext \fIapp_context\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.LP +.eM +.PN XtAppGetExitFlag +will normally return \fBFalse\fP, indicating that event processing +may continue. When +.PN XtAppGetExitFlag +returns \fBTrue\fP, the loop must terminate and return to the caller, +which might then destroy the application context. +.LP +Application writers should be aware that, if a thread is blocked in +.PN XtAppNextEvent , +.PN XtAppPeekEvent , +or +.PN XtAppProcessEvent +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. +.LP +The \*(xI manage access to events on a last-in, first-out basis. If +multiple threads in the same application context block in +.PN XtAppNextEvent , +.PN XtAppPeekEvent , +or +.PN XtAppProcessEvent , +the last thread to call one of these functions is the first +thread to return. +.bp diff --git a/specs/CH08 b/specs/CH08 new file mode 100644 index 0000000..6dfb529 --- /dev/null +++ b/specs/CH08 @@ -0,0 +1,452 @@ +.\" $Xorg: CH08,v 1.3 2000/08/17 19:42:46 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 8\fP\s-1 + +\s+1\fBCallbacks\fP\s-1 +.sp 2 +.nr H1 8 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 8 \(em Callbacks +.XE +.IN "Destroy Callbacks" +Applications and other widgets often need to register a procedure +with a widget that gets called under certain prespecified conditions. +For example, +when a widget is destroyed, +every procedure on the widget's \fIdestroy_callbacks\fP +list is called to notify clients of the widget's impending doom. +.LP +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. +.LP +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. + +.NH 2 +Using Callback Procedure and Callback List Definitions +.XS +\fB\*(SN Using Callback Procedure and Callback List Definitions\fP +.XE +.IN "XtCallbackList" +.IN "XtCallbackProc" +.LP +Callback procedure pointers for use in callback lists are of type +.PN XtCallbackProc . +.LP +.IN "XtCallbackProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtCallbackProc)(Widget, XtPointer, XtPointer); +.br + Widget \fIw\fP; +.br + XtPointer \fIclient_data\fP; +.br + XtPointer \fIcall_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget owning the list in which the callback is registered. +.IP \fIclient_data\fP 1i +Specifies additional data supplied by the client when the procedure +was registered. +.IP \fIcall_data\fP 1i +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. +.LP +.eM +The \fIclient_data\fP argument provides a way for the +client registering the callback procedure also to register client-specific data, +for example, a pointer to additional information about the widget, +a reason for invoking the callback, and so on. +The \fIclient_data\fP value may be NULL +if all necessary information is in the widget. +The \fIcall_data\fP argument is a convenience to avoid having simple +cases where the client could otherwise always call +.PN XtGetValues +or a widget-specific function to retrieve data from the widget. +Widgets should generally avoid putting complex state information +in \fIcall_data\fP. +The client can use the more general data retrieval methods, if necessary. +.LP +Whenever a client wants to pass a callback list as an argument in an +.PN XtCreateWidget , +.PN XtSetValues , +or +.PN XtGetValues +call, it should specify the address +of a NULL-terminated array of type +.PN XtCallbackList . +.IN "XtCallbackList" "" "@DEF@" +.IN "XtCallbackRec" "" "@DEF@" +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + XtCallbackProc callback; + XtPointer closure; +} XtCallbackRec, *XtCallbackList; +.De +.LP +.eM +For example, the callback list for procedures A and B with client data +clientDataA and clientDataB, respectively, is +.LP +.KS +.Ds 5 +.TA .5i 3i +.ta .5i 3i +static XtCallbackRec callbacks[] = { + {A, (XtPointer) clientDataA}, + {B, (XtPointer) clientDataB}, + {(XtCallbackProc) NULL, (XtPointer) NULL} +}; +.De +.KE +.LP +Although callback lists are passed by address in arglists +and varargs lists, +the \*(xI 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 \*(xI automatically do this, +potentially using a different structure for their +internal representation. + +.NH 2 +Identifying Callback Lists +.XS +\fB\*(SN Identifying Callback Lists\fP +.XE +.LP +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 functions described in this chapter +except +.PN XtCallCallbackList +check +to see that the requested callback list is indeed implemented by the widget. +.LP +For the \*(xI to find and correctly handle callback lists, +they must be declared with a resource type of +.PN XtRCallback . +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 +.PN XtCallbackStatus +.PN XtCallbackHasNone ), +access to callback list resources must be made +through other \*(xI procedures. + +.NH 2 +Adding Callback Procedures +.XS +\fB\*(SN Adding Callback Procedures\fP +.XE +.LP +To add a callback procedure to a widget's callback list, use +.PN XtAddCallback . +.LP +.IN "XtAddCallback" "" "@DEF@" +.sM +.FD 0 +void XtAddCallback(\fIw\fP, \fIcallback_name, \fP\fIcallback\fP, \ +\fIclient_data\fP) +.br + Widget \fIw\fP; +.br + String \fIcallback_name\fP; +.br + XtCallbackProc \fIcallback\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(oI +.IP \fIcallback_name\fP 1i +Specifies the callback list to which the procedure is to be appended. +.IP \fIcallback\fP 1i +Specifies the callback procedure. +.IP \fIclient_data\fP 1i +Specifies additional data to be passed to the specified procedure +when it is invoked, +or NULL. +.LP +.eM +A callback will be invoked as many times as it occurs in the callback list. +.sp +.LP +To add a list of callback procedures to a given widget's callback list, use +.PN XtAddCallbacks . +.LP +.IN "XtAddCallbacks" "" "@DEF@" +.sM +.FD 0 +void XtAddCallbacks(\fIw\fP, \fIcallback_name, \fP\fIcallbacks\fP) +.br + Widget \fIw\fP; +.br + String \fIcallback_name\fP; +.br + XtCallbackList \fIcallbacks\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(oI +.IP \fIcallback_name\fP 1i +Specifies the callback list to which the procedures are to be appended. +.IP \fIcallbacks\fP 1i +Specifies the null-terminated list of callback procedures and corresponding +client data. +.LP +.eM +.NH 2 +Removing Callback Procedures +.XS +\fB\*(SN Removing Callback Procedures\fP +.XE +.LP +To delete a callback procedure from a widget's callback list, use +.PN XtRemoveCallback . +.LP +.IN "XtRemoveCallback" "" "@DEF@" +.sM +.FD 0 +void XtRemoveCallback(\fIw\fP, \fIcallback_name\fP, \fIcallback\fP, \ +\fIclient_data\fP) +.br + Widget \fIw\fP; +.br + String \fIcallback_name\fP; +.br + XtCallbackProc \fIcallback\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(oI +.IP \fIcallback_name\fP 1i +Specifies the callback list from which the procedure is to be deleted. +.IP \fIcallback\fP 1i +Specifies the callback procedure. +.IP \fIclient_data\fP 1i +Specifies the client data to match with the registered callback entry. +.LP +.eM +The +.PN XtRemoveCallback +function removes a callback only if both the procedure and the client +data match. +.sp +.LP +To delete a list of callback procedures from a given widget's callback list, use +.PN XtRemoveCallbacks . +.LP +.IN "XtRemoveCallbacks" "" "@DEF@" +.sM +.FD 0 +void XtRemoveCallbacks(\fIw\fP, \fIcallback_name\fP, \fIcallbacks\fP) +.br + Widget \fIw\fP; +.br + String \fIcallback_name\fP; +.br + XtCallbackList \fIcallbacks\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(oI +.IP \fIcallback_name\fP 1i +Specifies the callback list from which the procedures are to be deleted. +.IP \fIcallbacks\fP 1i +Specifies the null-terminated list of callback procedures and corresponding +client data. +.LP +.eM +To delete all callback procedures from a given widget's callback list +and free all storage associated with the callback list, use +.PN XtRemoveAllCallbacks . +.LP +.IN "XtRemoveAllCallbacks" "" "@DEF@" +.sM +.FD 0 +void XtRemoveAllCallbacks(\fIw\fP, \fIcallback_name\fP) +.br + Widget \fIw\fP; +.br + String \fIcallback_name\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(oI +.IP \fIcallback_name\fP 1i +Specifies the callback list to be cleared. +.LP +.eM +.NH 2 +Executing Callback Procedures +.XS +\*(SN Executing Callback Procedures +.XE +.LP +To execute the procedures in a given widget's callback list, +specifying the callback list by resource name, use +.PN XtCallCallbacks . +.LP +.IN "XtCallCallbacks" "" "@DEF@" +.sM +.FD 0 +void XtCallCallbacks(\fIw\fP, \fIcallback_name\fP, \fIcall_data\fP) +.br + Widget \fIw\fP; +.br + String \fIcallback_name\fP; +.br + XtPointer \fIcall_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(oI +.IP \fIcallback_name\fP 1i +Specifies the callback list to be executed. +.IP \fIcall_data\fP 1i +Specifies a callback-list-specific data value to pass to each of the callback +procedure in the list, or NULL. +.LP +.eM +.LP +.PN XtCallCallbacks +calls each of the callback procedures in the list +named by \fIcallback_name\fP in the specified widget, passing the client +data registered with the procedure and \fIcall-data\fP. +.sp +.LP +To execute the procedures in a callback list, specifying the callback +list by address, use +.PN XtCallCallbackList . +.LP +.IN "XtCallCallbackList" "" "@DEF@" +.sM +.FD 0 +void XtCallCallbackList(\fIwidget\fP, \fIcallbacks\fP, \fIcall_data\fP) +.br + Widget \fIwidget\fP; +.br + XtCallbackList \fIcallbacks\fP; +.br + XtPointer \fIcall_data\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget instance that contains the callback list. \*(oI +.IP \fIcallbacks\fP 1i +Specifies the callback list to be executed. +.IP \fIcall_data\fP 1i +Specifies a callback-list-specific data value to pass +to each of the callback procedures in the list, or NULL. +.LP +.eM +The \fIcallbacks\fP parameter must specify the contents of a widget or +object resource declared with representation type +.PN XtRCallback . +If \fIcallbacks\fP is NULL, +.PN XtCallCallbackList +returns immediately; otherwise it calls each of the callback +procedures in the list, passing the client data and \fIcall_data\fP. + +.NH 2 +Checking the Status of a Callback List +.XS +\*(SN Checking the Status of a Callback List +.XE +.LP +To find out the status of a given widget's callback list, use +.PN XtHasCallbacks . +.LP +.IN "XtHasCallbacks" "" "@DEF@" +.sp +.sM +.FD 0 +typedef enum {XtCallbackNoList, XtCallbackHasNone, XtCallbackHasSome} \ +XtCallbackStatus; +.sp +XtCallbackStatus XtHasCallbacks(\fIw\fP, \fIcallback_name\fP) +.br + Widget \fIw\fP; +.br + String \fIcallback_name\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(oI +.IP \fIcallback_name\fP 1i +Specifies the callback list to be checked. +.LP +.eM +The +.PN XtHasCallbacks +function first checks to see if the widget has a callback list identified +by \fIcallback_name\fP. +If the callback list does not exist, +.PN XtHasCallbacks +returns +.PN XtCallbackNoList . +If the callback list exists but is empty, +it returns +.PN XtCallbackHasNone . +If the callback list exists and has at least one callback registered, +it returns +.PN XtCallbackHasSome . +.bp diff --git a/specs/CH09 b/specs/CH09 new file mode 100644 index 0000000..9538651 --- /dev/null +++ b/specs/CH09 @@ -0,0 +1,3211 @@ +.\" $Xorg: CH09,v 1.3 2000/08/17 19:42:46 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 9\fP\s-1 + +\s+1\fBResource Management\fP\s-1 +.sp 2 +.nr H1 9 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 9 \(em Resource Management +.XE +A resource is a field in the widget record with a corresponding +resource entry in the \fIresources\fP list of the widget or any of its +superclasses. +This means that the field is +settable by +.PN XtCreateWidget +(by naming the field in the argument list), by an +entry in a resource file (by using either the name or class), and by +.PN XtSetValues . +In addition, it is readable by +.PN XtGetValues . +Not all fields in a widget record are resources. +Some are for bookkeeping use by the +generic routines (like \fImanaged\fP and \fIbeing_destroyed\fP). +Others can be for local bookkeeping, +and still others are derived from resources +(many graphics contexts and pixmaps). +.LP +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 +.PN XtCreateWidget , +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 database for all resources not specified +in the argument list, +and last, from the internal default, if needed. + +.NH 2 +Resource Lists +.XS +\*(SN Resource Lists +.XE +.LP +.IN "Resource Management" +A resource entry specifies a field in the widget, +the textual 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 specified. +The declaration for the +.PN XtResource +structure is +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +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; +.De +.IN "XtResourceList" +.eM + +.LP +When the resource list is specified as the +.PN CoreClassPart , +.PN ObjectClassPart , +.PN RectObjClassPart , +or +.PN ConstraintClassPart +\fIresources\fP field, the strings pointed to by \fIresource_name\fP, +\fIresource_class\fP, \fIresource_type\fP, and \fIdefault_type\fP must +be permanently allocated prior to or during the execution of the class +initialization procedure and must not be subsequently deallocated. + +.LP +The \fIresource_name\fP 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 \*(xI 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 \*(xI are named in +.Pn < X11/StringDefs.h >. +The \*(xI's symbolic resource names begin with +``XtN'' +and are followed by the string name (for example, XtNbackgroundPixel +for backgroundPixel). + +.LP +The \fIresource_class\fP field contains the class string used in resource +specification files to identify the field. +A resource class provides two functions: +.IP \(bu 5 +It isolates an application from different representations that widgets +can use for a similar resource. +.IP \(bu 5 +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. +.LP +For example, +a widget can have several pixel resources: background, foreground, +border, block cursor, pointer cursor, 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. +.LP +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 darkblue: +.LP +.Ds 5 +.TA .5i 1.5i +.ta .5i 1.5i +*Background: ivory +*Foreground: darkblue +.De +.LP +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: +.LP +.Ds 5 +.TA .5i 3i +.ta .5i 3i +*Font: 6x13 +.De +.LP +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). +.LP +The \fIresource_type\fP 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 +.PN String ) +or the format of the resource default value +(almost anything, but often +.PN String ) +to the desired +physical representation (see Section 9.6). +The \*(xI define the following resource types: +.TS H +lw(2.5i) lw(2.5i). +_ +.sp 6p +Resource Type Structure or Field Type +.sp 6p +_ +.sp 6p +.TH +.R +T{ +.PN XtRAcceleratorTable +T} XtAccelerators +T{ +.PN XtRAtom +T} Atom +T{ +.PN XtRBitmap +T} Pixmap, depth=1 +T{ +.PN XtRBoolean +T} Boolean +T{ +.PN XtRBool +T} Bool +T{ +.PN XtRCallback +T} XtCallbackList +T{ +.PN XtRCardinal +T} Cardinal +T{ +.PN XtRColor +T} XColor +T{ +.PN XtRColormap +T} Colormap +T{ +.PN XtRCommandArgArray +T} String* +T{ +.PN XtRCursor +T} Cursor +T{ +.PN XtRDimension +T} Dimension +T{ +.PN XtRDirectoryString +T} String +T{ +.PN XtRDisplay +T} Display* +T{ +.PN XtREnum +T} XtEnum +T{ +.PN XtREnvironmentArray +T} String* +T{ +.PN XtRFile +T} FILE* +T{ +.PN XtRFloat +T} float +T{ +.PN XtRFont +T} Font +T{ +.PN XtRFontSet +T} XFontSet +T{ +.PN XtRFontStruct +T} XFontStruct* +T{ +.PN XtRFunction +T} (*)() +T{ +.PN XtRGeometry +T} T{ +char*, format as defined by +.PN XParseGeometry +T} +T{ +.PN XtRGravity +T} int +T{ +.PN XtRInitialState +T} int +T{ +.PN XtRInt +T} int +T{ +.PN XtRLongBoolean +T} long +T{ +.PN XtRObject +T} Object +T{ +.PN XtRPixel +T} Pixel +T{ +.PN XtRPixmap +T} Pixmap +T{ +.PN XtRPointer +T} XtPointer +T{ +.PN XtRPosition +T} Position +T{ +.PN XtRRestartStyle +T} unsigned char +T{ +.PN XtRScreen +T} Screen* +T{ +.PN XtRShort +T} short +T{ +.PN XtRSmcConn +T} XtPointer +T{ +.PN XtRString +T} String +T{ +.PN XtRStringArray +T} String* +T{ +.PN XtRStringTable +T} String* +T{ +.PN XtRTranslationTable +T} XtTranslations +T{ +.PN XtRUnsignedChar +T} unsigned char +T{ +.PN XtRVisual +T} Visual* +T{ +.PN XtRWidget +T} Widget +T{ +.PN XtRWidgetClass +T} WidgetClass +T{ +.PN XtRWidgetList +T} WidgetList +T{ +.PN XtRWindow +T} Window +.sp 6p +_ +.TE +.sp +.LP +.Pn < X11/StringDefs.h > +also defines the following resource types as a +convenience for widgets, although they do not have any corresponding +data type assigned: +.PN XtREditMode , +.PN XtRJustify , +and +.PN XtROrientation . +.LP +The \fIresource_size\fP field is the size of the physical representation in bytes; +you should specify it as +.PN sizeof (\fItype\fP) +so that the +compiler fills in the value. +The \fIresource_offset\fP field is the offset in bytes of the field +within the widget. +You should use the +.PN XtOffsetOf +macro to retrieve this value. +The \fIdefault_type\fP field is the representation type of the default +resource value. +If \fIdefault_type\fP is different from \fIresource_type\fP and the default value +is needed, +the resource manager invokes a conversion procedure from \fIdefault_type\fP +to \fIresource_type\fP. +Whenever possible, +the default type should be identical to the resource type in order +to minimize widget 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 guaranteed to work (for example, +.PN XtDefaultForeground +for a pixel resource). +The \fIdefault_addr\fP field specifies the address of the default resource value. +As a special case, if \fIdefault_type\fP is +.PN XtRString , +then the value in the \fIdefault_addr\fP 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). +.LP +Two special representation types +(XtRImmediate +and +XtRCallProc) +are usable only as default resource types. +XtRImmediate +indicates that the value in the \fIdefault_addr\fP 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 +.PN XtPointer . +No conversion is possible, since there is no source representation type. +XtRCallProc +indicates that the value in the \fIdefault_addr\fP field is a procedure +pointer. +This procedure is automatically invoked with the widget, +\fIresource_offset\fP, and a pointer to an +.PN XrmValue +in which to store the result. +XtRCallProc +procedure pointers are of type +.PN XtResourceDefaultProc . +.LP +.sM +.FD 0 +typedef void (*XtResourceDefaultProc)(Widget, int, XrmValue*); +.br + Widget \fIw\fP; +.br + int \fIoffset\fP; +.br + XrmValue *\fIvalue\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget whose resource value is to be obtained. +.IP \fIoffset\fP 1i +Specifies the offset of the field in the widget record. +.IP \fIvalue\fP 1i +Specifies the resource value descriptor to return. +.LP +.eM +The +.PN XtResourceDefaultProc +procedure should fill in the \fIvalue->addr\fP field with a pointer +to the resource value in its correct representation type. +.sp +.LP +To get the resource list structure for a particular class, use +.PN XtGetResourceList . +.LP +.IN "XtGetResourceList" "" "@DEF@" +.sM +.FD 0 +void XtGetResourceList(\fIclass\fP, \fIresources_return\fP, \fInum_resources_return\fP); +.br + WidgetClass \fIclass\fP; +.br + XtResourceList *\fIresources_return\fP; +.br + Cardinal *\fInum_resources_return\fP; +.FN +.IP \fIclass\fP 1.5i +Specifies the object class to be queried. It must be +.PN objectClass +or any subclass thereof. +.IP \fIresources_return\fP 1.5i +Returns the resource list. +.IP \fInum_resources_return\fP 1.5i +Returns the number of entries in the resource list. +.LP +.eM +If +.PN XtGetResourceList +is called before the class is initialized, +it returns the resource list as specified in the class record. +If it is called after the class has been initialized, +.PN XtGetResourceList +returns a merged resource list that includes the resources +for all superclasses. +The list returned by +.PN XtGetResourceList +should be freed using +.PN XtFree +when it is no longer needed. +.sp +.LP +To get the constraint resource list structure for a particular widget +class, use +.PN XtGetConstraintResourceList . +.LP +.IN "XtGetConstraintResourceList" "" "@DEF@" +.sM +.FD 0 +void XtGetConstraintResourceList(\fIclass\fP, \fIresources_return\fP, \ +\fInum_resources_return\fP) +.br + WidgetClass \fIclass\fP; +.br + XtResourceList *\fIresources_return\fP; +.br + Cardinal *\fInum_resources_return\fP; +.FN +.IP \fIclass\fP 1.5i +Specifies the object class to be queried. It must be +.PN objectClass +or any subclass thereof. +.IP \fIresources_return\fP 1.5i +Returns the constraint resource list. +.IP \fInum_resources_return\fP 1.5i +Returns the number of entries in the constraint resource list. +.LP +.eM +If +.PN XtGetConstraintResourceList +is called before the widget class is +initialized, the resource list as specified in the widget +class Constraint part is returned. If +.PN XtGetConstraintResourceList +is called after the widget class has been initialized, the merged +resource list for the class and all Constraint superclasses is +returned. If the +specified class is not a subclass of +.PN constraintWidgetClass , +*\fIresources_return\fP is set to NULL +and *\fInum_resources_return\fP is set to zero. +The list returned by +.PN XtGetConstraintResourceList +should be freed using +.PN XtFree +when it is no longer needed. +.sp +.LP +The routines +.PN XtSetValues +and +.PN XtGetValues +also use the resource list to set and get widget state; +see Sections 9.7.1 and 9.7.2. +.LP +Here is an abbreviated version of a possible resource list for a Label widget: +.LP +.Ds +.TA .5i 1.5i 3i +.ta .5i 1.5i 3i +/* 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}, + . + . + . +} +.De +.LP +The complete resource name for a field of a widget instance is the +concatenation of the application shell name (from +.PN XtAppCreateShell ), +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 +.PN XtAppCreateShell ), +the widget class names of all the widget's parents up to the +top of the widget tree, +the widget class name of the widget itself, +and the resource class of the specified field of the widget. + +.NH 2 +Byte Offset Calculations +.XS +\*(SN Byte Offset Calculations +.XE +.LP +To determine the byte offset of a field within a structure type, use +.PN XtOffsetOf . +.LP +.IN "XtOffsetOf" "" "@DEF@" +.sM +.FD 0 +Cardinal XtOffsetOf(\fIstructure_type\fP, \fIfield_name\fP) +.br + \fIType structure_type\fP; +.br + \fIField field_name\fP; +.FN +.IP \fIstructure_type\fP 1i +Specifies a type that is declared as a structure. +.IP \fIfield_name\fP 1i +Specifies the name of a member within the structure. +.LP +.eM +The +.PN XtOffsetOf +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 +.PN XtOffset , +which serves the same function. + +.LP +To determine the byte offset of a field within a structure pointer type, use +.PN XtOffset . +.LP +.IN "XtOffset" "" "@DEF@" +.sM +.FD 0 +Cardinal XtOffset(\fIpointer_type\fP, \fIfield_name\fP) +.br + \fIType pointer_type\fP; +.br + \fIField field_name\fP; +.FN +.IP \fIpointer_type\fP 1i +Specifies a type that is declared as a pointer to a structure. +.IP \fIfield_name\fP 1i +Specifies the name of a member within the structure. +.LP +.eM +The +.PN XtOffset +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. +.PN XtOffset +is less portable than +.PN XtOffsetOf . + +.NH 2 +Superclass-to-Subclass Chaining of Resource Lists +.XS +\*(SN Superclass-to-Subclass Chaining of Resource Lists +.XE +.LP +.IN "Inheritance" +.IN "Superclass Chaining" +.IN "Chaining" +The +.PN XtCreateWidget +function gets resources as a superclass-to-subclass chained operation. +That is, the resources specified in the +.PN objectClass +resource list are fetched, +then those in +.PN rectObjClass , +and so on down to the resources specified +for this widget's class. Within a class, resources are fetched in the order +they are declared. +.LP +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 \fIbackground_pixel\fP. +Consequently, +the implementation of Label need not also have a resource entry +for \fIbackground_pixel\fP. +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. +.LP +.IN "class_initialize procedure" +.IN "Widget" "class initialization" +Also at class initialization time, the \*(xI produce an +internal representation of the resource list to optimize access time +when creating widgets. In order to save memory, the \*(xI 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. + +.NH 2 +Subresources +.XS +\*(SN Subresources +.XE +.LP +A widget does not do anything to retrieve its own resources; +instead, +.PN XtCreateWidget +does this automatically before calling the class initialize procedure. +.LP +Some widgets have subparts that are not widgets but for which the widget +would like to fetch resources. +Such widgets call +.PN XtGetSubresources +to accomplish this. +.LP +.IN "XtGetSubresources" "" "@DEF@" +.sM +.FD 0 +void XtGetSubresources(\fIw\fP, \fIbase\fP, \fIname\fP, \fIclass\fP, \ +\fIresources\fP, \fInum_resources\fP, \fIargs\fP, \fInum_args\fP) +.br + Widget \fIw\fP; +.br + XtPointer \fIbase\fP; +.br + String \fIname\fP; +.br + String \fIclass\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIw\fP 1i +Specifies the object used to qualify the subpart resource name and +class. \*(oI +.IP \fIbase\fP 1i +Specifies the base address of the subpart data structure into which the +resources will be written. +.IP \fIname\fP 1i +Specifies the name of the subpart. +.IP \fIclass\fP 1i +Specifies the class of the subpart. +.IP \fIresources\fP 1i +Specifies the resource list for the subpart. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP \fIargs\fP 1i +Specifies the argument list to override any other resource specifications. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtGetSubresources +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 \fIname\fP and \fIclass\fP 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 \fIargs\fP is NULL, +\fInum_args\fP must be zero. +However, if \fInum_args\fP is zero, +the argument list is not referenced. +.LP +.PN XtGetSubresources +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 +.PN XtGetSubresources +are reference-counted as +if they were 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. +.sp +.LP +To fetch resources for widget subparts using varargs lists, use +.PN XtVaGetSubresources . +.LP +.IN "XtVaGetSubresources" "" "@DEF@" +.sM +.FD 0 +void XtVaGetSubresources(\fIw\fP, \fIbase\fP, \fIname\fP, \fIclass\fP, \ +\fIresources\fP, \fInum_resources\fP, ...) +.br + Widget \fIw\fP; +.br + XtPointer \fIbase\fP; +.br + String \fIname\fP; +.br + String \fIclass\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.FN +.IP \fIw\fP 1i +Specifies the object used to qualify the subpart resource name and +class. \*(oI +.IP \fIbase\fP 1i +Specifies the base address of the subpart data structure into which the +resources will be written. +.IP \fIname\fP 1i +Specifies the name of the subpart. +.IP \fIclass\fP 1i +Specifies the class of the subpart. +.IP \fIresources\fP 1i +Specifies the resource list for the subpart. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP ... 1i +Specifies the variable argument list to override any other +resource specifications. +.LP +.eM +.PN XtVaGetSubresources +is identical in function to +.PN XtGetSubresources +with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as +described in Section 2.5.1. + +.NH 2 +Obtaining Application Resources +.XS +\fB\*(SN Obtaining Application Resources\fP +.XE +.LP +To retrieve resources that are not specific to a widget +but apply to the overall application, use +.PN XtGetApplicationResources . +.LP +.IN "XtGetApplicationResources" "" "@DEF@" +.sM +.FD 0 +void XtGetApplicationResources(\fIw\fP, \fIbase\fP, \fIresources\fP, \ +\fInum_resources\fP, \fIargs\fP, \fInum_args\fP) +.br + Widget \fIw\fP; +.br + XtPointer \fIbase\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIw\fP 1i +Specifies the object that identifies the resource database to search +(the database is that associated with the display for this object). \*(oI +.IP \fIbase\fP 1i +Specifies the base address into which +the resource values will be written. +.IP \fIresources\fP 1i +Specifies the resource list. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP \fIargs\fP 1i +Specifies the argument list to override any other resource specifications. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtGetApplicationResources +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 +ancestors, 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, +.PN XtGetApplicationResources +copies the resources into the addresses +obtained by adding \fIbase\fP to each \fIoffset\fP in the resource list. +If \fIargs\fP is NULL, +\fInum_args\fP must be zero. +However, if \fInum_args\fP is zero, +the argument list is not referenced. +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 \fIbase\fP argument. +.LP +.PN XtGetApplicationResources +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. Any per-display resources fetched by +.PN XtGetApplicationResources +will not be freed from the resource cache until the display is closed. +.sp +.LP +To retrieve resources for the overall application using varargs lists, use +.PN XtVaGetApplicationResources . +.LP +.IN "XtVaGetApplicationResources" "" "@DEF@" +.sM +.FD 0 +void XtVaGetApplicationResources(\fIw\fP, \fIbase\fP, \fIresources\fP, \ +\fInum_resources\fP, ...) +.br + Widget \fIw\fP; +.br + XtPointer \fIbase\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.FN +.IP \fIw\fP 1i +Specifies the object that identifies the resource database to search +(the database is that associated with the display for this object). \*(oI +.IP \fIbase\fP 1i +Specifies the base address into which +the resource values will be written. +.IP \fIresources\fP 1i +Specifies the resource list for the subpart. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP ... 1i +Specifies the variable argument list to override any other +resource specifications. +.LP +.eM +.PN XtVaGetApplicationResources +is identical in function to +.PN XtGetApplicationResources +with the \fIargs\fP and \fInum_args\fP parameters +replaced by a varargs list, as described in Section 2.5.1. + +.NH 2 +Resource Conversions +.XS +\*(SN Resource Conversions +.XE +.LP +The \*(xI provide a mechanism for registering representation converters that +are automatically invoked by the resource-fetching routines. +The \*(xI additionally provide and register several commonly used converters. +This resource conversion mechanism serves several purposes: +.IP \(bu 5 +It permits user and application resource files to contain textual +representations of nontextual values. +.IP \(bu 5 +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 runtime. +.IP \(bu 5 +It caches conversion source and result data. +Conversions that require much computation or space +(for example, 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. + +.NH 3 +Predefined Resource Converters +.XS +\*(SN Predefined Resource Converters +.XE +.LP +The \*(xI define all the representations used in the +Object, +RectObj, +Core, +Composite, +Constraint, +and +Shell +widget classes. +The \*(xI register the following resource converters that accept +input values of representation type +.PN XtRString . +.LP +.TS +lw(1.7i) lw(2.4i) lw(1.5i) . +_ +.sp 6p +Target Representation Converter Name Additional Args +.sp 6p +_ +.sp 6p +T{ +.PN XtRAcceleratorTable +T} T{ +.PN XtCvtStringToAcceleratorTable +T} +T{ +.PN XtRAtom +T} T{ +.PN XtCvtStringToAtom +T} Display* +T{ +.PN XtRBoolean +T} T{ +.PN XtCvtStringToBoolean +T} +T{ +.PN XtRBool +T} T{ +.PN XtCvtStringToBool +T} +T{ +.PN XtRCommandArgArray +T} T{ +.PN XtCvtStringToCommandArgArray +T} +T{ +.PN XtRCursor +T} T{ +.PN XtCvtStringToCursor +T} Display* +T{ +.PN XtRDimension +T} T{ +.PN XtCvtStringToDimension +T} +T{ +.PN XtRDirectoryString +T} T{ +.PN XtCvtStringToDirectoryString +T} +T{ +.PN XtRDisplay +T} T{ +.PN XtCvtStringToDisplay +T} +T{ +.PN XtRFile +T} T{ +.PN XtCvtStringToFile +T} +T{ +.PN XtRFloat +T} T{ +.PN XtCvtStringToFloat +T} +T{ +.PN XtRFont +T} T{ +.PN XtCvtStringToFont +T} Display* +T{ +.PN XtRFontSet +T} T{ +.PN XtCvtStringToFontSet +T} Display*, String \fIlocale\fP +T{ +.PN XtRFontStruct +T} T{ +.PN XtCvtStringToFontStruct +T} Display* +T{ +.PN XtRGravity +T} T{ +.PN XtCvtStringToGravity +T} +T{ +.PN XtRInitialState +T} T{ +.PN XtCvtStringToInitialState +T} +T{ +.PN XtRInt +T} T{ +.PN XtCvtStringToInt +T} +T{ +.PN XtRPixel +T} T{ +.PN XtCvtStringToPixel +T} T{ +.PN colorConvertArgs +T} +T{ +.PN XtRPosition +T} T{ +.PN XtCvtStringToPosition +T} +T{ +.PN XtRRestartStyle +T} T{ +.PN XtCvtStringToRestartStyle +T} +T{ +.PN XtRShort +T} T{ +.PN XtCvtStringToShort +T} +T{ +.PN XtRTranslationTable +T} T{ +.PN XtCvtStringToTranslationTable +T} +T{ +.PN XtRUnsignedChar +T} T{ +.PN XtCvtStringToUnsignedChar +T} +T{ +.PN XtRVisual +T} T{ +.PN XtCvtStringToVisual +T} Screen*, Cardinal \fIdepth\fP +.sp 6p +_ +.TE + +.LP +The String-to-Pixel conversion has two predefined constants that are +guaranteed to work and contrast with each other: +.PN XtDefaultForeground +and +.PN XtDefaultBackground . +.IN "XtDefaultBackground" "" "@DEF@" +.IN "XtDefaultForeground" "" "@DEF@" +They evaluate to the black and white pixel values of the widget's screen, +respectively. +.IN "Resources" "reverseVideo" +If the application resource reverseVideo is +.PN True , +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 +.PN XtDefaultFont +.IN "XtDefaultFont" "" "@DEF@" +.IN "Resources" "xtDefaultFont" +and evaluate this in the following manner: +.IP \(bu 5 +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 +.PN XtRString +value returned as the font name or a type +.PN XtRFont +or +.PN XtRFontStruct +value directly as the resource value. +.IP \(bu 5 +If the resource database does not contain a value for xtDefaultFont, +class XtDefaultFont, or if the returned font name cannot be +successfully opened, an implementation-defined font in ISO8859-1 +character set encoding is opened. (One possible algorithm is to +perform an +.PN XListFonts +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 locating a useable font; +for example, "-*-*-*-R-*-*-*-120-*-*-*-*-ISO8859-1".) +.IP \(bu 5 +If no suitable ISO8859-1 font can be found, issue a warning message +and return +.PN False . +.LP +The String-to-FontSet converter recognizes the constant +.PN XtDefaultFontSet +.IN "XtDefaultFontSet" "" "@DEF@" +.IN "Resources" "xtDefaultFontSet" +and evaluate this in the following manner: +.IP \(bu 5 +Query the resource database for the resource whose full name +is ``xtDefaultFontSet'', class ``XtDefaultFontSet'' (that is, no widget +name/class prefixes), and use a type +.PN XtRString +value returned as the base font name list or a type +.PN XtRFontSet +value directly as the resource value. +.IP \(bu 5 +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 +.PN XCreateFontSet +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 example, "-*-*-*-R-*-*-*-120-*-*-*-*".) +.IP \(bu 5 +If no suitable font set can be created, issue a warning message +and return +.PN False . +.LP +If a font set is created but \fImissing_charset_list\fP is not +empty, a warning is issued and the partial font set is returned. +The \*(xI 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. +.LP +The String-to-Gravity conversion accepts string values that are the +names of window and bit gravities and their numerical equivalents, +as defined in \fI\*(xL\fP: +.PN ForgetGravity , +.PN UnmapGravity , +.PN NorthWestGravity , +.PN NorthGravity , +.PN NorthEastGravity , +.PN WestGravity , +.PN CenterGravity , +.PN EastGravity , +.PN SouthWestGravity , +.PN SouthGravity , +.PN SouthEastGravity , +and +.PN StaticGravity . +Alphabetic case is not significant in the conversion. +.LP +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. +.LP +.IN "XtCurrentDirectory" "" "@DEF@" +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. +.LP +The String-to-RestartStyle conversion accepts the values +.PN RestartIfRunning , +.PN RestartAnyway , +.PN RestartImmediately , +and +.PN RestartNever +as defined by the \fIX Session Management Protocol\fP. +.LP +The String-to-InitialState conversion accepts the values +.PN NormalState +or +.PN IconicState +as defined by the \fI\*(xC\fP. +.LP +The String-to-Visual conversion calls +.PN XMatchVisualInfo +using the +\fIscreen\fP and \fIdepth\fP 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 +.PN XtRVisual +after the depth resource. +The allowed string values are the visual class names defined in \fI\*(xP\fP, +Section 8; +.PN StaticGray , +.PN StaticColor , +.PN TrueColor , +.PN GrayScale , +.PN PseudoColor , +and +.PN DirectColor . + +.LP +The \*(xI register the following resource converter that accepts +an input value of representation type +.PN XtRColor . +.LP +.TS +lw(1.5i) lw(2.25i) lw(1.5i) . +_ +.sp 6p +Target Representation Converter Name Additional Args +.sp 6p +_ +.sp 6p +T{ +.PN XtRPixel +T} T{ +.PN XtCvtColorToPixel +T} +.sp 6p +_ +.TE + +.LP +The \*(xI register the following resource converters that accept +input values of representation type +.PN XtRInt . +.LP +.TS +lw(1.5i) lw(2.25i) lw(1.5i) . +_ +.sp 6p +Target Representation Converter Name Additional Args +.sp 6p +_ +.sp 6p +T{ +.PN XtRBoolean +T} T{ +.PN XtCvtIntToBoolean +T} +T{ +.PN XtRBool +T} T{ +.PN XtCvtIntToBool +T} +T{ +.PN XtRColor +T} T{ +.PN XtCvtIntToColor +T} T{ +.PN colorConvertArgs +T} +T{ +.PN XtRDimension +T} T{ +.PN XtCvtIntToDimension +T} +T{ +.PN XtRFloat +T} T{ +.PN XtCvtIntToFloat +T} +T{ +.PN XtRFont +T} T{ +.PN XtCvtIntToFont +T} +T{ +.PN XtRPixel +T} T{ +.PN XtCvtIntToPixel +T} +T{ +.PN XtRPixmap +T} T{ +.PN XtCvtIntToPixmap +T} +T{ +.PN XtRPosition +T} T{ +.PN XtCvtIntToPosition +T} +T{ +.PN XtRShort +T} T{ +.PN XtCvtIntToShort +T} +T{ +.PN XtRUnsignedChar +T} T{ +.PN XtCvtIntToUnsignedChar +T} +.sp 6p +_ +.TE + +.LP +The \*(xI register the following resource converter that accepts +an input value of representation type +.PN XtRPixel . +.LP +.TS +lw(1.5i) lw(2.25i) lw(1.5i) . +_ +.sp 6p +Target Representation Converter Name Additional Args +.sp 6p +_ +.sp 6p +T{ +.PN XtRColor +T} T{ +.PN XtCvtPixelToColor +T} +.sp 6p +_ +.TE + +.NH 3 +New Resource Converters +.XS +\*(SN New Resource Converters +.XE +.LP +Type converters use pointers to +.PN XrmValue +structures (defined in +.Pn < X11/Xresource.h >; +see Section 15.4 in \fI\*(xL\fP) +for input and output values. +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + unsigned int size; + XPointer addr; +} XrmValue, *XrmValuePtr; +.De +.LP +.eM +The \fIaddr\fP field specifies the address of the data, and the \fIsize\fP +field gives the total number of significant bytes in the data. +For values of type +.PN String , +\fIaddr\fP is the address of the first character and \fIsize\fP +includes the NULL-terminating byte. +.LP +A resource converter procedure pointer is of type +.PN XtTypeConverter . +.LP +.IN "XtTypeConverter" "" "@DEF@" +.sM +.FD 0 +typedef Boolean (*XtTypeConverter)(Display*, XrmValue*, Cardinal*, + XrmValue*, XrmValue*, XtPointer*); +.br + Display *\fIdisplay\fP; +.br + XrmValue *\fIargs\fP; +.br + Cardinal *\fInum_args\fP; +.br + XrmValue *\fIfrom\fP; +.br + XrmValue *\fIto\fP; +.br + XtPointer *\fIconverter_data\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display connection with which this conversion is associated. +.IP \fIargs\fP 1i +Specifies a list of additional +.PN XrmValue +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 \fIdisplay\fP, +and the String-to-Pixel converter needs the widget's \fIscreen\fP and \fIcolormap\fP. +.IP \fInum_args\fP 1i +Specifies the number of entries in \fIargs\fP. +.IP \fIfrom\fP 1i +Specifies the value to convert. +.IP \fIto\fP 1i +Specifies a descriptor for a location into which to store the converted value. +.IP \fIconverter_data\fP 1i +Specifies a location into which the converter may +store converter-specific data associated +with this conversion. +.LP +.eM +The \fIdisplay\fP argument is normally used only when generating error +messages, to identify the application context (with the function +.PN XtDisplayToApplicationContext ). +.LP +The \fIto\fP argument specifies the size and location into which the +converter should store the converted value. If the \fIaddr\fP field is NULL, +the converter should allocate appropriate storage and store the size +and location into the \fIto\fP descriptor. 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 +\fIaddr\fP field is not NULL, the converter must check the \fIsize\fP field to +ensure that sufficient space has been allocated before storing the +converted value. If insufficient space is specified, the converter +should update the \fIsize\fP field with the number of bytes required and +return +.PN False +without modifying the data at the specified location. +If sufficient space was allocated by the caller, the converter should +update the \fIsize\fP field with the number of bytes actually occupied by the +converted value. For converted values of type +.PN XtRString , +the size should +include the NULL-terminating byte, if any. +The converter may store any value in the location specified +in \fIconverter_data\fP; this value will be passed to the destructor, if any, +when the resource is freed by the \*(xI. +.LP +The converter must return +.PN True +if the conversion was successful and +.PN False +otherwise. If the conversion cannot be performed because of an +improper source value, a warning message should also be issued with +.PN XtAppWarningMsg . + +.LP +Most type converters just take the data described by the specified \fIfrom\fP +argument and return data by writing into the location specified in +the \fIto\fP argument. +A few need other information, which is available in \fIargs\fP. +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. +.LP +Note that if an address is written into \fIto->addr\fP, 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, +.PN XtGetApplicationResources , +or +.PN XtGetSubresources +in an implementation-defined manner; however, insertion of new entries +or changes to existing entries is allowed and will not directly cause +an error. + +.LP +The following is an example of a converter that takes a +.PN string +and converts it to a +.PN Pixel . +Note that the \fIdisplay\fP parameter is +used only to generate error messages; the +.PN Screen +conversion argument is +still required to inform the \*(xI that the converted value is +a function of the particular display (and colormap). +.LP +.Ds 0 +.TA .3i .7i 1i 1.3i 1.7i 2i 4i +.ta .3i .7i 1i 1.3i 1.7i 2i 4i + +#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)); + } + + + 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); + } +} +.De +.LP +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 manner as +.PN XtDefaultForeground , +.PN XtDefaultBackground , +and +.PN XtDefaultFont . +.sp +.LP +To allow the \*(xI to deallocate resources produced by type +converters, a resource destructor procedure may also be provided. +.LP +A resource destructor procedure pointer is of type +.PN XtDestructor . +.LP +.IN "XtDestructor" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtDestructor) (XtAppContext, XrmValue*, XtPointer, XrmValue*, \ +Cardinal*); +.br + XtAppContext \fIapp\fP; +.br + XrmValue *\fIto\fP; +.br + XtPointer \fIconverter_data\fP; +.br + XrmValue *\fIargs\fP; +.br + Cardinal *\fInum_args\fP; +.FN +.IP \fIapp\fP 1i +Specifies an application context in which the resource is being freed. +.IP \fIto\fP 1i +Specifies a descriptor for the resource produced by the type converter. +.IP \fIconverter_data\fP 1i +Specifies the converter-specific data returned by the type converter. +.IP \fIargs\fP 1i +Specifies the additional converter arguments as passed +to the type converter when the conversion was performed. +.IP \fInum_args\fP 1i +Specifies the number of entries in \fIargs\fP. +.LP +.eM +The destructor procedure is responsible for freeing the resource +specified by the \fIto\fP argument, including any auxiliary storage +associated with that resource, but not the memory directly addressed +by the size and location in the \fIto\fP argument or the memory specified +by \fIargs\fP. + +.NH 3 +Issuing Conversion Warnings +.XS +\*(SN Issuing Conversion Warnings +.XE +.LP +The +.PN XtDisplayStringConversionWarning +procedure is a convenience routine for resource type converters +that convert from string values. +.LP +.IN "XtDisplayStringConversionWarning" "" "@DEF@" +.sM +.FD 0 +void XtDisplayStringConversionWarning(\fIdisplay\fP, \fIfrom_value\fP, \ +\fIto_type\fP) +.br + Display *\fIdisplay\fP; +.br + String \fIfrom_value\fP, \fIto_type\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display connection with which the conversion is associated. +.IP \fIfrom_value\fP 1i +Specifies the string that could not be converted. +.IP \fIto_type\fP 1i +Specifies the target representation type requested. +.LP +.eM +The +.PN XtDisplayStringConversionWarning +procedure issues a warning message using +.PN XtAppWarningMsg +with \fIname\fP ``conversionError'', +\fItype\fP ``string'', \fIclass\fP ``XtToolkitError'', and the default message +``Cannot convert "\fIfrom_value\fP" to type \fIto_type\fP''. +.LP +To issue other types of warning or error messages, the type converter +should use +.PN XtAppWarningMsg +or +.PN XtAppErrorMsg . +.sp +.LP +To retrieve the application context associated with a given +display connection, use +.PN XtDisplayToApplicationContext . +.LP +.IN "XtDisplayToApplicationContext" "" "@DEF@" +.sM +.FD 0 +XtAppContext XtDisplayToApplicationContext( \fIdisplay\fP ) +.br + Display *\fIdisplay\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies an open and initialized display connection. +.LP +.eM +The +.PN XtDisplayToApplicationContext +function returns the application +context in which the specified \fIdisplay\fP was initialized. If the +display is not known to the \*(xI, an error message is issued. + +.NH 3 +Registering a New Resource Converter +.XS +\fB\*(SN Registering a New Resource Converter\fP +.XE +.LP +When registering a resource converter, the client must specify 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 +.PN XtCacheType +.LP +.IN "XtCacheType" "" "@DEF@" +argument. +.sM +.Ds 0 +typedef int XtCacheType; +.De +.LP +.eM +An +.PN XtCacheType +field may contain one of the following values: +.br +.sp +.LP +.PN XtCacheNone +.IN "XtCacheNone" "" "@DEF@" +.IP +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. +.br +.sp +.LP +.PN XtCacheAll +.IN "XtCacheAll" "" "@DEF@" +.IP +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. +.br +.sp +.LP +.PN XtCacheByDisplay +.IN "XtCacheByDisplay" "" "@DEF@" +.IP +Specifies that the results of a previous conversion +should be used as for +.PN XtCacheAll +but the destructor will be called, if specified, if +.PN XtCloseDisplay +is called +for the display connection associated with the converted value, and +the value will be removed from the conversion cache. +.LP +The qualifier +.PN XtCacheRefCount +.IN "XtCacheRefCount" "" "@DEF@" +may be ORed with any of the above values. If +.PN XtCacheRefCount +is specified, calls to +.PN XtCreateWidget , +.PN XtCreateManagedWidget , +.PN XtGetApplicationResources , +and +.PN XtGetSubresources +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. + +.LP +To register a type converter for all application contexts in a +process, use +.PN XtSetTypeConverter , +and to register a type converter in a single application context, use +.PN XtAppSetTypeConverter . +.LP +.IN "XtSetTypeConverter" "" "@DEF@" +.sM +.FD 0 +void XtSetTypeConverter(\fIfrom_type\fP, \fIto_type\fP, \fIconverter\fP, \ +\fIconvert_args\fP, \fInum_args\fP, + \fIcache_type\fP, \fIdestructor\fP) +.br + String \fIfrom_type\fP; +.br + String \fIto_type\fP; +.br + XtTypeConverter \fIconverter\fP; +.br + XtConvertArgList \fIconvert_args\fP; +.br + Cardinal \fInum_args\fP; +.br + XtCacheType \fIcache_type\fP; +.br + XtDestructor \fIdestructor\fP; +.FN +.IP \fIfrom_type\fP 1i +Specifies the source type. +.IP \fIto_type\fP 1i +Specifies the destination type. +.IP \fIconverter\fP 1i +Specifies the resource type converter procedure. +.IP \fIconvert_args\fP 1i +Specifies additional conversion arguments, or NULL. +.IP \fInum_args\fP 1i +Specifies the number of entries in \fIconvert_args\fP. +.IP \fIcache_type\fP 1i +Specifies whether or not resources produced by this +converter are sharable or display-specific and when +they should be freed. +.IP \fIdestructor\fP 1i +Specifies a destroy procedure for resources produced by +this conversion, or NULL if no additional action is +required to deallocate resources produced by the converter. +.LP +.IN "XtAppSetTypeConverter" "" "@DEF@" +.FD 0 +void XtAppSetTypeConverter(\fIapp_context\fP, \fIfrom_type\fP, \fIto_type\fP, \ +\fIconverter\fP, \fIconvert_args\fP, + \fInum_args\fP, \fIcache_type\fP, \fIdestructor\fP) +.br + XtAppContext \fIapp_context\fP; +.br + String \fIfrom_type\fP; +.br + String \fIto_type\fP; +.br + XtTypeConverter \fIconverter\fP; +.br + XtConvertArgList \fIconvert_args\fP; +.br + Cardinal \fInum_args\fP; +.br + XtCacheType \fIcache_type\fP; +.br + XtDestructor \fIdestructor\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fIfrom_type\fP 1i +Specifies the source type. +.IP \fIto_type\fP 1i +Specifies the destination type. +.IP \fIconverter\fP 1i +Specifies the resource type converter procedure. +.IP \fIconvert_args\fP 1i +Specifies additional conversion arguments, or NULL. +.IP \fInum_args\fP 1i +Specifies the number of entries in \fIconvert_args\fP. +.IP \fIcache_type\fP 1i +Specifies whether or not resources produced by this +converter are sharable or display-specific and when +they should be freed. +.IP \fIdestructor\fP 1i +Specifies a destroy procedure for resources produced by +this conversion, or NULL if no additional action is +required to deallocate resources produced by the converter. +.LP +.eM +.PN XtSetTypeConverter +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. +.PN XtAppSetTypeConverter +registers the specified type converter in the +single application context specified. If the same \fIfrom_type\fP and +\fIto_type\fP are specified in multiple calls to either function, the most +recent overrides the previous ones. +.sp +.LP +For the few type converters that need additional arguments, +the \*(xI conversion mechanism provides a method of specifying +how these arguments should be computed. +The enumerated type +.PN XtAddressMode +and the structure +.PN XtConvertArgRec +specify how each argument is derived. +These are defined in +.Pn < X11/Intrinsic.h >. +.LP +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +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; +.sp +typedef struct { + XtAddressMode address_mode; + XtPointer address_id; + Cardinal size; +} XtConvertArgRec, *XtConvertArgList; +.De +.eM +.LP +The \fIsize\fP field specifies the length of the data in bytes. +The \fIaddress_mode\fP field specifies how the \fIaddress_id\fP field should be +interpreted. +.PN XtAddress +.IN "XtAddress" "" "@DEF@" +causes \fIaddress_id\fP to be interpreted as the address of the data. +.PN XtBaseOffset +.IN "XtBaseOffset" "" "@DEF@" +causes \fIaddress_id\fP to be interpreted as the offset from the widget base. +.PN XtImmediate +.IN "XtImmediate" "" "@DEF@" +causes \fIaddress_id\fP to be interpreted as a constant. +.PN XtResourceString +.IN "XtResourceString" "" "@DEF@" +causes \fIaddress_id\fP to be interpreted as the name of a resource +that is to be converted into an offset from the widget base. +.PN XtResourceQuark +.IN "XtResourceQuark" "" "@DEF@" +causes \fIaddress_id\fP to be interpreted as the result of an +.PN XrmStringToQuark +conversion on the name of a resource, +which is to be converted into an offset from the widget base. +.PN XtWidgetBaseOffset +.IN "XtWidgetBaseOffset" "" "@DEF@" +is similar to +.PN XtBaseOffset +except that it +searches for the closest windowed ancestor if the object is not +of a subclass of +Core +(see Chapter 12). +.PN XtProcedureArg +.IN "XtProcedureArg" "" "@DEF@" +specifies that \fIaddress_id\fP is a pointer to a procedure to +be invoked to return the conversion argument. If +.PN XtProcedureArg +is specified, \fIaddress_id\fP must contain +the address of a function of type +.PN XtConvertArgProc . +.LP +.IN "XtConvertArgProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtConvertArgProc)(Widget, Cardinal*, XrmValue*); +.br + Widget \fIobject\fP; +.br + Cardinal *\fIsize\fP; +.br + XrmValue *\fIvalue\fP; +.FN +.IP \fIobject\fP 1i +Passes the object for which the resource is being +converted, or NULL if the converter was invoked by +.PN XtCallConverter +or +.PN XtDirectConvert . +.IP \fIsize\fP 1i +Passes a pointer to the \fIsize\fP field from the +.PN XtConvertArgRec . +.IP \fIvalue\fP 1i +Passes a pointer to a descriptor into which the procedure +must store the conversion argument. +.LP +.eM +When invoked, the +.PN XtConvertArgProc +procedure must derive a conversion +argument and store the address and size of the argument in the location +pointed to by \fIvalue\fP. +.LP +In order to permit reentrancy, the +.PN XtConvertArgProc +should return the address of storage whose lifetime is no shorter than the +lifetime of \fIobject\fP. If \fIobject\fP is NULL, the lifetime of the conversion +argument must be no shorter than the lifetime of the resource with +which the conversion argument is associated. The \*(xI do not +guarantee to copy this storage but do guarantee not to reference it if +the resource is removed from the conversion cache. +.LP +The following example illustrates how to register the CvtStringToPixel +routine given earlier: +.LP +.Ds +.TA .2i 3i +.ta .2i 3i +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); +.De +.LP +The conversion argument descriptors +.PN colorConvertArgs +and +.PN screenConvertArg +are predefined by the \*(xI. Both take the +values from the closest windowed ancestor if the object is not of a +subclass of +Core. +The +.PN screenConvertArg +descriptor puts the widget's \fIscreen\fP field into \fIargs\fP[0]. The +.PN colorConvertArgs +descriptor puts the widget's \fIscreen\fP field into \fIargs\fP[0], +and the widget's \fIcolormap\fP field into \fIargs\fP[1]. +.LP +Conversion routines should not just put a descriptor for the address of the +base of the widget into \fIargs\fP[0], and use that 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 conversion cache. +This way the cache is smaller and has fewer and more widely applicable entries. +.LP +If any conversion arguments of type +.PN XtBaseOffset , +.PN XtResourceString , +.PN XtResourceQuark , +and +.PN XtWidgetBaseOffset +are specified for conversions performed by +.PN XtGetApplicationResources , +.PN XtGetSubresources , +.PN XtVaGetApplicationResources , +or +.PN XtVaGetSubresources , +the arguments are +computed with respect to the specified widget, not the base address or +resource list specified in the call. +.LP +If the +.PN XtConvertArgProc +modifies the resource database, +the changes affect any in-progress widget creation, +.PN XtGetApplicationResources , +or +.PN XtGetSubresources +in an implementation-defined manner; however, insertion of new entries +or changes to existing entries are allowed and will not directly cause +an error. + +.NH 3 +Resource Converter Invocation +.XS +\fB\*(SN Resource Converter Invocation\fP +.XE +.LP +All resource-fetching routines (for example, +.PN XtGetSubresources , +.PN XtGetApplicationResources , +and so on) call resource converters if the resource database or +varargs list specifies 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 +representation. +.sp +.LP +To invoke explicit resource conversions, use +.PN XtConvertAndStore +or +.PN XtCallConverter . +.LP +.sM +.Ds 0 +typedef XtPointer XtCacheRef; +.De +.IN "XtCallConverter" "" "@DEF@" +.FD 0 +Boolean XtCallConverter(\fIdisplay\fP, \fIconverter\fP, \ +\fIconversion_args\fP, \fInum_args\fP, \fIfrom\fP, \fIto_in_out\fP, + \fIcache_ref_return\fP) +.br + Display* \fIdisplay\fP; +.br + XtTypeConverter \fIconverter\fP; +.br + XrmValuePtr \fIconversion_args\fP; +.br + Cardinal \fInum_args\fP; +.br + XrmValuePtr \fIfrom\fP; +.br + XrmValuePtr \fIto_in_out\fP; +.br + XtCacheRef *\fIcache_ref_return\fP; +.FN +.IP \fIdisplay\fP 1.5i +Specifies the display with which the conversion is to be associated. +.IP \fIconverter\fP 1.5i +Specifies the conversion procedure to be called. +.IP \fIconversion_args\fP 1.5i +Specifies the additional conversion arguments needed +to perform the conversion, or NULL. +.IP \fInum_args\fP 1.5i +Specifies the number of entries in \fIconversion_args\fP. +.IP \fIfrom\fP 1.5i +Specifies a descriptor for the source value. +.IP \fIto_in_out\fP 1.5i +Returns the converted value. +.IP \fIcache_ref_return\fP 1.5i +Returns a conversion cache id. +.LP +.eM +The +.PN XtCallConverter +function looks up the +specified type converter in the application context associated with +the display and, if the converter was not registered or was registered +with cache type +.PN XtCacheAll +or +.PN XtCacheByDisplay , +looks in the conversion cache to see if this conversion procedure +has been called with the specified conversion arguments. If so, it +checks the success status of the prior call, and if +the conversion failed, +.PN XtCallConverter +returns +.PN False +immediately; +otherwise it checks the size specified in the \fIto\fP 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 +\fIto->addr\fP, stores the cache size into \fIto->size\fP, and returns +.PN True . +If the size specified in the \fIto\fP argument is smaller than the size stored +in the cache, +.PN XtCallConverter +copies the cache size into \fIto->size\fP and returns +.PN False . +If the converter was registered with cache type +.PN XtCacheNone +or no value was found in the conversion cache, +.PN XtCallConverter +calls the converter, and if it was not registered with cache type +.PN XtCacheNone , +enters the result in the cache. +.PN XtCallConverter +then returns what the converter returned. +.LP +The \fIcache_ref_return\fP field specifies storage allocated by the caller in which +an opaque value will be stored. If the type converter has been +registered with the +.PN XtCacheRefCount +modifier and if the value returned +in \fIcache_ref_return\fP is non-NULL, then the caller should store the +\fIcache_ref_return\fP value in order to decrement the reference count when +the converted value is no longer required. The \fIcache_ref_return\fP +argument should be +NULL if the caller is unwilling or unable to store the +value. +.sp +.LP +To explicitly decrement the reference counts for resources obtained +from +.PN XtCallConverter , +use +.PN XtAppReleaseCacheRefs . +.LP +.IN "XtAppReleaseCacheRefs" "" "@DEF@" +.sM +.FD 0 +void XtAppReleaseCacheRefs(\fIapp_context\fP, \fIrefs\fP) +.br + XtAppContext \fIapp_context\fP; +.br + XtCacheRef *\fIrefs\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fIrefs\fP 1i +Specifies the list of cache references to be released. +.LP +.eM +.PN XtAppReleaseCacheRefs +decrements the reference count for the +conversion entries identified by the \fIrefs\fP argument. +This argument is a +pointer to a NULL-terminated list of +.PN XtCacheRef +values. If any reference +count reaches zero, the destructor, if any, will be called and +the resource removed from the conversion cache. +.sp +.LP +As a convenience to clients needing to explicitly decrement reference +counts via a callback function, the \*(xI define two callback +procedures, +.PN XtCallbackReleaseCacheRef +and +.PN XtCallbackReleaseCacheRefList . +.LP +.IN "XtCallbackReleaseCacheRef" "" "@DEF@" +.sM +.FD 0 +void XtCallbackReleaseCacheRef(\fIobject\fP, \fIclient_data\fP, \fIcall_data\fP) +.br + Widget \fIobject\fP; +.br + XtPointer \fIclient_data\fP; +.br + XtPointer \fIcall_data\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object with which the resource is associated. +.IP \fIclient_data\fP 1i +Specifies the conversion cache entry to be released. +.IP \fIcall_data\fP 1i +Is ignored. +.LP +.eM +This callback procedure may be added to a callback list to release a +previously returned +.PN XtCacheRef +value. When adding the callback, the +callback \fIclient_data\fP argument must be specified as the value of the +.PN XtCacheRef +data cast to type +.PN XtPointer . +.LP +.IN "XtCallbackReleaseCacheRefList" "" "@DEF@" +.sM +.FD 0 +void XtCallbackReleaseCacheRefList(\fIobject\fP, \fIclient_data\fP, \fIcall_data\fP) +.br + Widget \fIobject\fP; +.br + XtPointer \fIclient_data\fP; +.br + XtPointer \fIcall_data\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object with which the resources are associated. +.IP \fIclient_data\fP 1i +Specifies the conversion cache entries to be released. +.IP \fIcall_data\fP 1i +Is ignored. +.LP +.eM +This callback procedure may be added to a callback list to release a +list of previously returned +.PN XtCacheRef +values. When adding the +callback, the callback \fIclient_data\fP argument must be specified as a +pointer to a NULL-terminated list of +.PN XtCacheRef +values. +.sp +.LP +To lookup and call a resource converter, copy the resulting value, +and free a cached resource when a widget is destroyed, use +.PN XtConvertAndStore . +.LP +.IN "XtConvertAndStore" "" "@DEF@" +.sM +.FD 0 +Boolean XtConvertAndStore(\fIobject\fP, \fIfrom_type\fP, \fIfrom\fP, \ +\fIto_type\fP, \fIto_in_out\fP) +.br + Widget \fIobject\fP; +.br + String \fIfrom_type\fP; +.br + XrmValuePtr \fIfrom\fP; +.br + String \fIto_type\fP; +.br + XrmValuePtr \fIto_in_out\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object to use for additional arguments, if any are needed, +and the destroy callback list. \*(oI +.IP \fIfrom_type\fP 1i +Specifies the source type. +.IP \fIfrom\fP 1i +Specifies the value to be converted. +.IP \fIto_type\fP 1i +Specifies the destination type. +.IP \fIto_in_out\fP 1i +Specifies a descriptor for storage into which the converted value +will be returned. +.LP +.eM +The +.PN XtConvertAndStore +function looks up the type converter registered +to convert \fIfrom_type\fP to \fIto_type\fP, computes any additional arguments +needed, and then calls +.PN XtCallConverter +(or +.PN XtDirectConvert +if an old-style converter was registered with +.PN XtAddConverter +or +.PN XtAppAddConverter ; +see Appendix C) with the \fIfrom\fP and \fIto_in_out\fP arguments. The +\fIto_in_out\fP argument specifies the size and location into which the +converted 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 \fIsize\fP field will be modified on return to indicate the actual +size of the converted data. +If the conversion succeeds, +.PN XtConvertAndStore +returns +.PN True ; +otherwise, it returns +.PN False . +.LP +.PN XtConvertAndStore +adds +.PN XtCallbackReleaseCacheRef +.IN "destroyCallback" +to the destroyCallback list of the specified object if the conversion +returns an +.PN XtCacheRef +value. The resulting resource should not be referenced +after the object has been destroyed. +.LP +.PN XtCreateWidget +performs processing equivalent to +.PN XtConvertAndStore +when initializing the object instance. Because there is extra memory +overhead required to implement reference counting, clients may +distinguish those objects that are never destroyed before the +application exits from those that may be destroyed and whose +resources should be deallocated. +.LP +To specify whether reference counting is to be enabled for the +resources of a particular object when the object is created, the +client can specify a value for the +.PN Boolean +resource +XtNinitialResourcesPersistent, +.IN "XtNinitialResourcesPersistent" "" "@DEF@" +class +XtCInitialResourcesPersistent. +.LP +When +.PN XtCreateWidget +is called, if this resource is not specified as +.PN False +in either the arglist or the resource database, 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 +.PN True ; +thus clients that expect to destroy one or +more objects and want resources deallocated must explicitly specify +.PN False +for +.IN XtNinitialResourcesPersistent +XtNinitialResourcesPersistent. +.LP +The resources are still freed and destructors called when +.PN XtCloseDisplay +is called if the conversion was registered as +.PN XtCacheByDisplay . + +.NH 2 +Reading and Writing Widget State +.XS +\fB\*(SN Reading and Writing Widget State\fP +.XE +.LP +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. + +.NH 3 +Obtaining Widget State +.XS +\fB\*(SN Obtaining Widget State\fP +.XE +.LP +To retrieve the current values of resources associated with a +widget instance, use +.PN XtGetValues . +.LP +.IN "XtGetValues" "" "@DEF@" +.sM +.FD 0 +void XtGetValues(\fIobject\fP, \fIargs\fP, \fInum_args\fP) +.br + Widget \fIobject\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object whose resource values are to be returned. \*(oI +.IP \fIargs\fP 1i +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. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtGetValues +function starts with the resources specified for the Object class +and proceeds down the subclass chain to the class of the object. +The \fIvalue\fP field of a passed argument 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 +\*(xI-defined resources, the following lifetimes apply: +.IP \(bu 3 +Not valid following any operation that modifies the resource: +.RS +.IP \- 3 +XtNchildren resource of composite widgets. +.IP \- 3 +All resources of representation type XtRCallback. +.RE +.IP \(bu 3 +Remain valid at least until the widget is destroyed: +.RS +.IP \- 3 +XtNaccelerators, XtNtranslations. +.RE +.IP \(bu 3 +Remain valid until the Display is closed: +.RS +.IP \- 3 +XtNscreen. +.RE +.LP +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. +.LP +If the class of the object's parent is a subclass of +.PN constraintWidgetClass , +.PN XtGetValues +then fetches the values for any constraint resources requested. +It starts with the constraint resources specified for +.PN constraintWidgetClass +and proceeds down the subclass chain to the parent's constraint resources. +If the argument list contains a resource name that is not found in any of the +resource lists searched, +the value at the corresponding address is not modified. +.IN "get_values_hook procedure" +If any get_values_hook procedures in the +object's class or superclass records are non-NULL, +they are called in superclass-to-subclass order after +all the resource values have been fetched by +.PN XtGetValues . +Finally, if the object's parent is a +subclass of +.PN constraintWidgetClass , +and if any of the parent's class or +superclass records have declared +.PN ConstraintClassExtension +records in +the Constraint class part \fIextension\fP field with a record type of +.PN \s-1NULLQUARK\s+1 , +and if the \fIget_values_hook\fP field in the extension record is non-NULL, +.PN XtGetValues +calls the get_values_hook procedures in superclass-to-subclass order. +This permits a Constraint parent to provide +nonresource data via +.PN XtGetValues . +.LP +Get_values_hook procedures may modify the data stored at the +location addressed by the \fIvalue\fP field, including (but not +limited to) making a copy of data whose resource representation is a +pointer. None of the \*(xI-defined object classes copy +data in this manner. Any operation that modifies the queried +object resource may invalidate the pointed-to data. + +.sp +.LP +To retrieve the current values of resources associated with a widget +instance using varargs lists, use +.PN XtVaGetValues . +.LP +.IN "XtVaGetValues" "" "@DEF@" +.sM +.FD 0 +void XtVaGetValues(\fIobject\fP, ...) +.br + Widget \fIobject\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object whose resource values are to be returned. \*(oI +.IP ... 1i +Specifies the variable argument list for the resources to +be returned. +.LP +.eM +.PN XtVaGetValues +is identical in function to +.PN XtGetValues +with the \fIargs\fP +and \fInum_args\fP 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 +storage is allocated. If +.PN XtVaTypedArg +is specified, the \fItype\fP argument +specifies the representation desired by the caller and \fIthe\fP size argument +specifies the number of bytes allocated to store the result of the +conversion. If the size is insufficient, a warning message is issued +and the list entry is skipped. + +.NH 4 +Widget Subpart Resource Data: The get_values_hook Procedure +.XS +\*(SN Widget Subpart Resource Data: The get_values_hook Procedure +.XE +.LP +Widgets that have subparts can return resource values from them through +.PN XtGetValues +by supplying a get_values_hook procedure. +The get_values_hook procedure pointer is of type +.PN XtArgsProc . +.LP +.IN "get_values_hook procedure" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtArgsProc)(Widget, ArgList, Cardinal*); +.br + Widget \fIw\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal *\fInum_args\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget whose subpart resource values are to be retrieved. +.IP \fIargs\fP 1i +Specifies the argument list that was passed to +.PN XtGetValues +or the transformed varargs list passed to +.PN XtVaGetValues . +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The widget with subpart resources should call +.PN XtGetSubvalues +in the get_values_hook procedure +and pass in its subresource list and the \fIargs\fP and \fInum_args\fP parameters. + +.NH 4 +Widget Subpart State +.XS +\*(SN Widget Subpart State +.XE +.LP +To retrieve the current values of subpart resource data associated with a +widget instance, use +.PN XtGetSubvalues . +For a discussion of subpart resources, +see Section 9.4. +.LP +.IN "XtGetSubvalues" "" "@DEF@" +.sM +.FD 0 +void XtGetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \ +\fIargs\fP, \fInum_args\fP) +.br + XtPointer \fIbase\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIbase\fP 1i +Specifies the base address of the subpart data structure for which the +resources should be retrieved. +.IP \fIresources\fP 1i +Specifies the subpart resource list. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP \fIargs\fP 1i +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. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtGetSubvalues +function obtains resource values from the structure identified by \fIbase\fP. +The \fIvalue\fP field in each argument entry must contain the address into +which to store the corresponding resource value. It is the caller's +responsibility 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 corresponding address is not modified. + +.sp +.LP +To retrieve the current values of subpart resources associated with +a widget instance using varargs lists, use +.PN XtVaGetSubvalues . +.LP +.IN "XtVaGetSubvalues" "" "@DEF@" +.sM +.FD 0 +void XtVaGetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, ...) +.br + XtPointer \fIbase\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.FN +.IP \fIbase\fP 1i +Specifies the base address of the subpart data structure for which the +resources should be retrieved. +.IP \fIresources\fP 1i +Specifies the subpart resource list. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP ... 1i +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. +.LP +.eM +.PN XtVaGetSubvalues +is identical in function to +.PN XtGetSubvalues +with the +\fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as described +in Section 2.5.1. +.PN XtVaTypedArg +is not supported for +.PN XtVaGetSubvalues . +If +.PN XtVaTypedArg +is specified in the list, a warning message is issued +and the entry is then ignored. + +.NH 3 +Setting Widget State +.XS +\fB\*(SN Setting Widget State\fP +.XE +.LP +To modify the current values of resources associated with a widget +instance, use +.PN XtSetValues . +.LP +.IN "XtSetValues" "" "@DEF@" +.sM +.FD 0 +void XtSetValues(\fIobject\fP, \fIargs\fP, \fInum_args\fP) +.br + Widget \fIobject\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object whose resources are to be modified. \*(oI +.IP \fIargs\fP 1i +Specifies the argument list of name/value pairs that contain the +resources to be modified and their new values. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtSetValues +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 \fIobject\fP resource fields with any values +specified in the argument list. +.PN XtSetValues +then calls the set_values procedures for the object in superclass-to-subclass +order. +.IN "set_values_hook procedure" +If the object has any non-NULL \fIset_values_hook\fP fields, +these are called immediately after the +corresponding set_values procedure. +This procedure permits subclasses to set subpart data via +.PN XtSetValues . +.LP +If the class of the object's parent is a subclass of +.PN constraintWidgetClass , +.PN XtSetValues +also updates the object's constraints. +It starts with the constraint resources specified for +.PN constraintWidgetClass +and proceeds down the subclass 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 constraint set_values procedures from +.PN constraintWidgetClass +down to the parent's class. +The constraint set_values procedures 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 specified that +do not match a resource list entry are silently ignored. +.LP +If the object is of a subclass of +RectObj, +.PN XtSetValues +determines if a geometry request is needed by comparing the old object to +the new object. +If any geometry changes are required, +.PN XtSetValues +restores the original geometry and makes the request on behalf of the widget. +If the geometry manager returns +.PN XtGeometryYes , +.PN XtSetValues +calls the object's resize procedure. +If the geometry manager returns +.PN XtGeometryDone , +.PN XtSetValues +continues, as the object's resize procedure should have been called +by the geometry manager. +If the geometry manager returns +.PN XtGeometryNo , +.PN XtSetValues +ignores the geometry request and continues. +If the geometry manager returns +.PN XtGeometryAlmost , +.PN XtSetValues +calls the set_values_almost procedure, +which determines what should be done. +.PN XtSetValues +then repeats this process, +deciding once more whether the geometry manager should be called. +.LP +Finally, if any of the set_values procedures returned +.PN True , +and the widget is realized, +.PN XtSetValues +causes the widget's expose procedure to be invoked by calling +.PN XClearArea +on the widget's window. +.sp +.LP +To modify the current values of resources associated with a widget +instance using varargs lists, use +.PN XtVaSetValues . +.LP +.IN "XtVaSetValues" "" "@DEF@" +.sM +.FD 0 +void XtVaSetValues(\fIobject\fP, ...) +.br + Widget \fIobject\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object whose resources are to be modified. \*(oI +.IP ... 1i +Specifies the variable argument list of name/value pairs that +contain the resources to be modified and their new values. +.LP +.eM +.PN XtVaSetValues +is identical in function to +.PN XtSetValues +with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as +described in Section 2.5.1. + +.NH 4 +Widget State: The set_values Procedure +.XS +\*(SN Widget State: The set_values Procedure +.XE +.LP +The set_values procedure pointer in a widget class is of type +.PN XtSetValuesFunc . +.LP +.IN "XtSetValuesFunc" "" "@DEF@" +.IN "set_values procedure" "" "@DEF@" +.sM +.FD 0 +typedef Boolean (*XtSetValuesFunc)(Widget, Widget, Widget, ArgList, Cardinal*); +.br + Widget \fIcurrent\fP; +.br + Widget \fIrequest\fP; +.br + Widget \fInew\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal *\fInum_args\fP; +.FN +.IP \fIcurrent\fP 1i +Specifies a copy of the widget as it was before the +.PN XtSetValues +call. +.IP \fIrequest\fP 1i +Specifies a copy of the widget with all values changed as asked for by the +.PN XtSetValues +call before any class set_values procedures have been called. +.IP \fInew\fP 1i +Specifies the widget with the new values that are actually allowed. +.IP \fIargs\fP 1i +Specifies the argument list passed to +.PN XtSetValues +or the transformed argument list passed to +.PN XtVaSetValues . +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +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 recomputation 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 \fIset_values\fP field in the class record. +.LP +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. +.LP +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. +.LP +As an example, +a subclass can visually surround its superclass display. +In this case, the width and height calculated 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 calculated by the +superclass or was specified explicitly. +All widgets must place themselves into whatever size is explicitly given, +but they should compute a reasonable size if no size is requested. +How does a subclass know the difference between a specified size +and a size computed by a superclass? +.LP +The \fIrequest\fP and \fInew\fP parameters provide the necessary information. +The \fIrequest\fP widget is a copy of the widget, updated as originally requested. +The \fInew\fP 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 \fIrequest\fP widget +unless it must resolve conflicts between the \fIcurrent\fP and \fInew\fP widgets. +Any changes the widget needs to make, including geometry changes, +should be made in the \fInew\fP widget. +.LP +In the above example, +the subclass with the visual surround can see +if the \fIwidth\fP and \fIheight\fP in the \fIrequest\fP widget are zero. +If so, +it adds its surround size to the \fIwidth\fP and +\fIheight\fP fields in the \fInew\fP 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. +.LP +The \fInew\fP widget is the actual widget instance record. +Therefore, +the set_values procedure should do all its work on the \fInew\fP widget; +the \fIrequest\fP widget should never be modified. +If the set_values procedure needs to call any routines that operate on +a widget, it should specify \fInew\fP as the widget instance. +.LP +Before calling the set_values procedures, the \*(xI modify the +resources of the \fIrequest\fP 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 \fIargs\fP. +.LP +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 +.PN True ; +the X server will eventually generate an +.PN Expose +event, if necessary. +After calling all the set_values procedures, +.PN XtSetValues +forces a redisplay by calling +.PN XClearArea +if any of the set_values procedures returned +.PN True . +Therefore, a set_values procedure should not try to do its own redisplaying. +.LP +Set_values procedures should not do any work in response to changes in +geometry because +.PN XtSetValues +eventually will perform a geometry request, and that request might be denied. +If the widget actually changes size in response to a +call to +.PN XtSetValues , +its resize procedure is called. +Widgets should do any geometry-related work in their resize procedure. +.LP +Note that it is permissible to call +.PN XtSetValues +before a widget is realized. +Therefore, the set_values procedure must not assume that the widget is realized. + +.NH 4 +Widget State: The set_values_almost Procedure +.XS +\*(SN Widget State: The set_values_almost Procedure +.XE +.LP +The set_values_almost procedure pointer in the widget class record is of type +.PN XtAlmostProc . +.LP +.IN "set_values_almost procedure" "" "@DEF@" +.IN "XtAlmostProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtAlmostProc)(Widget, Widget, XtWidgetGeometry*, \ +XtWidgetGeometry*); +.br + Widget \fIold\fP; +.br + Widget \fInew\fP; +.br + XtWidgetGeometry *\fIrequest\fP; +.br + XtWidgetGeometry *\fIreply\fP; +.FN +.IP \fIold\fP 1i +Specifies a copy of the object as it was before the +.PN XtSetValues +call. +.IP \fInew\fP 1i +Specifies the object instance record. +.IP \fIrequest\fP 1i +Specifies the original geometry request that was sent to the geometry +manager that caused +.PN XtGeometryAlmost +to be returned. +.IP \fIreply\fP 1i +Specifies the compromise geometry that was returned by the geometry +manager with +.PN XtGeometryAlmost . +.LP +.eM +Most classes inherit the set_values_almost procedure from their superclass by +specifying +.PN XtInheritSetValuesAlmost +in the class initialization. +The +set_values_almost procedure in +.PN rectObjClass +accepts the compromise suggested. +.LP +The set_values_almost procedure is called when a client tries to set a widget's +geometry by means of a call to +.PN XtSetValues +and the geometry manager cannot +satisfy the request but instead returns +.PN XtGeometryNo +or +.PN XtGeometryAlmost +and a compromise geometry. +The \fInew\fP object is the actual instance record. The \fIx\fP, \fIy\fP, +\fIwidth\fP, \fIheight\fP, +and \fIborder_width\fP fields contain the original values as they were +before the +.PN XtSetValues +call, and all other fields contain the new +values. The \fIrequest\fP parameter contains the new geometry request that +was made to the parent. The \fIreply\fP parameter contains +\fIreply->request_mode\fP equal to zero if the parent returned +.PN XtGeometryNo +and contains the parent's compromise geometry otherwise. The +set_values_almost procedure takes the original geometry and the +compromise geometry and determines if the compromise is +acceptable or whether +to try a different compromise. +It returns its results in the \fIrequest\fP 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 \fIreply\fP geometry into the \fIrequest\fP geometry; to attempt an +alternative geometry, the procedure may modify any part of the \fIrequest\fP +argument; to terminate the geometry negotiation and retain the +original geometry, the procedure must set \fIrequest->request_mode\fP to +zero. The geometry fields of the \fIold\fP and \fInew\fP instances must not be modified +directly. + +.NH 4 +Widget State: The ConstraintClassPart set_values Procedure +.XS +\*(SN Widget State: The ConstraintClassPart set_values Procedure +.XE +.IN "set_values procedure" +.LP +The constraint set_values procedure pointer is of type +.PN XtSetValuesFunc . +The values passed to the parent's constraint set_values procedure +are the same as those passed to the child's class +set_values procedure. +A class can specify NULL for the \fIset_values\fP field of the +.PN ConstraintPart +if it need not compute anything. +.LP +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 \fIheight\fP field in the +widget. + +.NH 4 +Widget Subpart State +.XS +\*(SN Widget Subpart State +.XE +.LP +To set the current values of subpart resources associated with a +widget instance, use +.PN XtSetSubvalues . +For a discussion of subpart resources, +see Section 9.4. +.LP +.IN "XtSetSubvalues" "" "@DEF@" +.sM +.FD 0 +void XtSetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \ +\fIargs\fP, \fInum_args\fP) +.br + XtPointer \fIbase\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIbase\fP 1i +Specifies the base address of the subpart data structure into which the +resources should be written. +.IP \fIresources\fP 1i +Specifies the subpart resource list. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP \fIargs\fP 1i +Specifies the argument list of name/value pairs that contain the +resources to be modified and their new values. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtSetSubvalues +function updates the resource fields of the structure identified by +\fIbase\fP. Any specified arguments that do not match an entry in the +resource list are silently ignored. +.sp +.LP +To set the current values of subpart resources associated with +a widget instance using varargs lists, use +.PN XtVaSetSubvalues . +.LP +.IN "XtVaSetSubvalues" "" "@DEF@" +.sM +.FD 0 +void XtVaSetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, ...) +.br + XtPointer \fIbase\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.FN +.IP \fIbase\fP 1i +Specifies the base address of the subpart data structure into which the +resources should be written. +.IP \fIresources\fP 1i +Specifies the subpart resource list. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP ... 1i +Specifies the variable argument list of name/value pairs that +contain the resources to be modified and their new values. +.LP +.eM +.PN XtVaSetSubvalues +is identical in function to +.PN XtSetSubvalues +with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as +described in Section 2.5.1. +.PN XtVaTypedArg +is not supported for +.PN XtVaSetSubvalues . +If an entry containing +.PN XtVaTypedArg +is specified in the list, a warning message is issued +and the entry is ignored. + +.NH 4 +Widget Subpart Resource Data: The set_values_hook Procedure +.XS +\*(SN Widget Subpart Resource Data: The set_values_hook Procedure +.XE +.IN "set_values_hook procedure" +.NT +The set_values_hook procedure is obsolete, as the same information +is now available to the set_values procedure. The procedure has been +retained for those widgets that used it in versions prior to Release 4. +.NE +.LP +Widgets that have a subpart can set the subpart resource values through +.PN XtSetValues +by supplying a set_values_hook procedure. +The set_values_hook procedure pointer in a widget class is of type +.PN XtArgsFunc . +.LP +.IN "set_values_hook procedure" "" "@DEF@" +.IN "XtArgsFunc" "" "@DEF@" +.sM +.FD 0 +typedef Boolean (*XtArgsFunc)(Widget, Arglist, Cardinal*); +.br + Widget \fIw\fP; +.br + Arglist \fIargs\fP; +.br + Cardinal *\fInum_args\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget whose subpart resource values are to be changed. +.IP \fIargs\fP 1i +Specifies the argument list that was passed to +.PN XtSetValues +or the transformed varargs list passed to +.PN XtVaSetValues . +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The widget with subpart resources may call +.PN XtSetValues +from the set_values_hook procedure +and pass in its subresource list and the +\fIargs\fP and \fInum_args\fP parameters. +.bp diff --git a/specs/CH10 b/specs/CH10 new file mode 100644 index 0000000..b7c0139 --- /dev/null +++ b/specs/CH10 @@ -0,0 +1,1521 @@ +.\" $Xorg: CH10,v 1.3 2000/08/17 19:42:46 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 10\fP\s-1 + +\s+1\fBTranslation Management\s-1 +.sp 2 +.nr H1 10 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 10 \(em Translation Management +.XE +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. +.LP +The translation manager provides an interface to specify and manage the +mapping of X event sequences into widget-supplied functionality, +for example, calling procedure \fIAbc\fP when the \fIy\fP key +is pressed. +.LP +The translation manager uses two kinds of tables to perform translations: +.IP \(bu 5 +The action tables, which are in the widget class structure, +specify the mapping of externally available procedure name strings +to the corresponding procedure implemented by the widget class. +.IP \(bu 5 +A translation table, which is in the widget class structure, +specifies the mapping of event sequences to procedure name strings. +.LP +You can override the translation table in the class structure +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. + +.NH 2 +Action Tables +.XS +\fB\*(SN Action Tables\fP +.XE +.LP +All widget class records contain an action table, +an array of +.PN XtActionsRec +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 +.PN XtActionProc . +.LP +.IN "action_proc procedure" "" "@DEF@" +.IN "XtActionProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtActionProc)(Widget, XEvent*, String*, Cardinal*); +.br + Widget \fIw\fP; +.br + XEvent *\fIevent\fP; +.br + String *\fIparams\fP; +.br + Cardinal *\fInum_params\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget that caused the action to be called. +.IP \fIevent\fP 1i +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. +.IP \fIparams\fP 1i +Specifies a pointer to the list of strings that were specified +in the translation table as arguments to the action, or NULL. +.IP \fInum_params\fP 1i +Specifies the number of entries in \fIparams\fP. +.IN "XtActionsRec" +.IN "XtActionList" +.LP +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _XtActionsRec { + String string; + XtActionProc proc; +} XtActionsRec, *XtActionList; +.De +.LP +.eM +The \fIstring\fP field is the name used in translation tables to access +the procedure. +The \fIproc\fP field is a pointer to a procedure that implements +the functionality. +.LP +When the action list is specified as the +.PN CoreClassPart +\fIactions\fP field, the string pointed to by \fIstring\fP must be +permanently allocated prior to or during the execution of the class +initialization procedure and must not be subsequently deallocated. +.LP +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. +.LP +For example, a Pushbutton widget has procedures to take the following actions: +.IP \(bu 5 +Set the button to indicate it is activated. +.IP \(bu 5 +Unset the button back to its normal mode. +.IP \(bu 5 +Highlight the button borders. +.IP \(bu 5 +Unhighlight the button borders. +.IP \(bu 5 +Notify any callbacks that the button has been activated. +.LP +The action table for the Pushbutton widget class makes these functions +available to translation tables written for Pushbutton 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: +.LP +.IN "Action Table" +.Ds +.TA .5i 1.5i +.ta .5i 1.5i +XtActionsRec actionTable[] = { + {"Set", Set}, + {"Unset", Unset}, + {"Highlight", Highlight}, + {"Unhighlight", Unhighlight} + {"Notify", Notify}, +}; +.De +.LP +The \*(xI 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 \*(xI functions. + +.NH 3 +Action Table Registration +.XS +\fB\*(SN Action Table Registration\fP +.XE +.LP +.IN "actions" +The \fIactions\fP and \fInum_actions\fP fields of +.PN CoreClassPart +specify the actions implemented by a widget class. These are +automatically registered with the \*(xI 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 \*(xI may overwrite the storage in order to compile the +list into an internal representation. +.sp +.LP +To declare an action table within an application +and register it with the translation manager, use +.PN XtAppAddActions . +.LP +.IN "XtAppAddActions" "" "@DEF@" +.sM +.FD 0 +void XtAppAddActions(\fIapp_context\fP, \fIactions\fP, \fInum_actions\fP) +.br + XtAppContext \fIapp_context\fP; +.br + XtActionList \fIactions\fP; +.br + Cardinal \fInum_actions\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fIactions\fP 1i +Specifies the action table to register. +.IP \fInum_actions\fP 1i +Specifies the number of entries in this action table. +.LP +.eM +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 \*(xI register an action table containing +.PN XtMenuPopup +and +.PN XtMenuPopdown +as part of +.PN XtCreateApplicationContext . + +.NH 3 +Action Names to Procedure Translations +.XS +\fB\*(SN Action Names to Procedure Translations\fP +.XE +.LP +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 +performs a search for the name in the following tables, in order: +.IP \(bu 5 +The widget's class and all superclass action tables, in subclass-to-superclass +order. +.IP \(bu 5 +The parent's class and all superclass action tables, in subclass-to-superclass +order, then on up the ancestor tree. +.IP \(bu 5 +The action tables registered with +.PN XtAppAddActions +and +.PN XtAddActions +from the most recently added table to the oldest table. +.LP +As soon as it finds a name, +the translation manager stops the search. +If it cannot find a name, +the translation manager generates a warning message. + +.NH 3 +Action Hook Registration +.XS +\fB\*(SN Action Hook Registration\fP +.XE +.LP +An application can specify a procedure that will be called just before +every action routine is dispatched by the translation manager. To do +so, the application supplies a procedure pointer of type +.PN XtActionHookProc . +.LP +.IN "XtActionHookProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtActionHookProc)(Widget, XtPointer, String, XEvent*, \ +String*, Cardinal*); +.br + Widget \fIw\fP; +.br + XtPointer \fIclient_data\fP; +.br + String \fIaction_name\fP; +.br + XEvent* \fIevent\fP; +.br + String* \fIparams\fP; +.br + Cardinal* \fInum_params\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget whose action is about to be dispatched. +.IP \fIclient_data\fP 1i +Specifies the application-specific closure that was passed to +.PN XtAppAddActionHook. +.IP \fIaction_name\fP 1i +Specifies the name of the action to be dispatched. +.IP \fIevent\fP 1i +Specifies the event argument that will be passed to the action routine. +.IP \fIparams\fP 1i +Specifies the action parameters that will be passed to the action routine. +.IP \fInum_params\fP 1i +Specifies the number of entries in \fIparams\fP. +.LP +.eM +Action hooks should not modify any of the data pointed to by the +arguments other than the \fIclient_data\fP argument. +.sp +.LP +To add an action hook, use +.PN XtAppAddActionHook . +.LP +.IN "XtAppAddActionHook" "" "@DEF@" +.sM +.FD 0 +XtActionHookId XtAppAddActionHook(\fIapp\fP, \fIproc\fP, \fIclient_data\fP) +.br + XtAppContext \fIapp\fP; +.br + XtActionHookProc \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIapp\fP 1i +Specifies the application context. +.IP \fIproc\fP 1i +Specifies the action hook procedure. +.IP \fIclient_data\fP 1i +Specifies application-specific data to be passed to the action hook. +.LP +.eM +.PN XtAppAddActionHook +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 +.PN XtCallActionProc , +the action hook procedures will be called in reverse +order of registration just prior to invoking the action routine. +.LP +Action hook procedures are removed automatically and the +.PN XtActionHookId is +destroyed when the application context in which +they were added is destroyed. +.sp +.LP +To remove an action hook procedure without destroying the application +context, use +.PN XtRemoveActionHook . +.LP +.IN "XtRemoveActionHook" "" "@DEF@" +.sM +.FD 0 +void XtRemoveActionHook(\fIid\fP) +.br + XtActionHookId \fIid\fP; +.FN +.IP \fIid\fP 1i +Specifies the action hook id returned by +.PN XtAppAddActionHook . +.LP +.eM +.PN XtRemoveActionHook +removes the specified action hook procedure from +the list in which it was registered. + +.NH 2 +Translation Tables +.XS +\fB\*(SN Translation Tables\fP +.XE +.LP +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 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. +.LP +As an example, the default behavior of Pushbutton is +.IP \(bu 5 +Highlight on enter window. +.IP \(bu 5 +Unhighlight on exit window. +.IP \(bu 5 +Invert on left button down. +.IP \(bu 5 +Call callbacks and reinvert on left button up. +.LP +The following illustrates Pushbutton's default translation table: +.LP +.IN "Translation tables" +.Ds +.TA .5i 1.5i +.ta .5i 1.5i +static String defaultTranslations = + "<EnterWindow>: Highlight()\\n\\ + <LeaveWindow>: Unhighlight()\\n\\ + <Btn1Down>: Set()\\n\\ + <Btn1Up>: Notify() Unset()"; +.De +.LP +The \fItm_table\fP field of the +.PN CoreClassPart +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 +.PN XtInheritTranslations +into \fItm_table\fP. +In Core's class part initialization procedure, +the \*(xI compile this translation table into an efficient internal form. +Then, at widget creation time, +this default translation table is +combined with the XtNtranslations +and XtNbaseTranslations resources; see Section 10.3. +.LP +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 +.PN XtParseTranslationTable . +.LP +The \*(xI use the compiled form of the translation table to register the +necessary events with the event manager. +Widgets need do nothing other than specify the action and translation tables +for events to be processed by the translation manager. + +.NH 3 +Event Sequences +.XS +\fB\*(SN Event Sequences\fP +.XE +.LP +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 description consists of three parts: +The X event type, a prefix consisting of the X modifier bits, and +an event-specific suffix. +.LP +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. + +.NH 3 +Action Sequences +.XS +\fB\*(SN Action Sequences\fP +.XE +.LP +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 specifications. +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. + +.NH 3 +Multi-Click Time +.XS +\fB\*(SN Multi-Click Time\fP +.XE +.LP +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 +.IN "multiClickTime" "" "@DEF@" +.IN "Resources" "multiClickTime" +class ``MultiClickTime'' and may also be modified dynamically by the +application. The multi-click time is unique for each Display value and +is retrieved from the resource database by +.PN XtDisplayInitialize . +If no value is specified, the initial value is 200 milliseconds. +.sp +.LP +To set the multi-click time dynamically, use +.PN XtSetMultiClickTime . +.LP +.IN "XtSetMultiClickTime" "" "@DEF@" +.sM +.FD 0 +void XtSetMultiClickTime(\fIdisplay\fP, \fItime\fP) +.br + Display *\fIdisplay\fP; +.br + int \fItime\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display connection. +.IP \fItime\fP 1i +Specifies the multi-click time in milliseconds. +.LP +.eM +.PN XtSetMultiClickTime +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 specified in a translation +entry, the interval between the timestamps in each pair of repeated +events (e.g., between two +.PN ButtonPress +events) must be less than the +multi-click time in order for the translation actions to be taken. +.sp +.LP +To read the multi-click time, use +.PN XtGetMultiClickTime . +.LP +.IN "XtGetMultiClickTime" "" "@DEF@" +.sM +.FD 0 +int XtGetMultiClickTime(\fIdisplay\fP) +.br + Display *\fIdisplay\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display connection. +.LP +.eM +.PN XtGetMultiClickTime +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. + +.NH 2 +Translation Table Management +.XS +\fB\*(SN Translation Table Management\fP +.XE +.LP +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. +.LP +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. +.LP +Three \*(xI functions support this merging: +.TS +lw(2i) lw(3.75i). +T{ +.PN XtParseTranslationTable +T} T{ +Compiles a translation table. +T} +.sp +T{ +.PN XtAugmentTranslations +T} T{ +Merges a compiled translation table into a widget's +compiled translation table, ignoring any new translations that +conflict with existing translations. +T} +.sp +T{ +.PN XtOverrideTranslations +T} T{ +Merges a compiled translation table into a widget's +compiled translation table, replacing any existing translations that +conflict with new translations. +T} +.TE +.sp +.LP +To compile a translation table, use +.PN XtParseTranslationTable . +.LP +.IN "XtParseTranslationTable" "" "@DEF@" +.sM +.FD 0 +XtTranslations XtParseTranslationTable(\fItable\fP) +.br + String \fItable\fP; +.FN +.IP \fItable\fP 1i +Specifies the translation table to compile. +.LP +.eM +The +.PN XtParseTranslationTable +function compiles the translation table, provided in the format given +in Appendix B, into an opaque internal representation +of type +.PN XtTranslations . +Note that if an empty translation table is required for any purpose, +one can be obtained by calling +.PN XtParseTranslationTable +and passing an empty string. +.sp +.LP +To merge additional translations into an existing translation table, use +.PN XtAugmentTranslations . +.LP +.IN "XtAugmentTranslations" "" "@DEF@" +.sM +.FD 0 +void XtAugmentTranslations(\fIw\fP, \fItranslations\fP) +.br + Widget \fIw\fP; +.br + XtTranslations \fItranslations\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget into which the new translations are to be merged. \*(cI +.IP \fItranslations\fP 1i +Specifies the compiled translation table to merge in. +.LP +.eM +The +.PN XtAugmentTranslations +function merges the new translations into the existing widget +translations, ignoring any +.PN #replace , +.PN #augment , +or +.PN #override +directive that may have been specified +in the translation string. The translation table specified by +\fItranslations\fP is not altered by this process. +.PN XtAugmentTranslations +logically appends the string representation of the new translations to +the string representation of the widget's current 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 translations, +the new translation is ignored. +.sp +.LP +To overwrite existing translations with new translations, use +.PN XtOverrideTranslations . +.LP +.IN "XtOverrideTranslations" "" "@DEF@" +.sM +.FD 0 +void XtOverrideTranslations(\fIw\fP, \fItranslations\fP) +.br + Widget \fIw\fP; +.br + XtTranslations \fItranslations\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget into which the new translations are to be merged. \*(cI +.IP \fItranslations\fP 1i +Specifies the compiled translation table to merge in. +.LP +.eM +The +.PN XtOverrideTranslations +function merges the new translations into the existing widget +translations, ignoring any +.PN #replace , +.PN #augment , +or +.PN #override +directive that may have been +specified in the translation string. The translation table +specified by \fItranslations\fP is not altered by this process. +.PN XtOverrideTranslations +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 translations, +the new translation overrides the widget's translation. +.LP +To replace a widget's translations completely, use +.PN XtSetValues +on the XtNtranslations resource and specify a compiled translation table +as the value. +.sp +.LP +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 table +followed by one of the keywords ``replace'', ``augment'', or +``override'' to indicate +whether to replace, augment, or override the existing table. +The replace or merge +operation is performed during the +Core +instance initialization. +Each merge operation produces a new +translation resource value; if the original tables were shared by +other widgets, they are unaffected. If no directive is +specified, ``#replace'' is assumed. +.LP +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 \fItranslations\fP 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 \fItranslations\fP 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. +.sp +.LP +To completely remove existing translations, use +.PN XtUninstallTranslations . +.LP +.IN "XtUninstallTranslations" "" "@DEF@" +.sM +.FD 0 +void XtUninstallTranslations(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget from which the translations are to be removed. \*(cI +.LP +.eM +The +.PN XtUninstallTranslations +function causes the entire translation table for the widget to be removed. + +.NH 2 +Using Accelerators +.XS +\fB\*(SN Using Accelerators\fP +.XE +.LP +It is often desirable to be able to bind events in one widget to actions in +another. +In particular, +it is often useful to be able to invoke menu actions from the keyboard. +The \*(xI provide a facility, called accelerators, that lets you +accomplish this. +.IN "Accelerator" "" "@DEF@" +An accelerator table is a translation table that is bound with its +actions in the context of a particular widget, the \fIsource\fP widget. +The accelerator table can then be installed on one or more \fIdestination\fP widgets. +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 accelerator source +widget. The event is +passed to the action 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 reference +to the source widget's window if the widget is realized. +.LP +Each widget instance contains that widget's exported accelerator 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 +.PN XtStringProc . +.LP +.IN "display_accelerator procedure" "" "@DEF@" +.IN "XtStringProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtStringProc)(Widget, String); +.br + Widget \fIw\fP; +.br + String \fIstring\fP; +.FN +.IP \fIw\fP 1i +Specifies the source widget that supplied the accelerators. +.IP \fIstring\fP 1i +Specifies the string representation of the accelerators for this widget. +.LP +.eM +Accelerators can be specified in resource files, +and the string representation is the same as for a translation table. +However, +the interpretation of the +.PN #augment +and +.PN #override +directives applies to +what will happen when the accelerator is installed; +that is, whether or not the accelerator translations will override the +translations in the destination widget. +The default is +.PN #augment , +which means that the accelerator translations have lower priority +than the destination translations. +The +.PN #replace +directive is ignored for accelerator tables. +.sp +.LP +To parse an accelerator table, use +.PN XtParseAcceleratorTable . +.LP +.IN "XtParseAcceleratorTable" "" "@DEF@" +.sM +.FD 0 +XtAccelerators XtParseAcceleratorTable(\fIsource\fP) +.br + String \fIsource\fP; +.FN +.IP \fIsource\fP 1i +Specifies the accelerator table to compile. +.LP +.eM +The +.PN XtParseAcceleratorTable +function compiles the accelerator table into an opaque internal representation. +The client +should set the XtNaccelerators resource of +each widget that is to be activated by these translations +to the returned value. +.sp +.LP +To install accelerators from a widget on another widget, use +.PN XtInstallAccelerators . +.LP +.IN "XtInstallAccelerators" "" "@DEF@" +.sM +.FD 0 +void XtInstallAccelerators(\fIdestination\fP, \fIsource\fP) +.br + Widget \fIdestination\fP; +.br + Widget \fIsource\fP; +.FN +.IP \fIdestination\fP 1i +Specifies the widget on which the accelerators are to be installed. \*(cI +.IP \fIsource\fP 1i +Specifies the widget from which the accelerators are to come. \*(cI +.LP +.eM +The +.PN XtInstallAccelerators +function installs the \fIaccelerators\fP resource value from +\fIsource\fP onto \fIdestination\fP +by merging the source accelerators into the destination translations. +If the source \fIdisplay_accelerator\fP field is non-NULL, +.PN XtInstallAccelerators +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. +.sp +.LP +As a convenience for installing all accelerators from a widget and all its +descendants onto one destination, use +.PN XtInstallAllAccelerators . +.LP +.IN "XtInstallAllAccelerators" "" "@DEF@" +.sM +.FD 0 +void XtInstallAllAccelerators(\fIdestination\fP, \fIsource\fP) +.br + Widget \fIdestination\fP; +.br + Widget \fIsource\fP; +.FN +.IP \fIdestination\fP 1i +Specifies the widget on which the accelerators are to be installed. \*(cI +.IP \fIsource\fP 1i +Specifies the root widget of the widget tree +from which the accelerators are to come. \*(cI +.LP +.eM +The +.PN XtInstallAllAccelerators +function recursively descends the widget tree rooted at \fIsource\fP +and installs the accelerators resource value +of each widget encountered onto \fIdestination\fP. +A common use is to call +.PN XtInstallAllAccelerators +and pass the application main window as the source. + +.NH 2 +KeyCode-to-KeySym Conversions +.XS +\*(SN KeyCode-to-KeySym Conversions +.XE +.LP +The translation manager provides support for automatically translating +KeyCodes in incoming key events into KeySyms. +KeyCode-to-KeySym translator procedure pointers are of type +.PN XtKeyProc . +.LP +.IN "XtKeyProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtKeyProc)(Display*, KeyCode, Modifiers, Modifiers*, \ +KeySym*); +.br + Display *\fIdisplay\fP; +.br + KeyCode \fIkeycode\fP; +.br + Modifiers \fImodifiers\fP; +.br + Modifiers *\fImodifiers_return\fP; +.br + KeySym *\fIkeysym_return\fP; +.FN +.IP \fIdisplay\fP 1.1i +Specifies the display that the KeyCode is from. +.IP \fIkeycode\fP 1.1i +Specifies the KeyCode to translate. +.IP \fImodifiers\fP 1.1i +Specifies the modifiers to the KeyCode. +.IP \fImodifiers_return\fP 1.1i +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 specified keycode. +.IP \fIkeysym_return\fP 1.1i +Specifies a location in which to store the resulting KeySym. +.LP +.eM +This procedure takes a KeyCode and modifiers and produces a KeySym. +For any given key translator function and keyboard encoding, +\fImodifiers_return\fP will be a constant per KeyCode that indicates +the subset of all modifiers that are examined by the key translator +for that KeyCode. +.LP +The KeyCode-to-KeySym translator procedure +must be implemented such that multiple calls with the same +\fIdisplay\fP, \fIkeycode\fP, and \fImodifiers\fP return the same +result until either a new case converter, an +.PN XtCaseProc , +is installed or a +.PN MappingNotify +event is received. + +.sp +.LP +The \*(xI 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 perform the same mapping. +.LP +To return a pointer to the KeySym-to-KeyCode mapping table for a +particular display, use +.PN XtGetKeysymTable . +.LP +.IN "XtGetKeysymTable" "" "@DEF@" +.sM +.FD 0 +KeySym *XtGetKeysymTable(\fIdisplay\fP, \fImin_keycode_return\fP, \ +\fIkeysyms_per_keycode_return\fP) +.br + Display *\fIdisplay\fP; +.br + KeyCode *\fImin_keycode_return\fP; +.br + int *\fIkeysyms_per_keycode_return\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display whose table is required. +.IP \fImin_keycode_return\fP 1i +Returns the minimum KeyCode valid for the display. +.IP \fIkeysyms_per_keycode_return\fP 1i +Returns the number of KeySyms stored for each KeyCode. +.LP +.eM +.PN XtGetKeysymTable +returns a pointer to the \*(xI' copy of the +server's KeyCode-to-KeySym table. This table must not be modified. +There are \fIkeysyms_per_keycode_return\fP KeySyms associated with each +KeyCode, located in the table with indices starting at index +.IP + (test_keycode - min_keycode_return) * keysyms_per_keycode_return +.LP +for KeyCode \fItest_keycode\fP. Any entries that have no KeySyms associated +with them contain the value +.PN NoSymbol . +Clients should not cache the KeySym table but should call +.PN XtGetKeysymTable +each time the value is +needed, as the table may change prior to dispatching each event. +.LP +For more information on this table, see Section 12.7 in \fI\*(xL\fP. +.sp +.LP +To register a key translator, use +.PN XtSetKeyTranslator . +.LP +.IN "XtSetKeyTranslator" "" "@DEF@" +.sM +.FD 0 +void XtSetKeyTranslator(\fIdisplay\fP, \fIproc\fP) +.br + Display *\fIdisplay\fP; +.br + XtKeyProc \fIproc\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display from which to translate the events. +.IP \fIproc\fP 1i +Specifies the procedure to perform key translations. +.LP +.eM +The +.PN XtSetKeyTranslator +function sets the specified procedure as the current key translator. +The default translator is +.PN XtTranslateKey , +an +.PN XtKeyProc +that uses the Shift, Lock, numlock, and group modifiers +with the interpretations defined in \fI\*(xP\fP, 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. +.sp +.LP +To invoke the currently registered KeyCode-to-KeySym translator, +use +.PN XtTranslateKeycode . +.LP +.IN "XtTranslateKeycode" "" "@DEF@" +.sM +.FD 0 +void XtTranslateKeycode(\fIdisplay\fP, \fIkeycode\fP, \fImodifiers\fP, \ +\fImodifiers_return\fP, \fIkeysym_return\fP) +.br + Display *\fIdisplay\fP; +.br + KeyCode \fIkeycode\fP; +.br + Modifiers \fImodifiers\fP; +.br + Modifiers *\fImodifiers_return\fP; +.br + KeySym *\fIkeysym_return\fP; +.FN +.IP \fIdisplay\fP 1.1i +Specifies the display that the KeyCode is from. +.IP \fIkeycode\fP 1.1i +Specifies the KeyCode to translate. +.IP \fImodifiers\fP 1.1i +Specifies the modifiers to the KeyCode. +.IP \fImodifiers_return\fP 1.1i +Returns a mask that indicates the modifiers actually used +to generate the KeySym. +.IP \fIkeysym_return\fP 1.1i +Returns the resulting KeySym. +.LP +.eM +The +.PN XtTranslateKeycode +function passes the specified arguments +directly to the currently registered KeyCode-to-KeySym translator. +.sp +.LP +To handle capitalization of nonstandard KeySyms, the \*(xI allow +clients to register case conversion routines. +Case converter procedure pointers are of type +.PN XtCaseProc . +.LP +.IN "XtCaseProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtCaseProc)(Display*, KeySym, KeySym*, KeySym*); +.br + Display *\fIdisplay\fP; +.br + KeySym \fIkeysym\fP; +.br + KeySym *\fIlower_return\fP; +.br + KeySym *\fIupper_return\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display connection for which the conversion is required. +.IP \fIkeysym\fP 1i +Specifies the KeySym to convert. +.IP \fIlower_return\fP 1i +Specifies a location into which to store the lowercase equivalent for +the KeySym. +.IP \fIupper_return\fP 1i +Specifies a location into which to store the uppercase equivalent for +the KeySym. +.LP +.eM +If there is no case distinction, +this procedure should store the KeySym into both return values. +.sp +.LP +To register a case converter, use +.PN XtRegisterCaseConverter . +.LP +.IN "XtRegisterCaseConverter" "" "@DEF@" +.sM +.FD 0 +void XtRegisterCaseConverter(\fIdisplay\fP, \fIproc\fP, \fIstart\fP, \fIstop\fP) +.br + Display *\fIdisplay\fP; +.br + XtCaseProc \fIproc\fP; +.br + KeySym \fIstart\fP; +.br + KeySym \fIstop\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display from which the key events are to come. +.IP \fIproc\fP 1i +Specifies the +.PN XtCaseProc +to do the conversions. +.IP \fIstart\fP 1i +Specifies the first KeySym for which this converter is valid. +.IP \fIstop\fP 1i +Specifies the last KeySym for which this converter is valid. +.LP +.eM +The +.PN XtRegisterCaseConverter +registers the specified case converter. +The \fIstart\fP and \fIstop\fP arguments provide the inclusive range of KeySyms +for which this converter is to be called. +The new converter overrides any previous converters for KeySyms in that range. +No interface exists to remove converters; +you need to register an identity converter. +When a new converter is registered, +the \*(xI refresh the keyboard state if necessary. +The default converter understands case conversion for all +Latin KeySyms defined in \fI\*(xP\fP, Appendix A. +.sp +.LP +To determine uppercase and lowercase equivalents for a KeySym, use +.PN XtConvertCase . +.LP +.IN "XtConvertCase" "" "@DEF@" +.sM +.FD 0 +void XtConvertCase(\fIdisplay\fP, \fIkeysym\fP, \fIlower_return\fP, \ +\fIupper_return\fP) +.br + Display *\fIdisplay\fP; +.br + KeySym \fIkeysym\fP; +.br + KeySym *\fIlower_return\fP; +.br + KeySym *\fIupper_return\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display that the KeySym came from. +.IP \fIkeysym\fP 1i +Specifies the KeySym to convert. +.IP \fIlower_return\fP 1i +Returns the lowercase equivalent of the KeySym. +.IP \fIupper_return\fP 1i +Returns the uppercase equivalent of the KeySym. +.LP +.eM +The +.PN XtConvertCase +function calls the appropriate converter and returns the results. +A user-supplied +.PN XtKeyProc +may need to use this function. + +.NH 2 +Obtaining a KeySym in an Action Procedure +.XS +\fB\*(SN Obtaining a KeySym in an Action Procedure\fP +.XE +.LP +When an action procedure is invoked on a +.PN KeyPress +or +.PN KeyRelease +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 +\*(xI to match the translation entry, the KeySym and modifiers +are stored for the duration of the action procedure and are made +available to the client. +.LP +To retrieve the KeySym and modifiers that matched the final event +specification in the translation table entry, use +.PN XtGetActionKeysym . +.LP +.IN "XtGetActionKeysym" "" "@DEF@" +.sM +.FD 0 +KeySym XtGetActionKeysym(\fIevent\fP, \fImodifiers_return\fP) +.br + XEvent *\fIevent\fP; +.br + Modifiers *\fImodifiers_return\fP; +.FN +.IP \fIevent\fP 1.25i +Specifies the event pointer passed to the action procedure by the \*(xI. +.IP \fImodifiers_return\fP 1.25i +Returns the modifiers that caused the match, if non-NULL. +.LP +.eM +If +.PN XtGetActionKeysym +is called after an action procedure has been +invoked by the \*(xI and before that action procedure 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 +.PN KeyPress +or +.PN KeyRelease +event, then +.PN XtGetActionKeysym +returns the KeySym that matched the final +event specification in the translation table and, if \fImodifiers_return\fP +is non-NULL, the modifier state actually used to generate this KeySym; +otherwise, if the event is a +.PN KeyPress +or +.PN KeyRelease +event, then +.PN XtGetActionKeysym +calls +.PN XtTranslateKeycode +and returns the results; +else it returns +.PN NoSymbol +and does not examine \fImodifiers_return\fP. +.LP +Note that if an action procedure invoked by the \*(xI +invokes a subsequent action procedure (and so on) via +.PN XtCallActionProc , +the nested action procedure may also call +.PN XtGetActionKeysym +to retrieve the \*(xI' KeySym and modifiers. + +.NH 2 +KeySym-to-KeyCode Conversions +.XS +\*(SN KeySym-to-KeyCode Conversions +.XE +.LP +To return the list of KeyCodes that map to a particular KeySym in +the keyboard mapping table maintained by the \*(xI, use +.PN XtKeysymToKeycodeList . +.LP +.IN "XtKeysymToKeycodeList" "" "@DEF@" +.sM +.FD 0 +void XtKeysymToKeycodeList(\fIdisplay\fP, \fIkeysym\fP, \fIkeycodes_return\fP, \ +\fIkeycount_return\fP) +.br + Display *\fIdisplay\fP; +.br + KeySym \fIkeysym\fP; +.br + KeyCode **\fIkeycodes_return\fP; +.br + Cardinal *\fIkeycount_return\fP; +.FN +.IP \fIdisplay\fP 1.25i +Specifies the display whose table is required. +.IP \fIkeysym\fP 1.25i +Specifies the KeySym for which to search. +.IP \fIkeycodes_return\fP 1.25i +Returns a list of KeyCodes that have \fIkeysym\fP +associated with them, or NULL if \fIkeycount_return\fP is 0. +.IP \fIkeycount_return\fP 1.25i +Returns the number of KeyCodes in the keycode list. +.LP +.eM +The +.PN XtKeysymToKeycodeList +procedure returns all the KeyCodes that have \fIkeysym\fP +in their entry for the keyboard mapping table associated with \fIdisplay\fP. +For each entry in the +table, the first four KeySyms (groups 1 and 2) are interpreted as +specified by \fI\*(xP\fP, Section 5. If no KeyCodes map to the +specified KeySym, \fIkeycount_return\fP is zero and *\fIkeycodes_return\fP is NULL. +.LP +The caller should free the storage pointed to by \fIkeycodes_return\fP using +.PN XtFree +when it is no longer useful. If the caller needs to examine +the KeyCode-to-KeySym table for a particular KeyCode, it should call +.PN XtGetKeysymTable . + +.NH 2 +Registering Button and Key Grabs for Actions +.XS +\fB\*(SN Registering Button and Key Grabs for Actions\fP +.XE +.LP +To register button and key grabs for a widget's window according to the +event bindings in the widget's translation table, use +.PN XtRegisterGrabAction . +.LP +.IN "XtRegisterGrabAction" "" "@DEF@" +.sM +.FD 0 +void XtRegisterGrabAction(\fIaction_proc\fP, \fIowner_events\fP, \ +\fIevent_mask\fP, \fIpointer_mode\fP, \fIkeyboard_mode\fP) +.br + XtActionProc \fIaction_proc\fP; +.br + Boolean \fIowner_events\fP; +.br + unsigned int \fIevent_mask\fP; +.br + int \fIpointer_mode\fP, \fIkeyboard_mode\fP; +.FN +.IP \fIaction_proc\fP 1i +Specifies the action procedure to search for in translation tables. +.sp +.IP \fIowner_events\fP +.br +.ns +.IP \fIevent_mask\fP +.br +.ns +.IP \fIpointer_mode\fP +.br +.ns +.IP \fIkeyboard_mode\fP 1i +Specify arguments to +.PN XtGrabButton +or +.PN XtGrabKey . +.LP +.eM +.PN XtRegisterGrabAction +adds the specified \fIaction_proc\fP 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 modified, its translation table and any installed +accelerators are scanned for action procedures on this list. +If any are invoked on +.PN ButtonPress +or +.PN KeyPress +events as the only or final event +in a sequence, the \*(xI will call +.PN XtGrabButton +or +.PN XtGrabKey +for the widget with every button or KeyCode which maps to the +event detail field, passing the specified \fIowner_events\fP, \fIevent_mask\fP, +\fIpointer_mode\fP, and \fIkeyboard_mode\fP. For +.PN ButtonPress +events, the modifiers +specified in the grab are determined directly from the translation +specification and \fIconfine_to\fP and \fIcursor\fP are specified as +.PN None . +For +.PN KeyPress +events, if the translation table entry specifies colon (:) in +the modifier list, the modifiers are determined by calling the key +translator procedure registered for the display and calling +.PN XtGrabKey +for every combination of standard modifiers which map the KeyCode to +the specified event detail KeySym, and ORing any modifiers specified in +the translation table entry, and \fIevent_mask\fP 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 +.PN ButtonPress +and +.PN KeyPress +events, don't-care modifiers are ignored unless the translation entry +explicitly specifies ``Any'' in the \fImodifiers\fP field. +.LP +If the specified \fIaction_proc\fP is already registered for the calling +process, the new values will replace the previously specified values +for any widgets that become realized following the call, but existing +grabs are not altered on currently realized widgets. +.LP +When translations or installed accelerators are modified for a +realized widget, any previous key or button grabs registered +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 +.PN XtGrabKey +or +.PN XtGrabButton . + +.NH 2 +Invoking Actions Directly +.XS +\fB\*(SN Invoking Actions Directly\fP +.XE +.LP +Normally action procedures are invoked by the \*(xI when an +event or event sequence arrives for a widget. To +invoke an action procedure directly, without generating +(or synthesizing) events, use +.PN XtCallActionProc . +.LP +.IN "XtCallActionProc" "" "@DEF@" +.sM +.FD 0 +void XtCallActionProc(\fIwidget\fP, \fIaction\fP, \fIevent\fP, \fIparams\fP, \ +\fInum_params\fP) +.br + Widget \fIwidget\fP; +.br + String \fIaction\fP; +.br + XEvent *\fIevent\fP; +.br + String *\fIparams\fP; +.br + Cardinal \fInum_params\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget in which the action is to be invoked. \*(cI +.IP \fIaction\fP 1i +Specifies the name of the action routine. +.IP \fIevent\fP 1i +Specifies the contents of the \fIevent\fP passed to the action routine. +.IP \fIparams\fP 1i +Specifies the contents of the \fIparams\fP passed to the action routine. +.IP \fInum_params\fP 1i +Specifies the number of entries in \fIparams\fP. +.LP +.eM +.PN XtCallActionProc +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 +.PN XtCallActionProc . +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 \fIevent\fP, \fIparams\fP, and \fInum_params\fP arguments are +appropriate for the specified action routine and, if necessary, that +the specified widget is realized or sensitive. If the named action +routine cannot be found, +.PN XtCallActionProc +generates a warning message and returns. + +.NH 2 +Obtaining a Widget's Action List +.XS +\*(SN Obtaining a Widget's Action List +.XE +.LP +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 registered in the superclass's +\fIactions\fP field, use +.PN XtGetActionList . +.LP +.IN "XtGetActionList" "" "@DEF@" +.sM +.FD 0 +void XtGetActionList(\fIwidget_class\fP, \fIactions_return\fP, \ +\fInum_actions_return\fP) +.br + WidgetClass \fIwidget_class\fP; +.br + XtActionList *\fIactions_return\fP; +.br + Cardinal *\fInum_actions_return\fP; +.FN +.IP \fIwidget_class\fP 1.5i +Specifies the widget class whose actions are to be returned. +.IP \fIactions_return\fP 1.5i +Returns the action list. +.IP \fInum_actions_return\fP 1.5i +Returns the number of action procedures declared by the class. +.LP +.eM +.PN XtGetActionList +returns the action table defined by the specified +widget class. This table does not include actions defined by the +superclasses. If \fIwidget_class\fP is not initialized, or is not +.PN coreWidgetClass +or a subclass thereof, or if the class does not define any actions, +*\fIactions_return\fP will be NULL and *\fInum_actions_return\fP +will be zero. +If *\fIactions_return\fP is non-NULL the client is responsible for freeing +the table using +.PN XtFree +when it is no longer needed. +.bp diff --git a/specs/CH11 b/specs/CH11 new file mode 100644 index 0000000..55b8d92 --- /dev/null +++ b/specs/CH11 @@ -0,0 +1,3566 @@ +.\" $Xorg: CH11,v 1.3 2000/08/17 19:42:47 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 11\fP\s-1 + +\s+1\fBUtility Functions\fP\s-1 +.sp 2 +.nr H1 11 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 11 \(em Utility Functions +.XE +The \*(xI provide a number of utility functions that you can use to +.IP \(bu 5 +Determine the number of elements in an array. +.IP \(bu 5 +Translate strings to widget instances. +.IP \(bu 5 +Manage memory usage. +.IP \(bu 5 +Share graphics contexts. +.IP \(bu 5 +Manipulate selections. +.IP \(bu 5 +Merge exposure events into a region. +.IP \(bu 5 +Translate widget coordinates. +.IP \(bu 5 +Locate a widget given a window id. +.IP \(bu 5 +Handle errors. +.IP \(bu 5 +Set the WM_COLORMAP_WINDOWS property. +.IP \(bu 5 +Locate files by name with string substitutions. +.IP \(bu 5 +Register callback functions for external agents. +.IP \(bu 5 +Locate all the displays of an application context. + +.NH 2 +Determining the Number of Elements in an Array +.XS +\fB\*(SN Determining the Number of Elements in an Array\fP +.XE +.LP +To determine the number of elements in a fixed-size array, use +.PN XtNumber . +.LP +.IN "XtNumber" "" "@DEF@" +.sM +.FD 0 +Cardinal XtNumber(\fIarray\fP) +.br + \fIArrayType array\fP; +.FN +.IP \fIarray\fP 1i +Specifies a fixed-size array of arbitrary type. +.LP +.eM +The +.PN XtNumber +macro returns the number of elements allocated to the array. + +.NH 2 +Translating Strings to Widget Instances +.XS +\fB\*(SN Translating Strings to Widget Instances\fP +.XE +.LP +To translate a widget name to a widget instance, use +.PN XtNameToWidget . +.LP +.IN "XtNameToWidget" "" "@DEF@" +.sM +.FD 0 +Widget XtNameToWidget(\fIreference\fP, \fInames\fP) +.br + Widget \fIreference\fP; +.br + String \fInames\fP; +.FN +.IP \fIreference\fP 1i +Specifies the widget from which the search is to start. \*(cI +.IP \fInames\fP 1i +Specifies the partially qualified name of the desired widget. +.LP +.eM +The +.PN XtNameToWidget +function searches for a descendant of the \fIreference\fP +widget whose name matches the specified names. The \fInames\fP parameter +specifies a simple object name or a series of simple object name +components separated by periods or asterisks. +.PN XtNameToWidget +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 +Composite : +.IP \(bu 5 +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. +.IP \(bu 5 +Return the first object in the enumeration that matches the +specified name, where each component of \fInames\fP matches exactly the +corresponding component of the qualified object name and asterisk +matches any series of components, including none. +.IP \(bu 5 +If no match is found, return NULL. +.LP +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 \*(xI do not require that all +children of a widget have unique names, +.PN XtNameToWidget +may return any +child that matches if there are multiple objects in the subtree 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 single period. + +.NH 2 +Managing Memory Usage +.XS +\fB\*(SN Managing Memory Usage\fP +.XE +.LP +The \*(xI memory management functions provide uniform checking for +null pointers and error reporting on memory allocation errors. +These functions are completely compatible with their standard C language +runtime counterparts +.PN malloc , +.PN calloc , +.PN realloc , +and +.PN free +with the following added functionality: +.IP \(bu 5 +.PN XtMalloc , +.PN XtCalloc , +and +.PN XtRealloc +give an error if there is not enough memory. +.IP \(bu 5 +.PN XtFree +simply returns if passed a NULL pointer. +.IP \(bu 5 +.PN XtRealloc +simply allocates new storage if passed a NULL pointer. +.LP +See the standard C library documentation on +.PN malloc , +.PN calloc , +.PN realloc , +and +.PN free +for more information. +.sp +.LP +To allocate storage, use +.PN XtMalloc . +.LP +.IN "XtMalloc" "" "@DEF@" +.sM +.FD 0 +char *XtMalloc(\fIsize\fP) +.br + Cardinal \fIsize\fP; +.FN +.IP \fIsize\fP 1i +Specifies the number of bytes desired. +.LP +.eM +The +.PN XtMalloc +function returns a pointer to a block of storage of at least +the specified \fIsize\fP bytes. +If there is insufficient memory to allocate the new block, +.PN XtMalloc +calls +.PN XtErrorMsg . +.sp +.LP +To allocate and initialize an array, use +.PN XtCalloc . +.LP +.IN "XtCalloc" "" "@DEF@" +.sM +.FD 0 +char *XtCalloc(\fInum\fP, \fIsize\fP) +.br + Cardinal \fInum\fP; +.br + Cardinal \fIsize\fP; +.FN +.IP \fInum\fP 1i +Specifies the number of array elements to allocate. +.IP \fIsize\fP 1i +Specifies the size of each array element in bytes. +.LP +.eM +The +.PN XtCalloc +function allocates space for the specified number of array elements +of the specified size and initializes the space to zero. +If there is insufficient memory to allocate the new block, +.PN XtCalloc +calls +.PN XtErrorMsg . +.PN XtCalloc +returns the address of the allocated storage. +.sp +.LP +To change the size of an allocated block of storage, use +.PN XtRealloc . +.LP +.IN "XtRealloc" "" "@DEF@" +.sM +.FD 0 +char *XtRealloc(\fIptr\fP, \fInum\fP) +.br + char *\fIptr\fP; +.br + Cardinal \fInum\fP; +.FN +.IP \fIptr\fP 1i +Specifies a pointer to the old storage allocated with +.PN XtMalloc , +.PN XtCalloc , +or +.PN XtRealloc , +or NULL. +.IP \fInum\fP 1i +Specifies number of bytes desired in new storage. +.LP +.eM +The +.PN XtRealloc +function changes the size of a block of storage, possibly moving it. +Then it copies the old contents (or as much as will fit) into the new block +and frees the old block. +If there is insufficient memory to allocate the new block, +.PN XtRealloc +calls +.PN XtErrorMsg . +If \fIptr\fP is NULL, +.PN XtRealloc +simply calls +.PN XtMalloc . +.PN XtRealloc +then returns the address of the new block. +.sp +.LP +To free an allocated block of storage, use +.PN XtFree . +.LP +.IN "XtFree" "" "@DEF@" +.sM +.FD 0 +void XtFree(\fIptr\fP) +.br + char *\fIptr\fP; +.FN +.IP \fIptr\fP 1i +Specifies a pointer to a block of storage allocated with +.PN XtMalloc , +.PN XtCalloc , +or +.PN XtRealloc , +or NULL. +.LP +.eM +The +.PN XtFree +function returns storage, allowing it to be reused. +If \fIptr\fP is NULL, +.PN XtFree +returns immediately. +.sp +.LP +To allocate storage for a new instance of a type, use +.PN XtNew . +.LP +.IN "XtNew" "" "@DEF@" +.sM +.FD 0 +\fItype\fP *XtNew(\fItype\fP) +.br + \fItype t\fP; +.FN +.IP \fItype\fP 1i +Specifies a previously declared type. +.LP +.eM +.PN XtNew +returns a pointer to the allocated storage. +If there is insufficient memory to allocate the new block, +.PN XtNew +calls +.PN XtErrorMsg . +.PN XtNew +is a convenience macro that calls +.PN XtMalloc +with the following arguments specified: +.LP +.Ds +.TA .5i +.ta .5i +((type *) XtMalloc((unsigned) sizeof(type))) +.De +.LP +The storage allocated by +.PN XtNew +should be freed using +.PN XtFree . +.sp +.LP +To copy an instance of a string, use +.PN XtNewString . +.LP +.IN "XtNewString" "" "@DEF@" +.sM +.FD 0 +String XtNewString(\fIstring\fP) +.br + String \fIstring\fP; +.FN +.IP \fIstring\fP 1i +Specifies a previously declared string. +.LP +.eM +.PN XtNewString +returns a pointer to the allocated storage. +If there is insufficient memory to allocate the new block, +.PN XtNewString +calls +.PN XtErrorMsg . +.PN XtNewString +is a convenience macro that calls +.PN XtMalloc +with the following arguments specified: +.LP +.Ds +.TA .5i +.ta .5i +(strcpy(XtMalloc((unsigned)strlen(str) + 1), str)) +.De +.LP +The storage allocated by +.PN XtNewString +should be freed using +.PN XtFree . + +.NH 2 +Sharing Graphics Contexts +.XS +\fB\*(SN Sharing Graphics Contexts\fP +.XE +.LP +The \*(xI 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. +.LP +To obtain a shareable GC with modifiable fields, use +.PN XtAllocateGC . +.LP +.IN "XtAllocateGC" "" "@DEF@" +.sM +.FD 0 +GC XtAllocateGC(\fIwidget\fP, \fIdepth\fP, \fIvalue_mask\fP, \fIvalues\fP, \ +\fIdynamic_mask\fP, \fIunused_mask\fP) +.br + Widget \fIobject\fP; +.br + Cardinal \fIdepth\fP; +.br + XtGCMask \fIvalue_mask\fP; +.br + XGCValues *\fIvalues\fP; +.br + XtGCMask \fIdynamic_mask\fP; +.br + XtGCMask \fIunused_mask\fP; +.FN +.IP \fIobject\fP 1i +Specifies an object, giving the screen for which the +returned GC is valid. \*(oI +.IP \fIdepth\fP 1i +Specifies the depth for which the returned GC is valid, or 0. +.IP \fIvalue_mask\fP 1i +Specifies fields of the GC that are initialized from \fIvalues\fP. +.IP \fIvalues\fP 1i +Specifies the values for the initialized fields. +.IP \fIdynamic_mask\fP 1i +Specifies fields of the GC that will be modified by the caller. +.IP \fIunused_mask\fP 1i +Specifies fields of the GC that will not be needed by the caller. +.LP +.eM +The +.PN XtAllocateGC +function returns a shareable GC that may be +modified by the client. The \fIscreen\fP field of the specified +widget or of the nearest widget ancestor of the specified +object and the specified \fIdepth\fP argument supply +the root and drawable depths for which the GC is to be +valid. If \fIdepth\fP is zero, the depth is taken from the +\fIdepth\fP field of the specified widget or of the nearest +widget ancestor of the specified object. +.LP +The \fIvalue_mask\fP argument specifies fields of the GC +that are initialized with the respective member of the +\fIvalues\fP structure. The \fIdynamic_mask\fP 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 \fIunused_mask\fP argument +specifies fields of the GC that are of no interest to the +caller. The caller may make no assumptions about the contents +of any fields specified in \fIunused_mask\fP. The caller may assume +that at all times all fields not specified in either +\fIdynamic_mask\fP or \fIunused_mask\fP have their default value if not +specified in \fIvalue_mask\fP or the value specified by \fIvalues\fP. +If a field is specified in both \fIvalue_mask\fP and \fIdynamic_mask\fP, +the effect is as if it were specified only in \fIdynamic_mask\fP +and then immediately set to the value in \fIvalues\fP. If a field +is set in \fIunused_mask\fP and also in either \fIvalue_mask\fP or +\fIdynamic_mask\fP, the specification in \fIunused_mask\fP is ignored. +.LP +.PN XtAllocateGC +tries to minimize the number of unique GCs +created by comparing the arguments with those of previous +calls and returning an existing GC when there are no +conflicts. +.PN XtAllocateGC +may modify and return an existing GC if it was allocated with a +nonzero \fIunused_mask\fP. +.sp +.LP +To obtain a shareable GC with no modifiable fields, use +.PN XtGetGC . +.LP +.IN "XtGetGC" "" "@DEF@" +.sM +.FD 0 +GC XtGetGC(\fIobject\fP, \fIvalue_mask\fP, \fIvalues\fP) +.br + Widget \fIobject\fP; +.br + XtGCMask \fIvalue_mask\fP; +.br + XGCValues *\fIvalues\fP; +.FN +.IP \fIobject\fP 1i +Specifies an object, giving the screen and depth for which the +returned GC is valid. \*(oI +.IP \fIvalue_mask\fP 1i +Specifies which fields of the \fIvalues\fP structure are specified. +.IP \fIvalues\fP 1i +Specifies the actual values for this GC. +.LP +.eM +The +.PN XtGetGC +function returns a shareable, read-only GC. +The parameters to this function are the same as those for +.PN XCreateGC +except that an Object is passed instead of a Display. +.PN XtGetGC +is equivalent to +.PN XtAllocateGC +with \fIdepth\fP, \fIdynamic_mask\fP, and \fIunused_mask\fP all zero. +.LP +.PN XtGetGC +shares only GCs in which all values in the GC returned by +.PN XCreateGC +are the same. +In particular, it does not use the \fIvalue_mask\fP provided to +determine which fields of the GC a widget considers relevant. +The \fIvalue_mask\fP is used only to tell the server which fields should be +filled in from \fIvalues\fP and which it should fill in with default values. +.sp +.LP +To deallocate a shared GC when it is no longer needed, use +.PN XtReleaseGC . +.LP +.IN "XtReleaseGC" "" "@DEF@" +.sM +.FD 0 +void XtReleaseGC(\fIobject\fP, \fIgc\fP) +.br + Widget \fIobject\fP; +.br + GC \fIgc\fP; +.FN +.IP \fIobject\fP 1i +Specifies any object on the Display for which the GC was created. \*(oI +.IP \fIgc\fP 1i +Specifies the shared GC obtained with either +.PN XtAllocateGC +or +.PN XtGetGC . +.LP +.eM +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. + +.NH 2 +Managing Selections +.XS +\*(SN Managing Selections +.XE +.LP +Arbitrary widgets in multiple applications can communicate +with each other by means of the \*(xI global selection mechanism, +which conforms to the specifications in the \fI\*(xC\fP. +The \*(xI supply functions for providing and receiving selection data in +one logical piece (atomic transfers) +or in smaller logical segments (incremental transfers). +.LP +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 \*(xI 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 +allocate additional storage to copy the pieces contiguously. Any +owner or requestor that prefers to deal with the selection value in +segments can use the incremental interfaces to do so. +The transfer between the selection owner or requestor and the \*(xI is not +required to match the underlying +transport protocol between the application and the X server; +the \*(xI will break too large a selection +into smaller pieces for transport if necessary +and will coalesce a selection transmitted incrementally if the value +was requested atomically. + +.NH 3 +Setting and Getting the Selection Timeout Value +.XS +\fB\*(SN Setting and Getting the Selection Timeout Value\fP +.XE +.LP +To set the \*(xI selection timeout, use +.PN XtAppSetSelectionTimeout . +.LP +.IN "XtAppSetSelectionTimeout" "" "@DEF@" +.sM +.FD 0 +void XtAppSetSelectionTimeout(\fIapp_context\fP, \fItimeout\fP) +.br + XtAppContext \fIapp_context\fP; +.br + unsigned long \fItimeout\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fItimeout\fP 1i +Specifies the selection timeout in milliseconds. +.eM +.LP +To get the current selection timeout value, use +.PN XtAppGetSelectionTimeout . +.LP +.IN "XtAppGetSelectionTimeout" "" "@DEF@" +.sM +.FD 0 +unsigned long XtAppGetSelectionTimeout(\fIapp_context\fP) +.br + XtAppContext \fIapp_context\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.LP +.eM +The +.PN XtAppGetSelectionTimeout +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 timeout value is set by the +selectionTimeout +.IN "selectionTimeout" +application resource as retrieved by +.PN XtDisplayInitialize . +If +selectionTimeout +is not specified, +the default is five seconds. + +.NH 3 +Using Atomic Transfers +.XS +\*(SN Using Atomic Transfers +.XE +.LP +When using atomic transfers, the owner will completely +process one selection request at a time. +The owner may consider each request individually, +since there is no possibility for overlap +between evaluation of two requests. + +.NH 4 +Atomic Transfer Procedures +.XS +\*(SN Atomic Transfer Procedures +.XE +.IN "Selections" "atomic" +.LP +The following procedures are used by the selection owner when +providing selection data in a single unit. +.LP +The procedure pointer specified by the owner to supply the selection +data to the \*(xI is of type +.PN XtConvertSelectionProc . +.LP +.IN "XtConvertSelectionProc" "" "@DEF@" +.sM +.FD 0 +typedef Boolean (*XtConvertSelectionProc)(Widget, Atom*, Atom*, Atom*, +.br + XtPointer*, unsigned long*, int*); +.br + Widget \fIw\fP; +.br + Atom *\fIselection\fP; +.br + Atom *\fItarget\fP; +.br + Atom *\fItype_return\fP; +.br + XtPointer *\fIvalue_return\fP; +.br + unsigned long *\fIlength_return\fP; +.br + int *\fIformat_return\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget that currently owns this selection. +.IP \fIselection\fP 1i +Specifies the atom naming the selection requested +(for example, +.PN XA_PRIMARY +or +.PN XA_SECONDARY ). +.IP \fItarget\fP 1i +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). +.IP \fItype_return\fP 1i +Specifies a pointer to an atom into which the property type of the +converted value of the selection is to be stored. +For instance, either File Name or Text might have property type +.PN XA_STRING . +.IP \fIvalue_return\fP 1i +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 +.PN XtSelectionDoneProc +for the selection, +this storage is owned by the selection owner; +otherwise, it is owned by the \*(xI selection mechanism, +which frees it by calling +.PN XtFree +when it is done with it. +.IP \fIlength_return\fP 1i +Specifies a pointer into which the number of elements in \fIvalue_return\fP, +each of size indicated by \fIformat_return\fP, is to be stored. +.IP \fIformat_return\fP 1i +Specifies a pointer into which the size in bits of the data elements +of the selection value is to be stored. +.LP +.eM +This procedure is called by the \*(xI selection mechanism +to get the value of a selection as a given type +from the current selection owner. +It returns +.PN True +if the owner successfully converted the selection to the target type or +.PN False +otherwise. +If the procedure returns +.PN False , +the values of the return arguments are undefined. +Each +.PN XtConvertSelectionProc +should respond to target value +.PN TARGETS +by returning a value containing the list of the targets +into which it is +prepared to convert the selection. +The value returned in +\fIformat_return\fP must be one of 8, 16, or 32 to allow the server to +byte-swap the data if necessary. +.LP +.IN "Selections" "MULTIPLE" +.IN "Selections" "TIMESTAMP" +This procedure does not need to worry about responding to the +MULTIPLE or the TIMESTAMP target values (see Section 2.6.2 in the \fI\*(xC\fP). +A selection request with +the MULTIPLE target type is transparently transformed into a +series of calls to this procedure, one for each target type, and a +selection request with the TIMESTAMP target value is answered +automatically by the \*(xI using the time specified in the +call to +.PN XtOwnSelection +or +.PN XtOwnSelectionIncremental . +.sp +.LP +To retrieve the +.PN SelectionRequest +event that triggered the +.PN XtConvertSelectionProc +procedure, use +.PN XtGetSelectionRequest . +.LP +.IN "XtGetSelectionRequest" "" "@DEF@" +.sM +.FD 0 +XSelectionRequestEvent *XtGetSelectionRequest(\fIw\fP, \fIselection\fP, \ +\fIrequest_id\fP) +.br + Widget \fIw\fP; +.br + Atom \fIselection\fP; +.br + XtRequestId \fIrequest_id\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget that currently owns this selection. \*(cI +.IP \fIselection\fP 1i +Specifies the selection being processed. +.IP \fIrequest_id\fP 1i +Specifies the requestor id in the case of incremental +selections, or NULL in the case of atomic transfers. +.LP +.eM +.PN XtGetSelectionRequest +may be called only from within an +.PN XtConvertSelectionProc +procedure and returns a pointer to the +.PN SelectionRequest +event that caused the conversion procedure to be invoked. +\fIRequest_id\fP specifies a unique id for the individual request in the +case that multiple incremental transfers are outstanding. For atomic +transfers, \fIrequest_id\fP must be specified as NULL. If no +.PN SelectionRequest +event is being processed for the specified +\fIwidget\fP, \fIselection\fP, and \fIrequest_id\fP, +.PN XtGetSelectionRequest +returns NULL. +.sp +.LP +The procedure pointer specified by the owner when it desires +notification upon losing ownership is of type +.PN XtLoseSelectionProc . +.LP +.IN "XtLoseSelectionProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtLoseSelectionProc)(Widget, Atom*); +.br + Widget \fIw\fP; +.br + Atom *\fIselection\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget that has lost selection ownership. +.IP \fIselection\fP 1i +Specifies the atom naming the selection. +.LP +.eM +This procedure is called by the \*(xI selection mechanism +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. +.sp +.LP +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 +.PN XtSelectionDoneProc . +.LP +.IN "XtSelectionDoneProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtSelectionDoneProc)(Widget, Atom*, Atom*); +.br + Widget \fIw\fP; +.br + Atom *\fIselection\fP; +.br + Atom *\fItarget\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget that owns the converted selection. +.IP \fIselection\fP 1i +Specifies the atom naming the selection that was converted. +.IP \fItarget\fP 1i +Specifies the target type to which the conversion was done. +.LP +.eM +This procedure is called by the \*(xI selection mechanism +to inform the selection owner that a selection requestor has successfully +retrieved a selection value. +If the selection owner has registered an +.PN XtSelectionDoneProc , +it should expect it to be called once for each conversion that it performs, +after the converted value has been successfully transferred +to the requestor. +If the selection owner has registered an +.PN XtSelectionDoneProc , +it also owns the storage containing the converted +selection value. + +.NH 4 +Getting the Selection Value +.XS +\*(SN Getting the Selection Value +.XE +.LP +The procedure pointer specified by the requestor to receive the +selection data from the \*(xI is of type +.PN XtSelectionCallbackProc . +.LP +.IN "XtSelectionCallbackProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtSelectionCallbackProc)(Widget, XtPointer, Atom*, Atom*, \ +XtPointer, unsigned long*, int*); +.br + Widget \fIw\fP; +.br + XtPointer \fIclient_data\fP; +.br + Atom *\fIselection\fP; +.br + Atom *\fItype\fP; +.br + XtPointer \fIvalue\fP; +.br + unsigned long *\fIlength\fP; +.br + int *\fIformat\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget that requested the selection value. +.IP \fIclient_data\fP 1i +Specifies a value passed in by the widget when it requested the +selection. +.IP \fIselection\fP 1i +Specifies the name of the selection that was requested. +.IP \fItype\fP 1i +Specifies the representation type of the selection value (for example, +.PN XA_STRING ). +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 +.PN XT_CONVERT_FAIL +is used to indicate that the selection conversion failed because the +selection owner did not respond within the \*(xI selection timeout +interval. +.IP \fIvalue\fP 1i +Specifies a pointer to the selection value. +The requesting client owns this storage and is responsible for freeing it +by calling +.PN XtFree +when it is done with it. +.IP \fIlength\fP 1i +Specifies the number of elements in \fIvalue\fP. +.IP \fIformat\fP 1i +Specifies the size in bits of the data in each element of \fIvalue\fP. +.LP +.eM +This procedure is called by the \*(xI selection mechanism to deliver the +requested selection to the requestor. +.LP +If the +.PN SelectionNotify +event returns a property of +.PN None , +meaning the conversion has been refused because there is no owner for the +specified selection or the owner cannot convert the selection to the +requested target for any reason, the procedure is called with a value +of NULL and a length of zero. +.sp +.LP +To obtain the selection value in a single logical unit, use +.PN XtGetSelectionValue +or +.PN XtGetSelectionValues . +.LP +.IN "XtGetSelectionValue" "" "@DEF@" +.sM +.FD 0 +void XtGetSelectionValue(\fIw\fP, \fIselection\fP, \fItarget\fP, \ +\fIcallback\fP, \fIclient_data\fP, \fItime\fP) +.br + Widget \fIw\fP; +.br + Atom \fIselection\fP; +.br + Atom \fItarget\fP; +.br + XtSelectionCallbackProc \fIcallback\fP; +.br + XtPointer \fIclient_data\fP; +.br + Time \fItime\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget making the request. \*(cI +.IP \fIselection\fP 1i +Specifies the particular selection desired; for example, +.PN XA_PRIMARY . +.IP \fItarget\fP 1i +Specifies the type of information needed about the selection. +.IP \fIcallback\fP 1i +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. +.IP \fIclient_data\fP 1i +Specifies additional data to be passed to the specified procedure +when it is called. +.IP \fItime\fP 1i +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 +.PN CurrentTime +is not acceptable. +.LP +.eM +The +.PN XtGetSelectionValue +function requests the value of the selection converted to +the target type. +The specified callback is called at some time after +.PN XtGetSelectionValue +is called, when the selection value is received from the X server. +It may be called before or after +.PN XtGetSelectionValue +returns. +For more information about \fIselection\fP, \fItarget\fP, and +\fItime\fP, see Section 2.6 in the \fI\*(xC\fP. +.sp +.LP +.IN "XtGetSelectionValues" "" "@DEF@" +.sM +.FD 0 +void XtGetSelectionValues(\fIw\fP, \fIselection\fP, \fItargets\fP, \ +\fIcount\fP, \fIcallback\fP, \fIclient_data\fP, \fItime\fP) +.br + Widget \fIw\fP; +.br + Atom \fIselection\fP; +.br + Atom *\fItargets\fP; +.br + int \fIcount\fP; +.br + XtSelectionCallbackProc \fIcallback\fP; +.br + XtPointer *\fIclient_data\fP; +.br + Time \fItime\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget making the request. \*(cI +.IP \fIselection\fP 1i +Specifies the particular selection desired (that is, primary or secondary). +.IP \fItargets\fP 1i +Specifies the types of information needed about the selection. +.IP \fIcount\fP 1i +Specifies the length of the \fItargets\fP and \fIclient_data\fP lists. +.IP \fIcallback\fP 1i +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. +.IP \fIclient_data\fP 1i +Specifies a list of additional data values, one for each target type, +that are passed to the callback procedure when it is called for that target. +.IP \fItime\fP 1i +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 +.PN CurrentTime +is not acceptable. +.LP +.eM +The +.PN XtGetSelectionValues +function is similar to multiple calls to +.PN XtGetSelectionValue +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 +target value with the corresponding client data. +For more information about \fIselection\fP, \fItarget\fP, and +\fItime\fP, see Section 2.6 in the \fI\*(xC\fP. + +.NH 4 +Setting the Selection Owner +.XS +\*(SN Setting the Selection Owner +.XE +.LP +To set the selection owner and indicate that the selection value will +be provided in one piece, use +.PN XtOwnSelection . +.LP +.IN "XtOwnSelection" "" "@DEF@" +.sM +.FD 0 +Boolean XtOwnSelection(\fIw\fP, \fIselection\fP, \fItime\fP, \ +\fIconvert_proc\fP, \fIlose_selection\fP, \fIdone_proc\fP) +.br + Widget \fIw\fP; +.br + Atom \fIselection\fP; +.br + Time \fItime\fP; +.br + XtConvertSelectionProc \fIconvert_proc\fP; +.br + XtLoseSelectionProc \fIlose_selection\fP; +.br + XtSelectionDoneProc \fIdone_proc\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget that wishes to become the owner. \*(cI +.IP \fIselection\fP 1i +Specifies the name of the selection (for example, +.PN XA_PRIMARY ). +.IP \fItime\fP 1i +Specifies the timestamp that indicates when the ownership request was +initiated. +This should be the timestamp of the event that triggered ownership; +the value +.PN CurrentTime +is not acceptable. +.IP \fIconvert_proc\fP 1i +Specifies the procedure to be called whenever a client requests the +current value of the selection. +.IP \fIlose_selection\fP 1i +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. +.IP \fIdone_proc\fP 1i +Specifies the procedure called +after the requestor has received the selection value, or NULL if the +owner is not +interested in being called back. +.LP +.eM +The +.PN XtOwnSelection +function informs the \*(xI selection mechanism that a +widget wishes to own a selection. +It returns +.PN True +if the widget successfully becomes the owner and +.PN False +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 ownership either +because some other widget asserted later ownership of the selection +or because the widget voluntarily gave up ownership of the selection. +The lose_selection procedure is not called +if the widget fails to obtain selection ownership in the first place. +.LP +If a done_proc is specified, the client owns the storage allocated +for passing the value to the \*(xI. If \fIdone_proc\fP is NULL, +the convert_proc must allocate storage using +.PN XtMalloc , +.PN XtRealloc , +or +.PN XtCalloc , +and the value specified is freed by the +\*(xI when the transfer is complete. +.sp +.LP +Usually, a selection owner maintains ownership indefinitely until some +other widget requests ownership, at which time +the \*(xI 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 \*(xI +by using +.PN XtDisownSelection +that it no longer is to be the selection owner. +.LP +.IN "XtDisownSelection" "" "@DEF@" +.sM +.FD 0 +void XtDisownSelection(\fIw\fP, \fIselection\fP, \fItime\fP) +.br + Widget \fIw\fP; +.br + Atom \fIselection\fP; +.br + Time \fItime\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget that wishes to relinquish ownership. +.IP \fIselection\fP 1i +Specifies the atom naming the selection being given up. +.IP \fItime\fP 1i +Specifies the timestamp that indicates when the request to +relinquish selection ownership was initiated. +.LP +.eM +The +.PN XtDisownSelection +function informs the \*(xI selection mechanism that +the specified widget is to lose ownership 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, +.PN XtDisownSelection +does nothing. +.LP +After a widget has called +.PN XtDisownSelection , +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 conversion that started +before the call to +.PN XtDisownSelection +finishes after the call to +.PN XtDisownSelection . + +.NH 3 +Using Incremental Transfers +.XS +\*(SN Using Incremental Transfers +.XE +.LP +When using the incremental interface, an owner may have to process +more than one selection request for the same selection, converted to +the same target, at the same time. The incremental functions take a +\fIrequest_id\fP argument, which is an identifier that is guaranteed to be +unique among all incremental requests that are active concurrently. +.LP +For example, consider the following: +.IP \(bu 5 +Upon receiving a request for the selection value, the owner sends +the first segment. +.IP \(bu 5 +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 selection value. +.IP \(bu 5 +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 asking for the first segment. + +.NH 4 +Incremental Transfer Procedures +.XS +\*(SN Incremental Transfer Procedures +.XE +.IN "Selections" "incremental" +.LP +The following procedures are used by selection owners who wish to +provide the selection data in multiple segments. +.LP +The procedure pointer specified by the incremental owner to supply the +selection data to the \*(xI is of type +.PN XtConvertSelectionIncrProc . +.LP +.sM +.Ds 0 +typedef XtPointer XtRequestId; +.De +.IN "XtRequestId" "" "@DEF@" +.IN "XtConvertSelectionIncrProc" "" "@DEF@" +.FD 0 +typedef Boolean (*XtConvertSelectionIncrProc)(Widget, Atom*, Atom*, \ +Atom*, XtPointer*, + unsigned long*, int*, unsigned long*, \ +XtPointer, XtRequestId*); +.br + Widget \fIw\fP; +.br + Atom *\fIselection\fP; +.br + Atom *\fItarget\fP; +.br + Atom *\fItype_return\fP; +.br + XtPointer *\fIvalue_return\fP; +.br + unsigned long *\fIlength_return\fP; +.br + int *\fIformat_return\fP; +.br + unsigned long *\fImax_length\fP; +.br + XtPointer \fIclient_data\fP; +.br + XtRequestId *\fIrequest_id\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget that currently owns this selection. +.IP \fIselection\fP 1i +Specifies the atom that names the selection requested. +.IP \fItarget\fP 1i +Specifies the type of information required about the selection. +.IP \fItype_return\fP 1i +Specifies a pointer to an atom into which the property +type of the converted value of the selection is to be +stored. +.IP \fIvalue_return\fP 1i +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. +.IP \fIlength_return\fP 1i +Specifies a pointer into which the number of elements +in \fIvalue_return\fP, each of size indicated by +\fIformat_return\fP, is to be stored. +.IP \fIformat_return\fP 1i +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. +.IP \fImax_length\fP 1i +Specifies the maximum number of bytes which may be +transferred at any one time. +.IP \fIclient_data\fP 1i +Specifies the value passed in by the widget when it +took ownership of the selection. +.IP \fIrequest_id\fP 1i +Specifies an opaque identification for a specific request. +.LP +.eM +This procedure is called repeatedly by the \*(xI selection mechanism to get +the next incremental chunk of data from a selection owner who has +called +.PN XtOwnSelectionIncremental . +It must return +.PN True +if the procedure has succeeded in converting the selection data or +.PN False +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 \*(xI; +that is, a fixed transfer area may be allocated and returned in \fIvalue_return\fP +for each segment to be transferred. This procedure should store a +non-NULL value in \fIvalue_return\fP and zero in \fIlength_return\fP to indicate that the +entire selection has been delivered. After returning this final +segment, the request id may be reused by the \*(xI to begin a +new transfer. +.LP +To retrieve the +.PN SelectionRequest +event that triggered the selection conversion procedure, use +.PN XtGetSelectionRequest , +described in Section 11.5.2.1. +.sp +.LP +The procedure pointer specified by the incremental selection owner +when it desires notification upon no longer having ownership is of +type +.PN XtLoseSelectionIncrProc . +.LP +.IN "XtLoseSelectionIncrProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtLoseSelectionIncrProc)(Widget, Atom*, XtPointer); +.br + Widget \fIw\fP; +.br + Atom *\fIselection\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget that has lost the selection ownership. +.IP \fIselection\fP 1i +Specifies the atom that names the selection. +.IP \fIclient_data\fP 1i +Specifies the value passed in by the widget when it +took ownership of the selection. +.LP +.eM +This procedure, which is optional, is called by the \*(xI to +inform the selection owner that it no longer owns the selection. +.sp +.LP +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 +.PN XtSelectionDoneIncrProc . +.LP +.IN "XtSelectionDoneIncrProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtSelectionDoneIncrProc)(Widget, Atom*, Atom*, \ +XtRequestId*, XtPointer); +.br + Widget \fIw\fP; +.br + Atom *\fIselection\fP; +.br + Atom *\fItarget\fP; +.br + XtRequestId *\fIrequest_id\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget that owns the selection. +.IP \fIselection\fP 1i +Specifies the atom that names the selection being transferred. +.IP \fItarget\fP 1i +Specifies the target type to which the conversion was done. +.IP \fIrequest_id\fP 1i +Specifies an opaque identification for a specific request. +.IP \fIclient_data\fP 1i +Specified the value passed in by the widget when it +took ownership of the selection. +.LP +.eM +This procedure, which is optional, is called by the \*(xI 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 \*(xI will free only the +final value returned by the selection owner using +.PN XtFree . +.sp +.LP +The procedure pointer specified by the incremental selection owner to +notify it if a transfer should be terminated prematurely is of type +.PN XtCancelConvertSelectionProc . +.LP +.IN "XtCancelConvertSelectionProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtCancelConvertSelectionProc)(Widget, Atom*, Atom*, \ +XtRequestId*, XtPointer); +.br + Widget \fIw\fP; +.br + Atom *\fIselection\fP; +.br + Atom *\fItarget\fP; +.br + XtRequestId *\fIrequest_id\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget that owns the selection. +.IP \fIselection\fP 1i +Specifies the atom that names the selection being transferred. +.IP \fItarget\fP 1i +Specifies the target type to which the conversion was done. +.IP \fIrequest_id\fP 1i +Specifies an opaque identification for a specific request. +.IP \fIclient_data\fP 1i +Specifies the value passed in by the widget when it took ownership of +the selection. +.LP +.eM +This procedure is called by the \*(xI 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. + +.NH 4 +Getting the Selection Value Incrementally +.XS +\*(SN Getting the Selection Value Incrementally +.XE +.LP +To obtain the value of the selection using incremental transfers, use +.PN XtGetSelectionValueIncremental +or +.PN XtGetSelectionValuesIncremental . +.LP +.IN "XtGetSelectionValueIncremental" "" "@DEF@" +.sM +.FD 0 +void XtGetSelectionValueIncremental(\fIw\fP, \fIselection\fP, \fItarget\fP, \ +\fIselection_callback\fP, \fIclient_data\fP, \fItime\fP) +.br + Widget \fIw\fP; +.br + Atom \fIselection\fP; +.br + Atom \fItarget\fP; +.br + XtSelectionCallbackProc \fIselection_callback\fP; +.br + XtPointer \fIclient_data\fP; +.br + Time \fItime\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget making the request. \*(cI +.IP \fIselection\fP 1i +Specifies the particular selection desired. +.IP \fItarget\fP 1i +Specifies the type of information needed +about the selection. +.IP \fIselection_callback\fP 1i +Specifies the callback procedure to be +called to receive each data segment. +.IP \fIclient_data\fP 1i +Specifies client-specific data to be passed to +the specified callback procedure when it is invoked. +.IP \fItime\fP 1i +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 +.PN CurrentTime +is not acceptable. +.LP +.eM +The +.PN XtGetSelectionValueIncremental +function is similar to +.PN XtGetSelectionValue +except that the selection_callback procedure will +be called repeatedly upon delivery of multiple segments of the +selection value. The end of the selection value is indicated when +\fIselection_callback\fP 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 timeout), the selection_callback procedure is +called with a type value equal to the symbolic constant +.PN XT_CONVERT_FAIL +so that the requestor can dispose +of the partial selection value it has collected up until that point. +Upon receiving +.PN XT_CONVERT_FAIL , +the requesting client must determine +for itself whether or not a partially completed data transfer is meaningful. +For more information about \fIselection\fP, \fItarget\fP, and +\fItime\fP, see Section 2.6 in the \fI\*(xC\fP. +.LP +.IN "XtGetSelectionValuesIncremental" "" "@DEF@" +.sM +.FD 0 +void XtGetSelectionValuesIncremental(\fIw\fP, \fIselection\fP, \fItargets\fP, \ +\fIcount\fP, \fIselection_callback\fP, \fIclient_data\fP, \fItime\fP) +.br + Widget \fIw\fP; +.br + Atom \fIselection\fP; +.br + Atom *\fItargets\fP; +.br + int \fIcount\fP; +.br + XtSelectionCallbackProc \fIselection_callback\fP; +.br + XtPointer *\fIclient_data\fP; +.br + Time \fItime\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget making the request. \*(cI +.IP \fIselection\fP 1i +Specifies the particular selection desired. +.IP \fItargets\fP 1i +Specifies the types of information needed about +the selection. +.IP \fIcount\fP 1i +Specifies the length of the \fItargets\fP and \fIclient_data\fP lists. +.IP \fIselection_callback\fP 1i +Specifies the callback procedure to be called +to receive each selection value. +.IP \fIclient_data\fP 1i +Specifies a list of client data (one for each target +type) values that are passed to the callback procedure when +it is invoked for the corresponding target. +.IP \fItime\fP 1i +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 +.PN CurrentTime +is not acceptable. +.LP +.eM +The +.PN XtGetSelectionValuesIncremental +function is similar to +.PN XtGetSelectionValueIncremental +except that it takes a list of targets and client data. +.PN XtGetSelectionValuesIncremental +is equivalent to calling +.PN XtGetSelectionValueIncremental +successively for each \fItarget/client_data\fP pair except that +.PN XtGetSelectionValuesIncremental +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 +.PN XtGetSelectionValueIncremental +repeatedly. +For more information about \fIselection\fP, \fItarget\fP, and +\fItime\fP, see Section 2.6 in the \fI\*(xC\fP. + +.NH 4 +Setting the Selection Owner for Incremental Transfers +.XS +\*(SN Setting the Selection Owner for Incremental Transfers +.XE +.LP +To set the selection owner when using incremental transfers, use +.PN XtOwnSelectionIncremental . +.LP +.IN "XtOwnSelectionIncremental" "" "@DEF@" +.sM +.FD 0 +Boolean XtOwnSelectionIncremental(\fIw\fP, \fIselection\fP, \fItime\fP, \ +\fIconvert_callback\fP, \fIlose_callback\fP, + \fIdone_callback\fP, \ +\fIcancel_callback\fP, \fIclient_data\fP) +.br + Widget \fIw\fP; +.br + Atom \fIselection\fP; +.br + Time \fItime\fP; +.br + XtConvertSelectionIncrProc \fIconvert_callback\fP; +.br + XtLoseSelectionIncrProc \fIlose_callback\fP; +.br + XtSelectionDoneIncrProc \fIdone_callback\fP; +.br + XtCancelConvertSelectionProc \fIcancel_callback\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIw\fP 1.25i +Specifies the widget that wishes to become the owner. \*(cI +.IP \fIselection\fP 1.25i +Specifies the atom that names the selection. +.IP \fItime\fP 1.25i +Specifies the timestamp that indicates when the +selection ownership request was initiated. This should be +the timestamp of the event that triggered ownership; the value +.PN CurrentTime +is not acceptable. +.IP \fIconvert_callback\fP 1.25i +Specifies the procedure to be called whenever +the current value of the selection is requested. +.IP \fIlose_callback\fP 1.25i +Specifies the procedure to be called whenever +the widget has lost selection ownership, or NULL if the +owner is not interested in being notified. +.IP \fIdone_callback\fP 1.25i +Specifies the procedure called after the +requestor has received the entire selection, or NULL if +the owner is not interested in being notified. +.IP \fIcancel_callback\fP 1.25i +Specifies the callback procedure to be called +when a selection request aborts because a timeout expires, +or NULL if the owner is not interested in being notified. +.IP \fIclient_data\fP 1.25i +Specifies the argument to be passed to each of +the callback procedures when they are called. +.LP +.eM +The +.PN XtOwnSelectionIncremental +procedure informs the \*(xI +incremental selection mechanism that the specified widget wishes to +own the selection. It returns +.PN True +if the specified widget successfully becomes the selection owner or +.PN False +otherwise. +For more information about \fIselection\fP, \fItarget\fP, and +\fItime\fP, see Section 2.6 in the \fI\*(xC\fP. +.LP +If a done_callback procedure is specified, the client owns the storage allocated +for passing the value to the \*(xI. If \fIdone_callback\fP is NULL, +the convert_callback procedure must allocate storage using +.PN XtMalloc , +.PN XtRealloc , +or +.PN XtCalloc , +and the final value specified is freed by the +\*(xI when the transfer is complete. After a selection transfer +has started, only one of the done_callback or cancel_callback +procedures is invoked to indicate completion of the transfer. +.LP +The lose_callback procedure does not indicate completion of any in-progress +transfers; it is invoked at the time a +.PN SelectionClear +event is dispatched regardless of any active transfers, which are still +expected to continue. +.LP +A widget that becomes the selection owner using +.PN XtOwnSelectionIncremental +may use +.PN XtDisownSelection +to relinquish selection ownership. + +.NH 3 +Setting and Retrieving Selection Target Parameters +.XS +\*(SN Setting and Retrieving Selection Target Parameters +.XE +.LP +To specify target parameters for a selection request with a single target, +use +.PN XtSetSelectionParameters . +.LP +.IN "XtSetSelectionParameters" "" "@DEF@" +.sM +.FD 0 +void XtSetSelectionParameters(\fIrequestor\fP, \fIselection\fP, \fItype\fP, \ +\fIvalue\fP, \fIlength\fP, \fIformat\fP) +.br + Widget \fIrequestor\fP; +.br + Atom \fIselection\fP; +.br + Atom \fItype\fP; +.br + XtPointer \fIvalue\fP; +.br + unsigned long \fIlength\fP; +.br + int \fIformat\fP; +.FN +.IP \fIrequestor\fP 1i +Specifies the widget making the request. \*(cI +.IP \fIselection\fP 1i +Specifies the atom that names the selection. +.IP \fItype\fP 1i +Specifies the type of the property in which the parameters are passed. +.IP \fIvalue\fP 1i +Specifies a pointer to the parameters. +.IP \fIlength\fP 1i +Specifies the number of elements containing data in \fIvalue\fP, +each element of a size indicated by \fIformat\fP. +.IP \fIformat\fP 1i +Specifies the size in bits of the data in the elements of \fIvalue\fP. +.LP +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 +.PN XtGetSelectionValue +or to +.PN XtGetSelectionValueIncremental +specifying the same requestor widget and selection atom will generate a +.PN ConvertSelection +request referring to the property containing the parameters. If +.PN XtSetSelectionParameters +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. +.LP +.eM +The possible values of \fIformat\fP are 8, 16, or 32. If the format is 8, +the elements of \fIvalue\fP are assumed to be sizeof(char); +if 16, sizeof(short); if 32, sizeof(long). +.LP +To generate a MULTIPLE +target request with parameters for any of the multiple targets of the +selection request, precede individual calls to +.PN XtGetSelectionValue +and +.PN XtGetSelectionValueIncremental +with corresponding individual calls to +.PN XtSetSelectionParameters , +and enclose these all within +.PN XtCreateSelectionRequest +and +.PN XtSendSelectionRequest. +.PN XtGetSelectionValues +and +.PN XtGetSelectionValuesIncremental +cannot be used to make selection requests with parameterized targets. +.sp +.LP +To retrieve any target parameters needed to perform a selection conversion, +the selection owner calls +.PN XtGetSelectionParameters . +.LP +.IN "XtGetSelectionParameters" "" "@DEF@" +.sM +.FD 0 +void XtGetSelectionParameters(\fIowner\fP, \fIselection\fP, \ +\fIrequest_id\fP, \fItype_return\fP, \fIvalue_return\fP, + \fIlength_return\fP, \ +\fIformat_return\fP) +.br + Widget \fIowner\fP; +.br + Atom \fIselection\fP; +.br + XtRequestId \fIrequest_id\fP; +.br + Atom *\fItype_return\fP; +.br + XtPointer *\fIvalue_return\fP; +.br + unsigned long *\fIlength_return\fP; +.br + int *\fIformat_return\fP; +.FN +.IP \fIowner\fP 1i +Specifies the widget that owns the specified selection. +.IP \fIselection\fP 1i +Specifies the selection being processed. +.IP \fIrequest_id\fP 1i +Specifies the requestor id in the case of incremental selections, +or NULL in the case of atomic transfers. +.IP \fItype_return\fP 1i +Specifies a pointer to an atom in which the property type +of the parameters is stored. +.IP \fIvalue_return\fP 1i +Specifies a pointer into which a pointer to the parameters is to be stored. +A NULL is stored if no parameters accompany the request. +.IP \fIlength_return\fP 1i +Specifies a pointer into which the number of data elements +in \fIvalue_return\fP of size indicated by \fIformat_return\fP are stored. +.IP \fIformat_return\fP 1i +Specifies a pointer into which the size in bits of the parameter data +in the elements of \fIvalue\fP is stored. +.LP +.eM +.PN XtGetSelectionParameters +may be called only from within an +.PN XtConvertSelectionProc +or from within the first call to an +.PN XtConvertSelectionIncrProc +with a new request_id. +.LP +It is the responsibility of the caller to free the returned parameters using +.PN XtFree +when the parameters are no longer needed. + +.NH 3 +Generating MULTIPLE Requests +.XS +\*(SN Generating MULTIPLE Requests +.XE +.LP +To have the \*(xI bundle multiple calls to make selection requests into +a single request using a \s-1MULTIPLE\s+1 target, use +.PN XtCreateSelectionRequest +and +.PN XtSendSelectionRequest . +.LP +.IN "XtCreateSelectionRequest" "" "@DEF@" +.sM +.FD 0 +void XtCreateSelectionRequest(\fIrequestor\fP, \fIselection\fP) +.br + Widget \fIrequestor\fP; +.br + Atom \fIselection\fP; +.FN +.IP \fIrequestor\fP 1i +Specifies the widget making the request. \*(cI +.IP \fIselection\fP 1i +Specifies the particular selection desired. +.LP +.eM +When +.PN XtCreateSelectionRequest +is called, subsequent calls to +.PN XtGetSelectionValue , +.PN XtGetSelectionValueIncremental , +.PN XtGetSelectionValues , +and +.PN XtGetSelectionValuesIncremental , +with the requestor and selection as specified to +.PN XtCreateSelectionRequest , +are bundled into a single selection request with +multiple targets. The request is made by calling +.PN XtSendSelectionRequest . +.LP +.IN "XtSendSelectionRequest" "" "@DEF@" +.sM +.FD 0 +void XtSendSelectionRequest(\fIrequestor\fP, \fIselection\fP, \fItime\fP) +.br + Widget \fIrequestor\fP; +.br + Atom \fIselection\fP; +.br + Time \fItime\fP; +.FN +.IP \fIrequestor\fP 1i +Specifies the widget making the request. \*(cI +.IP \fIselection\fP 1i +Specifies the particular selection desired. +.IP \fItime\fP 1i +Specifies the timestamp that indicates when the selection request was +initiated. The value +.PN CurrentTime +is not acceptable. +.LP +.eM +When +.PN XtSendSelectionRequest +is called with a value of \fIrequestor\fP and \fIselection\fP matching +a previous call to +.PN XtCreateSelectionRequest , +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 +.PN XtGetSelectionValue , +.PN XtGetSelectionValueIncremental , +.PN XtGetSelectionValues , +and +.PN XtGetSelectionValueIncremental +are invoked. +.LP +Multi-threaded applications should lock the application context before +calling +.PN XtCreateSelectionRequest +and release the lock after calling +.PN XtSendSelectionRequest +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. +.sp +.LP +To relinquish the composition of a MULTIPLE request without sending it, use +.PN XtCancelSelectionRequest . +.LP +.IN "XtCancelSelectionRequest" "" "@DEF@" +.sM +.FD 0 +void XtCancelSelectionRequest(\fIrequestor\fP, \fIselection\fP) +.br + Widget \fIrequestor\fP; +.br + Atom \fIselection\fP; +.FN +.IP \fIrequestor\fP 1i +Specifies the widget making the request. \*(cI +.IP \fIselection\fP 1i +Specifies the particular selection desired. +.LP +.eM +When +.PN XtCancelSelectionRequest +is called, any requests queued since the last call to +.PN XtCreateSelectionRequest +for the same widget and selection are discarded +and any resources reserved are released. +A subsequent call to +.PN XtSendSelectionRequest +will not result in any request being made. +Subsequent calls to +.PN XtGetSelectionValue , +.PN XtGetSelectionValues , +.PN XtGetSelectionValueIncremental , +or +.PN XtGetSelectionValuesIncremental +will not be deferred. + +.NH 3 +Auxiliary Selection Properties +.XS +\*(SN Auxiliary Selection Properties +.XE +.LP +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 circumstances and +thereby reduce the number of unique atoms created in the server, +the \*(xI provides two interfaces for acquiring temporary property names. +.LP +To acquire a temporary property name atom for use in a selection +request, the client may call +.PN XtReservePropertyAtom . +.LP +.IN "XtReservePropertyAtom" "" "@DEF@" +.sM +.FD 0 +Atom XtReservePropertyAtom(\fIw\fP) +.br + Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget making a selection request. +.LP +.eM +.PN XtReservePropertyAtom +returns an atom that may be used as a property name during selection +requests involving the specified widget. +As long as the atom remains reserved, it is unique with respect to all +other reserved atoms for the widget. +.LP +To return a temporary property name atom for reuse and to delete +the property named by that atom, use +.PN XtReleasePropertyAtom . +.LP +.IN "XtReleasePropertyAtom" "" "@DEF@" +.sM +.FD 0 +void XtReleasePropertyAtom(\fIw\fP, \fIatom\fP) +.br + Widget \fIw\fP; +.br + Atom \fIatom\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget used to reserve the property name atom. +.IP \fIatom\fP 1i +Specifies the property name atom returned by +.PN XtReservePropertyAtom +that is to be released for reuse. +.LP +.eM +.PN XtReleasePropertyAtom +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 \fIatom\fP does not +specify a value returned by +.PN XtReservePropertyAtom +for the specified widget, the results are undefined. + +.NH 3 +Retrieving the Most Recent Timestamp +.XS +\*(SN Retrieving the Most Recent Timestamp +.XE +.LP +To retrieve the timestamp from the most recent call to +.PN XtDispatchEvent +that contained a timestamp, use +.PN XtLastTimestampProcessed . +.LP +.IN "XtLastTimestampProcessed" "" "@DEF@" +.sM +.FD 0 +Time XtLastTimestampProcessed(\fIdisplay\fP) +.br + Display *\fIdisplay\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies an open display connection. +.LP +.eM +If no +.PN KeyPress , +.PN KeyRelease , +.PN ButtonPress , +.PN ButtonRelease , +.PN MotionNotify , +.PN EnterNotify , +.PN LeaveNotify , +.PN PropertyNotify , +or +.PN SelectionClear +event has yet been passed to +.PN XtDispatchEvent +for the specified display, +.PN XtLastTimestampProcessed +returns zero. + +.NH 3 +Retrieving the Most Recent Event +.XS +\*(SN Retrieving the Most Recent Event +.XE +.LP +To retrieve the event from the most recent call to +.PN XtDispatchEvent +for a specific display, use +.PN XtLastEventProcessed . +.LP +.IN "XtLastEventProcessed" "" "@DEF@" +.sM +.FD 0 +XEvent *XtLastEventProcessed(\fIdisplay\fP) +.br + Display *\fIdisplay\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display connection from which to retrieve the event. +.LP +.eM +Returns the last event passed to +.PN XtDispatchEvent +for the specified display. Returns NULL if there is no such event. +The client must not modify the contents of the returned event. + +.NH 2 +Merging Exposure Events into a Region +.XS +\*(SN Merging Exposure Events into a Region +.XE +.LP +The \*(xI provide an +.PN XtAddExposureToRegion +utility function that merges +.PN Expose +and +.PN GraphicsExpose +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 \fI\*(xL\fP. +.sp +.LP +To merge +.PN Expose +and +.PN GraphicsExpose +events into a region, use +.PN XtAddExposureToRegion . +.LP +.IN "XtAddExposureToRegion" "" "@DEF@" +.sM +.FD 0 +void XtAddExposureToRegion(\fIevent\fP, \fIregion\fP) +.br + XEvent *\fIevent\fP; +.br + Region \fIregion\fP; +.FN +.IP \fIevent\fP 1i +Specifies a pointer to the +.PN Expose +or +.PN GraphicsExpose +event. +.IP \fIregion\fP 1i +Specifies the region object (as defined in +.Pn < X11/Xutil.h >). +.LP +.eM +The +.PN XtAddExposureToRegion +function computes the union of the rectangle defined by the exposure +event and the specified region. +Then it stores the results back in \fIregion\fP. +If the event argument is not an +.PN Expose +or +.PN GraphicsExpose +event, +.PN XtAddExposureToRegion +returns without an error and without modifying \fIregion\fP. +.LP +This function is used by the exposure compression mechanism; +see Section 7.9.3. + +.NH 2 +Translating Widget Coordinates +.XS +\fB\*(SN Translating Widget Coordinates\fP +.XE +.LP +To translate an x-y coordinate pair from widget coordinates to root +window absolute coordinates, use +.PN XtTranslateCoords . +.LP +.IN "XtTranslateCoords" "" "@DEF@" +.sM +.FD 0 +void XtTranslateCoords(\fIw\fP, \fIx\fP, \fIy\fP, \fIrootx_return\fP, \ +\fIrooty_return\fP) +.br + Widget \fIw\fP; +.br + Position \fIx\fP, \fIy\fP; +.br + Position *\fIrootx_return\fP, *\fIrooty_return\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget. \*(rI +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the widget-relative x and y coordinates. +.IP \fIrootx_return\fP 1i +.br +.ns +.IP \fIrooty_return\fP 1i +Return the root-relative x and y coordinates. +.LP +.eM +While +.PN XtTranslateCoords +is similar to the Xlib +.PN XTranslateCoordinates +function, it does not generate a server request because all the required +information already is in the widget's data structures. + +.NH 2 +Translating a Window to a Widget +.XS +\fB\*(SN Translating a Window to a Widget\fP +.XE +.LP +To translate a given window and display pointer into a widget instance, use +.PN XtWindowToWidget . +.LP +.IN "XtWindowToWidget" "" "@DEF@" +.sM +.FD 0 +Widget XtWindowToWidget(\fIdisplay\fP, \fIwindow\fP) +.br + Display *\fIdisplay\fP; +.br + Window \fIwindow\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display on which the window is defined. +.IP \fIwindow\fP 1i +Specifies the drawable for which you want the widget. +.LP +.eM +If there is a realized widget whose window is the specified drawable on +the specified \fIdisplay\fP, +.PN XtWindowToWidget +returns that widget. +If not and if the drawable has been associated with a widget through +.PN XtRegisterDrawable , +.PN XtWindowToWidget +returns the widget associated with the drawable. In other cases it +returns NULL. + +.NH 2 +Handling Errors +.XS +\fB\*(SN Handling Errors\fP +.XE +.LP +The \*(xI 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. +.LP +Two levels of interface are provided: +.IP \(bu 5 +A high-level interface that takes an error +name and class and retrieves the error message text from +an error resource database. +.IP \(bu 5 +A low-level interface that takes a simple string to display. +.LP +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. +.NT +The application-context-specific error handling is not +implemented on many systems, although the interfaces are +always present. +Most implementations 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. +.NE +.sp +.LP +To obtain the error database (for example, to merge with +an application- or widget-specific database), use +.PN XtAppGetErrorDatabase . +.LP +.IN "XtAppGetErrorDatabase" "" "@DEF@" +.sM +.FD 0 +XrmDatabase *XtAppGetErrorDatabase(\^\fIapp_context\fP\^) +.br + XtAppContext \fIapp_context\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.LP +.eM +The +.PN XtAppGetErrorDatabase +function returns the address of the error database. +The \*(xI do a lazy binding of the error database and do not merge in the +database file until the first call to +.PN XtAppGetErrorDatabaseText . +.LP +For a complete listing of all errors and warnings +that can be generated by the \*(xI, see Appendix D. +.sp +.LP +The high-level error and warning handler procedure pointers are of type +.PN XtErrorMsgHandler . +.LP +.IN "XtErrorMsgHandler" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtErrorMsgHandler)(String, String, String, String, \ +String*, Cardinal*); +.br + String \fIname\fP; +.br + String \fItype\fP; +.br + String \fIclass\fP; +.br + String \fIdefaultp\fP; +.br + String *\fIparams\fP; +.br + Cardinal *\fInum_params\fP; +.FN +.IP \fIname\fP 1i +Specifies the name to be concatenated with the specified type to form +the resource name of the error message. +.IP \fItype\fP 1i +Specifies the type to be concatenated with the name to form the +resource name of the error message. +.IP \fIclass\fP 1i +Specifies the resource class of the error message. +.IP \fIdefaultp\fP 1i +Specifies the default message to use if no error database entry is found. +.IP \fIparams\fP 1i +Specifies a pointer to a list of parameters to be substituted in the message. +.IP \fInum_params\fP 1i +Specifies the number of entries in \fIparams\fP. +.LP +.eM +The specified name can be a general kind of error, +like ``invalidParameters'' or ``invalidWindow'', +and the specified type gives extra information +such as the name of the routine in which the error was detected. +Standard +.PN printf +notation is used to substitute the parameters into the message. +.sp +.LP +An error message handler can obtain the error database text for an +error or a warning by calling +.PN XtAppGetErrorDatabaseText . +.LP +.IN "XtAppGetErrorDatabaseText" "" "@DEF@" +.sM +.FD 0 +void XtAppGetErrorDatabaseText(\fIapp_context\fP, \fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \fIbuffer_return\fP, \fInbytes\fP, \fIdatabase\fP) +.br + XtAppContext \fIapp_context\fP; +.br + String \fIname\fP, \fItype\fP, \fIclass\fP; +.br + String \fIdefault\fP; +.br + String \fIbuffer_return\fP; +.br + int \fInbytes\fP; +.br + XrmDatabase \fIdatabase\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fIname\fP 1i +.br +.ns +.IP \fItype\fP 1i +Specify the name and type concatenated to form the resource name +of the error message. +.IP \fIclass\fP 1i +Specifies the resource class of the error message. +.IP \fIdefault\fP 1i +Specifies the default message to use if an error database entry is not found. +.IP \fIbuffer_return\fP 1i +Specifies the buffer into which the error message is to be returned. +.IP \fInbytes\fP 1i +Specifies the size of the buffer in bytes. +.IP \fIdatabase\fP 1i +Specifies the name of the alternative database to be used, +or NULL if the application context's error database is to be used. +.LP +.eM +The +.PN XtAppGetErrorDatabaseText +returns the appropriate message 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 \fIname\fP and \fItype\fP are concatenated with a single ``.'' +between them and the \fIclass\fP is concatenated with itself with a +single ``.'' if it does not already contain a ``.''. +.sp +.LP +To return the application name and class as passed to +.PN XtDisplayInitialize +for a particular Display, use +.PN XtGetApplicationNameAndClass . +.LP +.IN "XtGetApplicationNameAndClass" "" "@DEF@" +.sM +.FD 0 +void XtGetApplicationNameAndClass(\fIdisplay\fP, \fIname_return\fP, \ +\fIclass_return\fP) +.br + Display* \fIdisplay\fP; +.br + String* \fIname_return\fP; +.br + String* \fIclass_return\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies an open display connection that has been initialized with +.PN XtDisplayInitialize . +.IP \fIname_return\fP 1i +Returns the application name. +.IP \fIclass_return\fP 1i +Returns the application class. +.LP +.eM +.PN XtGetApplicationNameAndClass +returns the application name and class passed to +.PN XtDisplayInitialize +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 \*(xI and must not be modified +or freed by the caller. +.sp +.LP +To register a procedure to be called on fatal error conditions, use +.PN XtAppSetErrorMsgHandler . +.LP +.IN "XtAppSetErrorMsgHandler" "" "@DEF@" +.sM +.FD 0 +XtErrorMsgHandler XtAppSetErrorMsgHandler(\fIapp_context\fP, \fImsg_handler\fP) +.br + XtAppContext \fIapp_context\fP; +.br + XtErrorMsgHandler \fImsg_handler\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fImsg_handler\fP 1i +Specifies the new fatal error procedure, which should not return. +.LP +.eM +.PN XtAppSetErrorMsgHandler +returns a pointer to the previously +installed high-level fatal error handler. +The default high-level fatal error handler provided by the \*(xI is named +.PN _XtDefaultErrorMsg +.IN "_XtDefaultErrorMsg" "" "@DEF" +and constructs a string from the error resource database and calls +.PN XtError . +Fatal error message handlers should not return. +If one does, +subsequent \*(xI behavior is undefined. +.sp +.LP +To call the high-level error handler, use +.PN XtAppErrorMsg . +.LP +.IN "XtAppErrorMsg" "" "@DEF@" +.sM +.FD 0 +void XtAppErrorMsg(\fIapp_context\fP, \fIname\fP, \fItype\fP, \fIclass\fP, \ +\fIdefault\fP, \ \fIparams\fP, \fInum_params\fP) +.br + XtAppContext \fIapp_context\fP; +.br + String \fIname\fP; +.br + String \fItype\fP; +.br + String \fIclass\fP; +.br + String \fIdefault\fP; +.br + String *\fIparams\fP; +.br + Cardinal *\fInum_params\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fIname\fP 1i +Specifies the general kind of error. +.IP \fItype\fP 1i +Specifies the detailed name of the error. +.IP \fIclass\fP 1i +Specifies the resource class. +.IP \fIdefault\fP 1i +Specifies the default message to use if an error database entry is not found. +.IP \fIparams\fP 1i +Specifies a pointer to a list of values to be stored in the message. +.IP \fInum_params\fP 1i +Specifies the number of entries in \fIparams\fP. +.LP +.eM +The \*(xI internal errors all have class +``XtToolkitError''. +.sp +.LP +To register a procedure to be called on nonfatal error conditions, use +.PN XtAppSetWarningMsgHandler . +.LP +.IN "XtAppSetWarningMsgHandler" "" "@DEF@" +.sM +.FD 0 +XtErrorMsgHandler XtAppSetWarningMsgHandler(\fIapp_context\fP, \fImsg_handler\fP) +.br + XtAppContext \fIapp_context\fP; +.br + XtErrorMsgHandler \fImsg_handler\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fImsg_handler\fP 1i +Specifies the new nonfatal error procedure, which usually returns. +.LP +.eM +.PN XtAppSetWarningMsgHandler +returns a pointer to the previously +installed high-level warning handler. +The default high-level warning handler provided by the \*(xI is named +.PN _XtDefaultWarningMsg +.IN "_XtDefaultWarningMsg" "" "@DEF@" +and constructs a string +from the error resource database and calls +.PN XtWarning . +.sp +.LP +To call the installed high-level warning handler, use +.PN XtAppWarningMsg . +.LP +.IN "XtAppWarningMsg" "" "@DEF@" +.sM +.FD 0 +void XtAppWarningMsg(\fIapp_context\fP, \fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \fIparams\fP, \fInum_params\fP) +.br + XtAppContext \fIapp_context\fP; +.br + String \fIname\fP; +.br + String \fItype\fP; +.br + String \fIclass\fP; +.br + String \fIdefault\fP; +.br + String *\fIparams\fP; +.br + Cardinal *\fInum_params\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fIname\fP 1i +Specifies the general kind of error. +.IP \fItype\fP 1i +Specifies the detailed name of the error. +.IP \fIclass\fP 1i +Specifies the resource class. +.IP \fIdefault\fP 1i +Specifies the default message to use if an error database entry is not found. +.IP \fIparams\fP 1i +Specifies a pointer to a list of values to be stored in the message. +.IP \fInum_params\fP 1i +Specifies the number of entries in \fIparams\fP. +.LP +.eM +The \*(xI internal warnings all have class +``XtToolkitError''. +.sp +.LP +The low-level error and warning handler procedure pointers are of type +.PN XtErrorHandler . +.LP +.IN "XtErrorHandler" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtErrorHandler)(String); +.br + String \fImessage\fP; +.FN +.IP \fImessage\fP 1i +Specifies the error message. +.LP +.eM +The error handler should display the message string in some appropriate fashion. +.sp +.LP +To register a procedure to be called on fatal error conditions, use +.PN XtAppSetErrorHandler . +.LP +.IN "XtAppSetErrorHandler" "" "@DEF@" +.sM +.FD 0 +XtErrorHandler XtAppSetErrorHandler(\fIapp_context\fP, \fIhandler\fP) +.br + XtAppContext \fIapp_context\fP; +.br + XtErrorHandler \fIhandler\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fIhandler\fP 1i +Specifies the new fatal error procedure, which should not return. +.LP +.eM +.PN XtAppSetErrorHandler +returns a pointer to the previously installed +low-level fatal error handler. +The default low-level error handler provided by the \*(xI is +.PN _XtDefaultError . +.IN "_XtDefaultError" "" "@DEF@" +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 \*(xI behavior is undefined. +.sp +.LP +To call the installed fatal error procedure, use +.PN XtAppError . +.LP +.IN "XtAppError" "" "@DEF@" +.sM +.FD 0 +void XtAppError(\fIapp_context\fP, \fImessage\fP) +.br + XtAppContext \fIapp_context\fP; +.br + String \fImessage\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fImessage\fP 1i +Specifies the message to be reported. +.LP +.eM +Most programs should use +.PN XtAppErrorMsg , +not +.PN XtAppError , +to provide for customization and internationalization of error messages. +.sp +.LP +To register a procedure to be called on nonfatal error conditions, use +.PN XtAppSetWarningHandler . +.LP +.IN "XtAppSetWarningHandler" "" "@DEF@" +.sM +.FD 0 +XtErrorHandler XtAppSetWarningHandler(\fIapp_context\fP, \fIhandler\fP) +.br + XtAppContext \fIapp_context\fP; +.br + XtErrorHandler \fIhandler\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fIhandler\fP 1i +Specifies the new nonfatal error procedure, which usually returns. +.LP +.eM +.PN XtAppSetWarningHandler +returns a pointer to the previously installed +low-level warning handler. +The default low-level warning handler provided by the \*(xI is +.PN _XtDefaultWarning . +.IN "_XtDefaultWarning" "" "@DEF@" +On POSIX-based systems, +it prints the message to standard error and returns to the caller. +.sp +.LP +To call the installed nonfatal error procedure, use +.PN XtAppWarning . +.LP +.IN "XtAppWarning" "" "@DEF@" +.sM +.FD 0 +void XtAppWarning(\fIapp_context\fP, \fImessage\fP) +.br + XtAppContext \fIapp_context\fP; +.br + String \fImessage\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fImessage\fP 1i +Specifies the nonfatal error message to be reported. +.LP +.eM +Most programs should use +.PN XtAppWarningMsg , +not +.PN XtAppWarning , +to provide for customization and internationalization of warning messages. + +.NH 2 +Setting WM_COLORMAP_WINDOWS +.XS +\fB\*(SN Setting WM_COLORMAP_WINDOWS\fP +.XE +.LP +A client may set the value of the \s-1WM_COLORMAP_WINDOWS\s+1 +.IN "WM_COLORMAP_WINDOWS" "" "@DEF@" +property on a widget's window by calling +.PN XtSetWMColormapWindows . +.LP +.IN "XtSetWMColormapWindows" "" "@DEF@" +.sM +.FD 0 +void XtSetWMColormapWindows(\fIwidget\fP, \fIlist\fP, \fIcount\fP) +.br + Widget \fIwidget\fP; +.br + Widget* \fIlist\fP; +.br + Cardinal \fIcount\fP; +.FN +.IP \fIwidget\fP 1i +Specifies the widget on whose window the \s-1WM_COLORMAP_WINDOWS\s+1 +property is stored. \*(cI +.IP \fIlist\fP 1i +Specifies a list of widgets whose windows are potentially to be +listed in the \s-1WM_COLORMAP_WINDOWS\s+1 property. +.IP \fIcount\fP 1i +Specifies the number of widgets in \fIlist\fP. +.LP +.eM +.PN XtSetWMColormapWindows +returns immediately if \fIwidget\fP is not realized or if \fIcount\fP is 0. +Otherwise, +.PN XtSetWMColormapWindows +constructs an ordered list of windows +by examining each widget in \fIlist\fP 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. +.LP +Finally, +.PN XtSetWMColormapWindows +stores the resulting window list in the \s-1WM_COLORMAP_WINDOWS\s+1 +property on the specified widget's window. +Refer to Section 4.1.8 in the \fI\*(xC\fP for details of +the semantics of the \s-1WM_COLORMAP_WINDOWS\s+1 property. + +.NH 2 +Finding File Names +.XS +\fB\*(SN Finding File Names\fP +.XE +.LP +The \*(xI provide procedures to look for a file by name, allowing +string substitutions in a list of file specifications. Two +routines are provided for this: +.PN XtFindFile +and +.PN XtResolvePathname . +.PN XtFindFile +uses an arbitrary set of client-specified substitutions, and +.PN XtResolvePathname +uses a set of standard substitutions corresponding +to the \fIX/Open Portability Guide\fP language localization conventions. +Most applications should use +.PN XtResolvePathname . +.LP +A string substitution is defined by a list of +.PN Substitution +.IN "Substitution" "" "@DEF@" +entries. +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + char match; + String substitution; +} SubstitutionRec, *Substitution; +.De +.eM +.LP +File name evaluation is handled in an operating-system-dependent +fashion by an +.PN XtFilePredicate +.IN "XtFilePredicate" "" "@DEF@" +procedure. +.LP +.sM +.FD 0 +typedef Boolean (*XtFilePredicate)(String); +.br + String \fIfilename\fP; +.FN +.IP \fIfilename\fP 1i +Specifies a potential filename. +.LP +.eM +A file predicate procedure is called with a string that is +potentially a file name. It should return +.PN True +if this string specifies a file that is appropriate for the intended use and +.PN False +otherwise. +.sp +.LP +To search for a file using substitutions in a path list, use +.PN XtFindFile . +.LP +.IN "XtFindFile" "" "@DEF@" +.sM +.FD 0 +String XtFindFile(\fIpath\fP, \fIsubstitutions\fP, \fInum_substitutions\fP, \ +\fIpredicate\fP) +.br + String \fIpath\fP; +.br + Substitution \fIsubstitutions\fP; +.br + Cardinal \fInum_substitutions\fP; +.br + XtFilePredicate \fIpredicate\fP; +.FN +.IP \fIpath\fP 1.2i +Specifies a path of file names, including substitution characters. +.IP \fIsubstitutions\fP 1.2i +Specifies a list of substitutions to make into the path. +.IP \fInum_substitutions\fP 1.2i +Specifies the number of substitutions passed in. +.IP \fIpredicate\fP 1.2i +Specifies a procedure called to judge each potential file name, or NULL. +.LP +.eM +The \fIpath\fP parameter specifies a string that consists of a series of +potential file names delimited by colons. Within each name, the +percent character specifies a string substitution 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, +.PN XtFindFile +looks through the +specified \fIsubstitutions\fP for that character in the \fImatch\fP field +and, if found, +replaces the percent and match characters with the string in the +corresponding \fIsubstitution\fP field. A \fIsubstitution\fP 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, +.PN XtFindFile +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 +.PN XtFindFile +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 +.PN True ; +this string is the return value for +.PN XtFindFile . +If no string yields a +.PN True +return from the predicate, +.PN XtFindFile +returns NULL. +.LP +If the \fIpredicate\fP parameter is NULL, an internal procedure that checks +if the file exists, is readable, and is not a directory is used. +.LP +It is the responsibility of the caller to free the returned string using +.PN XtFree +when it is no longer needed. +.sp +.LP +To search for a file using standard substitutions in a path list, use +.PN XtResolvePathname . +.LP +.IN "XtResolvePathname" "" "@DEF@" +.sM +.FD 0 +String XtResolvePathname(\fIdisplay\fP, \fItype\fP, \fIfilename\fP, \fIsuffix\fP, \ +\fIpath\fP, \fIsubstitutions\fP, \fInum_substitutions\fP, \fIpredicate\fP) +.br + Display *\fIdisplay\fP; +.br + String \fItype\fP, \fIfilename\fP, \fIsuffix\fP, \fIpath\fP; +.br + Substitution \fIsubstitutions\fP; +.br + Cardinal \fInum_substitutions\fP; +.br + XtFilePredicate \fIpredicate\fP; +.FN +.IP \fIdisplay\fP 1.2i +Specifies the display to use to find the language for language substitutions. +.IP \fItype\fP +.br +.ns +.IP \fIfilename\fP +.br +.ns +.IP \fIsuffix\fP 1.2i +Specify values to substitute into the path. +.IP \fIpath\fP 1.2i +Specifies the list of file specifications, or NULL. +.IP \fIsubstitutions\fP 1.2i +Specifies a list of additional substitutions to make into the path, or NULL. +.IP \fInum_substitutions\fP 1.2i +Specifies the number of entries in \fIsubstitutions\fP. +.IP \fIpredicate\fP 1.2i +Specifies a procedure called to judge each potential file name, or NULL. +.LP +.eM +The substitutions specified by +.PN XtResolvePathname +are determined from the value of the language string retrieved by +.PN XtDisplayInitialize +for the specified display. +To set the +language for all applications specify ``*xnlLanguage: \fIlang\fP'' in the +resource database. +.IN "xnlLanguage" +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 accomplished is implementation-defined, +and the \*(xI make no interpretation of the parts other +than to use them in substitutions as described below. +.LP +.PN XtResolvePathname +calls +.PN XtFindFile +with the following substitutions +in addition to any passed by the caller and returns the value returned by +.PN XtFindFile : +.IP %N 5 +The value of the \fIfilename\fP parameter, or the application's +class name if \fIfilename\fP is NULL. +.IP %T 5 +The value of the \fItype\fP parameter. +.IP %S 5 +The value of the \fIsuffix\fP parameter. +.IP %L 5 +The language string associated with the specified display. +.IP %l 5 +The language part of the display's language string. +.IP %t 5 +The territory part of the display's language string. +.IP %c 5 +The codeset part of the display's language string. +.IP %C 5 +The customization string retrieved from the resource +database associated with \fIdisplay\fP. +.IP %D 5 +The value of the implementation-specific default path. +.LP +If a path is passed to +.PN XtResolvePathname , +it is passed along to +.PN XtFindFile . +If the \fIpath\fP argument is NULL, the value of the +.PN \s-1XFILESEARCHPATH\s+1 +.IN "XFILESEARCHPATH" "" "@DEF@" +environment variable is passed to +.PN XtFindFile . +If +.PN \s-1XFILESEARCHPATH\s+1 +is not defined, an implementation-specific default path is used +that contains at least six entries. These entries +must contain the following substitutions: + +.nf +.ta .3i 2i 2.5i +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 +.fi + +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, \fB%N%S\fP is inserted between them. +.LP +The \fItype\fP 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''. +.LP +The \fIsuffix\fP parameter is intended to be appended to the file name. +Possible values might include ``.txt'', ``.dat'', and ``.bm''. +.LP +A suggested value for the default path on POSIX-based systems is +.IP +/usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:\\ +.br +/usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:\\ +.br +/usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S + +.LP +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 \fItype\fP +parameter is used as a subdirectory of the language directory or of +/usr/lib/X11, and \fIsuffix\fP is appended to the file name. +.LP +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 +.PN \s-1XFILESEARCHPATH\s+1 +to +.IP +%D:ourdir/%T/%N%C:ourdir/%T/%N +.LP +The customization string is obtained by querying the resource database +currently associated with the display (the database returned by +.PN XrmGetDatabase ) +for the resource \fIapplication_name\fP.customization, class +\fIapplication_class\fP.Customization, where \fIapplication_name\fP +and \fIapplication_class\fP are the values returned by +.PN XtGetApplicationNameAndClass . +If no value is specified in the database, the empty string is used. +.LP +It is the responsibility of the caller to free the returned string using +.PN XtFree +when it is no longer needed. + +.NH 2 +Hooks for External Agents +.XS +\fB\*(SN Hooks for External Agents\fP +.XE +.LP +Applications may register +functions that are called at a particular control points in the \*(xI. +These functions are intended to be used to provide notification +of an \*Q\*(tk event\*U, 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 control points containing such registration hooks are identified +in a \*Qhook registration\*U object. +.LP +To retrieve the hook registration widget, use +.PN XtHooksOfDisplay . +.LP +.IN "XtHooksOfDisplay" "" "@DEF@" +.sM +.FD 0 +Widget XtHooksOfDisplay(\fIdisplay\fP) +.br + Display *\fIdisplay\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the desired display. +.LP +.eM +The class of this object is a private, implementation-dependent +subclass of +.PN Object . +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 parentless shells. All of the callback lists are initially +empty. When a display is closed, the hook object associated with it +is destroyed. +.LP +The following procedures can be called with the hook registration object +as an argument: +.sp +.IP +.PN XtAddCallback , +.PN XtAddCallbacks , +.PN XtRemoveCallback , +.PN XtRemoveCallbacks , +.PN XtRemoveAllCallbacks , +.PN XtCallCallbacks , +.PN XtHasCallbacks , +.PN XtCallCallbackList +.IP +.PN XtClass , +.PN XtSuperclass , +.PN XtIsSubclass , +.PN XtCheckSubclass , +.PN XtIsObject , +.PN XtIsRectObj , +.PN XtIsWidget , +.PN XtIsComposite , +.PN XtIsConstraint , +.PN XtIsShell , +.PN XtIsOverrideShell , +.PN XtIsWMShell , +.PN XtIsVendorShell , +.PN XtIsTransientShell , +.PN XtIsToplevelShell , +.PN XtIsApplicationShell , +.PN XtIsSessionShell +.IP +.PN XtWidgetToApplicationContext +.IP +.PN XtName , +.PN XtParent , +.PN XtDisplayOfObject , +.PN XtScreenOfObject +.IP +.PN XtSetValues , +.PN XtGetValues , +.PN XtVaSetValues , +.PN XtVaGetValues +.sp +.LP + +.NH 3 +Hook Object Resources +.XS +\fB\*(SN Hook Object Resources\fP +.XE +.LP +The resource names, classes, and representation types that are specified +in the hook object resource list are: +.KS +.TS +lw(1.5i) lw(1.5i) lw(2.5i) . +_ +.sp 6p +Name Class Representation +.sp 6p +_ +.sp 6p +XtNcreateHook XtCCallback XtRCallback +XtNchangeHook XtCCallback XtRCallback +XtNconfigureHook XtCCallback XtRCallback +XtNgeometryHook XtCCallback XtRCallback +XtNdestroyHook XtCCallback XtRCallback +XtNshells XtCReadOnly XtRWidgetList +XtNnumShells XtCReadOnly XtRCardinal +.sp 6p +_ +.TE +.KE +.LP +Descriptions of each of these resources: +.LP +The XtNcreateHook callback list is called from: +.PN XtCreateWidget , +.PN XtCreateManagedWidget , +.PN XtCreatePopupShell , +.PN XtAppCreateShell , +and their corresponding varargs versions. +.LP +The \fIcall_data\fP parameter in a createHook callback may be +cast to type +.PN XtCreateHookData . +.LP +.IN "XtCreateHookData" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + String type; + Widget widget; + ArgList args; + Cardinal num_args; +} XtCreateHookDataRec, *XtCreateHookData; +.De +.eM +.LP +The \fItype\fP is set to +.PN XtHcreate , +\fIwidget\fP is the newly created widget, and \fIargs\fP and \fInum_args\fP +are the arguments passed to the create function. The callbacks are +called before returning from the create function. +.LP +The XtNchangeHook callback list is called from: +.IP +.PN XtSetValues , +.PN XtVaSetValues +.IP +.PN XtManageChild , +.PN XtManageChildren , +.PN XtUnmanageChild , +.PN XtUnmanageChildren +.IP +.PN XtRealizeWidget , +.PN XtUnrealizeWidget +.IP +.PN XtAddCallback , +.PN XtRemoveCallback , +.PN XtAddCallbacks, +.PN XtRemoveCallbacks , +.PN XtRemoveAllCallbacks +.IP +.PN XtAugmentTranslations , +.PN XtOverrideTranslations , +.PN XtUninstallTranslations +.IP +.PN XtSetKeyboardFocus , +.PN XtSetWMColormapWindows +.IP +.PN XtSetMappedWhenManaged , +.PN XtMapWidget , +.PN XtUnmapWidget +.IP +.PN XtPopup , +.PN XtPopupSpringLoaded , +.PN XtPopdown +.LP +.sp +.LP +The \fIcall_data\fP parameter in a changeHook callback may +be cast to type +.PN XtChangeHookData . +.IN "XtChangeHookData" "" "@DFEF@" +.LP +.KS +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + String type; + Widget widget; + XtPointer event_data; + Cardinal num_event_data; +} XtChangeHookDataRec, *XtChangeHookData; +.De +.eM +.KE +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtSetValues +or +.PN XtVaSetValues , +\fItype\fP is set to +.PN XtHsetValues , +\fIwidget\fP is the new widget passed to the set_values procedure, and +\fIevent_data\fP may be cast to type +.PN XtChangeHookSetValuesData . +.IN "XtChangeHookSetValuesData" "" "@DEF@" +.LP +.KS +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + Widget old, req; + ArgList args; + Cardinal num_args; +} XtChangeHookSetValuesDataRec, *XtChangeHookSetValuesData; +.De +.eM +.KE +.LP +The \fIold\fP, \fIreq\fP, \fIargs\fP, and \fInum_args\fP 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. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtManageChild +or +.PN XtManageChildren , +\fItype\fP is set to +.PN XtHmanageChildren , +\fIwidget\fP is the parent, \fIevent_data\fP may be cast to type +WidgetList and is the list of children being managed, and +\fInum_event_data\fP is the length of the widget list. +The callbacks are called after the children have been managed. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtUnmanageChild +or +.PN XtUnmanageChildren , +\fItype\fP is set to +.PN XtHunmanageChildren , +\fIwidget\fP is the parent, \fIevent_data\fP may be cast to type +WidgetList and is a list of the children being unmanaged, and +\fInum_event_data\fP is the length of the widget list. +The callbacks are called after the children have been unmanaged. +.LP +The changeHook callbacks are called twice as a result of a call to +.PN XtChangeManagedSet , +once after unmanaging and again after managing. +When the callbacks are called the first time, \fItype\fP is set to +.PN XtHunmanageSet , +\fIwidget\fP is the parent, \fIevent_data\fP may be cast to type +WidgetList and is a list of the children being unmanaged, and +\fInum_event_data\fP is the length of the widget list. +When the callbacks are called the second time, the \fItype\fP is set to +.PN XtHmanageSet , +\fIwidget\fP is the parent, \fIevent_data\fP may be cast to type +WidgetList and is a list of the children being managed, and +\fInum_event_data\fP is the length of the widget list. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtRealizeWidget , +the \fItype\fP is set to +.PN XtHrealizeWidget +and \fIwidget\fP is the widget being realized. +The callbacks are called after the widget has been realized. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtUnrealizeWidget , +the \fItype\fP is set to +.PN XtHunrealizeWidget , +and \fIwidget\fP is the widget being unrealized. +The callbacks are called after the widget has been unrealized. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtAddCallback , +\fItype\fP is set to +.PN XtHaddCallback , +\fIwidget\fP is the widget to which the callback is being added, and +\fIevent_data\fP 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. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtAddCallbacks , +the \fItype\fP is set to +.PN XtHaddCallbacks , +\fIwidget\fP is the widget to which the callbacks are being added, and +\fIevent_data\fP 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. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtRemoveCallback , +the \fItype\fP is set to +.PN XtHremoveCallback , +\fIwidget\fP is the widget from which the callback is being removed, and +\fIevent_data\fP 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. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtRemoveCallbacks , +the \fItype\fP is set to +.PN XtHremoveCallbacks , +\fIwidget\fP is the widget from which the callbacks are being removed, and +\fIevent_data\fP 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 widget. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtRemoveAllCallbacks , +the \fItype\fP is set to +.PN XtHremoveAllCallbacks +and \fIwidget\fP is the widget from which the callbacks are being removed. +The callbacks are called after the callbacks have been removed from the +widget. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtAugmentTranslations , +the \fItype\fP is set to +.PN XtHaugmentTranslations +and \fIwidget\fP is the widget whose translations are being modified. +The callbacks are called after the widget's translations have been +modified. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtOverrideTranslations , +the \fItype\fP is set to +.PN XtHoverrideTranslations +and \fIwidget\fP is the widget whose translations are being modified. +The callbacks are called after the widget's translations have been +modified. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtUninstallTranslations , +The \fItype\fP is +.PN XtHuninstallTranslations +and \fIwidget\fP is the widget whose translations are being uninstalled. +The callbacks are called after the widget's translations have been +uninstalled. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtSetKeyboardFocus , +the \fItype\fP is set to +.PN XtHsetKeyboardFocus +and \fIevent_data\fP may be cast to type Widget and is the value of +the descendant argument passed to \fBXtSetKeyboardFocus\fP. The +callbacks are called before returning from \fBXtSetKeyboardFocus\fP. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtSetWMColormapWindows , +\fItype\fP is set to +.PN XtHsetWMColormapWindows , +\fIevent_data\fP may be cast to type WidgetList and is the value of +the list argument passed to \fBXtSetWMColormapWindows\fP, and +\fInum_event_data\fP is the length of the list. The callbacks are +called before returning from \fBXtSetWMColormapWindows\fP. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtSetMappedWhenManaged , +the \fItype\fP is set to +.PN XtHsetMappedWhenManaged +and \fIevent_data\fP may be cast to type Boolean and is the value of +the mapped_when_managed argument passed to \fBXtSetMappedWhenManaged\fP. +The callbacks are called after setting the widget's mapped_when_managed +field and before realizing or unrealizing the widget. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtMapWidget , +the \fItype \fP is set to +.PN XtHmapWidget +and \fIwidget\fP is the widget being mapped. +The callbacks are called after mapping the widget. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtUnmapWidget , +the \fItype \fP is set to +.PN XtHunmapWidget +and \fIwidget\fP is the widget being unmapped. +The callbacks are called after unmapping the widget. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtPopup , +the \fItype\fP is set to +.PN XtHpopup , +\fIwidget\fP is the widget being popped up, and \fIevent_data\fP may +be cast to type XtGrabKind and is the value of the grab_kind argument +passed to \fBXtPopup\fP. +The callbacks are called before returning from \fBXtPopup\fP. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtPopupSpringLoaded , +the \fItype\fP is set to +.PN XtHpopupSpringLoaded +and \fIwidget\fP is the widget being popped up. +The callbacks are called +before returning from \fBXtPopupSpringLoaded\fP. +.LP +When the changeHook callbacks are called as a result of a call to +.PN XtPopdown , +the \fItype\fP is set to +.PN XtHpopdown +and \fIwidget\fP is the widget being popped down. +The callbacks are called +before returning from \fBXtPopdown\fP. +.LP +A widget set that exports interfaces that change application state +without employing the \*(xI library should invoke the change hook +itself. This is done by: +.sp +.Ds +.TA .5i 2i +.ta .5i 2i + XtCallCallbacks(XtHooksOfDisplay(dpy), XtNchangeHook, call_data); +.De +.sp +.LP +The XtNconfigureHook callback list is called any time the \*(xI +move, resize, or configure a widget and when +.PN XtResizeWindow +is called. +.LP +The \fIcall_data\fP parameter may be cast to type +.PN XtConfigureHookData. +.LP +.IN "XtConfigureHookData" "" "@DEF@" +.KS +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + String type; + Widget widget; + XtGeometryMask changeMask; + XWindowChanges changes; +} XtConfigureHookDataRec, *XtConfigureHookData; +.De +.eM +.KE +.sp +.LP +When the configureHook callbacks are called, the \fItype\fP is +.PN XtHconfigure , +\fIwidget\fP is the widget being configured, and \fIchangeMask\fP and +\fIchanges\fP reflect the changes made to the widget. The callbacks +are called after changes have been made to the widget. +.LP +The XtNgeometryHook callback list is called from +.PN XtMakeGeometryRequest +and +.PN XtMakeResizeRequest +once before and once after geometry negotiation occurs. +.LP +The \fIcall_data\fP parameter may be cast to type +.PN XtGeometryHookData . +.LP +.IN "XtGeometryHookData" "" "@DFEF@" +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + String type; + Widget widget; + XtWidgetGeometry* request; + XtWidgetGeometry* reply; + XtGeometryResult result; +} XtGeometryHookDataRec, *XtGeometryHookData; +.De +.eM +.sp +.LP +When the geometryHook callbacks are called prior to geometry negotiation, +the \fItype\fP is +.PN XtHpreGeometry , +\fIwidget\fP is the widget for which the request is being made, and +\fIrequest\fP is the requested geometry. +When the geometryHook callbacks +are called after geometry negotiation, the \fItype\fP is +.PN XtHpostGeometry , +\fIwidget\fP is the widget for which the request was made, \fIrequest\fP +is the requested geometry, \fIreply\fP is the resulting geometry granted, +and \fIresult\fP is the value returned from the geometry negotiation. +.LP +The XtNdestroyHook callback list is called when a widget is destroyed. +The \fIcall_data parameter\fP may be cast to type +.PN XtDestroyHookData . +.LP +.IN "XtDestroyHookData" "" "@DFEF@" +.sp +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + String type; + Widget widget; +} XtDestroyHookDataRec, *XtDestroyHookData; +.De +.eM +.sp +.LP +When the destroyHook callbacks are called as a result of a call to +.PN XtDestroyWidget , +the \fItype\fP is +.PN XtHdestroy +and \fIwidget\fP is the widget being destroyed. The callbacks are +called upon completion of phase one destroy for a widget. +.LP +The XtNshells and XtnumShells are read-only resources that report a +list of all parentless shell widgets associated with a display. +.LP +Clients who use these hooks must exercise caution in calling \*(xI +functions in order to avoid recursion. + +.NH 3 +Querying Open Displays +.XS +\fB\*(SN Querying Open Displays\fP +.XE +.LP +To retrieve a list of the Displays associated with an application context, +use +.PN XtGetDisplays . +.LP +.IN "XtGetDisplays" "" "@DEF@" +.sM +.FD 0 +void XtGetDisplays(\fIapp_context\fP, \fIdpy_return\fP, \fInum_dpy_return\fP) +.br + XtAppContext \fIapp_context\fP; +.br + Display ***\fIdpy_return\fP; +.br + Cardinal *\fInum_dpy_return\fP; +.FN +.IP \fIapp_context\fP 1.5i +Specifies the application context. +.IP \fIdpy_return\fP 1.5i +Returns a list of open Display connections in the specified application +context. +.IP \fInum_dpy_return\fP 1.5i +Returns the count of open Display connections in \fIdpy_return\fP. +.LP +.eM +\fBXtGetDisplays\fP may 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 +.PN XtFree . +.bp diff --git a/specs/CH12 b/specs/CH12 new file mode 100644 index 0000000..34e8ec7 --- /dev/null +++ b/specs/CH12 @@ -0,0 +1,1067 @@ +.\" $Xorg: CH12,v 1.3 2000/08/17 19:42:47 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 12\fP\s-1 + +\s+1\fBNonwidget Objects\fP\s-1 +.sp 2 +.nr H1 12 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 12 \(em Nonwidget Objects +.XE +.LP +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 +(Rectangle Object), and (\fIunnamed\fP), +and members of these classes +are referred to generically as \fIobjects\fP. By convention, the term +\fIwidget\fP refers only to objects that are a subclass of +Core, +and the term \fInonwidget\fP refers to objects that are not a subclass of +Core. +In the preceding portion of this specification, the interface +descriptions indicate explicitly whether the generic \fIwidget\fP argument +is restricted to particular 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 \*(xI routines. + +.NH 2 +Data Structures +.XS +\*(SN Data Structures +.XE +.LP +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 complete data structures +with filler for the widget fields they do not use. This +allows the static class initializers for existing widgets to remain +unchanged. + +.NH 2 +Object Objects +.XS +\fB\*(SN Object Objects\fP +.XE +.LP +.IN "Object" "" "@DEF@" +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 subclasses of +Object, +which is defined by the +.PN ObjectClassPart +and +.PN ObjectPart +structures. + +.NH 3 +ObjectClassPart Structure +.XS +\*(SN ObjectClassPart Structure +.XE +.LP +The common fields for all object classes are defined in the +.PN ObjectClassPart +structure. All fields have the same purpose, +function, and restrictions as the corresponding fields in +.PN CoreClassPart ; +fields whose +names are obj\fI\s+1n\s-1\fP for some integer \s+1\fIn\fP\s-1 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 +obj\fI\s+1n\s-1\fP fields with NULL or zero as appropriate to the type. +.LP +.IN "ObjectClassPart" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +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; +.De +.LP +.eM +The extension record defined for +.PN ObjectClassPart +with a \fIrecord_type\fP equal to +.PN \s-1NULLQUARK\s+1 +is +.PN ObjectClassExtensionRec . +.LP +.IN "ObjectClassExtensionRec" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +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; +.De +.LP +.eM +The prototypical +.PN ObjectClass +consists of just the +.PN ObjectClassPart . +.LP +.IN "ObjectClassRec" "" "@DEF@" +.IN "ObjectClass" "" "@DEF@" +.IN "objectClass" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _ObjectClassRec { + ObjectClassPart object_class; +} ObjectClassRec, *ObjectClass; +.De +.LP +.eM +The predefined class record and pointer for +.PN ObjectClassRec +are +.LP +In +.PN IntrinsicP.h : +.sM +.Ds 0 +extern ObjectClassRec objectClassRec; +.De +.LP +.eM +In +.PN Intrinsic.h : +.sM +.Ds 0 +extern WidgetClass objectClass; +.De +.LP +.eM +The opaque types +.PN Object +and +.PN ObjectClass +and the opaque variable +.PN objectClass +are defined for generic actions on objects. +The symbolic constant for the +.PN ObjectClassExtension +version identifier is +.PN XtObjectExtensionVersion +(see Section 1.6.12). +.PN Intrinsic.h +uses an incomplete structure definition to ensure that the +compiler catches attempts to access private data: +.LP +.sM +.Ds 0 +typedef struct _ObjectClassRec* ObjectClass; +.De +.LP +.eM + +.NH 3 +ObjectPart Structure +.XS +\*(SN ObjectPart Structure +.XE +.LP +The common fields for all object instances are defined in the +.PN ObjectPart +structure. All fields have the same meaning as the +corresponding fields in +.PN CorePart . +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.IN "ObjectPart" "" "@DEF@" +typedef struct _ObjectPart { + Widget self; + WidgetClass widget_class; + Widget parent; + Boolean being_destroyed; + XtCallbackList destroy_callbacks; + XtPointer constraints; +} ObjectPart; +.De +.LP +.eM +All object instances have the +Object +fields as their first component. The prototypical type +.PN Object +is defined with only this set of fields. +Various routines can cast object pointers, as needed, to specific +object types. +.LP +In +.PN IntrinsicP.h : +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _ObjectRec { + ObjectPart object; +} ObjectRec, *Object; +.De +.LP +.eM +.IN "ObjectRec" "" "@DEF@" +In +.PN Intrinsic.h : +.LP +.sM +.Ds 0 +typedef struct _ObjectRec *Object; +.De +.LP +.eM + +.NH 3 +Object Resources +.XS +\fB\*(SN Object Resources\fP +.XE +.LP +The resource names, classes, and representation types specified in the +.PN objectClassRec +resource list are: +.LP +.TS +lw(1.5i) lw(1.5i) lw(2.5i) . +_ +.sp 6p +Name Class Representation +.sp 6p +_ +.sp 6p +XtNdestroyCallback XtCCallback XtRCallback +.sp 6p +_ +.TE + +.NH 3 +ObjectPart Default Values +.XS +\fB\*(SN ObjectPart Default Values\fP +.XE +.LP +All fields in +.PN ObjectPart +have the same default values as the corresponding fields in +.PN CorePart . + +.NH 3 +Object Arguments to \*(xI Routines +.XS +\*(SN Object Arguments to \*(xI Routines +.XE +.LP +The WidgetClass arguments to the following procedures may be +.PN objectClass +or any subclass: +.sp +.IP +.PN XtInitializeWidgetClass , +.PN XtCreateWidget , +.PN XtVaCreateWidget +.IP +.PN XtIsSubclass , +.PN XtCheckSubclass +.IP +.PN XtGetResourceList , +.PN XtGetConstraintResourceList +.sp +.LP +The Widget arguments to the following procedures may be of class +Object +or any subclass: +.sp +.IP +.PN XtCreateWidget , +.PN XtVaCreateWidget +.IP +.PN XtAddCallback , +.PN XtAddCallbacks , +.PN XtRemoveCallback , +.PN XtRemoveCallbacks , +.PN XtRemoveAllCallbacks , +.PN XtCallCallbacks , +.PN XtHasCallbacks , +.PN XtCallCallbackList +.IP +.PN XtClass , +.PN XtSuperclass , +.PN XtIsSubclass , +.PN XtCheckSubclass , +.PN XtIsObject , +.PN XtIsRectObj , +.PN XtIsWidget , +.PN XtIsComposite , +.PN XtIsConstraint , +.PN XtIsShell , +.PN XtIsOverrideShell , +.PN XtIsWMShell , +.PN XtIsVendorShell , +.PN XtIsTransientShell , +.PN XtIsToplevelShell , +.PN XtIsApplicationShell , +.PN XtIsSessionShell +.IP +.PN XtIsManaged , +.PN XtIsSensitive +.br +(both will return +.PN False +if argument is not a subclass of +RectObj) +.IP +.PN XtIsRealized +.br +(returns the state of the nearest windowed ancestor +if class of argument is not a subclass of +Core) +.IP +.PN XtWidgetToApplicationContext +.IP +.PN XtDestroyWidget +.IP +.PN XtParent , +.PN XtDisplayOfObject , +.PN XtScreenOfObject , +.PN XtWindowOfObject +.IP +.PN XtSetKeyboardFocus +(descendant) +.IP +.PN XtGetGC , +.PN XtReleaseGC +.IP +.PN XtName +.IP +.PN XtSetValues , +.PN XtGetValues , +.PN XtVaSetValues , +.PN XtVaGetValues +.IP +.PN XtGetSubresources , +.PN XtGetApplicationResources , +.PN XtVaGetSubresources , +.PN XtVaGetApplicationResources +.IP +.PN XtConvert , +.PN XtConvertAndStore +.sp +.LP +The return value of the following procedures will be of class +Object +or a subclass: +.sp +.IP +.PN XtCreateWidget , +.PN XtVaCreateWidget +.IP +.PN XtParent +.IP +.PN XtNameToWidget +.sp +.LP +The return value of the following procedures will be +.PN objectClass +or a subclass: +.sp +.IP +.PN XtClass , +.PN XtSuperclass + +.NH 3 +Use of Objects +.XS +\fB\*(SN Use of Objects\fP +.XE +.LP +The +Object +class exists to enable programmers to use the \*(xI' +classing and resource-handling mechanisms for things smaller +and simpler than widgets. +Objects make obsolete many common uses of subresources as described in +Sections 9.4, 9.7.2.4, and 9.7.2.5. +.LP +Composite +widget classes that wish to accept nonwidget children must +set the \fIaccepts_objects\fP field in the +.PN CompositeClassExtension +structure to +.PN True . +.PN XtCreateWidget +will otherwise generate an error message on an attempt to create a +nonwidget child. +.LP +Of the classes defined by the \*(xI, +ApplicationShell +and +SessionShell +accept nonwidget children, and the class of any nonwidget child +must not be +.PN rectObjClass +or any subclass. The intent of allowing +Object +children of +ApplicationShell +and +SessionShell +is to provide clients a simple mechanism +for establishing the resource-naming root of an object hierarchy. + +.NH 2 +Rectangle Objects +.XS +\fB\*(SN Rectangle Objects\fP +.XE +.LP +The class of rectangle objects is a subclass of +Object +that represents +rectangular areas. It encapsulates the mechanisms for geometry +management and is called RectObj +.IN "RectObj" "" "@DEF@" +to avoid conflict with the Xlib +.PN Rectangle +data type. + +.NH 3 +RectObjClassPart Structure +.XS +\*(SN RectObjClassPart Structure +.XE +.LP +As with the +.PN ObjectClassPart +structure, all fields in the +.PN RectObjClassPart +structure have the same +purpose and function as the corresponding fields in +.PN CoreClassPart ; +fields whose names are rect\fI\s+1n\s-1\fP for some integer +\fI\s+1n\s-1\fP are not used for +RectObj, but exist to pad the data structure so that it matches +Core's +class record. The class record initialization must fill all +rect\fI\s+1n\s-1\fP fields with NULL or zero as appropriate to the type. +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.IN "RectObjClassPart" "" "@DEF@" +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; +.De +.LP +.eM +The +RectObj +class record consists of just the +.PN RectObjClassPart . +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.IN "RectObjClassRec" "" "@DEF@" +.IN "RectObjClass" "" "@DEF@" +typedef struct _RectObjClassRec { + RectObjClassPart rect_class; +} RectObjClassRec, *RectObjClass; +.De +.LP +.eM +The predefined class record and pointer for +.PN RectObjClassRec +are +.LP +In +.PN Intrinsic.h : +.LP +.sM +.Ds 0 +extern RectObjClassRec rectObjClassRec; +.De +.LP +.eM +In +.PN Intrinsic.h : +.LP +.sM +.Ds 0 +extern WidgetClass rectObjClass; +.De +.LP +.eM +The opaque types +.PN RectObj +and +.PN RectObjClass +and the opaque variable +.PN rectObjClass +are defined for generic actions on objects +whose class is RectObj or a subclass of +RectObj. +.PN Intrinsic.h +uses an incomplete structure definition to ensure that the compiler +catches attempts to access private data: +.LP +.sM +.Ds 0 +typedef struct _RectObjClassRec* RectObjClass; +.De +.LP +.eM + +.NH 3 +RectObjPart Structure +.XS +\*(SN RectObjPart Structure +.XE +.LP +In addition to the +.PN ObjectPart +fields, +RectObj +objects have the following fields defined in the +.PN RectObjPart +structure. All fields have the same meaning as the corresponding field in +.PN CorePart . +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.IN "RectObjPart" "" "@DEF@" +typedef struct _RectObjPart { + Position x, y; + Dimension width, height; + Dimension border_width; + Boolean managed; + Boolean sensitive; + Boolean ancestor_sensitive; +} RectObjPart; +.De +.LP +.eM +RectObj +objects have the RectObj fields immediately following the Object fields. +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.IN "RectObjRec" "" "@DEF@" +typedef struct _RectObjRec { + ObjectPart object; + RectObjPart rectangle; +} RectObjRec, *RectObj; +.De +.LP +.eM +In +.PN Intrinsic.h : +.LP +.sM +.Ds 0 +typedef struct _RectObjRec* RectObj; +.De +.LP +.eM + +.NH 3 +RectObj Resources +.XS +\fB\*(SN RectObj Resources\fP +.XE +.LP +The resource names, classes, and representation types that are specified in the +.PN rectObjClassRec +resource list are: +.TS +lw(1.5i) lw(1.5i) lw(2.5i) . +_ +.sp 6p +Name Class Representation +.sp 6p +_ +.sp 6p +XtNancestorSensitive XtCSensitive XtRBoolean +XtNborderWidth XtCBorderWidth XtRDimension +XtNheight XtCHeight XtRDimension +XtNsensitive XtCSensitive XtRBoolean +XtNwidth XtCWidth XtRDimension +XtNx XtCPosition XtRPosition +XtNy XtCPosition XtRPosition +.sp 6p +_ +.TE + +.NH 3 +RectObjPart Default Values +.XS +\fB\*(SN RectObjPart Default Values\fP +.XE +.LP +All fields in +.PN RectObjPart +have the same default values as the corresponding fields in +.PN CorePart . + +.NH 3 +Widget Arguments to \*(xI Routines +.XS +\fB\*(SN Widget Arguments to \*(xI Routines\fP +.XE +.LP +The WidgetClass arguments to the following procedures may be +.PN rectObjClass +or any subclass: +.sp +.IP +.PN XtCreateManagedWidget , +.PN XtVaCreateManagedWidget +.sp +.LP +The Widget arguments to the following procedures may be of class +RectObj +or any subclass: +.sp +.IP +.PN XtConfigureWidget , +.PN XtMoveWidget , +.PN XtResizeWidget +.IP +.PN XtMakeGeometryRequest , +.PN XtMakeResizeRequest +.IP +.PN XtManageChildren , +.PN XtManageChild , +.PN XtUnmanageChildren , +.PN XtUnmanageChild , +.PN XtChangeManagedSet +.IP +.PN XtQueryGeometry +.IP +.PN XtSetSensitive +.IP +.PN XtTranslateCoords +.sp +.LP +The return value of the following procedures will be of class +RectObj +or a subclass: +.sp +.IP +.PN XtCreateManagedWidget , +.PN XtVaCreateManagedWidget + +.NH 3 +Use of Rectangle Objects +.XS +\*(SN Use of Rectangle Objects +.XE +.LP +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 widgets. This can save memory +resources both in the server and in applications +but requires additional support code in the parent. +In the following +discussion, \fIrectobj\fP refers only to objects +whose class is RectObj or a subclass of +RectObj, +but not Core or a subclass of +Core. +.LP +Composite +widget classes that wish to accept rectobj children must set +the \fIaccepts_objects\fP field in the +.PN CompositeClassExtension +extension structure to +.PN True . +.PN XtCreateWidget +or +.PN XtCreateManagedWidget +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 +\*(xI accept rectobj children. +.LP +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 switching. The precise contents +of the exposure event and region arguments to the RectObj expose +procedure are not specified by the \*(xI; a particular rectangle object is +free to define the coordinate system origin (self-relative or +parent-relative) and whether or not the rectangle or region is assumed to +have been intersected with the visible region of the object. +.LP +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 completely 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. +.LP +The \*(xI will clear areas of a parent window obscured by +rectobj children, causing exposure events, under the following +circumstances: +.IP \(bu 5 +A rectobj child is managed or unmanaged. +.IP \(bu 5 +In a call to +.PN XtSetValues +on a rectobj child, one or more of the set_values procedures returns +.PN True . +.IP \(bu 5 +In a call to +.PN XtConfigureWidget +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. +.IP \(bu 5 +In a call to +.PN XtMoveWidget +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. +.IP \(bu 5 +In a call to +.PN XtResizeWidget +on a rectobj child, a single +rectangle will be cleared corresponding to the larger of the +old and the new child geometries if they are different. +.IP \(bu 5 +In a call to +.PN XtMakeGeometryRequest +(or +.PN XtMakeResizeRequest ) +on a rectobj child with +.PN XtQueryOnly +not set, if the manager returns +.PN XtGeometryYes , +two rectangles will be cleared corresponding to both the old and +the new child geometries. +.LP +Stacking order is not supported for rectobj children. Composite widgets with +rectobj children are free to define any semantics desired if the child +geometries overlap, including making this an error. +.LP +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 procedure. + +.NH 2 +Undeclared Class +.XS +\*(SN Undeclared Class +.XE +.LP +The \*(xI 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 +.IP \(bu 5 +The \fIcore_class.superclass\fP field of +.PN coreWidgetClassRec +contains a pointer to the unnamed class record. +.IP \(bu 5 +A pointer to the unnamed class record when dereferenced as an +.PN ObjectClass +will contain a pointer to +.PN rectObjClassRec +in its \fIobject_class.superclass\fP field. +.LP +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. + +.NH 2 +Widget Arguments to \*(xI Routines +.XS +\*(SN Widget Arguments to \*(xI Routines +.XE +.LP +The WidgetClass arguments to the following procedures must be of class +Shell +or a subclass: +.sp +.IP +.PN XtCreatePopupShell , +.PN XtVaCreatePopupShell , +.PN XtAppCreateShell , +.PN XtVaAppCreateShell , +.PN XtOpenApplication , +.PN XtVaOpenApplication +.sp +.LP +The Widget arguments to the following procedures must be of class +Core +or any subclass: +.sp +.IP +.PN XtCreatePopupShell , +.PN XtVaCreatePopupShell +.IP +.PN XtAddEventHandler , +.PN XtAddRawEventHandler , +.PN XtRemoveEventHandler , +.br +.PN XtRemoveRawEventHandler , +.PN XtInsertEventHandler , +.PN XtInsertRawEventHandler +.br +.PN XtInsertEventTypeHandler , +.PN XtRemoveEventTypeHandler , +.IP +.PN XtRegisterDrawable +.PN XtDispatchEventToWidget +.IP +.PN XtAddGrab , +.PN XtRemoveGrab , +.PN XtGrabKey , +.PN XtGrabKeyboard , +.PN XtUngrabKey , +.PN XtUngrabKeyboard , +.PN XtGrabButton , +.PN XtGrabPointer , +.PN XtUngrabButton , +.br +.PN XtUngrabPointer +.IP +.PN XtBuildEventMask +.IP +.PN XtCreateWindow , +.PN XtDisplay , +.PN XtScreen , +.PN XtWindow +.IP +.PN XtNameToWidget +.IP +.PN XtGetSelectionValue , +.PN XtGetSelectionValues , +.PN XtOwnSelection , +.PN XtDisownSelection , +.PN XtOwnSelectionIncremental , +.PN XtGetSelectionValueIncremental , +.PN XtGetSelectionValuesIncremental , +.br +.PN XtGetSelectionRequest +.IP +.PN XtInstallAccelerators , +.PN XtInstallAllAccelerators +(both destination and source) +.IP +.PN XtAugmentTranslations , +.PN XtOverrideTranslations , +.PN XtUninstallTranslations , +.br +.PN XtCallActionProc +.IP +.PN XtMapWidget , +.PN XtUnmapWidget +.IP +.PN XtRealizeWidget , +.PN XtUnrealizeWidget +.IP +.PN XtSetMappedWhenManaged +.IP +.PN XtCallAcceptFocus , +.PN XtSetKeyboardFocus +(subtree) +.IP +.PN XtResizeWindow +.IP +.PN XtSetWMColormapWindows +.sp +.LP +The Widget arguments to the following procedures must be of class +Composite +or any subclass: +.sp +.IP +.PN XtCreateManagedWidget , +.PN XtVaCreateManagedWidget +.sp +.LP +The Widget arguments to the following procedures must be of a subclass of +Shell: +.sp +.IP +.PN XtPopdown , +.PN XtCallbackPopdown , +.PN XtPopup , +.PN XtCallbackNone , +.PN XtCallbackNonexclusive , +.PN XtCallbackExclusive , +.PN XtPopupSpringLoaded +.sp +.LP +The return value of the following procedure will be of class +Core +or a subclass: +.sp +.IP +.PN XtWindowToWidget +.sp +.LP +The return value of the following procedures will be of a subclass of +Shell: +.sp +.IP +.PN XtAppCreateShell , +.PN XtVaAppCreateShell , +.PN XtAppInitialize , +.PN XtVaAppInitialize , +.PN XtCreatePopupShell , +.PN XtVaCreatePopupShell +.bp diff --git a/specs/CH13 b/specs/CH13 new file mode 100644 index 0000000..8c944a6 --- /dev/null +++ b/specs/CH13 @@ -0,0 +1,805 @@ +.\" $Xorg: CH13,v 1.3 2000/08/17 19:42:47 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 13\fP\s-1 + +\s+1\fBEvolution of the \*(xI\fP\s-1 +.sp 2 +.nr H1 13 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 13 \(em Evolution of the \*(xI +.XE +.LP +The interfaces described by this specification have undergone 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 conforming +implementations of these specifications may be produced that provide +source compatibility with widgets and applications written to +previous Consortium standard revisions. +.LP +The \*(xI do not place any special requirement on widget +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 provide such compatibility. +.LP +In particular, widget programmers may wish to conform to the convention +described in Section 1.6.12 when defining class extension records. + +.NH 2 +Determining Specification Revision Level +.XS +\fB\*(SN Determining Specification Revision Level\fP +.XE +.LP +Widget and application developers who wish to maintain a common source +pool that will build properly with implementations of the \*(xI +at different revision levels of these specifications but that take +advantage of newer features added in later revisions may use the +symbolic macro +.PN XtSpecificationRelease . +.LP +.Ds 0 +#define XtSpecificationRelease 6 +.De +.IN "XtSpecificationRelease" "" "@DEF@" +.LP +As the symbol +.PN XtSpecificationRelease +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. + +.NH 2 +Release 3 to Release 4 Compatibility +.XS +\fB\*(SN Release 3 to Release 4 Compatibility\fP +.XE +.LP +At the data structure level, Release 4 retains binary compatibility +with Release 3 (the first X Consortium standard release) for all data +structures except +.PN WMShellPart, +.PN TopLevelShellPart , +and +.PN TransientShellPart . +Release 4 changed the argument type to most procedures that now take +arguments of type +.PN XtPointer +and structure members that are now of type +.PN XtPointer +in order to avoid potential ANSI C conformance problems. It is +expected that most implementations will be binary compatible with the +previous definition. +.LP +Two fields in +.PN CoreClassPart +were changed from +.PN Boolean +to +.PN XtEnum +to allow implementations additional freedom in specifying the +representations of each. This change should require no source +modification. + +.NH 3 +Additional Arguments +.XS +\*(SN Additional Arguments +.XE +.LP +Arguments were added to the procedure definitions for +.PN XtInitProc , +.PN XtSetValuesFunc , +and +.PN XtEventHandler +to provide more information and to +allow event handlers to abort further dispatching of the current event +(caution is advised!). The added arguments to +.PN XtInitProc +and +.PN XtSetValuesFunc +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. + +.NH 3 +set_values_almost Procedures +.XS +\*(SN set_values_almost Procedures +.XE +.LP +The use of the arguments by a set_values_almost procedure was poorly +described in Release 3 and was inconsistent with other conventions. +.LP +The current specification for the manner in which a set_values_almost +procedure returns information to the \*(xI is not compatible with +the Release 3 specification, and all widget implementations should +verify that any set_values_almost procedures conform to the current +interface. +.LP +No known implementation of the \*(xI correctly implemented the +Release 3 interface, so it is expected that the impact of this +specification change is small. + +.NH 3 +Query Geometry +.XS +\*(SN Query Geometry +.XE +.LP +A composite widget layout routine that calls +.PN XtQueryGeometry +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 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. + +.NH 3 +unrealizeCallback Callback List +.XS +\*(SN unrealizeCallback Callback List +.XE +.LP +In order to provide a mechanism for widgets to be notified when they +become unrealized through a call to +.PN XtUnrealizeWidget , +the callback +list name ``unrealizeCallback'' has been defined by the \*(xI. 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. + +.NH 3 +Subclasses of WMShell +.XS +\*(SN Subclasses of WMShell +.XE +.LP +The formal adoption of the \fI\*(xC\fP as +an X Consortium standard has meant the addition of four fields to +.PN WMShellPart +and one field to +.PN TopLevelShellPart . +In deference to some +widget libraries that had developed their own additional conventions +to provide binary compatibility, these five new fields were added at +the end of the respective data structures. +.LP +To provide more convenience for TransientShells, a field was added +to the previously empty +.PN TransientShellPart . +On some architectures the size of the part structure will not +have changed as a result of this. +.LP +Any widget implementation whose class is a subclass of +TopLevelShell +or +TransientShell +must at minimum be +recompiled with the new data structure declarations. Because +.PN WMShellPart +no longer contains a contiguous +.PN XSizeHints +data structure, +a subclass that expected to do a single structure assignment of an +.PN XSizeHints +structure to the \fIsize_hints\fP field of +.PN WMShellPart +must be revised, though the old fields remain at the same positions within +.PN WMShellPart . + +.NH 3 +Resource Type Converters +.XS +\*(SN Resource Type Converters +.XE +.LP +A new interface declaration for resource type converters was defined +to provide more information to converters, to support conversion +cache cleanup with resource reference counting, and to allow +additional procedures to be declared to free resources. The old +interfaces remain (in the compatibility section), and a new set of +procedures was defined that work only with the new type converter +interface. +.LP +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 +.PN XtConverter +was incomplete. + +.NH 3 +KeySym Case Conversion Procedure +.XS +\*(SN KeySym Case Conversion Procedure +.XE +.LP +The specification for the +.PN XtCaseProc +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 \*(xI +implemented the previously documented interface. + +.NH 3 +Nonwidget Objects +.XS +\*(SN Nonwidget Objects +.XE +.LP +Formal support for nonwidget objects is new to Release 4. A +prototype implementation was latent in at least one Release 3 +implementation of the \*(xI, but the specification has changed +somewhat. The most significant change is the requirement for a +composite widget to declare the +.PN CompositeClassExtension +record with the \fIaccepts_objects\fP field set to +.PN True +in order to permit a client to create a nonwidget child. +.LP +The addition of this extension field ensures that composite widgets +written under Release 3 will not encounter unexpected errors if an +application attempts to create a nonwidget child. In Release 4 there +is no requirement that all composite widgets implement the extra +functionality required to manage windowless children, so the +\fIaccepts_objects\fP field allows a composite widget to declare that it +is not prepared to do so. + +.NH 2 +Release 4 to Release 5 Compatibility +.XS +\fB\*(SN Release 4 to Release 5 Compatibility\fP +.XE +.LP +At the data structure level, Release 5 retains complete binary +compatibility with Release 4. The specification of the +.PN ObjectPart , +.PN RectObjPart , +.PN CorePart , +.PN CompositePart , +.PN ShellPart , +.PN WMShellPart , +.PN TopLevelShellPart , +and +.PN ApplicationShellPart +instance records was made less strict to permit implementations to +add internal fields to these structures. Any implementation that +chooses to do so would, of course, force a recompilation. +The Xlib specification for +.PN XrmValue +and +.PN XrmOptionDescRec +was updated to use a new type, +.PN XPointer , +for the \fIaddr\fP and \fIvalue\fP fields, respectively, to avoid +ANSI C conformance problems. The definition of +.PN XPointer +is binary compatible with the previous implementation. + +.NH 3 +baseTranslations Resource +.XS +\fB\*(SN baseTranslations Resource\fP +.XE + +.LP +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''. +.LP +Applications wishing to take advantage of the new functionality +would change their application defaults file, e.g., from +.Ds + app.widget.translations: \fIvalue\fP +.DE +to +.Ds + app.widget.baseTranslations: \fIvalue\fP +.DE +If it is important to the application to preserve complete +compatibility of the defaults file between different versions +of the application running under Release 4 and Release 5, +the full translations can be replicated in both the ``translations'' +and the ``baseTranslations'' resource. + +.NH 3 +Resource File Search Path +.XS +\fB\*(SN Resource File Search Path\fP +.XE + +.LP +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 specific application together in one directory. The Release 5 +specification allows the default path to specify the substitution +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 +.PN \s-1XFILESEARCHPATH\s+1 +and +.PN \s-1XUSERFILESEARCHPATH\s+1 +values when overriding the system defaults. + +.NH 3 +Customization Resource +.XS +\fB\*(SN Customization Resource\fP +.XE + +.LP +.PN XtResolvePathname +supports a new substitution string, %C, for specifying separate +application class resource files according to arbitrary user-specified +categories. The primary motivation for this addition was separate +monochrome and color application class defaults files. The +substitution value is obtained by querying the current resource +database for the application resource name ``customization'', class +``Customization''. Any application that previously used this +resource name and class will need to be aware of the possibly +conflicting semantics. + +.NH 3 +Per-Screen Resource Database +.XS +\fB\*(SN Per-Screen Resource Database\fP +.XE + +.LP +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 application that modified the (formerly unique) +resource database associated with the display subsequent to the \*(xI +database initialization. Such applications will need to be aware +of the particular screen on which each shell widget is to be created. +.LP +Although the wording of the specification changed substantially 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 +.PN XtResolvePathname . + +.NH 3 +Internationalization of Applications +.XS +\fB\*(SN Internationalization of Applications\fP +.XE + +.LP +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 \*(xI +the restrictions of this model have been followed. +In particular, the new \*(xI interfaces are designed not to +preclude an application from using other alternatives. +For this reason, no \*(xI 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. +.LP +As many objects in X, particularly resource databases, now inherit +the global locale when they are created, applications wishing to use +the ANSI C locale model should use the new function +.PN XtSetLanguageProc +to do so. +.LP +The internationalization additions also define event filters +as a part of the Xlib Input Method specifications. The +\*(xI enable the use of event filters through additions to +.PN XtDispatchEvent . +Applications that may not be dispatching all events through +.PN XtDispatchEvent +should be reviewed in the context of this new input method mechanism. +.LP +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 mechanism has yet been suggested to +allow the \*(xI to locate the database from localization information +supplied by the client. +.LP +The previous specification for the syntax of the language string +specified by +.PN xnlLanguage +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. + +.NH 3 +Permanently Allocated Strings +.XS +\*(SN Permanently Allocated Strings +.XE + +.LP +In order to permit additional memory savings, an Xlib interface was +added to allow the resource manager to avoid copying certain string +constants. The \*(xI specification was updated to explicitly require +the Object \fIclass_name\fP, \fIresource_name\fP, \fIresource_class\fP, +\fIresource_type\fP, \fIdefault_type\fP in resource tables, Core \fIactions\fP +\fIstring\fP field, and Constraint \fIresource_name\fP, \fIresource_class\fP, +\fIresource_type\fP, and \fIdefault_type\fP resource fields to be +permanently allocated. This explicit requirement is expected to +affect only applications that may create and destroy classes +on the fly. + +.NH 3 +Arguments to Existing Functions +.XS +\fB\*(SN Arguments to Existing Functions\fP +.XE + +.LP +The \fIargs\fP argument to +.PN XtAppInitialize , +.PN XtVaAppInitialize , +.PN XtOpenDisplay , +.PN XtDisplayInitialize , +and +.PN XtInitialize +were changed from +.PN Cardinal * +to int* to conform to pre-existing convention and avoid otherwise +annoying typecasting in ANSI C environments. + +.NH 2 +Release 5 to Release 6 Compatibility +.XS +\fB\*(SN Release 5 to Release 6 Compatibility\fP +.XE +.LP +At the data structure level, Release 6 retains binary compatibility +with Release 5 for all data structures except +.PN WMShellPart . +Three resources were added to the specification. +The known implementations had unused space in the data structure, +therefore on some architectures and implementations, +the size of the part structure will not have changed as a result of this. + +.NH 3 +Widget Internals +.XS +\*(SN Widget Internals +.XE +.LP +Two new widget methods for instance allocation and deallocation were added +to the Object class. These new methods +allow widgets to be treated as C++ objects in the C++ environment +when an appropriate allocation method is specified or inherited +by the widget class. +.LP +The textual descriptions of the processes of widget creation and +widget destruction have been edited to provide clarification to widget +writers. Widgets writers may have reason to rely on the specific order of +the stages of widget creation and destruction; with that motivation, +the specification now more exactly describes the process. +.LP +As a convenience, an interface to locate a widget class extension +record on a linked list, +.PN XtGetClassExtension , +has been added. +.LP +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 procedure that can accommodate +additions and deletions to the managed set of children in a single +invocation should set allows_change_managed_set to \fBTrue\fP in the +extension record. +.LP +The wording of the process followed by +.PN XtUnmanageChildren +has changed slightly to better handle changes to the managed set +during phase 2 destroy processing. +.LP +A new exposure event compression flag, +.PN XtExposeNoRegion , +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 \*(xI need not +compute the region. + +.NH 3 +General Application Development +.XS +\*(SN General Application Development +.XE +.LP +.PN XtOpenApplication +is a new convenience procedure to initialize 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, +.PN XtAppInitialize , +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 recommended one so that clients may easily +become session participants. +The old convenience procedures appear in the compatibility section. +.LP +The toolkit initialization function +.PN XtToolkitInitialize +may be called multiple times without penalty. +.LP +In order to optimize changes in geometry to a set of geometry-managed +children, a new interface, +.PN XtChangeManagedSet , +has been added. + +.NH 3 +Communication with Window and Session Managers +.XS +\*(SN Communication with Window and Session Managers +.XE +.LP +The revision of the \fI\*(xC\fP as an X Consortium standard has resulted +in the addition of three fields to the specification of +.PN WMShellPart . +These are \fIurgency\fP, \fIclient_leader\fP, and \fIwindow_role\fP. +.LP +The adoption of the \fIX Session Management Protocol\fP as an X Consortium +standard has resulted in the addition of a new shell widget, +.PN SessionShell , +and an accompanying subclass verification interface, +.PN XtIsSessionShell . +This widget provides 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 +.PN ApplicationShell , +the +.PN ApplicationShell +was subclassed to create the new widget class. +The session protocol requires a modal response to certain checkpointing +operations by participating applications. The +.PN SessionShell +structures +the application's notification of and responses to messages from the session +manager by use of various callback lists and by use of the new interfaces +.PN XtSessionGetToken +and +.PN XtSessionReturnToken . +There is also a new command line argument, -xtsessionID, which facilitates +the session manager in restarting applications based on the \*(xI. +.LP +The resource name and class strings defined by the \*(xI shell +widgets in +.Pn < X11/Shell.h > +are now listed in Appendix E. The addition of a new symbol +for the +.PN WMShell +\fIwait_for_wm\fP resource was made to bring the external symbol +and the string it represents into agreement. The actual resource name +string in +.PN WMShell +has not changed. +The resource representation type of the XtNwinGravity resource of the +.PN WMShell +was changed to XtRGravity in order to register a type +converter so that window gravity resource values could be specified by name. + +.NH 3 +Geometry Management +.XS +\*(SN Geometry Management +.XE +.LP +A clarification to the specification was made to indicate that geometry +requests may include current values along with the requested changes. + +.NH 3 +Event Management +.XS +\*(SN Event Management +.XE +.LP +In Release 6, support is provided for registering selectors +and event handlers for events generated by X protocol extensions +and for dispatching those events to the appropriate widget. +The new event handler registration interfaces are +.PN XtInsertEventTypeHandler +and +.PN XtRemoveEventTypeHandler . +Since the mechanism to indicate selection of extension events is specific +to the extension being used, the \*(xI introduces +.PN XtRegisterExtensionSelector , +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 \*(xI event dispatcher may now be replaced or enveloped +by the application with +.PN XtSetEventDispatcher . +The dispatcher may wish to call +.PN XtGetKeyboardFocusWidget +to determine the widget with the current \*(xI keyboard focus. +A dispatcher, after determining the destination widget, may use +.PN XtDispatchEventToWidget +to cause the event to be dispatched to the event handlers registered +by a specific widget. +.LP +To permit the dispatching of events +for nonwidget drawables, such as pixmaps that are not associated +with a widget's window, +.PN XtRegisterDrawable +and +.PN XtUnregisterDrawable +have been added to the library. A related update was made to +the description of +.PN XtWindowToWidget . +.LP +The library is now thread-safe, allowing one thread at a time to +enter the library and protecting global data as necessary from concurrent use. +Threaded toolkit applications are supported by the +new interfaces +.PN XtToolkitThreadInitialize , +.PN XtAppLock , +.PN XtAppUnlock , +.PN XtAppSetExitFlag , +and +.PN XtAppGetExitFlag . +Widget writers may also use +.PN XtProcessLock +and +.PN XtProcessUnlock . +.LP +Safe handling of POSIX signals and other asynchronous notifications +is now provided by use of +.PN XtAppAddSignal , +.PN XtNoticeSignal , +and +.PN XtRemoveSignal . +.LP +The application can receive notification of an impending block +in the \*(xI event manager by registering interest through +.PN XtAppAddBlockHook +and +.PN XtRemoveBlockHook . +.LP +.PN XtLastEventProcessed +returns the most recent event passed to +.PN XtDispatchEvent +for a specified display. + +.NH 3 +Resource Management +.XS +\*(SN Resource Management +.XE +.LP +Resource converters are registered by the \*(xI for window gravity +and for three new resource types associated with session participation: +RestartStyle, CommandArgArray and DirectoryString. +.LP +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 substitution string, %D. + +.NH 3 +Translation Management +.XS +\*(SN Translation Management +.XE +.LP +The default key translator now recognizes the NumLock modifier. +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. + +.NH 3 +Selections +.XS +\*(SN Selections +.XE +.LP +The targets of selection requests may be parameterized, as described +by the revised \fI\*(xC\fP. +When such requests are made, +.PN XtSetSelectionParameters +is used by the requestor to specify the target parameters and +.PN XtGetSelectionParameters +is used by the selection owner to retrieve the parameters. +When a parameterized target is specified in the context of a bundled +request for multiple targets, +.PN XtCreateSelectionRequest , +.PN XtCancelSelectionRequest , +and +.PN XtSendSelectionRequest +are used to envelop the assembly of the request. +When the parameters themselves are the names of properties, +the \*(xI provides support for the economical use of property atom names; +see +.PN XtReservePropertyAtom +and +.PN XtReleasePropertyAtom . + +.NH 3 +External Agent Hooks +.XS +\*(SN External Agent Hooks +.XE +.LP +External agent hooks were added for the benefit of applications +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 interfaces +related to this effort are +.PN XtHooksOfDisplay , +which returns the hook registration widget, and +.PN XtGetDisplays , +which returns a list of the X displays associated with an application context. +.bp diff --git a/specs/Makefile.am b/specs/Makefile.am new file mode 100644 index 0000000..887eb7e --- /dev/null +++ b/specs/Makefile.am @@ -0,0 +1,24 @@ +EXTRA_DIST = \ + CH01 \ + CH02 \ + CH03 \ + CH04 \ + CH05 \ + CH06 \ + CH07 \ + CH08 \ + CH09 \ + CH10 \ + CH11 \ + CH12 \ + CH13 \ + appA \ + appB \ + appC \ + appD \ + appE \ + appF \ + intr.idxmac.t \ + postproc \ + strings.mit \ + Xtk.intr.front diff --git a/specs/Xtk.intr.front b/specs/Xtk.intr.front new file mode 100644 index 0000000..0deb6dd --- /dev/null +++ b/specs/Xtk.intr.front @@ -0,0 +1,334 @@ +.\" $Xorg: Xtk.intr.front,v 1.3 2000/08/17 19:42:48 cpqbld Exp $ +.\" MIT header page and copyright notice +.\" MIT page header and footers +.\" +.EH '''' +.OH '''' +.EF '''' +.OF '''' +.ps 11 +.nr PS 11 +\& +.sp 8 +.ce 4 +\s+2\fB\*(xT\fP\s-2 + +\s+1\fBX Window System\fP\s-1 + +\s+1\fBX Version 11, Release \*(Rn\fP\s-1 + + +First Revision - April, 1994 +.sp 5 +.ce 4 +\s-1Joel McCormack +.sp 6p +Digital Equipment Corporation +Western Software Laboratory +.sp 2 +.ce 4 +Paul Asente +.sp 6p +Digital Equipment Corporation +Western Software Laboratory +.sp 2 +.ce 4 +Ralph R. Swick +.sp 6p +Digital Equipment Corporation +External Research Group +MIT X Consortium +.sp 2 +.ce 3 +version 6 edited by Donna Converse +.sp 6p +X Consortium, Inc.\s+1 +.bp +\& +.ps 9 +.nr PS 9 +.sp 8 +.LP +X Window System is a trademark of X Consortium, Inc. +.LP +Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994 +X Consortium +.LP +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation 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: +.LP +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. +.LP +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 PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE X CONSORTIUM 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. +.LP +Except as contained in this notice, the name of the X Consortium 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. +.LP +Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994 +Digital Equipment Corporation, Maynard, Massachusetts. +.LP +Permission to use, copy, modify and distribute this documentation 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 +permission 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. +.ps 11 +.nr PS 11 +.bp 11 +.EF ''\fB \\\\n(PN \fP'' +.OF ''\fB \\\\n(PN \fP'' +.af PN i +.XS ix +Acknowledgments +.XE +\& +.sp 1 +.ce 3 +\s+1\fBAcknowledgments\fP\s-1 +.sp 2 +.na +.LP +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 contributors to the design and/or implementation were: +.LP +.Ds +.ta 3i +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) +.De +.LP +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. +.LP +The design and implementation of the X10 Intrinsics were done by: +.LP +.Ds +Terry Weissman (Digital WSL) +Smokey Wallace (Digital WSL) +Phil Karlton (Digital WSL) +Charles Haynes (Digital WSL) +Frank Hall (HP) +.De +.LP +The design and implementation of the X10 toolkit's sample widgets were +by the above, as well as by: +.LP +.Ds +Ram Rao (Digital UEG) +Mary Larson (Digital UEG) +Mike Gancarz (Digital UEG) +Kathleen Langone (Digital UEG) +.De +These widgets provided a checklist of requirements that we +had to address in the X11 Intrinsics. +.LP +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. +.LP +Finally, a special thanks to Mike Chow, +whose extensive performance analysis of the X10 toolkit provided +the justification to redesign it entirely for X11. +.LP +.sp +.Ds 0 +Joel McCormack +Western Software Laboratory +Digital Equipment Corporation + +March 1988 +.De +.bp +.LP +The current design of the \*(xI has benefited greatly from the +input of several dedicated reviewers in the membership of the +X Consortium. +In addition to those already mentioned, +the following individuals have dedicated significant time +to suggesting improvements to the \*(xI: +.LP +.Ds +.ta 3i +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) +.De +.LP +Thanks go to each of them for the countless hours spent +reviewing drafts and code. +.LP +.sp +.Ds 0 +Ralph R. Swick +External Research Group +Digital Equipment Corporation +MIT Project Athena + +June 1988 +.De +.sp +.LP +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 implementation code contributed by each +of the following: +.LP +.Ds +.ta 3i +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) +.De +.sp +.LP +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. +.sp +.Ds 0 +Ralph R. Swick + +December 1989 +and +July 1991 +.De +.bp +.LP +The Release 6 Intrinsics is a result of the collaborative +efforts of participants in the X Consortium's \fBintrinsics\fP +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 contributions: +.LP +.Ds +.ta 3i +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) +.De +.LP +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 contributions: +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 Peterson, Kamesh Ramakrishna, Tom Rodriguez, +Jim VanGilder, Will Walker, and Mike Wexler. +.LP +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. +.sp +.Ds 0 +Donna Converse +X Consortium +April 1994 +.De +.bp +.XS xii +About This Manual +.XE +\& +.sp 1 +.ce 3 +\s+1\fBAbout This Manual\fP\s-1 +.sp 2 +.na +.LP +\fI\*(xT\fP is intended to be read by both application programmers who will +use one or more of the many widget sets built with the \*(xI +and by widget programmers who will use the \*(xI 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 \*(xI functions in writing an application and because the widget programmer +is likely to use many more, if not all, of the \*(xI 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 programmer will have to be familiar with all +the information.) +Therefore, all entries in the table of contents that are printed in \fBbold\fP +indicate the information that should be of special interest to an +application programmer. +.LP +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. +.SH +Conventions Used in this Manual +.LP +This document uses the following conventions: +.IP \(bu 5 +Global symbols are printed in +.PN this +.PN special +.PN font . +These can be either function names, +symbols defined in include files, data types, or structure names. +Arguments to functions, procedures, or macros are printed in \fIitalics\fP. +.IP \(bu 5 +Each function is introduced by a general discussion that +distinguishes it from other functions. +The function declaration itself follows, +and each argument is specifically explained. +General discussion of the function, if any is required, +follows the arguments. +.IP \(bu 5 +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 +\fIspecifies\fP or, in the case of multiple arguments, the word \fIspecify\fP. +The explanations for all arguments that are returned to you start with the +word \fIreturns\fP or, in the case of multiple arguments, the word \fIreturn\^\fP. +.bp 1 +.af PN 1 +.EH '\fBX Toolkit Intrinsics\fP''\fBX11 Release \*(Rn\fP' +.OH '\fBX Toolkit Intrinsics\fP''\fBX11 Release \*(Rn\fP' diff --git a/specs/appA b/specs/appA new file mode 100644 index 0000000..57a1890 --- /dev/null +++ b/specs/appA @@ -0,0 +1,107 @@ +.\" $Xorg: appA,v 1.3 2000/08/17 19:42:48 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +.bp +\& +.sp 1 +.ce 3 +\s+1\fBAppendix A\fP\s-1 + +\s+1\fBResource File Format\fP\s-1 +.sp 2 +.LP +.XS +\fBAppendix A \(em Resource File Format\fP +.XE +A resource file contains text representing the default resource values for an +application or set of applications. +.LP +The format of resource files is defined by \fI\*(xL\fP and is reproduced here +for convenience only. +.LP +The format of a resource specification is +.TS +l l . +ResourceLine = Comment | IncludeFile | ResourceSpec | <empty line> +Comment = ``!'' {<any character except null or newline>} +IncludeFile = ``#'' WhiteSpace ``include'' WhiteSpace FileName WhiteSpace +FileName = <valid filename for operating system> +ResourceSpec = WhiteSpace ResourceName WhiteSpace ``:'' WhiteSpace Value +ResourceName = [Binding] {Component Binding} ComponentName +Binding = ``.'' | ``*'' +WhiteSpace = {<space> | <horizontal tab>} +Component = ``?'' | ComponentName +ComponentName = NameChar {NameChar} +NameChar = ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' +Value = {<any character except null or unescaped newline>} +.TE +.LP +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. +.LP +If the last character on a line is a backslash (\\), +that line is assumed to continue on the next line. +.LP +To allow a Value to begin with whitespace, +the two-character sequence ``\\\^\fIspace\fP'' (backslash followed by space) +is recognized and replaced by a space character, +and the two-character sequence ``\\\^\fItab\fP'' +(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 ``\\\^\fInewline\fP'' +(backslash followed by newline) is +recognized and removed from the value. + +To allow a Value to contain arbitrary character codes, +the four-character sequence ``\\\^\fInnn\fP'', +where each \fIn\fP 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. diff --git a/specs/appB b/specs/appB new file mode 100644 index 0000000..3eb9ccc --- /dev/null +++ b/specs/appB @@ -0,0 +1,783 @@ +.\" $Xorg: appB,v 1.3 2000/08/17 19:42:48 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +.bp +\& +.sp 1 +.ce 3 +\s+1\fBAppendix B\fP\s-1 + +\s+1\fBTranslation Table Syntax\fP\s-1 +.sp 2 +.LP +.XS +\fBAppendix B \(em Translation Table Syntax\fP +.XE +.IN "Translation tables" +.SH +Notation +.LP +Syntax is specified in EBNF notation with the following conventions: +.TS +l l. +[ 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 +.TE +.LP +All terminals are enclosed in double quotation marks (`` ''). +Informal descriptions are enclosed in angle brackets (< >). +.SH +Syntax +.LP +The syntax of a translation table is +.TS +l l . +translationTable = [ directive ] { production } +directive = ( ``#replace'' | ``#override'' | ``#augment'' ) ``\\\\n'' +production = lhs ``:'' rhs ``\\\\n'' +lhs = ( event | keyseq ) { ``,'' (event | keyseq) } +keyseq = ``"'' keychar {keychar} ``"'' +keychar = [ ``^'' | ``$'' | ``\\\\'' ] <ISO Latin 1 character> +event = [modifier_list] ``<''event_type``>'' [ ``('' count[``+''] ``)'' ] {detail} +modifier_list = ( [``!''] [``:''] {modifier} ) | ``None'' +modifier = [``~''] modifier_name +count = (``1'' | ``2'' | ``3'' | ``4'' | ...) +modifier_name = ``@'' <keysym> | <see ModifierNames table below> +event_type = <see Event Types table below> +detail = <event specific details> +rhs = { name ``('' [params] ``)'' } +name = namechar { namechar } +namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' } +params = string {``,'' string} +string = quoted_string | unquoted_string +quoted_string = ``"'' {<Latin 1 character> | escape_char} [``\\\\\\\\'' ] ``"'' +escape_char = ``\\\\"'' +unquoted_string = {<Latin 1 character except space, tab, ``,'', ``\\\\n'', ``)''>} +.TE + +.LP +The \fIparams\fP field is parsed into a list of +.PN String +values that will be passed to the named action procedure. A +\fIquoted string\fP may contain an embedded quotation mark if the +quotation mark is preceded by a single backslash (\\). The +three-character sequence ``\\\\"'' is interpreted as ``single backslash +followed by end-of-string''. + +.SH +Modifier Names +.LP +The modifier field is used to specify standard X keyboard and button +modifier mask bits. +Modifiers are legal on event types +.PN KeyPress , +.PN KeyRelease , +.PN ButtonPress , +.PN ButtonRelease , +.PN MotionNotify , +.PN EnterNotify , +.PN LeaveNotify , +and their abbreviations. +An error is generated when a translation table +that contains modifiers for any other events is parsed. +.IP \(bu 5 +If the modifier list has no entries and is not ``None'', +it means ``don't care'' on all modifiers. +.IP \(bu 5 +If an exclamation point (!) is specified at the beginning +of the modifier list, +it means that the listed modifiers must be in the correct state +and no other modifiers can be asserted. +.IP \(bu 5 +If any modifiers are specified +and an exclamation point (!) is not specified, +it means that the listed modifiers must be in the +correct state and ``don't care'' about any other modifiers. +.IP \(bu 5 +If a modifier is preceded by a tilde (~), +it means that that modifier must not be asserted. +.IP \(bu 5 +If ``None'' is specified, it means no modifiers can be asserted. +.IP \(bu 5 +If a colon (:) is specified at the beginning of the modifier list, +it directs the \*(xI to apply any standard modifiers in the +event to map the event keycode into a KeySym. +The default standard modifiers are Shift and Lock, +with the interpretation as defined in \fI\*(xP\fP, Section 5. +The resulting KeySym must exactly match the specified +KeySym, and the nonstandard modifiers in the event must match the +modifier list. +For example, ``:<Key>a'' is distinct from ``:<Key>A'', +and ``:Shift<Key>A'' is distinct from ``:<Key>A''. +.IP \(bu 5 +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. +.IP \(bu 5 +If a colon (:) is not specified, +no standard modifiers are applied. +Then, for example, ``<Key>A'' and ``<Key>a'' are equivalent. +.LP +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 +character, in particular a double quote ("), a circumflex (^), +a dollar sign ($), and another backslash (\\). +Briefly: +.LP +.Ds 0 +.TA 2.5i +.ta 2.5i +No modifiers: None <event> detail +Any modifiers: <event> detail +Only these modifiers: ! mod1 mod2 <event> detail +These modifiers and any others: mod1 mod2 <event> detail +.De +.LP +The use of ``None'' for a modifier list is identical to the use +of an exclamation point with no modifers. +.LP +.TS H +lw(1i) lw(1i) lw(3i). +_ +.sp 6p +Modifier Abbreviation Meaning +.sp 6p +_ +.sp 6p +.R +.TH +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 +.sp 6p +_ +.TE +.LP +.IN "key modifier" +A key modifier is any modifier bit one of whose corresponding 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 additional interpretation of KeySyms for these modifiers. +.LP +Because it is possible to associate arbitrary KeySyms with modifiers, the set of +key modifiers is extensible. The ``@'' <keysym> syntax means any +modifier bit whose corresponding KeyCode contains the specified KeySym name. +.LP +A modifier_list/KeySym combination in a translation matches a +modifiers/KeyCode combination in an event in the following ways: +.IP 1. 5 +If a colon (:) is used, the \*(xI call the display's +.PN XtKeyProc +with the KeyCode and modifiers. +To match, (\fImodifiers\fP & ~\fImodifiers_return\fP) must equal \fImodifier_list\fP, and +\fIkeysym_return\fP must equal the given KeySym. +.IP 2. 5 +If (:) is not used, the \*(xI mask off all don't-care bits from the +modifiers. +This value must be equal to \fImodifier_list\fP. +Then, for each possible combination of +don't-care modifiers in the modifier list, the \*(xI call the display's +.PN XtKeyProc +with the KeyCode and that combination ORed with the cared-about modifier bits +from the event. +\fIKeysym_return\fP must match the KeySym in the translation. +.SH +Event Types +.LP +The event-type field describes XEvent types. +In addition to the standard +Xlib symbolic event type names, the following event type synonyms +are defined: +.TS H +lw(1.5i) lw(3i). +_ +.sp 6p +Type Meaning +.sp 6p +_ +.sp 6p +.TH +Key T{ +.PN KeyPress +T} +KeyDown T{ +.PN KeyPress +T} +KeyUp T{ +.PN KeyRelease +T} +BtnDown T{ +.PN ButtonPress +T} +BtnUp T{ +.PN ButtonRelease +T} +Motion T{ +.PN MotionNotify +T} +PtrMoved T{ +.PN MotionNotify +T} +MouseMoved T{ +.PN MotionNotify +T} +Enter T{ +.PN EnterNotify +T} +EnterWindow T{ +.PN EnterNotify +T} +Leave T{ +.PN LeaveNotify +T} +LeaveWindow T{ +.PN LeaveNotify +T} +FocusIn T{ +.PN FocusIn +T} +FocusOut T{ +.PN FocusOut +T} +Keymap T{ +.PN KeymapNotify +T} +Expose T{ +.PN Expose +T} +GrExp T{ +.PN GraphicsExpose +T} +NoExp T{ +.PN NoExpose +T} +Visible T{ +.PN VisibilityNotify +T} +Create T{ +.PN CreateNotify +T} +Destroy T{ +.PN DestroyNotify +T} +Unmap T{ +.PN UnmapNotify +T} +Map T{ +.PN MapNotify +T} +MapReq T{ +.PN MapRequest +T} +Reparent T{ +.PN ReparentNotify +T} +Configure T{ +.PN ConfigureNotify +T} +ConfigureReq T{ +.PN ConfigureRequest +T} +Grav T{ +.PN GravityNotify +T} +ResReq T{ +.PN ResizeRequest +T} +Circ T{ +.PN CirculateNotify +T} +CircReq T{ +.PN CirculateRequest +T} +Prop T{ +.PN PropertyNotify +T} +SelClr T{ +.PN SelectionClear +T} +SelReq T{ +.PN SelectionRequest +T} +Select T{ +.PN SelectionNotify +T} +Clrmap T{ +.PN ColormapNotify +T} +Message T{ +.PN ClientMessage +T} +Mapping T{ +.PN MappingNotify +T} +.sp 6p +_ +.TE +The supported abbreviations are: +.TS H +lw(1.5i) lw(1.25i) lw(1.75i). +_ +.sp 6p +Abbreviation Event Type Including +.sp 6p +_ +.sp 6p +.TH +.R +Ctrl T{ +.PN KeyPress +T} with Control modifier +Meta T{ +.PN KeyPress +T} with Meta modifier +Shift T{ +.PN KeyPress +T} with Shift modifier +Btn1Down T{ +.PN ButtonPress +T} with Button1 detail +Btn1Up T{ +.PN ButtonRelease +T} with Button1 detail +Btn2Down T{ +.PN ButtonPress +T} with Button2 detail +Btn2Up T{ +.PN ButtonRelease +T} with Button2 detail +Btn3Down T{ +.PN ButtonPress +T} with Button3 detail +Btn3Up T{ +.PN ButtonRelease +T} with Button3 detail +Btn4Down T{ +.PN ButtonPress +T} with Button4 detail +Btn4Up T{ +.PN ButtonRelease +T} with Button4 detail +Btn5Down T{ +.PN ButtonPress +T} with Button5 detail +Btn5Up T{ +.PN ButtonRelease +T} with Button5 detail +BtnMotion T{ +.PN MotionNotify +T} with any button modifier +Btn1Motion T{ +.PN MotionNotify +T} with Button1 modifier +Btn2Motion T{ +.PN MotionNotify +T} with Button2 modifier +Btn3Motion T{ +.PN MotionNotify +T} with Button3 modifier +Btn4Motion T{ +.PN MotionNotify +T} with Button4 modifier +Btn5Motion T{ +.PN MotionNotify +T} with Button5 modifier +.sp 6p +_ +.TE +.sp +.LP +The detail field is event-specific and normally corresponds to the +detail field of the corresponding event as described +by \fI\*(xP\fP, Section 11. The detail field is supported +for the following event types: +.LP +.TS H +l l . +_ +.sp 6p +Event Event Field +.sp 6p +_ +.TH +.sp 6p +KeyPress KeySym from event \fIdetail\fP (keycode) +KeyRelease KeySym from event \fIdetail\fP (keycode) +ButtonPress button from event \fIdetail\fP +ButtonRelease button from event \fIdetail\fP +MotionNotify event \fIdetail\fP +EnterNotify event \fImode\fP +LeaveNotify event \fImode\fP +FocusIn event \fImode\fP +FocusOut event \fImode\fP +PropertyNotify \fIatom\fP +SelectionClear \fIselection\fP +SelectionRequest \fIselection\fP +SelectionNotify \fIselection\fP +ClientMessage \fItype\fP +MappingNotify \fIrequest\fP +.sp 6p +_ +.TE +.LP +If the event type is +.PN KeyPress +or +.PN KeyRelease , +the detail field +specifies a KeySym name in standard format which is matched against +the event as described above, for example, <Key>A. +.LP +For the +.PN PropertyNotify , +.PN SelectionClear , +.PN SelectionRequest , +.PN SelectionNotify , +and +.PN ClientMessage +events the detail field is specified +as an atom name; for example, <Message>WM_PROTOCOLS. For the +.PN MotionNotify , +.PN EnterNotify , +.PN LeaveNotify , +.PN FocusIn , +.PN FocusOut , +and +.PN MappingNotify +events, either the symbolic constants as defined by +\fI\*(xP\fP, Section 11, +or the numeric values may be specified. +.LP +If no detail field is specified, then any value in the event detail is +accepted as a match. +.LP +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 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 +.Pn < X11/keysymdef.h > +with the ``XK_'' prefix removed. +.LP +.SH +Canonical Representation +.LP +Every translation table has a unique, canonical text representation. This +representation is passed to a widget's +.PN display_accelerator +procedure to describe the accelerators installed on that widget. +The canonical representation of a translation table is (see also +``Syntax'') +.TS +l l . +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 = ``@'' <keysym> | <see canonical modifier names below> +event_type = <see canonical event types below> +detail = <event-specific details> +rhs = { name ``('' [params] ``)'' } +name = namechar { namechar } +namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' } +params = string {``,'' string} +string = quoted_string +quoted_string = ``"'' {<Latin 1 character> | escape_char} [``\\\\\\\\'' ] ``"'' +escape_char = ``\\\\"'' +.TE +.LP +The canonical modifier names are +.LP +.Ds +.TA 1i 2.5i +.ta 1i 2.5i +Ctrl Mod1 Button1 +Shift Mod2 Button2 +Lock Mod3 Button3 + Mod4 Button4 + Mod5 Button5 +.De +.LP +The canonical event types are +.IP +.TS +l l. +T{ +.PN KeyPress +T} T{ +.PN KeyRelease +T} +T{ +.PN ButtonPress +T} T{ +.PN ButtonRelease +T} +T{ +.PN MotionNotify +T} T{ +.PN EnterNotify +T} +T{ +.PN LeaveNotify +T} T{ +.PN FocusIn +T} +T{ +.PN FocusOut +T} T{ +.PN KeymapNotify +T} +T{ +.PN Expose +T} T{ +.PN GraphicsExpose, +T} +T{ +.PN NoExpose +T} T{ +.PN VisibilityNotify +T} +T{ +.PN CreateNotify +T} T{ +.PN DestroyNotify +T} +T{ +.PN UnmapNotify +T} T{ +.PN MapNotify +T} +T{ +.PN MapRequest +T} T{ +.PN ReparentNotify +T} +T{ +.PN ConfigureNotify +T} T{ +.PN ConfigureRequest +T} +T{ +.PN GravityNotify +T} T{ +.PN ResizeRequest +T} +T{ +.PN CirculateNotify +T} T{ +.PN CirculateRequest +T} +T{ +.PN PropertyNotify +T} T{ +.PN SelectionClear +T} +T{ +.PN SelectionRequest +T} T{ +.PN SelectionNotify +T} +T{ +.PN ColormapNotify +T} T{ +.PN ClientMessage +T} +.TE +.LP + +.SH +Examples +.LP +.IP \(bu 5 +Always put more specific events in the table before more general ones: +.LP +.Ds +Shift <Btn1Down> : twas()\\n\\ +<Btn1Down> : brillig() +.De +.LP +.IP \(bu 5 +For double-click on Button1 Up with Shift, use this specification: +.IP +.Ds +Shift<Btn1Up>(2) : and() +.DE +.IP +This is equivalent to the following line with appropriate timers set +between events: +.IP +.Ds +Shift<Btn1Down>,Shift<Btn1Up>,Shift<Btn1Down>,Shift<Btn1Up> : and() +.De +.IP \(bu 5 +For double-click on Button1 Down with Shift, use this specification: +.IP +.Ds +Shift<Btn1Down>(2) : the() +.De +.IP +This is equivalent to the following line with appropriate timers set +between events: +.IP +.Ds +Shift<Btn1Down>,Shift<Btn1Up>,Shift<Btn1Down> : the() +.De +.IP \(bu 5 +Mouse motion is always discarded when it occurs between events in a table +where no motion event is specified: +.IP +.Ds +<Btn1Down>,<Btn1Up> : slithy() +.De +.IP +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. +.IP \(bu 5 +If an event sequence consists of a sequence of events that is also a +noninitial subsequence of another translation, +it is not taken if it occurs in the context of the longer sequence. +This occurs mostly in sequences like the following: +.IP +.Ds +<Btn1Down>,<Btn1Up> : toves()\\n\\ +<Btn1Up> : did() +.De +.IP +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. +.IP \(bu 5 +For single click on Button1 Up with Shift and Meta, use this specification: +.IP +.Ds +Shift Meta <Btn1Down>, Shift Meta<Btn1Up>: gyre() +.De +.IP \(bu 5 +For multiple clicks greater or equal to a minimum number, +a plus sign (+) may be appended to the final (rightmost) +count in an event sequence. The actions will be invoked +on the \fIcount\fP-th click and each subsequent one arriving +within the multi-click time interval. For example: +.IP +.Ds +Shift <Btn1Up>(2+) : and() +.De +.IP \(bu 5 +To indicate +.PN EnterNotify +with any modifiers, use this specification: +.IP +.Ds +<Enter> : gimble() +.De +.IP \(bu 5 +To indicate +.PN EnterNotify +with no modifiers, use this specification: +.IP +.Ds +None <Enter> : in() +.De +.IP \(bu 5 +To indicate +.PN EnterNotify +with Button1 Down and Button2 Up and ``don't care'' about +the other modifiers, use this specification: +.IP +.Ds +Button1 ~Button2 <Enter> : the() +.De +.IP \(bu 5 +To indicate +.PN EnterNotify +with Button1 down and Button2 down exclusively, use this specification: +.IP +.Ds +! Button1 Button2 <Enter> : wabe() +.De +.IP +You do not need to use a tilde (~) with an exclamation point (!). diff --git a/specs/appC b/specs/appC new file mode 100644 index 0000000..6f31fd7 --- /dev/null +++ b/specs/appC @@ -0,0 +1,1204 @@ +.\" $Xorg: appC,v 1.3 2000/08/17 19:42:48 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +.bp +\& +.sp 1 +.ce 3 +\s+1\fBAppendix C\fP\s-1 + +\s+1\fBCompatibility Functions\fP\s-1 +.sp 2 +.LP +.XS +\fBAppendix C \(em Compatibility Functions\fP +.XE +.FS +This appendix is part of the formal Intrinsics Specification. +.FE +.LP +In prototype versions of the \*(tk +each widget class +implemented an Xt<\^\fIWidget\fP\^>Create (for example, +.PN XtLabelCreate ) +function, in which most of the code was identical from widget to widget. +In the \*(xI, a single generic +.PN XtCreateWidget +performs most of the common work and then calls the initialize procedure +implemented for the particular widget class. +.LP +Each Composite class also implemented the procedures +Xt<\^\fIWidget\fP\^>Add and an Xt<\^\fIWidget\fP\^>Delete (for example, +.PN XtButtonBoxAddButton +and +.PN XtButtonBoxDeleteButton ). +In the \*(xI, the Composite generic procedures +.PN XtManageChildren +and +.PN XtUnmanageChildren +perform error checking and screening out of certain children. +Then they call the change_managed procedure +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. +.LP +Old-style calls can be implemented in the \*(tk by defining +one-line procedures or macros that invoke a generic routine. For example, +you could define the macro +.PN XtLabelCreate +as: +.IP +.Ds 0 +.TA .5i 3i +.ta .5i 3i +#define XtLabelCreate(\fIname\fP, \fIparent\fP, \fIargs\fP, \fInum_args\fP) \\ + ((LabelWidget) XtCreateWidget(\fIname\fP, \fIlabelWidgetClass\fP, \ +\fIparent\fP, \fIargs\fP, \fInum_args\fP)) +.De +.sp +.LP +Pop-up shells in some of the prototypes automatically performed an +.PN XtManageChild +on their child within their insert_child procedure. +.IN "insert_child procedure" +Creators of pop-up children need to call +.PN XtManageChild +themselves. +.sp +.LP +.PN XtAppInitialize +and +.PN XtVaAppInitialize +have been replaced by +.PN XtOpenApplication +and +.PN XtVaOpenApplication . +.LP +To initialize the \*(xI internals, create an application context, +open and initialize a display, and create the initial application shell +instance, an application may use +.PN XtAppInitialize +or +.PN XtVaAppInitialize . +.LP +.IN "XtAppInitialize" "" "@DEF@" +.sM +.FD 0 +Widget XtAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \ +\fIoptions\fP, \fInum_options\fP, +.br + \fIargc_in_out\fP, \fIargv_in_out\fP, \ +\fIfallback_resources\fP, \fIargs\fP, \fInum_args\fP) +.br + XtAppContext *\fIapp_context_return\fP; +.br + String \fIapplication_class\fP; +.br + XrmOptionDescList \fIoptions\fP; +.br + Cardinal \fInum_options\fP; +.br + int *\fIargc_in_out\fP; +.br + String *\fIargv_in_out\fP; +.br + String *\fIfallback_resources\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIapp_context_return\fP 1.5i +Returns the application context, if non-NULL. +.IP \fIapplication_class\fP 1.5i +Specifies the class name of the application. +.IP \fIoptions\fP 1.5i +Specifies the command line options table. +.IP \fInum_options\fP 1.5i +Specifies the number of entries in \fIoptions\fP. +.IP \fIargc_in_out\fP 1.5i +Specifies a pointer to the number of command line arguments. +.IP \fIargv_in_out\fP 1.5i +Specifies a pointer to the command line arguments. +.IP \fIfallback_resources\fP 1.5i +Specifies resource values to be used if the application class resource +file cannot be opened or read, or NULL. +.IP \fIargs\fP 1.5i +Specifies the argument list to override any +other resource specifications for the created shell widget. +.IP \fInum_args\fP 1.5i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtAppInitialize +function calls +.PN XtToolkitInitialize +followed by +.PN XtCreateApplicationContext , +then calls +.PN XtOpenDisplay +with \fIdisplay_string\fP NULL and +\fIapplication_name\fP NULL, and finally calls +.PN XtAppCreateShell +with \fIapplication_name\fP NULL, \fIwidget_class\fP +.PN application\%Shell\%Widget\%Class , +and the specified \fIargs\fP and \fInum_args\fP +and returns the created shell. The modified \fIargc\fP and \fIargv\fP returned by +.PN XtDisplayInitialize +are returned in \fIargc_in_out\fP and \fIargv_in_out\fP. If +\fIapp_context_return\fP 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 +.PN XtAppInitialize +terminates the application. If \fIfallback_resources\fP is non-NULL, +.PN XtAppSetFallbackResources +is called with the value prior to calling +.PN XtOpenDisplay . +.sp +.LP +.IN "XtVaAppInitialize" "" "@DEF@" +.sM +.FD 0 +Widget XtVaAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \ +\fIoptions\fP, \fInum_options\fP, +.br + \fIargc_in_out\fP, \fIargv_in_out\fP, \ +\fIfallback_resources\fP, ...) +.br + XtAppContext *\fIapp_context_return\fP; +.br + String \fIapplication_class\fP; +.br + XrmOptionDescList \fIoptions\fP; +.br + Cardinal \fInum_options\fP; +.br + int *\fIargc_in_out\fP; +.br + String *\fIargv_in_out\fP; +.br + String *\fIfallback_resources\fP; +.FN +.IP \fIapp_context_return\fP 1.5i +Returns the application context, if non-NULL. +.IP \fIapplication_class\fP 1.5i +Specifies the class name of the application. +.IP \fIoptions\fP 1.5i +Specifies the command line options table. +.IP \fInum_options\fP 1.5i +Specifies the number of entries in \fIoptions\fP. +.IP \fIargc_in_out\fP 1.5i +Specifies a pointer to the number of command line arguments. +.IP \fIargv_in_out\fP 1.5i +Specifies the command line arguments array. +.IP \fIfallback_resources\fP 1.5i +Specifies resource values to be used if the application class +resource file cannot be opened, or NULL. +.IP ... 1.5i +Specifies the variable argument list to override any other +resource specifications for the created shell. +.LP +.eM +The +.PN XtVaAppInitialize +procedure is identical in function to +.PN XtAppInitialize +with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, +as described +in Section 2.5.1. +.sp +.LP +As a convenience to people converting from earlier versions of the toolkit +without application contexts, the following routines exist: +.PN XtInitialize , +.PN XtMainLoop , +.PN XtNextEvent , +.PN XtProcessEvent , +.PN XtPeekEvent , +.PN XtPending , +.PN XtAddInput , +.PN XtAddTimeOut , +.PN XtAddWorkProc , +.PN XtCreateApplicationShell , +.PN XtAddActions , +.PN XtSetSelectionTimeout , +and +.PN XtGetSelectionTimeout . +.LP +.IN "XtInitialize" "" "@DEF@" +.sM +.FD 0 +Widget XtInitialize(\fIshell_name\fP, \fIapplication_class\fP, \fIoptions\fP, \ +\fInum_options\fP, \fIargc\fP, \fIargv\fP) +.br + String \fIshell_name\fP; +.br + String \fIapplication_class\fP; +.br + XrmOptionDescRec \fIoptions\fP[]; +.br + Cardinal \fInum_options\fP; +.br + int *\fIargc\fP; +.br + String \fIargv\fP[]; +.FN +.IP \fIshell_name\fP 1i +This parameter is ignored; therefore, you can specify NULL. +.IP \fIapplication_class\fP 1i +Specifies the class name of this application. +.IP \fIoptions\fP 1i +Specifies how to parse the command line for any application-specific resources. +The \fIoptions\fP argument is passed as a parameter to +.PN XrmParseCommand . +.IP \fInum_options\fP 1i +Specifies the number of entries in the options list. +.IP \fIargc\fP 1i +Specifies a pointer to the number of command line parameters. +.IP \fIargv\fP 1i +Specifies the command line parameters. +.LP +.eM +.PN XtInitialize +calls +.PN XtToolkitInitialize +to initialize the toolkit internals, +creates a default application context for use by the other convenience +routines, calls +.PN XtOpenDisplay +with \fIdisplay_string\fP NULL and \fIapplication_name\fP NULL, and +finally calls +.PN XtAppCreateShell +with \fIapplication_name\fP NULL and +returns the created shell. +The semantics of calling +.PN XtInitialize +more than once are undefined. +This routine has been replaced by +.PN XtOpenApplication . +.sp +.IN "XtMainLoop" "" "@DEF@" +.sM +.FD 0 +void XtMainLoop(void) +.FN +.LP +.eM +.PN XtMainLoop +first reads the next alternate input, timer, or X event by calling +.PN XtNextEvent . +Then it dispatches this to the appropriate registered procedure by calling +.PN XtDispatchEvent . +This routine has been replaced by +.PN XtAppMainLoop . +.sp +.IN "XtNextEvent" "" "@DEF@" +.sM +.FD 0 +void XtNextEvent(\fIevent_return\fP) +.br + XEvent *\fIevent_return\fP; +.FN +.IP \fIevent_return\fP 1i +Returns the event information to the specified event structure. +.LP +.eM +If no input is on the X input queue for the default application context, +.PN XtNextEvent +flushes the X output buffer +and waits for an event while looking at the alternate input sources +and timeout values and calling any callback procedures triggered by them. +This routine has been replaced by +.PN XtAppNextEvent . +.PN XtInitialize +must be called before using this routine. +.sp +.IN "XtProcessEvent" "" "@DEF@" +.sM +.FD 0 +void XtProcessEvent(\fImask\fP) +.br + XtInputMask \fImask\fP; +.FN +.IP \fImask\fP 1i +Specifies the type of input to process. +.LP +.eM +.PN XtProcessEvent +processes one X event, timeout, or alternate input source +(depending on the value of \fImask\fP), blocking if necessary. +It has been replaced by +.PN XtAppProcessEvent . +.PN XtInitialize +must be called before using this function. +.sp +.IN "XtPeekEvent" "" "@DEF@" +.sM +.FD 0 +Boolean XtPeekEvent(\fIevent_return\fP) +.br + XEvent *\fIevent_return\fP; +.FN +.IP \fIevent_return\fP 1i +Returns the event information to the specified event structure. +.LP +.eM +If there is an event in the queue for the default application context, +.PN XtPeekEvent +fills in the event and returns a nonzero value. +If no X input is on the queue, +.PN XtPeekEvent +flushes the output buffer and blocks until input is available, possibly +calling some timeout callbacks in the process. +If the input is an event, +.PN XtPeekEvent +fills in the event and returns a nonzero value. +Otherwise, the input is for an alternate input source, and +.PN XtPeekEvent +returns zero. +This routine has been replaced by +.PN XtAppPeekEvent . +.PN XtInitialize +must be called before using this routine. +.sp +.IN "XtPending" "" "@DEF@" +.sM +.FD 0 +Boolean XtPending() +.FN +.LP +.eM +.PN XtPending +returns a nonzero value if there are +events pending from the X server or alternate input sources in the default +application context. +If there are no events pending, +it flushes the output buffer and returns a zero value. +It has been replaced by +.PN XtAppPending . +.PN XtInitialize +must be called before using this routine. +.sp +.IN "XtAddInput" "" "@DEF@" +.sM +.FD 0 +XtInputId XtAddInput(\fIsource\fP, \fIcondition\fP, \fIproc\fP, \ +\fIclient_data\fP) +.br + int \fIsource\fP; +.br + XtPointer \fIcondition\fP; +.br + XtInputCallbackProc \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIsource\fP 1i +Specifies the source file descriptor on a POSIX-based system +or other operating-system-dependent device specification. +.IP \fIcondition\fP 1i +Specifies the mask that indicates either a read, write, or exception condition +or some operating-system-dependent condition. +.IP \fIproc\fP 1i +Specifies the procedure called when input is available. +.IP \fIclient_data\fP 1i +Specifies the parameter to be passed to \fIproc\fP when input is available. +.LP +.eM +The +.PN XtAddInput +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 \fIfile\fP should be loosely interpreted to mean any sink +or source of data.) +.PN XtAddInput +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 procedure is called. +This routine has been replaced by +.PN XtAppAddInput . +.PN XtInitialize +must be called before using this routine. +.sp +.IN "XtAddTimeOut" "" "@DEF@" +.sM +.FD 0 +XtIntervalId XtAddTimeOut(\fIinterval\fP, \fIproc\fP, \fIclient_data\fP) +.br + unsigned long \fIinterval\fP; +.br + XtTimerCallbackProc \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIinterval\fP 1i +Specifies the time interval in milliseconds. +.IP \fIproc\fP 1i +Specifies the procedure to be called when time expires. +.IP \fIclient_data\fP 1i +Specifies the parameter to be passed to \fIproc\fP when it is called. +.LP +.eM +The +.PN XtAddTimeOut +function creates a timeout in the default application context +and returns an identifier for it. +The timeout value is set to \fIinterval\fP. +The callback procedure will be called after +the time interval elapses, after which the timeout is removed. +This routine has been replaced by +.PN XtAppAddTimeOut . +.PN XtInitialize +must be called before using this routine. +.sp +.IN "XtAddWorkProc" "" "@DEF@" +.sM +.FD 0 +XtWorkProcId XtAddWorkProc(\fIproc\fP, \fIclient_data\fP) +.br + XtWorkProc \fIproc\fP; +.br + XtPointer \fIclient_data\fP; +.FN +.IP \fIproc\fP 1i +Procedure to call to do the work. +.IP \fIclient_data\fP 1i +Client data to pass to \fIproc\fP when it is called. +.LP +.eM +This routine registers a work procedure in the default application context. It has +been replaced by +.PN XtAppAddWorkProc . +.PN XtInitialize +must be called before using this routine. +.sp +.IN "XtCreateApplicationShell" "" "@DEF@" +.sM +.FD 0 +Widget XtCreateApplicationShell(\fIname\fP, \fIwidget_class\fP, \fIargs\fP, \ +\fInum_args\fP) +.br + String \fIname\fP; +.br + WidgetClass \fIwidget_class\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIname\fP 1i +This parameter is ignored; therefore, you can specify NULL. +.IP \fIwidget_class\fP 1i +Specifies the widget class pointer for the created application shell widget. +This will usually be +.PN topLevelShellWidgetClass +or a subclass thereof. +.IP \fIargs\fP 1i +Specifies the argument list to override any other resource specifications. +.IP \fInum_args\fP 1i +Specifies the number of entries in \fIargs\fP. +.LP +.eM +The procedure +.PN XtCreateApplicationShell +calls +.PN XtAppCreateShell +with \fIapplication_name\fP NULL, the application class passed to +.PN XtInitialize , +and the default application context created by +.PN XtInitialize . +This routine has been replaced by +.PN XtAppCreateShell . +.sp +.LP +An old-format resource type converter procedure pointer is of type +.PN XtConverter . +.LP +.IN "XtConverter" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtConverter)(XrmValue*, Cardinal*, XrmValue*, XrmValue*); +.br + XrmValue *\fIargs\fP; +.br + Cardinal *\fInum_args\fP; +.br + XrmValue *\fIfrom\fP; +.br + XrmValue *\fIto\fP; +.FN +.IP \fIargs\fP 1i +Specifies a list of additional +.PN XrmValue +arguments to the converter if additional context is needed +to perform the conversion, or NULL. +.IP \fInum_args\fP 1i +Specifies the number of entries in \fIargs\fP. +.IP \fIfrom\fP 1i +Specifies the value to convert. +.IP \fIto\fP 1i +Specifies the descriptor to use to return the converted value. +.LP +.eM +Type converters should perform the following actions: +.IP \(bu 5 +Check to see that the number of arguments passed is correct. +.IP \(bu 5 +Attempt the type conversion. +.IP \(bu 5 +If successful, return the size and pointer to the data in the \fIto\fP argument; +otherwise, call +.PN XtWarningMsg +and return without modifying the \fIto\fP argument. +.LP +Most type converters just take the data described by the specified \fIfrom\fP +argument and return data by writing into the specified \fIto\fP argument. +A few need other information, which is available in the specified +argument list. +A type converter can invoke another type converter, +which allows differing sources that may convert into a common intermediate +result to make maximum use of the type converter cache. +.LP +Note that the address returned in \fIto->addr\fP 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. +.LP +The procedure type +.PN XtConverter +has been replaced by +.PN XtTypeConverter . +.sp +.LP +The +.PN XtStringConversionWarning +.IN "XtStringConversionWarning" "" "@DEF@" +function is a convenience routine for old-format resource converters +that convert from strings. +.LP +.sM +.FD 0 +void XtStringConversionWarning(\fIsrc\fP, \fIdst_type\fP) +.br + String \fIsrc\fP, \fIdst_type\fP; +.FN +.IP \fIsrc\fP 1i +Specifies the string that could not be converted. +.IP \fIdst_type\fP 1i +Specifies the name of the type to which the string could not be converted. +.LP +.eM +The +.PN XtStringConversionWarning +function issues a warning message with name ``conversionError'', +type ``string'', class ``XtToolkitError, and the default message string +``Cannot convert "\fIsrc\fP" to type \fIdst_type\fP''. This routine +has been superseded by +.PN XtDisplayStringConversionWarning . +.sp +.LP +To register an old-format converter, use +.PN XtAddConverter +.IN "XtAddConverter" "" "@DEF@" +or +.PN XtAppAddConverter . +.IN "XtAppAddConverter" "" "@DEF@" +.LP +.sM +.FD 0 +void XtAddConverter(\fIfrom_type\fP, \fIto_type\fP, \fIconverter\fP, \ +\fIconvert_args\fP, \fInum_args\fP) +.br + String \fIfrom_type\fP; +.br + String \fIto_type\fP; +.br + XtConverter \fIconverter\fP; +.br + XtConvertArgList \fIconvert_args\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIfrom_type\fP 1i +Specifies the source type. +.IP \fIto_type\fP 1i +Specifies the destination type. +.IP \fIconverter\fP 1i +Specifies the type converter procedure. +.IP \fIconvert_args\fP 1i +Specifies how to compute the additional arguments to the converter, or NULL. +.IP \fInum_args\fP 1i +Specifies the number of entries in \fIconvert_args\fP. +.sp +.LP +.eM +.PN XtAddConverter +is equivalent in function to +.PN XtSetTypeConverter +with \fIcache_type\fP equal to +.PN XtCacheAll +for old-format type converters. It has been superseded by +.PN XtSetTypeConverter . +.sp +.sM +.FD 0 +void XtAppAddConverter(\fIapp_context\fP, \fIfrom_type\fP, \fIto_type\fP, \ +\fIconverter\fP, \fIconvert_args\fP, \fInum_args\fP) +.br + XtAppContext \fIapp_context\fP; +.br + String \fIfrom_type\fP; +.br + String \fIto_type\fP; +.br + XtConverter \fIconverter\fP; +.br + XtConvertArgList \fIconvert_args\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fIfrom_type\fP 1i +Specifies the source type. +.IP \fIto_type\fP 1i +Specifies the destination type. +.IP \fIconverter\fP 1i +Specifies the type converter procedure. +.IP \fIconvert_args\fP 1i +Specifies how to compute the additional arguments to the converter, or NULL. +.IP \fInum_args\fP 1i +Specifies the number of entries in \fIconvert_args\fP. +.LP +.eM +.PN XtAppAddConverter +is equivalent in function to +.PN XtAppSetTypeConverter +with \fIcache_type\fP equal to +.PN XtCacheAll +for old-format type converters. It has been superseded by +.PN XtAppSetTypeConverter . +.sp +.LP +To invoke resource conversions, a client may use +.PN XtConvert +or, for old-format converters only, +.PN XtDirectConvert . +.LP +.IN "XtConvert" "" "@DEF@" +.sM +.FD 0 +void XtConvert(\fIw\fP, \fIfrom_type\fP, \fIfrom\fP, \fIto_type\fP, \ +\fIto_return\fP) +.br + Widget \fIw\fP; +.br + String \fIfrom_type\fP; +.br + XrmValuePtr \fIfrom\fP; +.br + String \fIto_type\fP; +.br + XrmValuePtr \fIto_return\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget to use for additional arguments, if any are +needed. +.IP \fIfrom_type\fP 1i +Specifies the source type. +.IP \fIfrom\fP 1i +Specifies the value to be converted. +.IP \fIto_type\fP 1i +Specifies the destination type. +.IP \fIto_return\fP 1i +Returns the converted value. +.LP +.IN "XtDirectConvert" "" "@DEF@" +.FD 0 +void XtDirectConvert(\fIconverter\fP, \fIargs\fP, \fInum_args\fP, \fIfrom\fP, \ +\fIto_return\fP) +.br + XtConverter \fIconverter\fP; +.br + XrmValuePtr \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.br + XrmValuePtr \fIfrom\fP; +.br + XrmValuePtr \fIto_return\fP; +.FN +.IP \fIconverter\fP 1i +Specifies the conversion procedure to be called. +.IP \fIargs\fP 1i +Specifies the argument list that contains the additional arguments +needed to perform the conversion (often NULL). +.IP \fInum_args\fP 1i +Specifies the number of entries in \fIargs\fP. +.IP \fIfrom\fP 1i +Specifies the value to be converted. +.IP \fIto_return\fP 1i +Returns the converted value. +.LP +.eM +The +.PN XtConvert +function looks up the type converter registered to convert \fIfrom_type\fP +to \fIto_type\fP, computes any additional arguments needed, and then calls +.PN XtDirectConvert +or +.PN XtCallConverter . +The +.PN XtDirectConvert +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. +.LP +Before calling the specified converter, +.PN XtDirectConvert +sets the return value size to zero and the return value address to NULL. +To determine if the conversion was successful, +the client should check \fIto_return.addr\fP for non-NULL. +The data returned by +.PN XtConvert +must be copied immediately by the caller, +as it may point to static data in the type converter. +.LP +.PN XtConvert +has been replaced by +.PN XtConvertAndStore , +and +.PN XtDirectConvert +has been superseded by +.PN XtCallConverter . +.sp +.LP +To deallocate a shared GC when it is no longer needed, use +.PN XtDestroyGC . +.LP +.IN "XtDestroyGC" "" "@DEF@" +.sM +.FD 0 +void XtDestroyGC(\fIw\fP, \fIgc\fP) +.br + Widget \fIw\fP; +.br + GC \fIgc\fP; +.FN +.IP \fIw\fP 1i +Specifies any object on the display for which the shared GC was +created. \*(oI +.IP \fIgc\fP 1i +Specifies the shared GC to be deallocated. +.LP +.eM +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 +.PN XtDestroyGC +had only a \fIgc\fP argument. +Therefore, this function is not very portable, +and you are encouraged to use +.PN XtReleaseGC +instead. +.sp +.LP +To declare an action table in the default application context +and register it with the translation manager, use +.PN XtAddActions . +.LP +.IN "XtAddActions" "" "@DEF@" +.sM +.FD 0 +void XtAddActions(\fIactions\fP, \fInum_actions\fP) +.br + XtActionList \fIactions\fP; +.br + Cardinal \fInum_actions\fP; +.FN +.IP \fIactions\fP 1i +Specifies the action table to register. +.IP \fInum_actions\fP 1i +Specifies the number of entries in \fIactions\fP. +.LP +.eM +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 \*(xI register an action table for +.PN XtMenuPopup +and +.PN XtMenuPopdown +as part of \*(tk initialization. +This routine has been replaced by +.PN XtAppAddActions . +.PN XtInitialize +must be called before using this routine. +.sp +.LP +To set the \*(xI selection timeout in the default application context, use +.PN XtSetSelectionTimeout . +.LP +.IN "XtSetSelectionTimeout" "" "@DEF@" +.sM +.FD 0 +void XtSetSelectionTimeout(\fItimeout\fP) +.br + unsigned long \fItimeout\fP; +.FN +.IP \fItimeout\fP 1i +Specifies the selection timeout in milliseconds. +This routine has been replaced by +.PN XtAppSetSelectionTimeout . +.PN XtInitialize +must be called before using this routine. +.LP +.eM +.sp +.LP +To get the current selection timeout value in the default application +context, use +.PN XtGetSelectionTimeout . +.LP +.IN "XtGetSelectionTimeout" "" "@DEF@" +.sM +.FD 0 +unsigned long XtGetSelectionTimeout() +.FN +.LP +.eM +The selection timeout is the time within which the two communicating +applications must respond to one another. +If one of them does not respond within this interval, +the \*(xI abort the selection request. +.LP +This routine has been replaced by +.PN XtAppGetSelectionTimeout . +.PN XtInitialize +must be called before using this routine. +.sp +.LP +To obtain the global error database (for example, to merge with +an application- or widget-specific database), use +.PN XtGetErrorDatabase . +.LP +.IN "XtGetErrorDatabase" "" "@DEF@" +.sM +.FD 0 +XrmDatabase *XtGetErrorDatabase() +.FN +.LP +.eM +The +.PN XtGetErrorDatabase +function returns the address of the error database. +The \*(xI do a lazy binding of the error database and do not merge in the +database file until the first call to +.PN XtGetErrorDatbaseText . +This routine has been replaced by +.PN XtAppGetErrorDatabase . +.sp +.LP +An error message handler can obtain the error database text for an +error or a warning by calling +.PN XtGetErrorDatabaseText . +.LP +.IN "XtGetErrorDatabaseText" "" "@DEF@" +.sM +.FD 0 +void XtGetErrorDatabaseText(\fIname\fP, \fItype\fP, \fIclass\fP, \ +\fIdefault\fP, \fIbuffer_return\fP, \fInbytes\fP) +.br + String \fIname\fP, \fItype\fP, \fIclass\fP; +.br + String \fIdefault\fP; +.br + String \fIbuffer_return\fP; +.br + int \fInbytes\fP; +.FN +.IP \fIname\fP 1i +.br +.ns +.IP \fItype\fP 1i +Specify the name and type that are concatenated to form the resource name +of the error message. +.IP \fIclass\fP 1i +Specifies the resource class of the error message. +.IP \fIdefault\fP 1i +Specifies the default message to use if an error database entry is not found. +.IP \fIbuffer_return\fP 1i +Specifies the buffer into which the error message is to be returned. +.IP \fInbytes\fP 1i +Specifies the size of the buffer in bytes. +.LP +.eM +The +.PN XtGetErrorDatabaseText +returns the appropriate message from the error database +associated with the default application 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 \fIname\fP and \fItype\fP are concatenated with a single ``.'' +between them and the \fIclass\fP is concatenated with itself with a +single ``.'' if it does not already contain a ``.''. +This routine has been superseded by +.PN XtAppGetErrorDatabaseText . +.sp +.LP +To register a procedure to be called on fatal error conditions, use +.PN XtSetErrorMsgHandler . +.LP +.IN "XtSetErrorMsgHandler" "" "@DEF@" +.sM +.FD 0 +void XtSetErrorMsgHandler(\fImsg_handler\fP) +.br + XtErrorMsgHandler \fImsg_handler\fP; +.FN +.IP \fImsg_handler\fP 1i +Specifies the new fatal error procedure, which should not return. +.LP +.eM +The default error handler provided by the \*(xI constructs a +string from the error resource database and calls +.PN XtError . +Fatal error message handlers should not return. +If one does, +subsequent \*(xI behavior is undefined. +This routine has been superseded by +.PN XtAppSetErrorMsgHandler . +.sp +.LP +To call the high-level error handler, use +.PN XtErrorMsg . +.LP +.IN "XtErrorMsg" "" "@DEF@" +.sM +.FD 0 +void XtErrorMsg(\fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \ +\fIparams\fP, \fInum_params\fP) +.br + String \fIname\fP; +.br + String \fItype\fP; +.br + String \fIclass\fP; +.br + String \fIdefault\fP; +.br + String *\fIparams\fP; +.br + Cardinal *\fInum_params\fP; +.FN +.IP \fIname\fP 1i +Specifies the general kind of error. +.IP \fItype\fP 1i +Specifies the detailed name of the error. +.IP \fIclass\fP 1i +Specifies the resource class. +.IP \fIdefault\fP 1i +Specifies the default message to use if an error database entry is not found. +.IP \fIparams\fP 1i +Specifies a pointer to a list of values to be stored in the message. +.IP \fInum_params\fP 1i +Specifies the number of entries in \fIparams\fP. +.LP +.eM +This routine has been superseded by +.PN XtAppErrorMsg . +.sp +.LP +To register a procedure to be called on nonfatal error conditions, use +.PN XtSetWarningMsgHandler . +.LP +.IN "XtSetWarningMsgHandler" "" "@DEF@" +.sM +.FD 0 +void XtSetWarningMsgHandler(\fImsg_handler\fP) +.br + XtErrorMsgHandler \fImsg_handler\fP; +.FN +.IP \fImsg_handler\fP 1i +Specifies the new nonfatal error procedure, which usually returns. +.LP +.eM +The default warning handler provided by the \*(xI constructs a string +from the error resource database and calls +.PN XtWarning . +This routine has been superseded by +.PN XtAppSetWarningMsgHandler . +.sp +.LP +To call the installed high-level warning handler, use +.PN XtWarningMsg . +.LP +.IN "XtWarningMsg" "" "@DEF@" +.sM +.FD 0 +void XtWarningMsg(\fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \ +\fIparams\fP, \fInum_params\fP) +.br + String \fIname\fP; +.br + String \fItype\fP; +.br + String \fIclass\fP; +.br + String \fIdefault\fP; +.br + String *\fIparams\fP; +.br + Cardinal *\fInum_params\fP; +.FN +.IP \fIname\fP 1i +Specifies the general kind of error. +.IP \fItype\fP 1i +Specifies the detailed name of the error. +.IP \fIclass\fP 1i +Specifies the resource class. +.IP \fIdefault\fP 1i +Specifies the default message to use if an error database entry is not found. +.IP \fIparams\fP 1i +Specifies a pointer to a list of values to be stored in the message. +.IP \fInum_params\fP 1i +Specifies the number of entries in \fIparams\fP. +.LP +.eM +This routine has been superseded by +.PN XtAppWarningMsg . +.sp +.LP +To register a procedure to be called on fatal error conditions, use +.PN XtSetErrorHandler . +.LP +.IN "XtSetErrorHandler" "" "@DEF@" +.sM +.FD 0 +void XtSetErrorHandler(\fIhandler\fP) +.br + XtErrorHandler \fIhandler\fP; +.FN +.IP \fIhandler\fP 1i +Specifies the new fatal error procedure, which should not return. +.LP +.eM +The default error handler provided by the \*(xI is +.PN _XtError . +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 \*(tk behavior is undefined. +This routine has been superseded by +.PN XtAppSetErrorHandler . +.sp +.LP +To call the installed fatal error procedure, use +.PN XtError . +.LP +.IN "XtError" "" "@DEF@" +.sM +.FD 0 +void XtError(\fImessage\fP) +.br + String \fImessage\fP; +.FN +.IP \fImessage\fP 1i +Specifies the message to be reported. +.LP +.eM +Most programs should use +.PN XtAppErrorMsg , +not +.PN XtError , +to provide for customization and internationalization of error +messages. This routine has been superseded by +.PN XtAppError . +.sp +.LP +To register a procedure to be called on nonfatal error conditions, use +.PN XtSetWarningHandler . +.LP +.IN "XtSetWarningHandler" "" "@DEF@" +.sM +.FD 0 +void XtSetWarningHandler(\fIhandler\fP) +.br + XtErrorHandler \fIhandler\fP; +.FN +.IP \fIhandler\fP 1i +Specifies the new nonfatal error procedure, which usually returns. +.LP +.eM +The default warning handler provided by the \*(xI is +.PN _XtWarning . +On POSIX-based systems, +it prints the message to standard error and returns to the caller. +This routine has been superseded by +.PN XtAppSetWarningHandler . +.sp +.LP +To call the installed nonfatal error procedure, use +.PN XtWarning . +.LP +.IN "XtWarning" "" "@DEF@" +.sM +.FD 0 +void XtWarning(\fImessage\fP) +.br + String \fImessage\fP; +.FN +.IP \fImessage\fP 1i +Specifies the nonfatal error message to be reported. +.LP +.eM +Most programs should use +.PN XtAppWarningMsg , +not +.PN XtWarning , +to provide for customization and internationalization of warning messages. +This routine has been superseded by +.PN XtAppWarning . diff --git a/specs/appD b/specs/appD new file mode 100644 index 0000000..5322ff9 --- /dev/null +++ b/specs/appD @@ -0,0 +1,602 @@ +.\" $Xorg: appD,v 1.3 2000/08/17 19:42:48 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +.bp +\& +.sp 1 +.ce 3 +\s+1\fBAppendix D\fP\s-1 + +\s+1\fBIntrinsics Error Messages\fP\s-1 +.sp 2 +.LP +.XS +\fBAppendix D \(em Intrinsics Error Messages\fP +.XE +.LP +All \*(xI errors and warnings have class +``XtToolkitError''. +The following two tables summarize the common errors and warnings that can be +generated by the \*(xI. +Additional implementation-dependent messages are permitted. +.SH +Error Messages +.LP +.ps 9 +.nr PS 9 +.TS +lw(1.3i) lw(1.4i) lw(2.9i). +_ +.sp 6p +Name Type Default Message +.sp 6p +_ +.sp 6p +allocError calloc T{ +Cannot perform calloc +T} +allocError malloc T{ +Cannot perform malloc +T} +allocError realloc T{ +Cannot perform realloc +T} +internalError xtMakeGeometryRequest T{ +internal error; ShellClassExtension is NULL +T} +invalidArgCount xtGetValues T{ +Argument count > 0 on NULL argument list in XtGetValues +T} +invalidArgCount xtSetValues T{ +Argument count > 0 on NULL argument list in XtSetValues +T} +invalidClass applicationShellInsertChild T{ +ApplicationShell does not accept RectObj children; ignored +T} +invalidClass constraintSetValue T{ +Subclass of Constraint required in CallConstraintSetValues +T} +invalidClass xtAppCreateShell T{ +XtAppCreateShell requires non-NULL widget class +T} +invalidClass xtCreatePopupShell T{ +XtCreatePopupShell requires non-NULL widget class +T} +invalidClass xtCreateWidget T{ +XtCreateWidget requires non-NULL widget class +T} +invalidClass xtPopdown T{ +XtPopdown requires a subclass of shellWidgetClass +T} +invalidClass xtPopup T{ +XtPopup requires a subclass of shellWidgetClass +T} +invalidDimension xtCreateWindow T{ +Widget %s has zero width and/or height +T} +invalidDimension shellRealize T{ +Shell widget %s has zero width and/or height +T} +invalidDisplay xtInitialize T{ +Can't open display: %s +T} +invalidGetValues xtGetValues T{ +NULL ArgVal in XtGetValues +T} +invalidExtension shellClassPartInitialize T{ +widget class %s has invalid ShellClassExtension record +T} +invalidExtension xtMakeGeometryRequest T{ +widget class %s has invalid ShellClassExtension record +T} +invalidGeometryManager xtMakeGeometryRequest T{ +XtMakeGeometryRequest - parent has no geometry manager +T} +invalidParameter xtAddInput T{ +invalid condition passed to XtAddInput +T} +invalidParameter xtAddInput T{ +invalid condition passed to XtAppAddInput +T} +invalidParent xtChangeManagedSet T{ +Attempt to manage a child when parent is not Composite +T} +invalidParent xtChangeManagedSet T{ +Attempt to unmanage a child when parent is not Composite +T} +invalidParent xtCreatePopupShell T{ +XtCreatePopupShell requires non-NULL parent +T} +invalidParent xtCreateWidget T{ +XtCreateWidget requires non-NULL parent +T} +invalidParent xtMakeGeometryRequest T{ +non-shell has no parent in XtMakeGeometryRequest +T} +invalidParent xtMakeGeometryRequest T{ +XtMakeGeometryRequest - parent not composite +T} +invalidParent xtManageChildren T{ +Attempt to manage a child when parent is not Composite +T} +invalidParent xtUnmanageChildren T{ +Attempt to unmanage a child when parent is not Composite +T} +invalidProcedure inheritanceProc T{ +Unresolved inheritance operation +T} +invalidProcedure realizeProc T{ +No realize class procedure defined +T} +invalidWindow eventHandler T{ +Event with wrong window +T} +missingWidget fetchDisplayArg T{ +FetchDisplayArg called without a widget to reference +T} +nonWidget xtCreateWidget T{ +attempt to add non-widget child "%s" to parent "%s" which supports only widgets +T} +noPerDisplay closeDisplay T{ +Couldn't find per display information +T} +noPerDisplay getPerDisplay T{ +Couldn't find per display information +T} +noSelectionProperties freeSelectionProperty T{ +internal error: no selection property context for display +T} +noWidgetAncestor windowedAncestor T{ +Object "%s" does not have windowed ancestor +T} +nullDisplay xtRegisterExtensionSelector T{ +XtRegisterExtensionSelector requires a non-NULL display +T} +nullProc insertChild T{ +"%s" parent has NULL insert_child method +T} +r2versionMismatch widget T{ +Widget class %s must be re-compiled. +T} +R3versionMismatch widget T{ +Widget class %s must be re-compiled. +T} +R4orR5versionMismatch widget T{ +Widget class %s must be re-compiled. +T} +rangeError xtRegisterExtensionSelector T{ +Attempt to register multiple selectors for one extension event type +T} +sessionManagement SmcOpenConnection T{ +Tried to connect to session manager, %s +T} +subclassMismatch xtCheckSubclass T{ +Widget class %s found when subclass of %s expected: %s +T} +.sp 6p +_ +.TE +.ps 11 +.nr PS 11 +.SH +Warning Messages +.LP +.ps 9 +.nr PS 9 +.TS +lw(1.3i) lw(1.4i) lw(2.9i). +_ +.sp 6p +Name Type Default Message +.sp 6p +_ +.sp 6p +ambiguousParent xtChangeManagedSet T{ +Not all children have same parent +T} +ambiguousParent xtManageChildren T{ +Not all children have same parent in XtManageChildren +T} +ambiguousParent xtUnmanageChildren T{ +Not all children have same parent in XtUnmanageChildren +T} +badFormat xtGetSelectionValue T{ +Selection owner returned type INCR property with format != 32 +T} +badGeometry shellRealize T{ +Shell widget "%s" has an invalid geometry specification: "%s" +T} +badValue cvtStringToPixel T{ +Color name "%s" is not defined +T} +communicationError select T{ +Select failed; error code %s +T} +conversionError string T{ +Cannot convert string "%s" to type %s +T} +conversionError stringToVisual T{ +Cannot find Visual of class %s for display %s +T} +conversionFailed xtConvertVarToArgList T{ +Type conversion failed +T} +conversionFailed xtGetTypedArg T{ +Type conversion (%s to %s) failed for widget '%s' +T} +displayError invalidDisplay T{ +Can't find display structure +T} +grabError xtAddGrab T{ +XtAddGrab requires exclusive grab if spring_loaded is TRUE +T} +grabError xtRemoveGrab T{ +XtRemoveGrab asked to remove a widget not on the list +T} +.TE +.TS +lw(1.3i) lw(1.4i) lw(2.9i). +initializationError xtInitialize T{ +Initializing Resource Lists twice +T} +insufficientSpace xtGetTypedArg T{ +Insufficient space for converted type '%s' in widget '%s' +T} +internalError shell T{ +Shell's window manager interaction is broken +T} +invalidAddressMode computeArgs T{ +Conversion arguments for widget '%s' contain an unsupported address mode +T} +invalidArgCount getResources T{ +argument count > 0 on NULL argument list +T} +invalidCallbackList xtAddCallback T{ +Cannot find callback list in XtAddCallback +T} +invalidCallbackList xtAddCallback T{ +Cannot find callback list in XtAddCallbacks +T} +invalidCallbackList xtCallCallback T{ +Cannot find callback list in XtCallCallbacks +T} +invalidCallbackList xtRemoveAllCallback T{ +Cannot find callback list in XtRemoveAllCallbacks +T} +invalidCallbackList xtRemoveCallback T{ +Cannot find callback list in XtRemoveCallbacks +T} +invalidChild xtChangeManagedSet T{ +Null child passed to UnmanageChildren +T} +invalidChild xtManageChildren T{ +null child passed to ManageChildren +T} +invalidChild xtManageChildren T{ +null child passed to XtManageChildren +T} +invalidChild xtUnmanageChildren T{ +Null child passed to XtUnmanageChildren +T} +invalidChild xtUnmanageChildren T{ +Null child found in argument list to unmanage +T} +invalidDepth setValues T{ +Can't change widget depth +T} +invalidExtension xtCreateWidget T{ +widget "%s" class %s has invalid CompositeClassExtension record +T} +invalidExtension xtCreateWidget T{ +widget class %s has invalid ConstraintClassExtension record +T} +invalidGrab ungrabKeyOrButton T{ +Attempt to remove nonexistent passive grab +T} +invalidGrabKind xtPopup T{ +grab kind argument has invalid value; XtGrabNone assumed +T} +invalidParameters freeTranslations T{ +Freeing XtTranslations requires no extra arguments +T} +invalidParameters mergeTranslations T{ +MergeTM to TranslationTable needs no extra arguments +T} +invalidParameters xtMenuPopdown T{ +XtMenuPopdown called with num_params != 0 or 1 +T} +invalidParameters xtMenuPopupAction T{ +MenuPopup wants exactly one argument +T} +invalidParent xtCopyFromParent T{ +CopyFromParent must have non-NULL parent +T} +invalidPopup xtMenuPopup T{ +Can't find popup widget "%s" in XtMenuPopup +T} +invalidPopup xtMenuPopdown T{ +Can't find popup in widget "%s" in XtMenuPopdown +T} +invalidPopup unsupportedOperation T{ +Pop-up menu creation is only supported on ButtonPress, KeyPress or EnterNotify events. +T} +invalidPopup unsupportedOperation T{ +Pop-up menu creation is only supported on Button, Key or EnterNotify events. +T} +invalidProcedure deleteChild T{ +null delete_child procedure for class %s in XtDestroy +T} +invalidProcedure inputHandler T{ +XtRemoveInput: Input handler not found +T} +invalidProcedure set_values_almost T{ +set_values_almost procedure shouldn't be NULL +T} +invalidResourceCount getResources T{ +resource count > 0 on NULL resource list +T} +invalidResourceName computeArgs T{ +Cannot find resource name %s as argument to conversion +T} +invalidShell xtTranslateCoords T{ +Widget has no shell ancestor +T} +invalidSizeOverride xtDependencies T{ +Representation size %d must match superclass's to override %s +T} +missingCharsetList cvtStringToFontSet T{ +Missing charsets in String to FontSet conversion +T} +noActionProc xtCallActionProc T{ +No action proc named "%s" is registered for widget "%s" +T} +noColormap cvtStringToPixel T{ +Cannot allocate colormap entry for "%s" +T} +noFont cvtStringToFont T{ +Unable to load any usable ISO8859-1 font +T} +noFont cvtStringToFontSet T{ +Unable to load any usable fontset +T} +noFont cvtStringToFontStruct T{ +Unable to load any usable ISO8859-1 font +T} +.TE +.TS +lw(1.3i) lw(1.4i) lw(2.9i). +notInConvertSelection xtGetSelectionRequest T{ +XtGetSelectionRequest or XtGetSelectionParameters called for widget "%s" outside of ConvertSelection proc +T} +notRectObj xtChangeManagedSet T{ +child "%s", class %s is not a RectObj +T} +notRectObj xtManageChildren T{ +child "%s", class %s is not a RectObj +T} +nullWidget xtConvertVarToArgList T{ +XtVaTypedArg conversion needs non-NULL widget handle +T} +r3versionMismatch widget T{ +Shell Widget class %s binary compiled for R3 +T} +translationError nullTable T{ +Can't remove accelerators from NULL table +T} +translationError nullTable T{ +Tried to remove nonexistent accelerators +T} +translationError ambiguousActions T{ +Overriding earlier translation manager actions. +T} +translationError newActions T{ +New actions are:%s +T} +translationError nullTable T{ +table to (un)merge must not be null +T} +translationError nullTable T{ +Can't translate event through NULL table +T} +translationError oldActions T{ +Previous entry was: %s %s +T} +translationError unboundActions T{ +Actions not found: %s +T} +translationError xtTranslateInitialize T{ +Initializing Translation manager twice. +T} +translationParseError missingComma T{ + ... possibly due to missing ',' in event sequence. +T} +translationParseError nonLatin1 T{ + ... probably due to non-Latin1 character in quoted string +T} +translationParseError parseError T{ +translation table syntax error: %s +T} +translationParseError parseString T{ +Missing '"'. +T} +translationParseError showLine T{ + ... found while parsing '%s' +T} +typeConversionError noConverter T{ +No type converter registered for '%s' to '%s' conversion. +T} +unknownType xtConvertVarToArgList T{ +Unable to find type of resource for conversion +T} +unknownType xtGetTypedArg T{ +Unable to find type of resource for conversion +T} +versionMismatch widget T{ +Widget class %s version mismatch (recompilation needed):\\n widget %d vs. intrinsics %d. +T} +wrongParameters cvtIntOrPixelToXColor T{ +Pixel to color conversion needs screen and colormap arguments +T} +wrongParameters cvtIntToBool T{ +Integer to Bool conversion needs no extra arguments +T} +wrongParameters cvtIntToBoolean T{ +Integer to Boolean conversion needs no extra arguments +T} +wrongParameters cvtIntToFloat T{ +Integer to Float conversion needs no extra arguments +T} +wrongParameters cvtIntToFont T{ +Integer to Font conversion needs no extra arguments +T} +wrongParameters cvtIntToPixel T{ +Integer to Pixel conversion needs no extra arguments +T} +wrongParameters cvtIntToPixmap T{ +Integer to Pixmap conversion needs no extra arguments +T} +wrongParameters cvtIntToShort T{ +Integer to Short conversion needs no extra arguments +T} +wrongParameters cvtIntToUnsignedChar T{ +Integer to UnsignedChar conversion needs no extra arguments +T} +wrongParameters cvtStringToAcceleratorTable T{ +String to AcceleratorTable conversion needs no extra arguments +T} +wrongParameters cvtStringToAtom T{ +String to Atom conversion needs Display argument +T} +wrongParameters cvtStringToBool T{ +String to Bool conversion needs no extra arguments +T} +wrongParameters cvtStringToBoolean T{ +String to Boolean conversion needs no extra arguments +T} +wrongParameters cvtStringToCommandArgArray T{ +String to CommandArgArray conversion needs no extra arguments +T} +wrongParameters cvtStringToCursor T{ +String to cursor conversion needs display argument +T} +wrongParameters cvtStringToDimension T{ +String to Dimension conversion needs no extra arguments +T} +wrongParameters cvtStringToDirectoryString T{ +String to DirectoryString conversion needs no extra arguments +T} +.TE +.TS +lw(1.3i) lw(1.4i) lw(2.9i). +wrongParameters cvtStringToDisplay T{ +String to Display conversion needs no extra arguments +T} +wrongParameters cvtStringToFile T{ +String to File conversion needs no extra arguments +T} +wrongParameters cvtStringToFloat T{ +String to Float conversion needs no extra arguments +T} +wrongParameters cvtStringToFont T{ +String to font conversion needs display argument +T} +wrongParameters cvtStringToFontSet T{ +String to FontSet conversion needs display and locale arguments +T} +wrongParameters cvtStringToFontStruct T{ +String to font conversion needs display argument +T} +wrongParameters cvtStringToGravity T{ +String to Gravity conversion needs no extra arguments +T} +wrongParameters cvtStringToInitialState T{ +String to InitialState conversion needs no extra arguments +T} +wrongParameters cvtStringToInt T{ +String to Integer conversion needs no extra arguments +T} +wrongParameters cvtStringToPixel T{ +String to pixel conversion needs screen and colormap arguments +T} +wrongParameters cvtStringToRestartStyle T{ +String to RestartStyle conversion needs no extra arguments +T} +wrongParameters cvtStringToShort T{ +String to Integer conversion needs no extra arguments +T} +wrongParameters cvtStringToTranslationTable T{ +String to TranslationTable conversion needs no extra arguments +T} +wrongParameters cvtStringToUnsignedChar T{ +String to Integer conversion needs no extra arguments +T} +wrongParameters cvtStringToVisual T{ +String to Visual conversion needs screen and depth arguments +T} +wrongParameters cvtXColorToPixel T{ +Color to Pixel conversion needs no extra arguments +T} +wrongParameters freeCursor T{ +Free Cursor requires display argument +T} +wrongParameters freeDirectoryString T{ +Free Directory String requires no extra arguments +T} +wrongParameters freeFile T{ +Free File requires no extra arguments +T} +wrongParameters freeFont T{ +Free Font needs display argument +T} +wrongParameters freeFontSet T{ +FreeFontSet needs display and locale arguments +T} +wrongParameters freeFontStruct T{ +Free FontStruct requires display argument +T} +wrongParameters freePixel T{ +Freeing a pixel requires screen and colormap arguments +T} +.sp 6p +_ +.TE +.ps 11 +.nr PS 11 diff --git a/specs/appE b/specs/appE new file mode 100644 index 0000000..1ce7270 --- /dev/null +++ b/specs/appE @@ -0,0 +1,606 @@ +.\" $Xorg: appE,v 1.3 2000/08/17 19:42:48 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +.bp +\& +.sp 1 +.ce 3 +\s+1\fBAppendix E\fP\s-1 + +\s+1\fB\fBDefined Strings\fP\s-1 +.sp 2 +.LP +.XS +\fBAppendix E \(em Defined Strings\fP +.XE +.LP +The +.PN StringDefs.h +header file contains definitions for the following resource name, +class, and representation type symbolic constants. +.IN "String Constants" "resource names" +.LP +Resource names: +.TS +lw(2i) lw(2.5i). +_ +.sp 6p +Symbol Definition +.sp 6p +_ +.sp 6p +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" +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" +XtNuseRight "useRight" +XtNvalue "value" +XtNvSpace "vSpace" +XtNwidth "width" +XtNwindow "window" +XtNx "x" +XtNy "y" +.sp 6p +_ +.TE +.sp 6p +.IN "String Constants" "resource classes" +.LP +Resource classes: +.TS +lw(2i) lw(2.5i). +_ +.sp 6p +Symbol Definition +.sp 6p +_ +.sp 6p +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" +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" +.sp 6p +_ +.TE +.sp 6p +.IN "String Constants" "representation types" +.LP +Resource representation types: +.TS +lw(2i) lw(2.5i). +_ +.sp 6p +Symbol Definition +.sp 6p +_ +.sp 6p +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" +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" +.sp 6p +_ +.TE +.sp 6p +.LP +Boolean enumeration constants: +.TS +lw(2i) lw(2.5i). +_ +.sp 6p +Symbol Definition +.sp 6p +_ +.sp 6p +XtEoff "off" +XtEfalse "false" +XtEno "no" +XtEon "on" +XtEtrue "true" +XtEyes "yes" +.sp 6p +_ +.TE +.sp 6p +.LP +Orientation enumeration constants: +.TS +lw(2i) lw(2.5i). +_ +.sp 6p +Symbol Definition +.sp 6p +_ +.sp 6p +XtEvertical "vertical" +XtEhorizontal "horizontal" +.sp 6p +_ +.TE +.sp 6p +.LP +Text edit enumeration constants: +.TS +lw(2i) lw(2.5i). +_ +.sp 6p +Symbol Definition +.sp 6p +_ +.sp 6p +XtEtextRead "read" +XtEtextAppend "append" +XtEtextEdit "edit" +.sp 6p +_ +.TE +.sp 6p +.LP +Color enumeration constants: +.TS +lw(2i) lw(2.5i). +_ +.sp 6p +Symbol Definition +.sp 6p +_ +.sp 6p +XtExtdefaultbackground "xtdefaultbackground" +XtExtdefaultforeground "xtdefaultforeground" +.sp 6p +_ +.TE +.sp 6p +.LP +Font constant: +.TS +lw(2i) lw(2.5i). +_ +.sp 6p +Symbol Definition +.sp 6p +_ +.sp 6p +XtExtdefaultfont "xtdefaultfont" +.sp 6p +_ +.TE +.sp 6p +.LP +Hooks for External Agents constants: +.TS +lw(2i) lw(2.5i). +_ +.sp 6p +Symbol Definition +.sp 6p +_ +.sp 6p +XtHcreate "Xtcreate" +XtHsetValues "Xtsetvalues" +XtHmanageChildren "XtmanageChildren" +XtHunmanageChildren "XtunmanageChildren" +XtHmanageSet "XtmanageSet" +XtHunmanageSet "XtunmanageSet" +XtHrealizeWidget "XtrealizeWidget" +XtHunrealizeWidget "XtunrealizeWidget" +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" +.sp 6p +_ +.TE +.sp 6p +.LP +The +.PN Shell.h +header file contains definitions for the following resource name, +class, and representation type symbolic constants. +.IN "String Constants" "resource names" +.LP +Resource names: +.TS +lw(2i) lw(2.5i). +_ +.sp 6p +Symbol Definition +.sp 6p +_ +.sp 6p +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" +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" +.sp 6p +_ +.TE +.sp 6p +.IN "String Constants" "resource classes" +.LP +Resource classes: +.TS +lw(2i) lw(2.5i). +_ +.sp 6p +Symbol Definition +.sp 6p +_ +.sp 6p +XtCAllowShellResize "allowShellResize" +XtCArgc "Argc" +XtCArgv "Argv" +XtCBaseHeight "BaseHeight" +XtCBaseWidth "BaseWidth" +XtCClientLeader "ClientLeader" +XtCCloneCommand "CloneCommand" +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" +.sp 6p +_ +.TE +.sp 6p +.IN "String Constants" "representation types" +.LP +Resource representation types: +.TS +lw(2i) lw(2.5i). +_ +.sp 6p +Symbol Definition +.sp 6p +_ +.sp 6p +XtRAtom "Atom" +.sp 6p +_ +.TE diff --git a/specs/appF b/specs/appF new file mode 100644 index 0000000..b74cf4a --- /dev/null +++ b/specs/appF @@ -0,0 +1,125 @@ +.\" $Xorg: appF,v 1.3 2000/08/17 19:42:49 cpqbld Exp $ +.\" Copyright \(co 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 documentation 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 PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation 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 +.\" permission 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. +.\" +.bp +\& +.sp 1 +.ce 3 +\s+1\fBAppendix F\fP\s-1 + +\s+1\fBResource Configuration Management\fP\s-1 +.sp 2 +.LP +.XS +\fBAppendix F \(em Resource Configuration Management\fP +.XE +Setting and changing resources in X applications can be difficult for +both the application programmer and the end user. \fBResource +Configuration Management (RCM)\fP addresses this problem by changing +the \fBX Intrinsics\fP to 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. +.LP +The main difference between \fBRCM\fP and the \fBEditres\fP +protocol is that the \fBRCM\fP +customizing hooks reside in the \fBIntrinsics\fP and thus are linked with +other toolkits such as Motif and the Athena widgets. However, the +\fBEditRes\fP protocol requires the application to link with the +\fBEditRes\fP +routines in the Xmu library and Xmu is not used by all applications that +use Motif. Also, the \fBEditRes\fP protocol uses ClientMessage, +whereas the +\fBRCM\fP \fBIntrinsics\fP hooks use \fBPropertyNotify\fP events. +.LP +X Properties and the \fBPropertyNotify\fP events are used +to implement \fBRCM\fP and +allow on-the-fly resource customization. When the X Toolkit is +initialized, two atoms are interned with the strings +\fICustom Init\fP and +\fICustom Data\fP. Both +.PN _XtCreatePopupShell +and +.PN _XtAppCreateShell +register a \fBPropertyNotify\fP event handler to handle these properties. +.LP +A customization tool uses the \fICustom Init\fP property to \fIping\fP 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. +.LP +A customization tool uses the \fICustom Data\fP 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 \fBXA_STRING\fP and +the format of the string is: +.IP 1. 5 +The length of the resource name (the number of bytes in +the resource name) +.IP 2. 5 +One space character +.IP 3. 5 +The resource name +.IP 4. 5 +One space character +.IP 5. 5 +The resource value +.LP +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 +.PN XtSetValues. +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. +.LP +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. + + diff --git a/specs/intr.idxmac.t b/specs/intr.idxmac.t new file mode 100644 index 0000000..9a3572d --- /dev/null +++ b/specs/intr.idxmac.t @@ -0,0 +1,3 @@ +.eh '\fBX Toolkit Intrinsics\fP''\fBX11 Release \*(Rn\fP' +.oh '\fBX Toolkit Intrinsics\fP''\fBX11 Release \*(Rn\fP' +.so index.pageno diff --git a/specs/postproc b/specs/postproc new file mode 100644 index 0000000..588b1de --- /dev/null +++ b/specs/postproc @@ -0,0 +1,19 @@ +.\" $Xorg: postproc,v 1.3 2000/08/17 19:42:49 cpqbld Exp $ +.EH '''' +.OH '''' +.if o .bp \" blank page to make index and ToC start on odd page +\& +.nr PN +1 +.XS +Index +.XE +.EQ +delim $$ +.EN +.tm .pn \n(PN +.nr PN -1 +.\" print Table of Contents +.bp 3 +.af PN i +.PX + diff --git a/specs/strings.mit b/specs/strings.mit new file mode 100644 index 0000000..7a93ba8 --- /dev/null +++ b/specs/strings.mit @@ -0,0 +1,17 @@ +.\" $Xorg: strings.mit,v 1.3 2000/08/17 19:42:49 cpqbld Exp $ +.ds tk X Toolkit +.ds xT X Toolkit Intrinsics \(em C Language Interface +.ds xI Intrinsics +.ds xW X Toolkit Athena Widgets \(em C Language Interface +.ds xL Xlib \(em C Language X Interface +.ds xC Inter-Client Communication Conventions Manual +.ds xP X Window System Protocol +.ds Rn 6.8 +.ds Vn 2.2 +.ds oI Must be of class Object or any subclass thereof. +.ds rI Must be of class RectObj or any subclass thereof. +.ds cI Must be of class Core or any subclass thereof. +.ds oC Must be \fBobjectClass\fP or any subclass thereof. +.ds rC Must be \fBrectObjClass\fP or any subclass thereof. +.hw XtMake-Geometry-Request XtQuery-Geometry wid-get Composite-Part \ +Rect-Obj-Rec XtIsOverrideShell super-class |