From 5f8448ef6b85a9ff72c5af4cec99183c8bb60dc6 Mon Sep 17 00:00:00 2001 From: marha Date: Tue, 10 Apr 2012 14:58:33 +0200 Subject: Updated following packages: bigreqsproto-1.1.2 fontsproto-2.1.2 recordproto-1.14.2 scrnsaverproto-1.2.2 xcmiscproto-1.2.2 libXt-1.1.3 xhost-1.0.5 kbproto-1.0.6 libXrender-0.9.7 libxkbfile-1.0.8 freetype-2.4.9 libXaw-1.0.10 libXpm-3.5.10 xproto-7.0.23 --- libXt/specs/CH01 | 2471 ----------------- libXt/specs/CH01.xml | 2798 ++++++++++++++++++++ libXt/specs/CH02 | 3165 ---------------------- libXt/specs/CH02.xml | 4538 ++++++++++++++++++++++++++++++++ libXt/specs/CH03 | 1031 -------- libXt/specs/CH03.xml | 1406 ++++++++++ libXt/specs/CH04 | 1998 -------------- libXt/specs/CH04.xml | 2498 ++++++++++++++++++ libXt/specs/CH05 | 783 ------ libXt/specs/CH05.xml | 1063 ++++++++ libXt/specs/CH06 | 1110 -------- libXt/specs/CH06.xml | 1369 ++++++++++ libXt/specs/CH07 | 3555 ------------------------- libXt/specs/CH07.xml | 4989 +++++++++++++++++++++++++++++++++++ libXt/specs/CH08 | 452 ---- libXt/specs/CH08.xml | 613 +++++ libXt/specs/CH09 | 3211 ----------------------- libXt/specs/CH09.xml | 4326 ++++++++++++++++++++++++++++++ libXt/specs/CH10 | 1521 ----------- libXt/specs/CH10.xml | 2211 ++++++++++++++++ libXt/specs/CH11 | 3566 ------------------------- libXt/specs/CH11.xml | 5538 +++++++++++++++++++++++++++++++++++++++ libXt/specs/CH12 | 1067 -------- libXt/specs/CH12.xml | 1166 +++++++++ libXt/specs/CH13 | 805 ------ libXt/specs/CH13.xml | 770 ++++++ libXt/specs/Makefile.am | 61 +- libXt/specs/Makefile.in | 601 +++++ libXt/specs/Xtk.intr.front | 333 --- libXt/specs/acknowledgement.xml | 323 +++ libXt/specs/appA | 107 - libXt/specs/appA.xml | 112 + libXt/specs/appB | 783 ------ libXt/specs/appB.xml | 1181 +++++++++ libXt/specs/appC | 1204 --------- libXt/specs/appC.xml | 1970 ++++++++++++++ libXt/specs/appD | 602 ----- libXt/specs/appD.xml | 880 +++++++ libXt/specs/appE | 606 ----- libXt/specs/appE.xml | 1703 ++++++++++++ libXt/specs/appF | 125 - libXt/specs/appF.xml | 103 + libXt/specs/intr.idxmac.t | 3 - libXt/specs/intrinsics.xml | 128 + libXt/specs/postproc | 19 - libXt/specs/preface.xml | 51 + libXt/specs/strings.mit | 16 - 47 files changed, 40374 insertions(+), 28557 deletions(-) delete mode 100644 libXt/specs/CH01 create mode 100644 libXt/specs/CH01.xml delete mode 100644 libXt/specs/CH02 create mode 100644 libXt/specs/CH02.xml delete mode 100644 libXt/specs/CH03 create mode 100644 libXt/specs/CH03.xml delete mode 100644 libXt/specs/CH04 create mode 100644 libXt/specs/CH04.xml delete mode 100644 libXt/specs/CH05 create mode 100644 libXt/specs/CH05.xml delete mode 100644 libXt/specs/CH06 create mode 100644 libXt/specs/CH06.xml delete mode 100644 libXt/specs/CH07 create mode 100644 libXt/specs/CH07.xml delete mode 100644 libXt/specs/CH08 create mode 100644 libXt/specs/CH08.xml delete mode 100644 libXt/specs/CH09 create mode 100644 libXt/specs/CH09.xml delete mode 100644 libXt/specs/CH10 create mode 100644 libXt/specs/CH10.xml delete mode 100644 libXt/specs/CH11 create mode 100644 libXt/specs/CH11.xml delete mode 100644 libXt/specs/CH12 create mode 100644 libXt/specs/CH12.xml delete mode 100644 libXt/specs/CH13 create mode 100644 libXt/specs/CH13.xml create mode 100644 libXt/specs/Makefile.in delete mode 100644 libXt/specs/Xtk.intr.front create mode 100644 libXt/specs/acknowledgement.xml delete mode 100644 libXt/specs/appA create mode 100644 libXt/specs/appA.xml delete mode 100644 libXt/specs/appB create mode 100644 libXt/specs/appB.xml delete mode 100644 libXt/specs/appC create mode 100644 libXt/specs/appC.xml delete mode 100644 libXt/specs/appD create mode 100644 libXt/specs/appD.xml delete mode 100644 libXt/specs/appE create mode 100644 libXt/specs/appE.xml delete mode 100644 libXt/specs/appF create mode 100644 libXt/specs/appF.xml delete mode 100644 libXt/specs/intr.idxmac.t create mode 100644 libXt/specs/intrinsics.xml delete mode 100644 libXt/specs/postproc create mode 100644 libXt/specs/preface.xml delete mode 100644 libXt/specs/strings.mit (limited to 'libXt/specs') diff --git a/libXt/specs/CH01 b/libXt/specs/CH01 deleted file mode 100644 index 78f128bd7..000000000 --- a/libXt/specs/CH01 +++ /dev/null @@ -1,2471 +0,0 @@ -.\" $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 - -/* 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\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/libXt/specs/CH01.xml b/libXt/specs/CH01.xml new file mode 100644 index 000000000..df2f96f81 --- /dev/null +++ b/libXt/specs/CH01.xml @@ -0,0 +1,2798 @@ + +Intrinsics and Widgets + +The Intrinsics are a programming library tailored to the special requirements +of user interface construction within a network window system, +specifically the X Window System. +The Intrinsics and a widget set make up an X Toolkit. + + +Intrinsics + +The Intrinsics provide the base mechanism necessary to build +a wide variety of interoperating widget sets and application environments. +The Intrinsics are a layer on top of Xlib, the +C Library X Interface. They extend the +fundamental abstractions provided by the X Window System while still +remaining independent of any particular user interface policy or +style. + + + +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. + + + +When the Intrinsics were first conceived, the root of the object +hierarchy was a widget class named +Core. +In Release 4 of the +Intrinsics, three nonwidget superclasses were added above Core. +These superclasses are described in . +The name of the class +now at the root of the Intrinsics class hierarchy is +Object. +The remainder of this +specification refers uniformly to widgets and Core +as if they were the +base class for all Intrinsics operations. The argument descriptions +for each Intrinsics procedure and +describe which operations +are defined for the nonwidget superclasses of Core. The reader may +determine by context whether a specific reference to widget +actually means ``widget'' or ``object.'' + + + + +Languages + +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 client refers to +any module, widget, or application that calls an Intrinsics procedure. + + + +Applications that use the Intrinsics mechanisms +must include the header files +<X11/Intrinsic.h> +and +<X11/StringDefs.h>, +or their equivalent, +and they may also include +<X11/Xatoms.h> +and +<X11/Shell.h>. +In addition, widget implementations should include +<X11/IntrinsicP.h> +instead of +<X11/Intrinsic.h>. + + + +The applications must also include the additional header files for +each widget class that they are to use (for example, +<X11/Xaw/Label.h> +or +<X11/Xaw/Scrollbar.h>). +On a POSIX-based system, +the Intrinsics object library file is named +libXt.a +and is usually referenced as \-lXt when linking the application. + + + + +Procedures and Macros + +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. + + + +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: +, +, +, +, +, +and +. + + + + +Widgets + +The fundamental abstraction and data type of the X Toolkit is the widget, +which is a combination of an X window and its associated +input and display semantics +and which is 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. + + + +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 + + + +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 +The predefined widget classes adhere to these conventions. + + + +A widget instance is composed of two parts: + + + + +A data structure which contains instance-specific values. + + + + +A class structure which contains information that is applicable to +all widgets of that class. + + + + +Much of the input/output of a widget (for example, fonts, colors, sizes, +or border widths) is customizable by users. + + + +This chapter discusses the base widget classes, +Core, Composite, and Constraint, and +ends with a discussion of widget classing. + + +Core Widgets + +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 +CoreClassPart +and +CorePart +structures. + + +CoreClassPart Structure + +All widget classes contain the fields defined in the +CoreClassPart +structure. + + +typedef struct { + WidgetClass superclass; See + String class_name; See + Cardinal widget_size; See + XtProc class_initialize; See + XtWidgetClassProc class_part_initialize; See + XtEnum class_inited; See + XtInitProc initialize; See + XtArgsProc initialize_hook; See + XtRealizeProc realize; See + XtActionList actions; See + Cardinal num_actions; See + XtResourceList resources; See + Cardinal num_resources; See + XrmClass xrm_class; Private to resource manager + Boolean compress_motion; See + XtEnum compress_exposure; See + Boolean compress_enterleave; See + Boolean visible_interest; See + XtWidgetProc destroy; See + XtWidgetProc resize; See + XtExposeProc expose; See + XtSetValuesFunc set_values; See + XtArgsFunc set_values_hook; See + XtAlmostProc set_values_almost; See + XtArgsProc get_values_hook; See + XtAcceptFocusProc accept_focus; See + XtVersionType version; See + XtPointer callback_private; Private to callbacks + String tm_table; See + XtGeometryHandler query_geometry; See + XtStringProc display_accelerator; See + XtPointer extension; See +} CoreClassPart; + + +All widget classes have the Core class fields as their first component. +The prototypical +WidgetClass +and +CoreWidgetClass +are defined with only this set of fields. + + +typedef struct { + CoreClassPart core_class; +} WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass; + + +Various routines can cast widget class pointers, as needed, +to specific widget class types. + + + +The single occurrences of the class record and pointer for +creating instances of Core are + + + +In +IntrinsicP.h: + + +extern WidgetClassRec widgetClassRec; +#define coreClassRec widgetClassRec + + +In +Intrinsic.h: + + +extern WidgetClass widgetClass, coreWidgetClass; + + +The opaque types +Widget +and +WidgetClass +and the opaque variable +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 Intrinsics use +incomplete structure definitions in +Intrinsic.h: + + +typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass; + + + +CorePart Structure + +All widget instances contain the fields defined in the +CorePart +structure. + + +typedef struct _CorePart { + Widget self; Described below + WidgetClass widget_class; See + Widget parent; See + Boolean being_destroyed; See + XtCallbackList destroy_callbacks; + XtPointer constraints; See + Position x; See + Position y; See + Dimension width; See + Dimension height; See + Dimension border_width; See + Boolean managed; See + Boolean sensitive; See + Boolean ancestor_sensitive; See + XtTranslations accelerators; See + Pixel border_pixel; See + Pixmap border_pixmap; See + WidgetList popup_list; See + Cardinal num_popups; See + String name; See + Screen *screen; See + Colormap colormap; See + Window window; See + Cardinal depth; See + Pixel background_pixel; See + Pixmap background_pixmap; See + Boolean visible; See + Boolean mapped_when_managed; See +} CorePart; + + +All widget instances have the Core fields as their first component. +The prototypical type +Widget +is defined with only this set of fields. + + +typedef struct { + CorePart core; +} WidgetRec, *Widget, CoreRec, *CoreWidget; + + +Various routines can cast widget pointers, as needed, +to specific widget types. + + + +In order to make these types opaque and ensure that the compiler +does not allow applications to access private data, the Intrinsics use +incomplete structure definitions in +Intrinsic.h. + + +typedef struct _WidgetRec *Widget, *CoreWidget; + + + +Core Resources + +The resource names, classes, and representation types specified in the +coreClassRec +resource list are + + + + + + + + + + + Name + Class + Representation + + + + + XtNaccelerators + XtCAccelerators + XtRAcceleratorTable + + + XtNbackground + XtCBackground + XtRPixel + + + XtNbackgroundPixmap + XtCPixmap + XtRPixmap + + + XtNborderColor + XtCBorderColor + XtRPixel + + + XtNborderPixmap + XtCPixmap + XtRPixmap + + + XtNcolormap + XtCColormap + XtRColormap + + + XtNdepth + XtCDepth + XtRInt + + + XtNmappedWhenManaged + XtCMappedWhenManaged + XtRBoolean + + + XtNscreen + XtCScreen + XtRScreen + + + XtNtranslations + XtCTranslations + XtRTranslationTable + + + + + +Additional resources are defined for all widgets via the +objectClassRec +and +rectObjClassRec +resource lists; see and for details. + + + +CorePart Default Values + +The default values for the Core fields, which are filled in by the Intrinsics, +from the resource lists, and by the initialize procedures, are + + + + + + + + + Field + Default Value + + + + + self + Address of the widget structure (may not be changed). + + + widget_class + widget_class argument to + + (may not be changed). + + + parent + parent argument to + + (may not be changed). + + + being_destroyed + Parent's being_destroyed value. + + + destroy_callbacks + NULL + + + constraints + NULL + + + x + 0 + + + y + 0 + + + width + 0 + + + height + 0 + + + border_width + 1 + + + managed + False + + + sensitive + True + + + ancestor_sensitive + logical AND of parent's sensitive and + ancestor_sensitive values. + + + accelerators + NULL + + + border_pixel + XtDefaultForeground + + + border_pixmap + XtUnspecifiedPixmap + + + popup_list + NULL + + + num_popups + 0 + + + name + name argument to + + (may not be changed). + + + screen + Parent's screen; top-level widget gets screen from display specifier + (may not be changed). + + + colormap + Parent's colormap value. + + + window + NULL + + + depth + Parent's depth; top-level widget gets root window depth. + + + background_pixel + XtDefaultBackground + + + background_pixmap + XtUnspecifiedPixmap + + + visible + True + + + mapped_when_managed + True + + + + + +XtUnspecifiedPixmap +is a symbolic constant guaranteed to be unequal to +any valid Pixmap id, +None, +and +ParentRelative. + + + + + +Composite Widgets + +The Composite +widget class is a subclass of the +Core +widget class (see ). +Composite widgets are intended to be containers for other widgets. +The additional data used by composite widgets are defined by the +CompositeClassPart +and +CompositePart +structures. + + +CompositeClassPart Structure + +In addition to the +Core +class fields, +widgets of the Composite class have the following class fields. + + +typedef struct { + XtGeometryHandler geometry_manager; See + XtWidgetProc change_managed; See + XtWidgetProc insert_child; See + XtWidgetProc delete_child; See + XtPointer extension; See +} CompositeClassPart; + + +The extension record defined for +CompositeClassPart +with record_type +equal to +NULLQUARK +is +CompositeClassExtensionRec. + + +typedef struct { + XtPointer next_extension; See + XrmQuark record_type; See + long version; See + Cardinal record_size; See + Boolean accepts_objects; See + Boolean allows_change_managed_set; See +} CompositeClassExtensionRec, *CompositeClassExtension; + + +Composite +classes have the Composite class fields immediately following the +Core class fields. + + +typedef struct { + CoreClassPart core_class; + CompositeClassPart composite_class; +} CompositeClassRec, *CompositeWidgetClass; + + +The single occurrences of the class record and pointer for creating +instances of Composite are + + + +In +IntrinsicP.h: + + +extern CompositeClassRec compositeClassRec; + + +In +Intrinsic.h: + + +extern WidgetClass compositeWidgetClass; + + +The opaque types +CompositeWidget +and +CompositeWidgetClass +and the opaque variable +compositeWidgetClass +are defined for generic operations on widgets whose class +is Composite or a subclass of Composite. +The symbolic constant for the +CompositeClassExtension +version identifier is +XtCompositeExtensionVersion +(see ). +Intrinsic.h +uses an incomplete structure +definition to ensure that the compiler catches attempts to access +private data. + + +typedef struct _CompositeClassRec *CompositeWidgetClass; + + + +CompositePart Structure + +In addition to the +Core instance +fields, +widgets of the Composite class have the following +instance fields defined in the +CompositePart +structure. + + +typedef struct { + WidgetList children; See + Cardinal num_children; See + Cardinal num_slots; See + XtOrderProc insert_position; See +} CompositePart; + + +Composite +widgets have the Composite instance fields immediately following the Core +instance fields. + + +typedef struct { + CorePart core; + CompositePart composite; +} CompositeRec, *CompositeWidget; + + +Intrinsic.h +uses an incomplete structure definition to ensure that the +compiler catches attempts to access private data. + + +typedef struct _CompositeRec *CompositeWidget; + + + +Composite Resources + +The resource names, classes, and representation types +that are specified in +the +compositeClassRec +resource list are + + + + + + + + + + + Name + Class + Representation + + + + + XtNchildren + XtCReadOnly + XtRWidgetList + + + XtNinsertPosition + XtCInsertPosition + XtRFunction + + + XtNnumChildren + XtCReadOnly + XtRCardinal + + + + + + + +CompositePart Default Values + +The default values for the Composite fields, +which are filled in from the +Composite +resource list and by the +Composite +initialize procedure, are + + + + + + + + + + + Field + Default Value + + + + + childrenNULL + + + num_children0 + + + num_slots0 + + + insert_positionInternal function to insert at end + + + + + + +The children, num_children, +and insert_position fields are declared +as resources; +XtNinsertPosition +is a settable resource, +XtNchildren +and +XtNnumChildren +may be read by any client but should only be modified by the composite +widget class procedures. + + + + + +Constraint Widgets + +The Constraint +widget class is a subclass of the +Composite +widget class (see ). 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 +ConstraintClassPart +and +ConstraintPart +structures. + + +ConstraintClassPart Structure + +In addition to the +Core +and +Composite +class fields, +widgets of the Constraint class +have the following class fields. + + +typedef struct { + XtResourceList resources; See + Cardinal num_resources; See + Cardinal constraint_size; See + XtInitProc initialize; See + XtWidgetProc destroy; See + XtSetValuesFunc set_values; See + XtPointer extension; See +} ConstraintClassPart; + + +The extension record defined for +ConstraintClassPart +with record_type equal to +NULLQUARK +is +ConstraintClassExtensionRec. + + +typedef struct { + XtPointer next_extension; See + XrmQuark record_type; See + long version; See + Cardinal record_size; See + XtArgsProc get_values_hook; See +} ConstraintClassExtensionRec, *ConstraintClassExtension; + + +Constraint +classes have the Constraint class fields immediately following the +Composite class fields. + + +typedef struct _ConstraintClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ConstraintClassPart constraint_class; +} ConstraintClassRec, *ConstraintWidgetClass; + + +The single occurrences of the class record and pointer for creating +instances of Constraint are + + + +In +IntrinsicP.h: + + +extern ConstraintClassRec constraintClassRec; + + +In +Intrinsic.h: + + +extern WidgetClass constraintWidgetClass; + + +The opaque types +ConstraintWidget +and +ConstraintWidgetClass +and the opaque variable +constraintWidgetClass +are defined for generic operations on widgets +whose class is Constraint or a subclass +of Constraint. +The symbolic constant for the +ConstraintClassExtension +version identifier is +XtConstraintExtensionVersion +(see ). +Intrinsic.h +uses an incomplete structure definition to ensure that the +compiler catches attempts to access private data. + + +typedef struct _ConstraintClassRec *ConstraintWidgetClass; + + + +ConstraintPart Structure + +In addition to the +Core +and +Composite instance +fields, +widgets of the Constraint class have the following unused +instance fields defined in the +ConstraintPart +structure + + +typedef struct { + int empty; +} ConstraintPart; + + +Constraint +widgets have the Constraint instance fields immediately following the +Composite instance fields. + + +typedef struct { + CorePart core; + CompositePart composite; + ConstraintPart constraint; +} ConstraintRec, *ConstraintWidget; + + +Intrinsic.h +uses an incomplete structure definition to ensure that the +compiler catches attempts to access private data. + + +typedef struct _ConstraintRec *ConstraintWidget; + + + +Constraint Resources + +The +constraintClassRec +core_class and constraint_class resources fields are NULL, +and the num_resources fields are zero; +no additional resources beyond those declared by +the superclasses +are defined for +Constraint. + + + + + + +Implementation-Specific Types + +To increase the portability of widget and application source code +between different system environments, the Intrinsics define several +types whose precise representation is explicitly dependent upon, +and chosen by, each individual implementation of the Intrinsics. + + + +These implementation-defined types are + + + + + Boolean + + + +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 +True. + + + + + + + Cardinal + + + +An unsigned integer datum with a minimum range of [0..2^16-1]. + + + + + + + Dimension + + + +An unsigned integer datum with a minimum range of [0..2^16-1]. + + + + + + + Position + + + +A signed integer datum with a minimum range of [-2^15..2^15-1]. + + + + + + + XtPointer + + + +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 +XtPointer +and back again and the result will +compare equal to the original value. In ANSI C +environments it is expected that +XtPointer +will be +defined as void*. + + + + + + + XtArgVal + + + +A datum large enough to contain an +XtPointer, +Cardinal, +Dimension, +or +Position +value. + + + + + + + XtEnum + + + +An integer datum large enough to encode at least 128 distinct +values, two of which are the symbolic values +True +and +False. +The symbolic values +TRUE +and +FALSE +are +also defined to be equal to +True +and +False, +respectively. + + + + + + +In addition to these specific types, the precise order of the +fields within the structure declarations for any of the instance +part records +ObjectPart, +RectObjPart, +CorePart, +CompositePart, +ShellPart, +WMShellPart, +TopLevelShellPart, +and +ApplicationShellPart +is implementation-defined. These +structures may also have additional private +fields internal to the implementation. +The +ObjectPart, +RectObjPart, +and +CorePart +structures must be defined so that any member with the same name +appears at the same offset in +ObjectRec, +RectObjRec, +and +CoreRec +( WidgetRec ). +No other relations between the offsets of any two +fields may be assumed. + + + + +Widget Classing + +The widget_class 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. + + + +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 +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). + + + +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. + + + +To make good use of subclassing, +widget declarations and naming conventions are highly stylized. +A widget consists of three files: + + + + +A public .h file, used by client widgets or applications. + + + + +A private .h file, used by widgets whose classes +are subclasses of the widget class. + + + + +A .c file, which implements the widget. + + + + +Widget Naming Conventions + +The Intrinsics provide a vehicle by which programmers can create +new widgets and organize a collection of widgets into an application. +To ensure that applications need not deal with as many styles of capitalization +and spelling as the number of widget classes it uses, +the following guidelines should be followed when writing new widgets: + + + + +Use the X library naming conventions that are 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, +ArgList +or +XtSetValues ). + + + + +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 background_pixmap field has the corresponding identifier +XtNbackgroundPixmap, +which is defined as the string ``backgroundPixmap''. +Many predefined names are listed in +<X11/StringDefs.h>. +Before you invent a new name, +you should make sure there is not already a name that you can use. + + + + +A resource class string starts with a capital letter +and uses capitalization for compound names (for example,``BorderWidth''). +Each resource class string should have a symbolic identifier prefixed with +``XtC'' +(for example, XtCBorderWidth). +Many predefined classes are listed in +<X11/StringDefs.h>. + + + + +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 +<X11/StringDefs.h>. + + + + +New widget classes start with a capital and use uppercase for compound +words. +Given a new class name AbcXyz, you should derive several names: + + + + + + +Additional widget instance structure part name AbcXyzPart. + + + + +Complete widget instance structure names AbcXyzRec and _AbcXyzRec. + + + + +Widget instance structure pointer type name AbcXyzWidget. + + + + +Additional class structure part name AbcXyzClassPart. + + + + +Complete class structure names AbcXyzClassRec and _AbcXyzClassRec. + + + + +Class structure pointer type name AbcXyzWidgetClass. + + + + +Class structure variable abcXyzClassRec. + + + + +Class structure pointer variable abcXyzWidgetClass. + + + + + + +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''). + + + + +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 +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. + + + + +Widget Subclassing in Public .h Files + +The public .h file for a widget class is imported by clients +and contains + + + + +A reference to the public .h file for the superclass. + + + + +Symbolic identifiers for +the names and classes of the new resources that this widget adds +to its superclass. +The definitions should +have a single space between the definition name and the value and no +trailing space or comment in order to reduce the possibility of +compiler warnings from similar declarations in multiple classes. + + + + +Type declarations for any new resource data types defined by the class. + + + + +The class record pointer variable used to create widget instances. + + + + +The C type that corresponds to widget instances of this class. + + + + +Entry points for new class methods. + + + + +For example, the following is the public .h file for a possible +implementation of a Label widget: + + +#ifndef LABEL_H +#define LABEL_H +/* New resources */ +#define XtNjustify "justify" +#define XtNforeground "foreground" +#define XtNlabel "label" +#define XtNfont "font" +#define XtNinternalWidth "internalWidth" +#define XtNinternalHeight "internalHeight" +/* Class record pointer */ +extern WidgetClass labelWidgetClass; +/* C Widget type definition */ +typedef struct _LabelRec *LabelWidget; +/* New class method entry points */ +extern void LabelSetText(); + /* Widget w */ + /* String text */ +extern String LabelGetText(); + /* Widget w */ +#endif LABEL_H + + +The conditional inclusion of the text allows the application +to include header files for different widgets without being concerned +that they already may be included as a superclass of another widget. + + + +To accommodate operating systems with file name length restrictions, +the name of the public .h file is the first ten characters of the +widget class. +For example, +the public .h file for the +Constraint +widget class is +Constraint.h. + + + + +Widget Subclassing in Private .h Files + +The private .h file for a widget is imported by widget classes that are +subclasses of the widget and contains + + + + +A reference to the public .h file for the class. + + + + +A reference to the private .h file for the superclass. + + + + +Symbolic identifiers for any new resource 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. + + + + +A structure part definition for +the new fields that the widget instance adds to its superclass's +widget structure. + + + + +The complete widget instance structure definition for this widget. + + + + +A structure part definition for +the new fields that this widget class adds to its superclass's +constraint +structure if the widget class is a subclass of +Constraint. + + + + +The complete +constraint +structure definition if the widget class is a subclass of +Constraint. + + + + +Type definitions for any new procedure types used by class methods +declared in the widget class part. + + + + +A structure part definition for +the new fields that this widget class adds to its superclass's widget class +structure. + + + + +The complete widget class structure definition for this widget. + + + + +The complete widget class extension structure definition +for this widget, if any. + + + + +The symbolic constant identifying the class extension version, if any. + + + + +The name of the global class structure variable containing the generic +class structure for this class. + + + + +An inherit constant for each new procedure in the widget class part structure. + + + + +For example, the following is the private .h file for a possible Label widget: + + +#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; + + +/* 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 + + +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 +ConstrainP.h. + + + + +Widget Subclassing in .c Files + +The .c file for a widget contains the structure initializer +for the class record variable, +which contains the following parts: + + + + +Class information (for example, superclass, class_name, +widget_size, +class_initialize, and class_inited). + + + + +Data constants (for example, resources and num_resources, +actions and num_actions, visible_interest, +compress_motion, +compress_exposure, and version). + + + + +Widget operations (for example, initialize, realize, destroy, +resize, expose, set_values, accept_focus, +and any new operations specific to +the widget). + + + + +The superclass field points to the superclass +global class +record, declared in the superclass private .h file. +For direct subclasses of the generic core widget, +superclass should be initialized to the address of the +widgetClassRec +structure. +The superclass is used for class chaining operations and for +inheriting or enveloping a superclass's operations +(see , +, and +. + + + +The class_name 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. + + + +The widget_size field is the size of the corresponding widget +instance structure +(not the size of the class structure). + + + +The version field indicates the toolkit +implementation version number and is used for +runtime consistency checking of the X Toolkit and widgets in an application. +Widget writers must set it to the +implementation-defined symbolic value +XtVersion +in the widget class structure initialization. +Those widget writers who believe that their widget binaries are compatible +with other implementations of the Intrinsics can put the special value +XtVersionDontCheck +in the version field to disable version checking for those widgets. +If a widget needs to compile alternative code for different +revisions of the Intrinsics interface definition, it may use the symbol +XtSpecificationRelease, +as described in . +Use of +XtVersion +allows the Intrinsics implementation to recognize widget binaries +that were compiled with older implementations. + + + +The extension 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. + + + +All other fields are described in their respective sections. + + + +The .c file also contains the declaration of the global class +structure pointer variable used to create instances of the class. +The following is an abbreviated version of the .c file +for a Label widget. +The resources table is described in . + + +/* Resources specific to Label */ +static XtResource resources[] = { + {XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel), + XtOffset(LabelWidget, label.foreground), XtRString, + XtDefaultForeground}, + {XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct *), + XtOffset(LabelWidget, label.font),XtRString, + XtDefaultFont}, + {XtNlabel, XtCLabel, XtRString, sizeof(String), + XtOffset(LabelWidget, label.label), XtRString, NULL}, + . + . + . +} +/* Forward declarations of procedures */ +static void ClassInitialize(); +static void Initialize(); +static void Realize(); +static void SetText(); +static void GetText(); + . + . + . + + +/* Class record constant */ +LabelClassRec labelClassRec = { + { + /* core_class fields */ + /* superclass */ (WidgetClass)&coreClassRec, + /* class_name */ "Label", + /* widget_size */ sizeof(LabelRec), + /* class_initialize */ ClassInitialize, + /* class_part_initialize */ NULL, + /* class_inited */ False, + /* initialize */ Initialize, + /* initialize_hook */ NULL, + /* realize */ Realize, + /* actions */ NULL, + /* num_actions */ 0, + /* resources */ resources, + /* num_resources */ XtNumber(resources), + /* xrm_class */ NULLQUARK, + /* compress_motion */ True, + /* compress_exposure */ True, + /* compress_enterleave */ True, + /* visible_interest */ False, + /* destroy */ NULL, + /* resize */ Resize, + /* expose */ Redisplay, + /* set_values */ SetValues, + /* set_values_hook */ NULL, + /* 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 */ + . + . + . + + + + +Widget Class and Superclass Look Up + +To obtain the class of a widget, use +. + + + + + + + WidgetClass XtClass + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + + +The + +function returns a pointer to the widget's class structure. + + + +To obtain the superclass of a widget, use +XtSuperclass. + + + + + + WidgetClass XtSuperClass + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + + +The +XtSuperclass +function returns a pointer to the widget's superclass class structure. + + + + +Widget Subclass Verification + +To check the subclass to which a widget belongs, use +. + + + + + Boolean XtIsSubclass + Widget w + WidgetClass widget_class + + + + + + + w + + + +Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof. + + + + + + widget_class + + + +Specifies the widget class for which to test. Must be objectClass or any subclass thereof. + + + + + + + +The + +function returns +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 + +to find out if a widget belongs to the desired class of objects. + + + +To test if a given widget belongs to a subclass of an Intrinsics-defined +class, the Intrinsics define macros or functions equivalent to + +for each of the built-in classes. These procedures are +XtIsObject, +XtIsRectObj, +XtIsWidget, +XtIsComposite, +XtIsConstraint, +XtIsShell, +XtIsOverrideShell, +XtIsWMShell, +XtIsVendorShell, +XtIsTransientShell, +XtIsTopLevelShell, +XtIsApplicationShell, +and +XtIsSessionShell. + + + +All these macros and functions have the same argument description. + + + + + Boolean XtIs + Widget w + + + + + + + w + + + +Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof. + + + + + + +These procedures may be faster than calling + +directly for the built-in classes. + + + +To check a widget's class +and to generate a debugging error message, use +, +defined in +<X11/IntrinsicP.h>: + + + + + void XtCheckSubclass + Widget w + WidgetClass widget_class + String message + + + + + + + w + + + +Specifies the widget or object whose class is to be checked. Must be of class Object or any subclass thereof. + + + + + + widget_class + + + +Specifies the widget class for which to test. Must be objectClass or any subclass thereof. + + + + + + message + + + +Specifies the message to be used. + + + + + + +The + +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, + +constructs an error message from the supplied message, +the widget's actual class, and the expected class and calls +. + +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. + + + + +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. + + + + +Superclass Chaining + +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 Intrinsics access the field's value only after accessing its corresponding +superclass value (called downward superclass chaining) or +before accessing its corresponding superclass value (called upward superclass +chaining). The self-contained fields are + +In all widget classes: class_name + class_initialize + widget_size + realize + visible_interest + resize + expose + accept_focus + compress_motion + compress_exposure + compress_enterleave + set_values_almost + tm_table + version + allocate + deallocate + +In Composite widget classes: geometry_manager + change_managed + insert_child + delete_child + accepts_objects + allows_change_managed_set + +In Constraint widget classes: constraint_size + +In Shell widget classes: root_geometry_manager + + + +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 + + + class_part_initialize + get_values_hook + initialize + initialize_hook + set_values + set_values_hook + resources + + + +In addition, for subclasses of +Constraint, +the following fields of the +ConstraintClassPart +and +ConstraintClassExtensionRec +structures are chained from the +Constraint +class down to the subclass: + + + resources + initialize + set_values + get_values_hook + + + +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 + + + destroy + actions + + + +For subclasses of +Constraint, +the following field of +ConstraintClassPart +is chained from the subclass up to the +Constraint class: + destroy + + + + +Class Initialization: class_initialize and class_part_initialize Procedures + +Many class records can be initialized completely at compile or link time. +In some cases, however, +a class may need to register type converters or perform other sorts of +once-only runtime initialization. + + + +Because the C language does not have initialization 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 Intrinsics. +A class initialization procedure pointer is of type +XtProc: + + + +typedef void (*XtProc)(void); + + +A widget class indicates that it has no class initialization procedure by +specifying NULL in the class_initialize field. + + + +In addition to the class initialization that is done exactly once, +some classes perform initialization for fields in their parts +of the class record. +These are performed not just for the particular class, +but for subclasses as well, and are +done in the class's class part initialization procedure, +a pointer to which is stored in the class_part_initialize field. +The class_part_initialize procedure pointer is of type +XtWidgetClassProc. + + + + + void (*XtWidgetClassProc)(WidgetClass) + WidgetClass widget_class + + + + + + + widget_class + + + +Points to the class structure for the class being initialized. + + + + + +During class initialization, +the class part initialization procedures for the class and all its superclasses +are called in superclass-to-subclass order on the class record. +These procedures have the responsibility of doing any dynamic 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 +Classes that do not define any new class fields +or that need no extra processing for them can specify NULL +in the class_part_initialize field. + + + +All widget classes, whether they have a class initialization procedure or not, +must start with their class_inited field +False. + + + +The first time a widget of a class is created, + +ensures that the widget class and all superclasses are initialized, in +superclass-to-subclass order, by checking each class_inited field and, +if it is +False, +by calling the class_initialize and the class_part_initialize procedures +for the class and all its superclasses. +The Intrinsics then set the class_inited field to a nonzero value. +After the one-time initialization, +a class structure is constant. + + + +The following example provides the class initialization procedure for a Label class. + + +static void ClassInitialize() +{ + XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify, + NULL, 0, XtCacheNone, NULL); +} + + + + +Initializing a Widget Class + +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 +. + + + + + void XtInitializeWidgetClass + WidgetClass object_class + + + + + + + object_class + + + +Specifies the object class to initialize. May be +objectClass +or any subclass thereof. + + + + + + +If the specified widget class is already initialized, + +returns immediately. + + + +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 + +is called +(see ). + + + + +Inheritance of Superclass Operations + +A widget class is free to use any of its superclass's self-contained +operations rather than implementing its own code. +The most frequently inherited operations are + + + + +expose + + + + +realize + + + + +insert_child + + + + +delete_child + + + + +geometry_manager + + + + +set_values_almost + + + + + +To inherit an operation xyz, +specify the constant +XtInherit Xyz +in your class record. + + + +Every class that declares a new procedure in its widget class part must +provide for inheriting the procedure in its class_part_initialize +procedure. +The chained operations declared in Core +and Constraint +records are never inherited. +Widget classes that do nothing beyond what their superclass does +specify NULL for chained procedures +in their class records. + + + +Inheriting works by comparing the value of the field with a known, special +value and by copying in the superclass's value for that field if a match +occurs. +This special value, called the inheritance constant, +is usually the Intrinsics internal value +_XtInherit +cast to the appropriate type. +_XtInherit +is a procedure that issues an error message if it is actually called. + + + +For example, +CompositeP.h +contains these definitions: + + +#define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit) +#define XtInheritChangeManaged ((XtWidgetProc) _XtInherit) +#define XtInheritInsertChild ((XtArgsProc) _XtInherit) +#define XtInheritDeleteChild ((XtWidgetProc) _XtInherit) + + +Composite's class_part_initialize procedure begins as follows: + + +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; + } + . + . + . + + +Nonprocedure fields may be inherited in the same manner as procedure +fields. The class may declare any reserved value it wishes for +the inheritance constant for its new fields. The following inheritance +constants are defined: + + + +For Object: + + + + +XtInheritAllocate + + + + +XtInheritDeallocate + + + + +For Core: + + + + +XtInheritRealize + + + + +XtInheritResize + + + + +XtInheritExpose + + + + +XtInheritSetValuesAlmost + + + + +XtInheritAcceptFocus + + + + +XtInheritQueryGeometry + + + + +XtInheritTranslations + + + + +XtInheritDisplayAccelerator + + + + +For Composite: + + + + +XtInheritGeometryManager + + + + +XtInheritChangeManaged + + + + +XtInheritInsertChild + + + + +XtInheritDeleteChild + + + + +For Shell: + + + + +XtInheritRootGeometryManager + + + + + + +Invocation of Superclass Operations + +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 expose +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 insert_child +and then calling + +to add the child to the managed set. + + + + +A class method should not use +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. + + + +This technique is referred to as enveloping the superclass's operation. + + + + +Class Extension Records + +It may be necessary at times to add new fields to already existing +widget class structures. To permit this to be done without requiring +recompilation of all subclasses, the last field in a class part structure +should be an extension pointer. If no extension fields for a class +have yet been defined, subclasses should initialize the value of the +extension pointer to NULL. + + + +If extension fields exist, as is the case with the +Composite, +Constraint, +and +Shell +classes, subclasses can provide values for these fields by setting the +extension pointer for the appropriate part in their class structure to +point to a statically declared extension record containing the +additional fields. +Setting the extension field is never mandatory; code that uses fields +in the extension record must always check the extension field and take +some appropriate default action if it is NULL. + + + +In order to permit multiple subclasses and libraries to chain extension +records from a single extension 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: + + +struct { + XtPointer next_extension; + XrmQuark record_type; + long version; + Cardinal record_size; +}; + + + + + + next_extension + + + +Specifies the next record in the list, or NULL. + + + + + + record_type + + + +Specifies the particular structure declaration to which +each extension record instance conforms. + + + + + + version + + + +Specifies a version id symbolic constant supplied by +the definer of the structure. + + + + + + record_size + + + +Specifies the total number of bytes allocated for the +extension record. + + + + + + +The record_type 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 +record_type field is normally assigned the +result of +XrmStringToQuark +for a registered string constant. The +Intrinsics reserve all record type strings beginning with the two +characters ``XT'' for future standard uses. The value +NULLQUARK +may also be used +by the class part owner in extension records attached to its own class +part extension field to identify the extension record unique to that +particular class. + + + +The version 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 record_size field value includes the four common header fields and +should normally be initialized with +sizeof (). + + + +Any value stored in the class part extension fields of +CompositeClassPart, +ConstraintClassPart, +or +ShellClassPart +must point to an extension record conforming to this definition. + + + +The Intrinsics provide a utility function for widget writers to locate a +particular class extension record in a linked list, given a widget class +and the offset of the extension field in the class record. + + + +To locate a class extension record, use +. + + + + + XtPointer XtGetClassExtension + WidgetClass object_class + Cardinal byte_offset + XrmQuark type + long version + Cardinal record_size + + + + + + + object_class + + + +Specifies the object class containing the extension list to be searched. + + + + + + byte_offset + + + +Specifies the offset in bytes from the base of the +class record of the extension field to be searched. + + + + + + type + + + +Specifies the record_type of the class extension to be located. + + + + + + version + + + +Specifies the minimum acceptable version of the class +extension required for a match. + + + + + + record_size + + + +Specifies the minimum acceptable length of the class +extension record required for a match, or 0. + + + + + + +The list of extension records at the specified offset in the specified +object class will be searched for a match on the specified type, +a version greater than or equal to the specified version, and a record +size greater than or equal the specified record_size if it is nonzero. + +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. + + + + diff --git a/libXt/specs/CH02 b/libXt/specs/CH02 deleted file mode 100644 index cbb4bb8a5..000000000 --- a/libXt/specs/CH02 +++ /dev/null @@ -1,3165 +0,0 @@ -.\" $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/libXt/specs/CH02.xml b/libXt/specs/CH02.xml new file mode 100644 index 000000000..9cfd4479f --- /dev/null +++ b/libXt/specs/CH02.xml @@ -0,0 +1,4538 @@ + +Widget Instantiation + +A hierarchy of widget instances constitutes a widget tree. +The shell widget returned by + +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 ), +this widget tree instance defines the associated X Window tree. + + + +Widgets can be either composite or primitive. +Both kinds of widgets can contain children, +but the Intrinsics provide a set of management mechanisms for constructing +and interfacing between composite widgets, their children, and +other clients. + + + +Composite widgets, that is, members of the class +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. + + + +In addition, +the Intrinsics 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. + + + +A widget tree is manipulated by several Intrinsics functions. +For example, + +traverses the tree downward and recursively realizes all +pop-up widgets and children of composite widgets. + +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. + +traverses the tree up one level and calls the geometry manager +that is responsible for a widget child's geometry. + + + +To facilitate upward traversal of the widget tree, +each widget has a pointer to its parent widget. +The +Shell +widget that + +returns has a parent pointer of NULL. + + + +To facilitate downward traversal of the widget tree, +the children 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. + + + +Initializing the X Toolkit + +Before an application can call any Intrinsics function +other than +XtSetLanguageProc +and +, +it must initialize the Intrinsics by using + + + + +, +which initializes the Intrinsics internals + + + + +, +which initializes the per-application state + + + + + +or +, +which initializes the per-display state + + + + +, +which creates the root of a widget tree + + + + +Or an application can call the convenience procedure +, +which combines the functions of the preceding procedures. +An application wishing to use the ANSI C locale mechanism should call +XtSetLanguageProc +prior to calling +, +, +, +or +. + + + +Multiple instances of X Toolkit 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. +To accommodate both requirements, +the Intrinsics define application contexts, +each of which provides the information needed to distinguish one application +instance from another. +The major component of an application context is a list of one or more X +Display +pointers for that application. +The Intrinsics handle all display connections within a single application +context simultaneously, handling input in a round-robin fashion. +The application context type +XtAppContext +is opaque to clients. + + + +To initialize the Intrinsics internals, use +. + + + + + void XtToolkitInitialize + + + + + +If + +was previously called, it returns immediately. +When + +is called before +, +the latter is protected against +simultaneous activation by multiple threads. + + + +To create an application context, use +. + + + + + XtAppContext XtCreateApplicationContext + + + + + + +The + +function returns an application context, +which is an opaque type. +Every application must have at least one application context. + + + +To destroy an application context and close any +remaining display connections in it, use +. + + + + + void XtDestroyApplicationContext + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context. + + + + + + +The + +function destroys the specified application context. +If called from within an event dispatch (for example, in a callback procedure), + +does not destroy the application context until the dispatch is complete. + + + +To get the application context in which a given widget was created, use +. + + + + + XtAppContext XtWidgetToApplicationContext + Widget w + + + + + + + w + + + +Specifies the widget for which you want the application context. Must be of class Object or any subclass thereof. + + + + + + +The + +function returns the application context for the specified widget. + + + +To initialize a display and add it to an application context, use +. + + + + + void XtDisplayInitialize + XtAppContext app_context + Display * display + String application_name + String application_class + XrmOptionDescRec * options + Cardinal num_options + int * argc + String * argv + + + + + + + app_context + + + +Specifies the application context. + + + + + + display + + + +Specifies a previously opened display connection. Note that a single +display connection can be in at most one application context. + + + + + + application_name + + + +Specifies the name of the application instance. + + + + + + application_class + + + +Specifies the class name of this application, +which is usually the generic name for all instances of this application. + + + + + + options + + + +Specifies how to parse the command line for any application-specific resources. +The options argument is passed as a parameter to +XrmParseCommand. +For further information, +see Parsing Command Line Options in Xlib — C Language X Interface and of this specification. + + + + + + num_options + + + +Specifies the number of entries in the options list. + + + + + + argc + + + +Specifies a pointer to the number of command line parameters. + + + + + + argv + + + +Specifies the list of command line parameters. + + + + + + +The + +function retrieves the language string to be +used for the specified display (see ), +calls the language procedure (if set) with that language string, +builds the resource database for the default screen, calls the Xlib +XrmParseCommand +function to parse the command line, +and performs other per-display initialization. +After +XrmParseCommand +has been called, +argc and argv contain only those parameters that +were not in the standard option table or in the table specified by the +options argument. +If the modified argc is not zero, +most applications simply print out the modified argv along with a message +listing the allowable options. +On POSIX-based systems, +the application name is usually the final component of argv[0]. +If the synchronous resource is +True, + +calls the Xlib +XSynchronize +function to put Xlib into synchronous mode for this display connection +and any others currently open in the application context. +See +and +for details on the application_name, +application_class, options, and num_options arguments. + + + + +calls +XrmSetDatabase +to associate the resource database of the default screen with the +display before returning. + + + +To open a display, initialize it, and then +add it to an application context, use +. + + + + + Display *XtOpenDisplay + XtAppContext app_context + String display_string + String application_name + String application_class + XrmOptionDescRec * options + Cardinal num_options + int * argc + String * argv + + + + + + + + + + app_context + + + +Specifies the application context. + + + + + + display_string + + + +Specifies the display string, or NULL. + + + + + + application_name + + + +Specifies the name of the application instance, or NULL. + + + + + + application_class + + + +Specifies the class name of this application, +which is usually the generic name for all instances of this application. + + + + + + options + + + +Specifies how to parse the command line for any application-specific resources. +The options argument is passed as a parameter to +XrmParseCommand. + + + + + + num_options + + + +Specifies the number of entries in the options list. + + + + + + argc + + + +Specifies a pointer to the number of command line parameters. + + + + + + argv + + + +Specifies the list of command line parameters. + + + + + + +The + +function calls +XOpenDisplay +with the specified display_string. +If display_string is NULL, + +uses the current value of the \-display option specified in argv. +If no display is specified in argv, +the user's default display is retrieved from the environment. +On POSIX-based systems, +this is the value of the +DISPLAY +environment variable. + + + +If this succeeds, + +then calls + +and passes it the opened display and +the value of the \-name option specified in argv as the application name. +If no \-name option is specified +and application_name is +non-NULL, application_name is passed to +. +If application_name is NULL and if the environment variable +RESOURCE_NAME +is set, the value of +RESOURCE_NAME +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 argv[0] less any directory and file type components, that is, the +final component of argv[0], if specified. If argv[0] does not exist or +is the empty string, the application name is ``main''. + +returns the newly opened display or NULL if it failed. + + + +See +for information regarding the use of + +in multiple threads. + + + +To close a display and remove it from an application context, use +. + + + + + void XtCloseDisplay + Display * display + + + + + + + display + + + +Specifies the display. + + + + + + +The + +function calls +XCloseDisplay +with the specified display as soon as it is safe to do so. +If called from within an event dispatch (for example, a callback procedure), + +does not close the display until the dispatch is complete. +Note that applications need only call + +if they are to continue executing after closing the display; +otherwise, they should call +. + + + +See +for information regarding the use of + +in multiple threads. + + + + +Establishing the Locale + +Resource databases are specified to be created in the current process +locale. During display initialization prior to creating the +per-screen resource database, the Intrinsics will call out to a specified +application procedure to set the locale according to options found on +the command line or in the per-display resource specifications. + + + +The callout procedure provided by the application is of type +XtLanguageProc. + + + + + typedef String (*XtLanguageProc) + Display display + String language + XtPointer client_data + + + + + + + display + + + +Passes the display. + + + + + + language + + + +Passes the initial language value obtained from the command line +or server per-display resource specifications. + + + + + + client_data + + + +Passes the additional client data specified in the call to +XtSetLanguageProc. + + + + + +The language procedure allows an application to set the locale to +the value of the language resource determined by +. +The function returns a new language string that +will be subsequently used by + +to establish the path for loading resource files. The returned +string will be copied by the Intrinsics into new memory. + + + +Initially, no language procedure is set by the Intrinsics. +To set the language procedure for use by +, +use +XtSetLanguageProc. + + + + + XtLanguageProc XtSetLanguageProc + XtAppContext app_context + XtLanguageProc proc + XtPointer client_data + + + + + + + app_context + + + +Specifies the application context in which the language procedure is +to be used, or NULL. + + + + + + proc + + + +Specifies the language procedure. + + + + + + client_data + + + +Specifies additional client data to be passed to the language +procedure when it is called. + + + + + + +XtSetLanguageProc +sets the language procedure that will be called from + +for all subsequent Displays initialized in the specified application +context. If app_context 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 proc is NULL, a default language procedure is +registered. +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 +XtSetLanguageProc, +it will cause the default language procedure to be registered. + + + +The default language procedure does the following: + + + + +Sets the locale according to the environment. On ANSI C-based +systems this is done by calling +setlocale( +LC_ALL, +language ). +If an error is encountered, a warning message is issued with +. + + + + +Calls +XSupportsLocale +to verify that the current locale is supported. +If the locale is not supported, a warning message is issued with + +and the locale is set to ``C''. + + + + +Calls +XSetLocaleModifiers +specifying the empty string. + + + + +Returns the value of the current locale. On ANSI C-based systems this +is the return value from a final call to +setlocale( +LC_ALL, +NULL ). + + + + +A client wishing to use this mechanism to establish locale can do so +by calling +XtSetLanguageProc +prior to +, +as in the following example. + + + Widget top; + XtSetLanguageProc(NULL, NULL, NULL); + top = XtOpenApplication(...); + ... + + + + +Loading the Resource Database + +The + +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: + + + + +Application command line (argc, argv). + + + + +Per-host user environment resource file on the local host. + + + + +Per-screen resource specifications from the server. + + + + +Per-display resource specifications from the server or from +the user preference file on the local host. + + + + +Application-specific user resource file on the local host. + + + + +Application-specific class resource file on the local host. + + + + +When the resource database for a particular screen on the display +is needed (either internally, or when + +is called), +it is created in the following manner using the sources listed +above in the same order: + + + + +A temporary database, the ``server resource database'', is +created from the string returned by +XResourceManagerString +or, if +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/.Xdefaults. + + + + +If a language procedure has been set, + +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, + +queries the server resource database (which is assumed to be entirely +in XPCS) for the resource +name.xnlLanguage, class Class.XnlLanguage +where name +and Class are the application_name and +application_class specified to +. +The language procedure is then invoked with +the resource value if found, else the empty string. The +string returned from the language procedure is saved for all future +references in the Intrinsics that require the per-display language string. + + + + +The screen resource database is initialized by parsing the command +line in the manner specified by Section 2.4. + + + + +If a language procedure has not been set, +the initial database is then queried for the resource +name.xnlLanguage, class Class.XnlLanguage +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 +LANG +environment variable. If no language string is +found, the empty string is used. +This language string is saved for all future references in the Intrinsics +that require the per-display language string. + + + + +After determining the language string, the user's 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 +XENVIRONMENT +environment variable. +If this environment variable does not exist, the user's home directory +is searched for a file named +.Xdefaults-host, +where host is the host name of the machine on which the +application is running. + + + + +The per-screen resource specifications are then merged into the screen +resource database, if they exist. These specifications are the string +returned by +XScreenResourceString +for the respective screen and are owned entirely by the user. + + + + +Next, the server resource database created earlier is merged into the +screen resource database. The server property, and corresponding user +preference file, are owned and constructed entirely by the user. + + + + +The application-specific user resource file from the local host is +then merged into the screen resource database. +This file contains user customizations and is stored +in a directory owned by the user. +Either the user or the application or both can store resource specifications +in the file. Each should be prepared to find and respect entries made +by the other. +The file name is found by calling +XrmSetDatabase +with the current screen resource database, after preserving the +original display-associated database, then calling + +with the parameters +(display, NULL, NULL, NULL, path, NULL, 0, NULL), +where path is defined in an operating-system-specific way. +On POSIX-based systems, path is defined to be the value +of the environment variable +XUSERFILESEARCHPATH +if this is defined. If +XUSERFILESEARCHPATH +is not defined, an implementation-dependent default value is used. +This default value is constrained in the following manner: + + + + + + +If the environment variable +XAPPLRESDIR +is not defined, the default +XUSERFILESEARCHPATH +must contain at least six entries. These entries must contain +$HOME as the directory prefix, plus the following substitutions: + + + 1. %C, %N, %L or %C, %N, %l, %t, %c + 2. %C, %N, %l + 3. %C, %N + 4. %N, %L or %N, %l, %t, %c + 5. %N, %l + 6. %N + + +The order of these six entries within the path must be as given above. +The order and use of substitutions within a given entry are +implementation-dependent. + + + + If +XAPPLRESDIR +is defined, the default +XUSERFILESEARCHPATH +must contain at least seven entries. These entries must contain the +following directory prefixes and substitutions: + + + 1. $XAPPLRESDIR with %C, %N, %L or %C, %N, %l, %t, %c + 2. $XAPPLRESDIR with %C, %N, %l + 3. $XAPPLRESDIR with %C, %N + 4. $XAPPLRESDIR with %N, %L or %N, %l, %t, %c + 5. $XAPPLRESDIR with %N, %l + 6. $XAPPLRESDIR with %N + 7. $HOME with %N + + +The order of these seven entries within the path must be as given above. +The order and use of substitutions within a given entry are +implementation-dependent. + + + + + + +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 + +with the parameters +(display, ``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 +. +Note that the customization substitution string is retrieved +dynamically by + +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 +, +the original display-associated database is restored. + + + + + +To obtain the resource database for a particular screen, use +. + + + + + XrmDatabase XtScreenDatabase + Screen * screen + + + + + + + + screen + + + +Specifies the screen whose resource database is to be returned. + + + + + + +The + +function returns the fully merged resource database as specified above, +associated with the specified screen. If the specified screen +does not belong to a +Display +initialized by +, +the results are undefined. + + + +To obtain the default resource database associated with a particular display, use +. + + + + + + XrmDatabase XtDatabase + Display * display + + + + + + + + display + + + +Specifies the display. + + + + + + +The + +function is equivalent to +XrmGetDatabase. +It returns the database associated with the specified display, or +NULL if a database has not been set. + + + +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 +. + + + + + void XtAppSetFallbackResources + XtAppContext * app_context + String * specification_list + + + + + + + app_context + + + +Specifies the application context in which +the fallback specifications will be used. + + + + + + specification_list + + + +Specifies a NULL-terminated list of +resource specifications to preload +the database, or NULL. + + + + + + +Each entry in specification_list points to a string in the format of +XrmPutLineResource. +Following a call to +, +when a resource database is being created for a particular screen and +the Intrinsics are not able +to find or read an application-specific class resource file according to the +rules given above and if specification_list is not NULL, the +resource specifications in specification_list will be merged +into the screen resource database in place of the application-specific +class resource file. + +is not +required to copy specification_list; 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 + +is called again. The value NULL for +specification_list 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. + + + + +Parsing the Command Line + +The + +function first parses the command line for the following options: + + + -display + + +Specifies the display name for +XOpenDisplay. + + + + + -name + + +Sets the resource name prefix, +which overrides the application name passed to +. + + + + + -xnllanguage + + +Specifies the initial language string for establishing locale +and for finding application class resource files. + + + + + + + + +has a table of standard command line options that are passed to +XrmParseCommand +for adding resources to the resource database, +and it takes as a parameter additional +application-specific resource abbreviations. +The format of this table is described in Section 15.9 in Xlib — C Language X Interface. + + +typedef enum { + XrmoptionNoArg, /* Value is specified in OptionDescRec.value */ + XrmoptionIsArg, /* Value is the option string itself */ + XrmoptionStickyArg, /* Value is characters immediately following option */ + XrmoptionSepArg, /* Value is next argument in argv */ + XrmoptionResArg, /* Use the next argument as input to XrmPutLineResource*/ + XrmoptionSkipArg, /* Ignore this option and the next argument in argv */ + XrmoptionSkipNArgs, /* Ignore this option and the next */ + /* OptionDescRec.value arguments in argv */ + XrmoptionSkipLine /* Ignore this option and the rest of argv */ +} XrmOptionKind; +typedef struct { + char *option; /* Option name in argv */ + char *specifier; /* Resource name (without application name) */ + XrmOptionKind argKind; /* Location of the resource value */ + XPointer value; /* Value to provide if XrmoptionNoArg */ +} XrmOptionDescRec, *XrmOptionDescList; + +The standard table contains the following entries: + + + + + + + + + + + Option String + Resource Name + Argument Kind + Resource Value + + + + + −background + *background + SepArg + next argument + + + −bd + *borderColor + SepArg + next argument + + + −bg + *background + SepArg + next argument + + + −borderwidth + .borderWidth + SepArg + next argument + + + −bordercolor + *borderColor + SepArg + next argument + + + −bw + .borderWidth + SepArg + next argument + + + −display + .display + SepArg + next argument + + + −fg + *foreground + SepArg + next argument + + + −fn + *font + SepArg + next argument + + + −font + *font + SepArg + next argument + + + −foreground + *foreground + SepArg + next argument + + + −geometry + .geometry + SepArg + next argument + + + −iconic + .iconic + NoArg + "true" + + + −name + .name + SepArg + next argument + + + −reverse + .reverseVideo + NoArg + "on" + + + −rv + .reverseVideo + NoArg + "on" + + + +rv + .reverseVideo + NoArg + "off" + + + −selectionTimeout + .selectionTimeout + SepArg + next argument + + + −synchronous + .synchronous + NoArg + "on" + + + +synchronous + .synchronous + NoArg + "off" + + + −title + .title + SepArg + next argument + + + −xnllanguage + .xnlLanguage + SepArg + next argument + + + −xrm + next argument + ResArg + next argument + + + −xtsessionID + .sessionID + SepArg + next argument + + + + + + +Note that any unique abbreviation for an option name in the standard table +or in the application table is accepted. + + + +If reverseVideo is +True, +the values of +XtDefaultForeground +and +XtDefaultBackground +are exchanged for all screens on the Display. + + + +The value of the synchronous resource specifies whether or not +Xlib is put into synchronous mode. If a value is found in the resource +database during display initialization, + +makes a call to +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. + + + +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. + + + +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 +xmh, +you can start it up as + + +xmh -xrm 'xmh*Command.background: red' + + +When it parses the command line, + +merges the application option table with the standard option table +before calling the Xlib +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 Intrinsics reserve all option names +beginning with the characters ``-xt'' for future standard uses. + + + + +Creating Widgets + +The creation of widget instances is a three-phase process: + + + + + +The widgets are allocated and initialized with resources +and are optionally added to the managed subset of their parent. + + + + +All composite widgets are notified of their managed children +in a bottom-up traversal of the widget tree. + + + + +The widgets create X windows, which then are mapped. + + + + +To start the first phase, +the application calls + +for all its widgets and adds some (usually, most or all) of its widgets +to their respective parents' managed set by calling +. +To avoid an O(n2) 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. + + + +After all widgets have been created, +the application calls + +with the top-level widget to execute the second and third phases. + +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. + + + +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. + + + +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. + + + +Finally, + +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. + + + +Creating and Merging Argument Lists + +Many Intrinsics functions may be passed pairs of resource names and +values. +These are passed as an arglist, a pointer to an array of +Arg +structures, which contains + + +typedef struct { + String name; + XtArgVal value; +} Arg, *ArgList; + + +where +XtArgVal +is as defined in Section 1.5. + + + +If the size of the resource is less than or equal to the size of an +XtArgVal, +the resource value is stored directly in value; +otherwise, a pointer to it is stored in value. + + + +To set values in an +ArgList, +use +. + + + + + void XtSetArg + Arg arg + String name + XtArgVal value + + + + + + + + arg + + + +Specifies the name/value pair to set. + + + + + + name + + + +Specifies the name of the resource. + + + + + + value + + + +Specifies the value of the resource if it will fit in an +XtArgVal, +else the address. + + + + + + +The + +function is usually used in a highly stylized manner to +minimize the probability of making a mistake; for example: + + +Arg args[20]; +int n; +n = 0; +XtSetArg(args[n], XtNheight, 100); n++; +XtSetArg(args[n], XtNwidth, 200); n++; +XtSetValues(widget, args, n); + + +Alternatively, an application can statically declare the argument list +and use +: + + +static Args args[] = { + {XtNheight, (XtArgVal) 100}, + {XtNwidth, (XtArgVal) 200}, +}; +XtSetValues(Widget, args, XtNumber(args)); + + +Note that you should not use expressions with side effects such as +auto-increment or auto-decrement +within the first argument to +. + +can be implemented as a macro that evaluates the first argument twice. + + + +To merge two +arglist arrays, use +. + + + + + ArgList XtMergeArgLists + ArgList args1 + Cardinal num_args1 + ArgList args2 + Cardinal num_args2 + + + + + + + + args1 + + + +Specifies the first argument list. + + + + + + num_args1 + + + +Specifies the number of entries in the first argument list. + + + + + + args2 + + + +Specifies the second argument list. + + + + + + num_args2 + + + +Specifies the number of entries in the second argument list. + + + + + + +The + +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 +. + + + +All Intrinsics interfaces that require +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 +ArgList +procedure; e.g., +. +Each procedure named XtVasomething takes as its +last arguments, in place of the corresponding +ArgList/ +Cardinal +parameters, a variable parameter list of resource name and +value pairs where each name is of type +String +and each value is of type +XtArgVal. +The end of the list is identified by a name 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 +ArgList +and varargs forms interchangeably. + + + +Two special names are defined for use only in varargs lists: +XtVaTypedArg +and +XtVaNestedList. + + +#define XtVaTypedArg "XtVaTypedArg" + + +If the name +XtVaTypedArg +is specified in place of a resource +name, then the following four arguments are interpreted as a +name/type/value/size tuple where name is of type +String, +type is of type +String, +value is of type +XtArgVal, +and size is of type int. When a varargs list containing +XtVaTypedArg +is processed, a resource type +conversion (see ) is performed if necessary to convert the +value into the format required by the associated resource. If type is +XtRString, then value contains a pointer to the string and size +contains the number of bytes allocated, including the trailing null +byte. If type is not XtRString, then if size is +less than or equal to +sizeof(XtArgVal), the value should be the data cast to the type +XtArgVal, +otherwise value is a pointer to the data. If the type +conversion fails for any reason, a warning message is issued and the +list entry is skipped. + + +#define XtVaNestedList "XtVaNestedList" + + +If the name +XtVaNestedList +is specified in place of a resource name, +then the following argument is interpreted as an +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. + + + +To dynamically allocate a varargs list for use with +XtVaNestedList +in multiple calls, use +. + + +typedef XtPointer XtVarArgsList; + + + + + XtVarArgsList XtVaCreateArgsList + XtPointer unused + ... + + + + + + + unused + + + +This argument is not currently used and must be specified as NULL. + + + + + + ... + + + +Specifies a variable parameter list of resource +name and value pairs. + + + + + + +The + +function allocates memory and copies its arguments into a +single list pointer, which may be used with +XtVaNestedList. +The end of +both lists is identified by a name entry containing NULL. Any entries +of type +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 + +when no longer needed. + + + +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. + + + + +Creating a Widget Instance + +To create an instance of a widget, use +. + + + + + Widget XtCreateWidget + String name + WidgetClass object_class + Widget parent + ArgList args + Cardinal num_args + + + + + + + + name + + + +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. + + + + + + object_class + + + +Specifies the widget class pointer for the created object. Must be objectClass or any subclass thereof. + + + + + + parent + + + +Specifies the parent widget. Must be of class Object or any subclass thereof. + + + + + + args + + + +Specifies the argument list to override any other resource specifications. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +function performs all the boilerplate operations of widget +creation, doing the following in order: + + + + +Checks to see if the class_initialize procedure has been called for this class +and for all superclasses and, if not, calls those necessary in a +superclass-to-subclass order. + + + + +If the specified class is not +coreWidgetClass +or a subclass thereof, +and the parent's class is a subclass of +compositeWidgetClass +and either no extension record in +the parent's composite class part extension field exists with the +record_type +NULLQUARK +or the accepts_objects field in the extension +record is +False, + +issues a fatal error; see and . + + + + +If the specified class contains an extension record in the object class +part extension field with record_type +NULLQUARK +and the allocate field is not NULL, +the procedure is invoked to allocate memory +for the widget instance. If the parent is a member of the class +constraintWidgetClass, +the procedure also allocates memory for the +parent's constraints and stores the address of this memory into the +constraints field. If no allocate procedure is found, the Intrinsics +allocate memory for the widget and, when applicable, the constraints, +and initializes the constraints field. + + + + +Initializes the Core nonresource data fields +self, parent, widget_class, being_destroyed, +name, managed, window, visible, +popup_list, and num_popups. + + + + +Initializes the resource fields (for example, background_pixel) +by using the +CoreClassPart +resource lists specified for this class and all superclasses. + + + + +If the parent is a member of the class +constraintWidgetClass, +initializes the resource fields of the constraints record +by using the +ConstraintClassPart +resource lists specified for the parent's class +and all superclasses up to +constraintWidgetClass. + + + + +Calls the initialize procedures for the widget starting at the +Object +initialize procedure on down to the widget's initialize procedure. + + + + +If the parent is a member of the class +constraintWidgetClass, +calls the +ConstraintClassPart +initialize procedures, +starting at +constraintWidgetClass +on down to the parent's +ConstraintClassPart +initialize procedure. + + + + +If the parent is a member of the class +compositeWidgetClass, +puts the widget into its parent's children list by calling its parent's +insert_child procedure. +For further information, +see . + + + + +To create an instance of a widget using varargs lists, use +. + + + + + Widget XtVaCreateWidget + String name + WidgetClass object_class + Widget parent + ... + + + + + + + + name + + + +Specifies the resource name for the created widget. + + + + + + object_class + + + +Specifies the widget class pointer for the created object. Must be objectClass or any subclass thereof. + + + + + + parent + + + +Specifies the parent widget. Must be of class Object or any subclass thereof. + + + + + + ... + + + +Specifies the variable argument list to override any other +resource specifications. + + + + + + +The + +procedure is identical in function to + +with the args and num_args parameters replaced by a varargs list, +as described +in Section 2.5.1. + + + + +Creating an Application Shell Instance + +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 + +to create independent widget trees. + + + + + Widget XtAppCreateShell + String name + String application_class + WidgetClass widget_class + Display * display + ArgList args + Cardinal num_args + + + + + + + + name + + + +Specifies the instance name of the shell widget. +If name is NULL, +the application name passed to + +is used. + + + + + + application_class + + + +Specifies the resource class string to be used in +place of the widget class_name string when +widget_class is +applicationShellWidgetClass +or a subclass thereof. + + + + + + widget_class + + + +Specifies the widget class for the top-level widget (e.g., +applicationShellWidgetClass ). + + + + + + display + + + +Specifies the display for the default screen +and for the resource database used to retrieve +the shell widget resources. + + + + + + args + + + +Specifies the argument list to override any other resource specifications. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +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 +args 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 name.screen, +class Class.Screen where Class is the specified +application_class if widget_class is +applicationShellWidgetClass +or a subclass thereof. If widget_class is not +application\%Shell\%Widget\%Class +or a subclass, Class is the class_name +field from the +CoreClassPart +of the specified widget_class. +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 +args. The widget name and Class as determined above are +used as the leftmost (i.e., root) components in all fully qualified +resource names for objects within this widget tree. + + + +If the specified widget class is a subclass of WMShell, the name and +Class as determined above will be stored into the +WM_CLASS +property on the widget's window when it becomes realized. +If the specified widget_class is +applicationShellWidgetClass +or a subclass thereof, the +WM_COMMAND +property will also be set from the values of the XtNargv and +XtNargc resources. + + + +To create multiple top-level shells within a single (logical) +application, +you can use one of two methods: + + + + +Designate one shell as the real top-level shell and +create the others as pop-up children of it by using +. + + + + +Have all shells as pop-up children of an unrealized top-level shell. + + + + +The first method, +which is best used when there is a clear choice for what is the main window, +leads to resource specifications like the following: + + +xmail.geometry:... (the main window) +xmail.read.geometry:... (the read window) +xmail.compose.geometry:... (the compose window) + + +The second method, +which is best if there is no main window, +leads to resource specifications like the following: + + +xmail.headers.geometry:... (the headers window) +xmail.read.geometry:... (the read window) +xmail.compose.geometry:... (the compose window) + + +To create a top-level widget that is the root of a widget tree using +varargs lists, use +. + + + + + Widget XtVaAppCreateShell + String name + String application_class + WidgetClass widget_class + Display * display + + + + + + + name + + + +Specifies the instance name of the shell widget. +If name is NULL, +the application name passed to + +is used. + + + + + + application_class + + + +Specifies the resource class string to be used in +place of the widget class_name string when +widget_class is +applicationShellWidgetClass +or a subclass thereof. + + + + + + widget_class + + + +Specifies the widget class for the top-level widget. + + + + + + display + + + +Specifies the display for the default screen +and for the resource database used to retrieve +the shell widget resources. + + + + + + ... + + + +Specifies the variable argument list to override any other +resource specifications. + + + + + + +The + +procedure is identical in function to + +with the args and num_args parameters replaced by a varargs list, as +described in Section 2.5.1. + + + + +Convenience Procedure to Initialize an Application + +To initialize the Intrinsics internals, create an application context, +open and initialize a display, and create the initial root shell +instance, an application may use + +or +. + + + + + Widget XtOpenApplication + XtAppContext * app_context_return + String application_class + XrmOptionDescList options + Cardinal num_options + int * argc_in_out + String * argv_in_out + String * fallback_resources + WidgetClass widget_class + ArgList args + Cardinal num_args + + + + + + + app_context_return + + + +Returns the application context, if non-NULL. + + + + + + application_class + + + +Specifies the class name of the application. + + + + + + options + + + +Specifies the command line options table. + + + + + + num_options + + + +Specifies the number of entries in options. + + + + + + argc_in_out + + + +Specifies a pointer to the number of command line arguments. + + + + + + argv_in_out + + + +Specifies a pointer to the command line arguments. + + + + + + fallback_resources + + + +Specifies resource values to be used if the application class resource +file cannot be opened or read, or NULL. + + + + + + widget_class + + + +Specifies the class of the widget to be created. Must be shellWidgetClass +or a subclass. + + + + + + args + + + +Specifies the argument list to override any +other resource specifications for the created shell widget. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +function calls + +followed by +, +then calls + +with display_string NULL and +application_name NULL, and finally calls + +with name NULL, the specified widget_class, +an argument list and count, +and returns the created shell. +The recommended widget_class is +sessionShellWidgetClass. +The argument list and count are created by merging +the specified args and num_args with a list +containing the specified argc and argv. +The modified argc and argv returned by + +are returned in argc_in_out and argv_in_out. If +app_context_return 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 + +terminates the application. If fallback_resources is non-NULL, + +is called with the value prior to calling +. + + + + + Widget XtVaOpenApplication + XtAppContext * app_context_return + String application_class + XrmOptionDescList options + Cardinal num_options + int * argc_in_out + String * argv_in_out + String * fallback_resources + WidgetClass widget_class + + + + + + + app_context_return + + + +Returns the application context, if non-NULL. + + + + + + application_class + + + +Specifies the class name of the application. + + + + + + options + + + +Specifies the command line options table. + + + + + + num_options + + + +Specifies the number of entries in options. + + + + + + argc_in_out + + + +Specifies a pointer to the number of command line arguments. + + + + + + argv_in_out + + + +Specifies the command line arguments array. + + + + + + fallback_resources + + + +Specifies resource values to be used if the application class +resource file cannot be opened, or NULL. + + + + + + widget_class + + + +Specifies the class of the widget to be created. Must be shellWidgetClass +or a subclass. + + + + + + ... + + + +Specifies the variable argument list to override any other +resource specifications for the created shell. + + + + + + +The + +procedure is identical in function to + +with the args and num_args parameters replaced by a varargs list, +as described +in Section 2.5.1. + + + + +Widget Instance Allocation: The allocate Procedure + +A widget class may optionally provide an instance allocation procedure +in the +ObjectClassExtension +record. + + + +When the call to create a widget includes a varargs list containing +XtVaTypedArg, +these arguments will be passed to the allocation procedure in an +XtTypedArgList. + + +typedef struct { + String name; + String type; + XtArgVal value; + int size; +} XtTypedArg, *XtTypedArgList; + + +The allocate procedure pointer in the +ObjectClassExtension +record is of type +. + + + + + typedef void (*AllocateProc) + WidgetClass widget_class + Cardinal* constraint_size + Cardinal* more_bytes + ArgList args + Cardinal* num_args + XtTypedArgList typed_args + Cardinal* num_typed_args + Widget* new_return + XtPointer* more_bytes_return + + + + + + + widget_class + + + +Specifies the widget class of the instance to allocate. + + + + + + constraint_size + + + +Specifies the size of the constraint record to allocate, or 0. + + + + + + more_bytes + + + +Specifies the number of auxiliary bytes of memory to allocate. + + + + + + args + + + +Specifies the argument list as given in the call to create the widget. + + + + + + num_args + + + +Specifies the number of arguments. + + + + + + typed_args + + + +Specifies the list of typed arguments given in the call to create the widget. + + + + + + num_typed_args + + + +Specifies the number of typed arguments. + + + + + + new_return + + + +Returns a pointer to the newly allocated instance, or NULL in case of error. + + + + + + more_bytes_return + + + +Returns the auxiliary memory if it was requested, or NULL +if requested and an error occurred; otherwise, unchanged. + + + + + + +At widget allocation time, if an extension record with record_type +equal to +NULLQUARK +is located through the object class part extension field +and the allocate field is not NULL, the + +will be invoked to allocate memory for the widget. If no ObjectClassPart +extension record is declared with record_type equal to +NULLQUARK, +then +XtInheritAllocate +and +XtInheritDeallocate +are assumed. +If no + +is found, the Intrinsics will allocate memory for the widget. + + + +An + +must perform the following: + + + + +Allocate memory for the widget instance and return it in new_return. +The memory must be at least wc->core_class.widget_size bytes in length, +double-word aligned. + + + + +Initialize the core.constraints field in the instance record to NULL +or to point to a constraint record. If constraint_size +is not 0, the procedure must allocate memory for the constraint record. +The memory must be double-word aligned. + + + + +If more_bytes is not 0, then the address of a block of memory +at least more_bytes in size, double-word aligned, must be +returned in the more_bytes_return parameter, +or NULL to indicate an error. + + + + +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. + + + + +Widget Instance Initialization: The initialize Procedure + +The initialize procedure pointer in a widget class is of type +. + + + + + typedef void (*XtInitProc) + Widget request + Widget new + ArgList args + Cardinal * num_args + + + + + + + request + + + +Specifies a copy of the widget with resource values as requested by the +argument list, the resource database, and the widget defaults. + + + + + + new + + + +Specifies the widget with the new values, both resource and nonresource, +that are actually allowed. + + + + + + args + + + +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 +XtVaTypedArg +are converted to the widget representation and the list is transformed +into the +ArgList +format. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +An initialization procedure performs the following: + + + + +Allocates space for and copies any resources referenced by address +that the client is allowed to free or modify +after the widget has been created. +For example, +if a widget has a field that is a +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. + +It is not necessary to allocate space for or to copy callback lists. + + + + + +Computes values for unspecified resource fields. +For example, if width and height are zero, +the widget should compute an appropriate width and height +based on its other resources. + +A widget may directly assign only +its own width and height within the initialize, initialize_hook, +set_values, and +set_values_hook procedures; see . + + + + + +Computes values for uninitialized nonresource fields that are derived from +resource fields. +For example, graphics contexts (GCs) that the widget uses are derived from +resources like background, foreground, and font. + + + + +An initialization procedure also can check certain fields for +internal consistency. +For example, it makes no sense to specify a colormap for a depth +that does not support that colormap. + + + +Initialization procedures are called in superclass-to-subclass order +after all fields specified in the resource lists have been +initialized. The initialize procedure does not need to examine +args and num_args +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. + + + +If a subclass does not need an initialization procedure +because it does not need to perform any of the above operations, +it can specify NULL for the initialize field in the class record. + + + +Sometimes a subclass may want to overwrite values filled in by its +superclass. +In particular, size calculations of a superclass often are +incorrect for a subclass, and in this case, +the subclass must modify or recalculate fields declared +and computed by its superclass. + + + +As an example, +a subclass can visually surround its 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. + + + +The request and new 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 request widget is a copy of the widget as initialized by the +arglist and resource database. +The new widget starts with the values in the request, +but it has been updated by all superclass initialization procedures called +so far. +A subclass initialize procedure can compare these two to resolve +any potential conflicts. + + + +In the above example, +the subclass with the visual surround can see +if the width and height in the request widget are zero. +If so, +it adds its surround size to the width and height +fields in the new widget. +If not, it must make do with the size originally specified. + + + +The new widget will become the actual widget instance record. +Therefore, +the initialization procedure should do all its work on the new widget; +the request widget should never be modified. +If the initialize procedure +needs to call any routines that operate on a widget, +it should specify new as the widget instance. + + + + +Constraint Instance Initialization: The ConstraintClassPart initialize Procedure + +The constraint initialization procedure pointer, found in the +ConstraintClassPart +initialize field of the widget class record, is of type +. +The values passed to the parent constraint initialization procedures +are the same as those passed to the child's class widget initialization +procedures. + + + +The constraints field of the request widget points to a copy of the +constraints record as initialized by the arglist and resource database. + + + +The constraint initialization procedure should compute any constraint fields +derived from constraint resources. +It can make further changes to the new widget to make the widget +and any other constraint fields +conform to the specified constraints, for example, +changing the widget's size or position. + + + +If a constraint class does not need a constraint initialization procedure, +it can specify NULL for the initialize field of the +ConstraintClassPart +in the class record. + + + + +Nonwidget Data Initialization: The initialize_hook Procedure + + +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. + + + + +The initialize_hook procedure pointer is of type +: + + + + + typedef void(*XtArgsProc) + Widget w + ArgList args + Cardinal * num_args + + + + + + + w + + + +Specifies the widget. + + + + + + args + + + +Specifies the argument list passed by the client. +If the client created the widget using a varargs form, any resources +specified via +XtVaTypedArg +are converted to the widget representation and the list is transformed +into the +ArgList +format. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +If this procedure is not NULL, +it is called immediately after the corresponding initialize +procedure or in its place if the initialize field is NULL. + + + +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. + + + + + +Realizing Widgets + +To realize a widget instance, use +. + + + + + void XtRealizeWidget + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + +If the widget is already realized, + +simply returns. +Otherwise it performs the following: + + + + +Binds all action names in the widget's +translation table to procedures (see ). + + + + +Makes a postorder traversal of the widget tree rooted +at the specified widget and calls each non-NULL change_managed procedure +of all composite widgets that have one or more managed children. + + + + +Constructs an +XSetWindowAttributes +structure filled in with information derived from the +Core +widget fields and calls the realize procedure for the widget, +which adds any widget-specific attributes and creates the X window. + + + + +If the widget is +not a subclass of +compositeWidgetClass, + +returns; otherwise it continues and performs the following: + + + + + + +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. + + + + +Maps all of the managed children windows that have mapped_when_managed +True. +If a widget is managed but mapped_when_managed is +False, +the widget is allocated visual space but is not displayed. + + + + + + +If the widget is a top-level shell widget (that is, it has no parent), and +mapped_when_managed is +True, + +maps the widget window. + + + +, +, +, +, +XtUnmanage\%Children, +, +, +and +XtDestroy\%Widget +maintain the following invariants: + + + + +If a composite widget is realized, then all its managed children are realized. + + + + +If a composite widget is realized, then all its managed children that have +mapped_when_managed +True +are mapped. + + + + +All Intrinsics functions and all widget routines should accept +either realized or unrealized widgets. +When calling the realize or change_managed +procedures for children of a composite +widget, + +calls the procedures in reverse order of +appearance in the +CompositePart +children 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. + + + +To check whether or not a widget has been realized, use +. + + + + + Boolean XtIsRealized + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + +The + +function returns +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. + + + +Some widget procedures (for example, set_values) might wish to +operate differently +after the widget has been realized. + + +Widget Instance Window Creation: The realize Procedure + +The realize procedure pointer in a widget class is of type +. + + + + + typedef void (*XtRealizeProc) + Widget w + XtValueMask value_mask + XSetWindowAttributes attributes + + + + + + + w + + + +Specifies the widget. + + + + + + value_mask + + + +Specifies which fields in the attributes structure are used. + + + + + + attributes + + + +Specifies the window attributes to use in the +XCreateWindow +call. + + + + + + +The realize procedure must create the widget's window. + + + +Before calling the class realize procedure, the generic + +function fills in a mask and a corresponding +XSetWindowAttributes +structure. +It sets the following fields in attributes and +corresponding bits in value_mask +based on information in the widget +core +structure: + + + + +The background_pixmap (or background_pixel if background_pixmap is +XtUnspecifiedPixmap) +is filled in from the corresponding field. + + + + +The border_pixmap (or border_pixel if border_pixmap is +XtUnspecifiedPixmap) +is filled in from the corresponding field. + + + + +The colormap is filled in from the corresponding field. + + + + +The event_mask is filled in based on the event handlers registered, +the event translations specified, whether the expose field is non-NULL, +and whether visible_interest is +True. + + + + +The bit_gravity is set to +NorthWestGravity +if the expose field is NULL. + + + + +These or any other fields in attributes and the corresponding bits in +value_mask can be set by the realize procedure. + + + +Note that because realize is not a chained operation, +the widget class realize procedure must update the +XSetWindowAttributes +structure with all the appropriate fields from +non-Core +superclasses. + + + +A widget class can inherit its realize procedure from its superclass +during class initialization. +The realize procedure defined for +coreWidgetClass +calls + +with the passed value_mask and attributes +and with window_class and visual set to +CopyFromParent. +Both +compositeWidgetClass +and +constraintWidgetClass +inherit this realize procedure, and most new widget subclasses +can do the same (see ). + + + +The most common noninherited realize procedures set bit_gravity in the mask +and attributes to the appropriate value and then create the window. +For example, depending on its justification, Label might set bit_gravity to +WestGravity, +CenterGravity, +or +EastGravity. +Consequently, shrinking it would just move the bits appropriately, +and no +exposure +event is needed for repainting. + + + +If a composite widget's children should be realized in an order other +than that specified +(to control the stacking order, for example), +it should call + +on its children itself in the appropriate order from within its own +realize procedure. + + + +Widgets that have children and whose class is not a subclass of +compositeWidgetClass +are responsible for calling + +on their children, usually from within the realize procedure. + + + +Realize procedures cannot manage or unmanage their descendants. + + + + +Window Creation Convenience Routine + +Rather than call the Xlib +XCreateWindow +function explicitly, a realize procedure should normally call the Intrinsics analog +, +which simplifies the creation of windows for widgets. + + + + + void XtCreateWindow + Widget w + unsigned int window_class + Visual * visual + XtValueMask value_mask + XSetWindowAttributes attributes + + + + + + + w + + + +Specifies the widget that defines the additional window attributed. Must be of class Core or any subclass thereof. + + + + + + window_class + + + +Specifies the Xlib window class (for example, +InputOutput, +InputOnly, +or +CopyFromParent ). + + + + + + visual + + + +Specifies the visual type (usually +CopyFromParent ). + + + + + + value_mask + + + +Specifies which fields in the attributes structure are used. + + + + + + attributes + + + +Specifies the window attributes to use in the +XCreateWindow +call. + + + + + + +The + +function calls the Xlib +XCreateWindow +function with values from the widget structure and the passed parameters. +Then, it assigns the created window to the widget's window field. + + + + +evaluates the following fields of the widget core +structure: depth, screen, parent->core.window, x, +y, width, height, and +border_width. + + + + + +Obtaining Window Information from a Widget + +The +Core +widget class definition contains the screen and window ids. +The window field may be NULL for a while +(see and ). + + + +The display pointer, the parent widget, screen pointer, +and window of a widget are available to the widget writer by means of macros +and to the application writer by means of functions. + + + + + Display XtDisplay + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + +XtDisplay +returns the display pointer for the specified widget. + + + + + Widget XtParent + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + +XtParent +returns the parent object for the specified widget. The returned object +will be of class Object or a subclass. + + + + + Screen *XtScreen + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + + +returns the screen pointer for the specified widget. + + + + + Window XtWindow + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + + +returns the window of the specified widget. + + + +The display pointer, screen pointer, and window of a widget or +of the closest widget ancestor of a nonwidget object are available +by means of +, +, +and +. + + + + + Display *XtDisplayOfObject + Widget w + + + + + + + object + + + +Specifies the object. Must be of class Object or any subclass thereof. + + + + + + + +is identical in function to +XtDisplay +if the object is a widget; otherwise + +returns the display +pointer for the nearest ancestor of object that is of class +Widget or a subclass thereof. + + + + + Screen *XtScreenOfObject + Widget object + + + + + + + + object + + + +Specifies the object. Must be of class Object or any subclass thereof. + + + + + + + +is identical in function to + +if the object is a widget; otherwise + +returns the screen pointer +for the nearest ancestor of object that is of class +Widget or a subclass thereof. + + + + + Window XtWindowOfObject + Widget object + + + + + + + object + + + +Specifies the object. Must be of class Object or any subclass thereof. + + + + + + + +is identical in function to + +if the object is a widget; otherwise + +returns the window for the nearest ancestor of object that is of class +Widget or a subclass thereof. + + + +To retrieve the instance name of an object, use +. + + + + + String XtName + Widget object + + + + + + + object + + + +Specifies the object whose name is desired. Must be of class Object or any subclass thereof. + + + + + + + +returns a pointer to the instance name of the specified object. +The storage is owned by the Intrinsics and must not be modified. The +name is not qualified by the names of any of the object's ancestors. + + + +Several window attributes are locally cached in the widget instance. +Thus, they can be set by the resource manager and + +as well as used by routines that derive structures from these values +(for example, depth for deriving pixmaps, +background_pixel for deriving GCs, and so on) or in the + +call. + + + +The x, y, width, height, and border_width +window attributes are available to +geometry managers. +These fields are maintained synchronously inside the Intrinsics. +When an +XConfigureWindow +is issued by the Intrinsics on the widget's window (on request of its parent), +these values are updated immediately rather than some time later +when the server generates a +ConfigureNotify +event. +(In fact, most widgets do not select +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 +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 ). + + +Unrealizing Widgets + +To destroy the windows associated with a widget and its +non-pop-up descendants, use +. + + + + + void XtUnrealizeWidget + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + +If the widget is currently unrealized, + +simply returns. Otherwise it performs the following: + + + + +Unmanages the widget if the widget is managed. + + + + +Makes a postorder (child-to-parent) traversal of the widget tree +rooted at the specified widget and, for each widget that has +declared a callback list resource named ``unrealizeCallback'', executes the +procedures on the +XtNunrealizeCallback +list. + + + + +Destroys the widget's window and any subwindows by calling +XDestroyWindow +with the specified widget's window field. + + + + +Any events in the queue or which arrive following a call to + +will be dispatched as if the window(s) of the +unrealized widget(s) had never existed. + + + + + +Destroying Widgets + +The Intrinsics provide support + + + + +To destroy all the pop-up children of the widget being destroyed +and destroy all children of composite widgets. + + + + +To remove (and unmap) the widget from its parent. + + + + +To call the callback procedures that have been registered to trigger +when the widget is destroyed. + + + + +To minimize the number of things a widget has to deallocate when destroyed. + + + + +To minimize the number of +XDestroyWindow +calls when destroying a widget tree. + + + + +To destroy a widget instance, use +. + + + + + + void XtDestroyWidget + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + +The + +function provides the only method of destroying a widget, +including widgets that need to destroy themselves. +It can be called at any time, +including from an application callback routine of the widget being destroyed. +This requires a two-phase destroy process in order to avoid dangling +references to destroyed widgets. + + + +In phase 1, + +performs the following: + + + + +If the being_destroyed field of the widget is +True, +it returns immediately. + + + + +Recursively descends the widget tree and +sets the being_destroyed field to +True +for the widget and all normal and pop-up children. + + + + +Adds the widget to a list of widgets (the destroy list) that should be +destroyed when it is safe to do so. + + + + +Entries on the destroy list satisfy the invariant that +if w2 occurs after w1 on the destroy list, then w2 is not a descendent, +either normal or pop-up, of w1. + + + +Phase 2 occurs when all procedures that should execute as a result of +the current event have been called, including all procedures registered with +the event and translation managers, +that is, when the current invocation of + +is about to return, or immediately if not in +. + + + +In phase 2, + +performs the following on each entry in the destroy list in the order +specified: + + + + +If the widget is not a pop-up child and the widget's parent is a subclass of +composite\%WidgetClass, +and if the parent is not being destroyed, +it calls + +on the widget and then calls the widget's parent's delete_child procedure +(see ). + + + + +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). + + + + +The + +function then makes second traversal of the widget and all normal +and pop-up descendants to perform the following three items on each +widget in postorder: + + + + +If the widget is not a pop-up child and the widget's parent is a subclass of +constraint\%WidgetClass, +it calls the +ConstraintClassPart +destroy procedure for the parent, +then for the parent's superclass, +until finally it calls the +ConstraintClassPart +destroy procedure for +constraintWidgetClass. + + + + +Calls the +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. + + + + +If the widget class object class part contains an +ObjectClassExtension +record with the record_type +NULLQUARK +and the deallocate field is not NULL, +calls the deallocate procedure to deallocate the instance and if one +exists, the constraint record. Otherwise, the Intrinsics will deallocate +the widget instance record and if one exists, the constraint record. + + + + +Calls +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.) + + + + +Adding and Removing Destroy Callbacks + +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 +. +The destroy callback list is identified by the resource name +XtNdestroyCallback. + + + +For example, the following adds an application-supplied destroy callback +procedure ClientDestroy with client data to a widget by calling +. + + + +XtAddCallback(w, XtNdestroyCallback, ClientDestroy, client_data) + + + +Similarly, the following removes the application-supplied destroy callback +procedure ClientDestroy by calling +. + + + +XtRemoveCallback(w, XtNdestroyCallback, ClientDestroy, client_data) + + +The ClientDestroy argument is of type +; +see . + + + + +Dynamic Data Deallocation: The destroy Procedure + +The destroy procedure pointers in the +ObjectClassPart, +RectObjClassPart, +and +CoreClassPart +structures are of type +. + + + + + typedef void XtWidgetProc + Widget w + + + + + + + w + + + +Specifies the widget being destroyed. + + + + + + +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. + + + +Deallocating storage includes, but is not limited to, +the following steps: + + + + +Calling + +on dynamic storage allocated with +, +, +and so on. + + + + +Calling +XFreePixmap +on pixmaps created with direct X calls. + + + + +Calling + +on GCs allocated with +. + + + + +Calling +XFreeGC +on GCs allocated with direct X calls. + + + + +Calling + +on event handlers added to other widgets. + + + + +Calling + +on timers created with +. + + + + +Calling + +for each child if the widget has children +and is not a subclass of +compositeWidgetClass. + + + + +During destroy phase 2 for each widget, the Intrinsics remove the widget +from the modal cascade, unregister all event handlers, remove all key, +keyboard, button, and pointer grabs and remove all callback procedures +registered on the widget. Any outstanding selection transfers will time out. + + + + +Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure + +The constraint destroy procedure identified in the +ConstraintClassPart +constraintWidgetClass. +This constraint destroy procedure pointer is of type +. +The constraint destroy procedures are called in subclass-to-superclass order, +starting at the class of the widget's parent and ending at +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. + + + +If a parent does not need to deallocate any constraint storage, +the constraint destroy procedure entry +in its class record can be NULL. + + + + +Widget Instance Deallocation: The deallocate Procedure + +The deallocate procedure pointer in the +ObjectClassExtension +record is of type +XtDeallocateProc. + + + + + typedef void (*XtDeallocateProc) + Widget widget + XtPointer more_bytes + + + + + + + widget + + + +Specifies the widget being destroyed. + + + + + + more_bytes + + + +Specifies the auxiliary memory received from the corresponding allocator +along with the widget, or NULL. + + + + + + +When a widget is destroyed, if an +ObjectClassExtension +record exists in the object class part extension field +with record_type +NULLQUARK +and the deallocate field is not NULL, the +XtDeallocateProc +will be called. +If no ObjectClassPart extension record is declared with record_type +equal to +NULLQUARK, +then +XtInheritAllocate +and +XtInheritDeallocate +are assumed. +The responsibilities of the deallocate procedure are to deallocate the +memory specified by more_bytes if it is not NULL, +to deallocate the constraints record as specified by the +widget's core.constraints field if it is +not NULL, and to deallocate the widget instance itself. + + + +If no +XtDeallocateProc +is found, it is assumed that the Intrinsics +originally allocated the memory and is responsible for freeing it. + + + + + +Exiting from an Application + +All X Toolkit applications should terminate +by calling + +and then exiting +using the +standard method for their operating system (typically, by calling +exit +for POSIX-based systems). +The quickest way to make the windows disappear while exiting is to call + +on each top-level shell widget. +The Intrinsics have no resources beyond those in the program image, +and the X server will free its resources when its connection +to the application is broken. + + + +Depending upon the widget set in use, it may be necessary to explicitly +destroy individual widgets or widget trees with + +before calling + +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 ), then the client may wish to resign from the session +before exiting. See for details. + + + diff --git a/libXt/specs/CH03 b/libXt/specs/CH03 deleted file mode 100644 index f96a79781..000000000 --- a/libXt/specs/CH03 +++ /dev/null @@ -1,1031 +0,0 @@ -.\" $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/libXt/specs/CH03.xml b/libXt/specs/CH03.xml new file mode 100644 index 000000000..2b2e1d730 --- /dev/null +++ b/libXt/specs/CH03.xml @@ -0,0 +1,1406 @@ + +Composite Widgets and Their Children + +Composite widgets (widgets whose class is a subclass of +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 Intrinsics functions) include: + + + + +Overall management of children from creation to destruction. + + + + +Destruction of descendants when the composite widget is destroyed. + + + + +Physical arrangement (geometry management) of a displayable subset of +children (that is, the managed children). + + + + +Mapping and unmapping of a subset of the managed children. + + + + +Overall management is handled by the generic procedures + +and +. + +adds children to their parent by calling the parent's insert_child +procedure. + +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. + + + +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 Intrinsics. + + + +Children are added to and removed from their parent's managed set by using +, +, +, +, +and +, +which notify the parent to recalculate the physical layout of its children +by calling the parent's change_managed procedure. +The + +convenience function calls + +and + +on the result. + + + +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 map_when_managed field is +False. +The default is +True +and is changed by using +. + + + +Each composite widget class declares a geometry manager, +which is responsible for figuring out where the managed children +should appear within the composite widget's window. +Geometry management techniques fall into four classes: + + + Fixed boxes + + +Fixed boxes have a fixed number of children created by the parent. +All these children are managed, +and none ever makes geometry manager requests. + + + + + Homogeneous boxes + + +Homogeneous boxes treat all children equally and apply the same geometry +constraints to each child. +Many clients insert and delete widgets freely. + + + + + Heterogeneous boxes + + +Heterogeneous boxes have a specific location where each child is placed. +This location usually is not specified in pixels, +because the window may be resized, but is expressed rather +in terms of the relationship between a child +and the parent or between the child and other specific children. +The class of heterogeneous boxes is usually a subclass of +Constraint. + + + + + Shell boxes + + +Shell boxes typically have only one child, +and the child's size is usually +exactly the size of the shell. +The geometry manager must communicate with the window manager, if it exists, +and the box must also accept +ConfigureNotify +events when the window size is changed by the window manager. + + + + + + +Addition of Children to a Composite Widget: The insert_child Procedure + +To add a child to +the parent's list of children, the + +function calls the parent's class routine insert_child. +The insert_child procedure pointer in a composite widget is of type +. + + + + +typedef void (*XtWidgetProc) + Widget w + + + + + + + w + + + +Passes the newly created child. + + + + + + +Most composite widgets inherit their superclass's operation. +The insert_child routine in +CompositeWidgetClass calls the insert_position procedure +and inserts the child at the specified position +in the children list, expanding it if necessary. + + + +Some composite widgets define their own insert_child routine +so that they can order their children in some convenient way, +create companion controller widgets for a new widget, +or limit the number or class of their child widgets. +A composite widget class that wishes +to allow nonwidget children (see ) must specify a +CompositeClassExtension +extension record as described +in +and set the accepts_objects field in this record to +True. +If the +CompositeClassExtension +record is not specified or the +accepts_objects field is +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. + + + +If there is not enough room to insert a new child in the children array +(that is, num_children is equal to num_slots), +the insert_child procedure must first reallocate the array +and update num_slots. +The insert_child procedure then places the child at the appropriate position +in the array and increments the num_children field. + + + + +Insertion Order of Children: The insert_position Procedure + +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. + + + +An application controls the presentation order of a set of children by +supplying an +XtNinsertPosition +resource. +The insert_position procedure pointer in a composite widget instance is of type +. + + + + +typedef Cardinal (*XtOrderProc) + + Widget w + + + + + + + w + + + +Passes the newly created widget. + + + + + + +Composite widgets that allow clients to order their children (usually +homogeneous boxes) can call their widget instance's insert_position +procedure from the class's insert_child procedure to determine where a new +child should go in its children array. +Thus, a client using a composite class can apply different sorting criteria +to widget instances of the class, passing in a different insert_position +procedure resource when it creates each composite widget instance. + + + +The return value of the insert_position procedure +indicates how many children should go before the widget. +Returning zero indicates that the widget should go before all other children, +and returning num_children indicates that it should go after all other children. +The default insert_position function returns num_children +and can be overridden by a specific composite widget's resource list +or by the argument list provided when the composite widget is created. + + + + +Deletion of Children: The delete_child Procedure + + +To remove the child from the parent's children list, the + +function eventually causes a call to the Composite parent's class delete_child +procedure. +The delete_child procedure pointer is of type +. + + + + +typedef void (*XtWidgetProc) + Widget w + + + + + + + w + + + +Passes the child being deleted. + + + + + + + +Most widgets inherit the delete_child procedure from their superclass. +Composite widgets that create companion widgets define their own +delete_child procedure to remove these companion widgets. + + + + +Adding and Removing Children from the Managed Set + +The Intrinsics provide a set of generic routines to permit the addition of +widgets to or the removal of widgets from a composite widget's managed set. +These generic routines eventually call the composite widget's change_managed +procedure if the procedure pointer is non-NULL. +The change_managed procedure pointer is of type +. +The widget argument specifies the composite widget whose managed child +set has been modified. + + + +Managing Children + +To add a list of widgets to the geometry-managed (and hence displayable) +subset of their Composite parent, use +. + + +typedef Widget *WidgetList; + + + +void XtManageChildren + WidgetList children + Cardinal num_children + + + + + + + children + + + +Specifies a list of child widgets. Each child must be of class +RectObj or any subclass thereof. + + + + + + num_children + + + +Specifies the number of children in the list. + + + + + + +The + +function performs the following: + + + + +Issues an error if the children do not all have the same parent or +if the parent's class is not a subclass of +compositeWidgetClass. + + + + +Returns immediately if the common parent is being destroyed; +otherwise, for each unique child on the list, + +ignores the child if it already is managed or is being destroyed, +and marks it if not. + + + + +If the parent is realized and after all children have been marked, +it makes some of the newly managed children viewable: + + + + + + +Calls the change_managed routine of the widgets' parent. + + + + +Calls + +on each previously unmanaged child that is unrealized. + + + + +Maps each previously unmanaged child that has map_when_managed +True. + + + + + + +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 managed field is +True +and should ignore all other children. +Note that some composite widgets, especially fixed boxes, call + +from their insert_child procedure. + + + +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 +, +which first updates the x and y fields and which then calls +XMoveWindow. + + + +If the composite widget wishes to change the size or border width of any of +its children, it calls +, +which first updates the +width, height, and border_width +fields and then calls +XConfigureWindow. +Simultaneous repositioning and resizing may be done with +; +see . + + + +To add a single child to its parent widget's set of managed children, use +. + + + + +void XtManageChild + Widget child + + + + + + + child + + + +Specifies the child. Must be of class RectObj or any subclass thereof. + + + + + + +The + +function constructs a +WidgetList +of length 1 and calls +. + + + +To create and manage a child widget in a single procedure, use + +or +. + + + + +Widget XtCreateManagedWidget + String name + WidgetClass widget_class + Widget parent + ArgList args + Cardinal num_args + + + + + + + name + + + +Specifies the resource instance name for the created widget. + + + + + + widget_class + + + +Specifies the widget class pointer for the created widget. (rC + + + + + + parent + + + +Specifies the parent widget. Must be of class Composite or any +subclass thereof. + + + + + + args + + + +Specifies the argument list to override any other resource specifications. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +function is a convenience routine that calls + +and +. + + + + +Widget XtVaCreateManagedWidget + String name + WidgetClass widget_class + Widget parent + + + + + + + name + + + +Specifies the resource instance name for the created widget. + + + + + + widget_class + + + +Specifies the widget class pointer for the created widget. (rC + + + + + + parent + + + +Specifies the parent widget. Must be of class Composite or any +subclass thereof. + + + + + + ... + + + +Specifies the variable argument list to override any other +resource specifications. + + + + + + + +is identical in function to + +with the args and num_args parameters replaced +by a varargs list, as described in Section 2.5.1. + + + + +Unmanaging Children + +To remove a list of children from a parent widget's managed list, use +. + + + + +void XtUnmanageChildren + WidgetList children + Cardinal num_children + + + + + + + children + + + +Specifies a list of child widgets. Each child must be of class +RectObj or any subclass thereof. + + + + + + num_children + + + +Specifies the number of children. + + + + + + +The + +function performs the following: + + + + +Returns immediately if the common parent is being destroyed. + + + + +Issues an error if the children do not all have the same parent +or if the parent is not a subclass of +compositeWidgetClass. + + + + +For each unique child on the list, + +ignores the child if it is unmanaged; otherwise it performs the following: + + + + + + +Marks the child as unmanaged. + + + + +If the child is realized and the map_when_managed field is +True, +it is unmapped. + + + + + + +If the parent is realized and if any children have become unmanaged, +calls the change_managed routine of the widgets' parent. + + + + + +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, + +should be called instead; +see . + + + +To remove a single child from its parent widget's managed set, use +. + + + + +void XtUnmanageChild + Widget child + + + + + + + child + + + +Specifies the child. Must be of class RectObj or any subclass thereof. + + + + + + +The + +function constructs a widget list +of length 1 and calls +. + + + +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. + + + + +Bundling Changes to the Managed Set + +A client may simultaneously unmanage and manage children +with a single call to the Intrinsics. In this same call the +client may provide a callback procedure that can modify the +geometries of one or more children. The composite widget class +defines whether this single client call results in separate invocations +of the change_managed method, one to unmanage and the other to +manage, or in just a single invocation. + + + +To simultaneously remove from and add to the geometry-managed +set of children of a composite parent, use +. + + + + +void XtChangeManagedSet + WidgetList unmanage_children + Cardinal num_unmanage_children + XtDoChangeProc do_change_proc + XtPointer client_data + WidgetList manage_children + Cardinal num_manage_children + + + + + + + unmanage_children + + + +Specifies the list of widget children to initially remove from the managed set. + + + + + + num_unmanage_children + + + +Specifies the number of entries in the unmanage_children list. + + + + + + do_change_proc + + + +Specifies a procedure to invoke between unmanaging +and managing the children, or NULL. + + + + + + client_data + + + +Specifies client data to be passed to the do_change_proc. + + + + + + manage_children + + + +Specifies the list of widget children to finally add to the managed set. + + + + + + num_manage_children + + + +Specifies the number of entries in the manage_children list. + + + + + + +The + +function performs the following: + + + + +Returns immediately if num_unmanage_children and +num_manage_children are both 0. + + + + +Issues a warning and returns if the widgets specified in the +manage_children and +the unmanage_children lists do not all have the same parent or if +that parent is not a subclass of +compositeWidgetClass. + + + + +Returns immediately if the common parent is being destroyed. + + + + +If do_change_proc is not NULL and the parent's +CompositeClassExtension +allows_change_managed_set field is +False, +then + +performs the following: + + + + + + +Calls + +(unmanage_children, num_unmanage_children). + + + + +Calls the do_change_proc. + + + + +Calls + +(manage_children, num_manage_children). + + + + + + +Otherwise, the following is performed: + + + + + + +For each child on the unmanage_children list; if the child is +already unmanaged it is ignored, otherwise it is marked as unmanaged, +and if it is realized and its map_when_managed field is +True, +it is unmapped. + + + + +If do_change_proc is non-NULL, the procedure is invoked. + + + + +For each child on the manage_children list; if the child is already +managed or is being destroyed, it is ignored; otherwise it is +marked as managed. + + + + +If the parent is realized and after all children have been marked, +the change_managed method of the parent is invoked, and subsequently +some of the newly managed children are made viewable by calling + +on each previously unmanaged child that is unrealized and +mapping each previously unmanaged child that has map_when_managed +True. + + + + + + +If no +CompositeClassExtension +record is found in the parent's composite class part extension field +with record type +NULLQUARK +and version greater than 1, and if +XtInheritChangeManaged +was specified in the parent's class record during class initialization, +the value of the allows_change_managed_set +field is inherited from the superclass. The value inherited from +compositeWidgetClass +for the allows_change_managed_set field is +False. + + + +It is not an error to include a child in both the unmanage_children +and the manage_children lists. The effect of such a call is that +the child remains managed following the call, but the do_change_proc is +able to affect the child while it is in an unmanaged state. + + + +The do_change_proc is of type +. + + + + +typedef void *XtDoChangeProc + + Widget composite_parent + WidgetList unmange_children + Cardinal *num_unmanage_children + WidgetList manage_children + Cardinal *num_manage_children + XtPointer client_data + + + + + + + composite_parent + + + +Passes the composite parent whose managed set is being altered. + + + + + + unmanage_children + + + +Passes the list of children just removed from the managed set. + + + + + + num_unmanage_children + + + +Passes the number of entries in the unmanage_children list. + + + + + + manage_children + + + +Passes the list of children about to be added to the managed set. + + + + + + num_manage_children + + + +Passes the number of entries in the manage_children list. + + + + + + client_data + + + +Passes the client data passed to +. + + + + + + +The do_change_proc procedure is used by the caller of + +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 + +may take advantage of the fact that the Intrinsics internally grant +geometry requests made by unmanaged children without invoking +the parent's geometry manager. To achieve this advantage, if +the do_change_proc procedure +changes the geometry of a child or of a descendant of a child, then +that child should be included in the unmanage_children and +manage_children lists. + + + + +Determining if a Widget Is Managed + +To determine the managed state of a given child widget, use +. + + + + +Boolean XtIsManaged + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + +The + +function returns +True +if the specified widget is of class RectObj or any subclass thereof +and is managed, or +False +otherwise. + + + + + +Controlling When Widgets Get Mapped + +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 map_when_managed field to +False. + + + +To change the value of a given widget's map_when_managed field, use +. + + + + +void XtSetMappedWhenManaged + Widget w + Boolean map_when_managed + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + map_when_managed + + + +Specifies a Boolean value that indicates the new value +that is stored into the widget's map_when_managed +field. + + + + + + +If the widget is realized and managed, +and if map_when_managed is +True, + +maps the window. +If the widget is realized and managed, +and if map_when_managed is +False, +it unmaps the window. + +is a convenience function that is equivalent to (but slightly faster than) +calling + +and setting the new value for the XtNmappedWhenManaged resource +then mapping the widget as appropriate. +As an alternative to using + +to control mapping, +a client may set mapped_when_managed to +False +and use + +and + +explicitly. + + + +To map a widget explicitly, use +. + + + + + XtMapWidget + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + +To unmap a widget explicitly, use +. + + + + + XtUnmapWidget + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + + + + +Constrained Composite Widgets + +The Constraint +widget class is a subclass of +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. + + + +Constraint +widgets have all the responsibilities of normal composite widgets +and, in addition, must process and act upon the constraint information +associated with each of their children. + + + +To make it easy for widgets and the Intrinsics to keep track of the +constraints associated with a child, +every widget has a constraints 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 +constraintWidgetClass, +then the child's constraints field is NULL. + + + +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: + + +typedef struct { + Dimension max_width, max_height; +} MaxConstraintPart; +typedef struct { + MaxConstraintPart max; +} MaxConstraintRecord, *MaxConstraint; + + +A subclass of this widget class that also needs to maintain a minimum size would +define its constraint record as follows: + + +typedef struct { + Dimension min_width, min_height; +} MinConstraintPart; +typedef struct { + MaxConstraintPart max; + MinConstraintPart min; +} MaxMinConstraintRecord, *MaxMinConstraint; + + +Constraints are allocated, initialized, deallocated, and otherwise maintained +insofar as possible by the Intrinsics. +The Constraint class record part has several entries that facilitate this. +All entries in +ConstraintClassPart +are fields and procedures that are defined and implemented by the parent, +but they are called whenever actions are performed on the parent's children. + + + +The + +function uses the constraint_size field in the parent's class record +to allocate a constraint record when a child is created. + +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. + + + +When the + +and + +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. + +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 +ConstraintClassExtension +record in the +ConstraintClassPart +extension +fields with a record type of +NULLQUARK +and the get_values_hook field in +the extension record is non-NULL, + +calls the get_values_hook +procedure(s) to allow the parent to return derived constraint fields. + + + +The + +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; + +does this automatically. + + + diff --git a/libXt/specs/CH04 b/libXt/specs/CH04 deleted file mode 100644 index 0291aa333..000000000 --- a/libXt/specs/CH04 +++ /dev/null @@ -1,1998 +0,0 @@ -.\" $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\*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/libXt/specs/CH04.xml b/libXt/specs/CH04.xml new file mode 100644 index 000000000..d01fe6eae --- /dev/null +++ b/libXt/specs/CH04.xml @@ -0,0 +1,2498 @@ + +Shell Widgets + + +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. + + + +If a shell widget is resized from the outside (typically by a window manager), +the shell widget also resizes its managed child widget automatically. +Similarly, if the shell's child widget needs to change size, +it can make a geometry request to the shell, +and the shell negotiates the size change with the outer environment. +Clients should never attempt to change the size of their shells directly. + + +The five types of public shells are: + + + OverrideShell + + + Used for shell windows that completely bypass the window manager + (for example, pop-up menu shells). + + + + + TransientShell + + Used for shell windows that have the + WM_TRANSIENT_FOR + property set. The effect of this property is dependent upon the + window manager being used. + + + + + TopLevelShell + + Used for normal top-level windows + (for example, any additional top-level widgets an application needs). + + + + + ApplicationShell + + Formerly used for the single main top-level window that + the window manager identifies as an application instance and + made obsolete by SessionShell. + + + + + SessionShell + + + Used for the single main top-level window that + the window manager identifies as an application instance and + that interacts with the session manager. + + + + + + +Shell Widget Definitions + +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. + + + +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. + + +The eight different types of shells are: + + + Shell + + The base class for shell widgets; provides the + fields needed for all types of shells. Shell + is a direct subclass of + compositeWidgetClass. + + + + + OverrideShell + + A subclass of Shell; used for shell windows that completely + bypass the window manager. + + + + WMShell + + A subclass of Shell; contains fields needed by the + common window manager protocol. + + + + VendorShell + + A subclass of WMShell; contains fields used by + vendor-specific window managers. + + + + + TransientShell + + A subclass of VendorShell; used for shell windows that + desire the WM_TRANSIENT_FOR + property. + + + + TopLevelShell + + A subclass of VendorShell; used for normal top-level windows. + + + + + ApplicationShell + + A subclass of TopLevelShell; may be used for an application's additional + root windows. + + + + SessionShell + + A subclass of ApplicationShell; used for an application's + main root window. + + + + + +Note that the classes +Shell, +WMShell, +and +VendorShell +are internal and should not be instantiated or subclassed. +Only +OverrrideShell, +TransientShell, +TopLevelShell, +ApplicationShell, +and +SessionShell +are intended for public use. + + + +ShellClassPart Definitions + +Only the Shell +class has additional class fields, which are all contained in the +ShellClassExtensionRec. +None of the other Shell classes have any additional class fields: + + + +typedef struct { + XtPointer extension; +} ShellClassPart, OverrideShellClassPart, +WMShellClassPart, VendorShellClassPart, TransientShellClassPart, +TopLevelShellClassPart, ApplicationShellClassPart, SessionShellClassPart; + + +The full Shell class record definitions are: + + +typedef struct _ShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; +} ShellClassRec; + + + +typedef struct { + XtPointer next_extension; See + XrmQuark record_type; See + long version; See + Cardinal record_size; See + XtGeometryHandler root_geometry_manager; See below +} ShellClassExtensionRec, *ShellClassExtension; + + + +typedef struct _OverrideShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + OverrideShellClassPart override_shell_class; +} OverrideShellClassRec; + + + +typedef struct _WMShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + WMShellClassPart wm_shell_class; +} WMShellClassRec; + + + +typedef struct _VendorShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + WMShellClassPart wm_shell_class; + VendorShellClassPart vendor_shell_class; +} VendorShellClassRec; + + + +typedef struct _TransientShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + WMShellClassPart wm_shell_class; + VendorShellClassPart vendor_shell_class; + TransientShellClassPart transient_shell_class; +} TransientShellClassRec; + + + +typedef struct _TopLevelShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + WMShellClassPart wm_shell_class; + VendorShellClassPart vendor_shell_class; + TopLevelShellClassPart top_level_shell_class; +} TopLevelShellClassRec; + + + +typedef struct _ApplicationShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + WMShellClassPart wm_shell_class; + VendorShellClassPart vendor_shell_class; + TopLevelShellClassPart top_level_shell_class; + ApplicationShellClassPart application_shell_class; +} ApplicationShellClassRec; + + + +typedef struct _SessionShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + WMShellClassPart wm_shell_class; + VendorShellClassPart vendor_shell_class; + TopLevelShellClassPart top_level_shell_class; + ApplicationShellClassPart application_shell_class; + SessionShellClassPart session_shell_class; +} SessionShellClassRec; + + + +The single occurrences of the class records and pointers for creating +instances of shells are: + + + +extern ShellClassRec shellClassRec; +extern OverrideShellClassRec overrideShellClassRec; +extern WMShellClassRec wmShellClassRec; +extern VendorShellClassRec vendorShellClassRec; +extern TransientShellClassRec transientShellClassRec; +extern TopLevelShellClassRec topLevelShellClassRec; +extern ApplicationShellClassRec applicationShellClassRec; +extern SessionShellClassRec sessionShellClassRec; +extern WidgetClass shellWidgetClass; +extern WidgetClass overrideShellWidgetClass; +extern WidgetClass wmShellWidgetClass; +extern WidgetClass vendorShellWidgetClass; +extern WidgetClass transientShellWidgetClass; +extern WidgetClass topLevelShellWidgetClass; +extern WidgetClass applicationShellWidgetClass; +extern WidgetClass sessionShellWidgetClass; + + + +The following opaque types and opaque variables are defined +for generic operations on widgets whose class is a subclass of +Shell. + + + + + + + + + + Types + Variables + + + + + ShellWidget + shellWidgetClass + + + OverrideShellWidget + overrideShellWidgetClass + + + WMShellWidget + wmShellWidgetClass + + + VendorShellWidget + vendorShellWidgetClass + + + TransientShellWidget + transientShellWidgetClass + + + TopLevelShellWidget + topLevelShellWidgetClass + + + ApplicationShellWidget + applicationShellWidgetClass + + + SessionShellWidget + sessionShellWidgetClass + + + ShellWidgetClass + + + + OverrideShellWidgetClass + + + + WMShellWidgetClass + + + + VendorShellWidgetClass + + + + TransientShellWidgetClass + + + + TopLevelShellWidgetClass + + + + ApplicationShellWidgetClass + + + + SessionShellWidgetClass + + + + + + + +The declarations for all Intrinsics-defined shells except +VendorShell appear in +Shell.h +and +ShellP.h. +VendorShell has separate public and private .h files which are included by +Shell.h +and +ShellP.h. + + + +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. + + + +The symbolic constant for the +ShellClassExtension +version identifier is +XtShellExtensionVersion +(see ). + + + +The root_geometry_manager procedure acts as +the parent geometry manager for geometry requests made by shell +widgets. When a shell widget calls either + +or +, +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 +XtGeometryYes; +if the window manager denies the geometry +request or does not change the window geometry within some timeout +interval (equal to wm_timeout in the case of WMShells), the +root_geometry_manager procedure should return +XtGeometryNo. +If the window manager makes some alternative geometry change, the +root_geometry_manager procedure may return either +XtGeometryNo +and handle the new geometry as a resize or +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. + + + +If no +ShellClassPart +extension record is declared with record_type +equal to +NULLQUARK, +then +XtInheritRootGeometryManager +is assumed. + + + + +ShellPart Definition + +The various shell widgets have the following additional instance +fields defined in +their widget records: + + + +typedef struct { + String geometry; + XtCreatePopupChildProc create_popup_child_proc; + XtGrabKind grab_kind; + Boolean spring_loaded; + Boolean popped_up; + Boolean allow_shell_resize; + Boolean client_specified; + Boolean save_under; + Boolean override_redirect; + XtCallbackList popup_callback; + XtCallbackList popdown_callback; + Visual * visual; +} ShellPart; + + + +typedef struct { + int empty; +} OverrideShellPart; + + + +typedef struct { + String title; + int wm_timeout; + Boolean wait_for_wm; + Boolean transient; + Boolean urgency; + Widget client_leader; + String window_role; + struct _OldXSizeHints { + long flags; + int x, y; + int width, height; + int min_width, min_height; + int max_width, max_height; + int width_inc, height_inc; + struct { + int x; + int y; + } min_aspect, max_aspect; + } size_hints; + XWMHints wm_hints; + int base_width, base_height, win_gravity; + Atom title_encoding; +} WMShellPart; + + + +typedef struct { + int vendor_specific; +} VendorShellPart; + + + +typedef struct { + Widget transient_for; +} TransientShellPart; +typedef struct { + String icon_name; + Boolean iconic; + Atom icon_name_encoding; +} TopLevelShellPart; + + + +typedef struct { + char * class; + XrmClass xrm_class; + int argc; + char ** argv; +} ApplicationShellPart; + + + +typedef struct { + SmcConn connection; + String session_id; + String * restart_command; + String * clone_command; + String * discard_command; + String * resign_command; + String * shutdown_command; + String * environment; + String current_dir; + String program_path; + unsigned char restart_style; + Boolean join_session; + XtCallbackList save_callbacks; + XtCallbackList interact_callbacks; + XtCallbackList cancel_callbacks; + XtCallbackList save_complete_callbacks; + XtCallbackList die_callbacks; + XtCallbackList error_callbacks; +} SessionShellPart; + + + +The full shell widget instance record definitions are: + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; +} ShellRec, *ShellWidget; + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + OverrideShellPart override; +} OverrideShellRec, *OverrideShellWidget; + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; +} WMShellRec, *WMShellWidget; + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; +} VendorShellRec, *VendorShellWidget; + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; + TransientShellPart transient; +} TransientShellRec, *TransientShellWidget; + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; + TopLevelShellPart topLevel; +} TopLevelShellRec, *TopLevelShellWidget; + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; + TopLevelShellPart topLevel; + ApplicationShellPart application; +} ApplicationShellRec, *ApplicationShellWidget; + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; + TopLevelShellPart topLevel; + ApplicationShellPart application; + SessionShellPart session; +} SessionShellRec, *SessionShellWidget; + + + + + +Shell Resources + +The resource names, classes, and representation types specified in +the +shellClassRec +resource list are: + + + + + + + + + + + Name + Class + Representation + + + + + XtNallowShellResize + XtCAllowShellResize + XtRBoolean + + + XtNcreatePopupChildProc + XtCCreatePopupChildProc + XtRFunction + + + XtNgeometry + XtCGeometry + XtRString + + + XtNoverrideRedirect + XtCOverrideRedirect + XtRBoolean + + + XtNpopdownCallback + XtCCallback + XtRCallback + + + XtNpopupCallback + XtCCallback + XtRCallback + + + XtNsaveUnder + XtCSaveUnder + XtRBoolean + + + XtNvisual + XtCVisual + XtRVisual + + + + + + +OverrideShell +declares no additional resources beyond those defined by +Shell. + + + +The resource names, classes, and representation types specified in +the +wmShellClassRec +resource list are: + + + + + + + + + + + Name + Class + Representation + + + + + XtNbaseHeight + XtCBaseHeight + XtRInt + + + XtNbaseWidth + XtCBaseWidth + XtRInt + + + XtNclientLeader + XtCClientLeader + XtRWidget + + + XtNheightInc + XtCHeightInc + XtRInt + + + XtNiconMask + XtCIconMask + XtRBitmap + + + XtNiconPixmap + XtCIconPixmap + XtRBitmap + + + XtNiconWindow + XtCIconWindow + XtRWindow + + + XtNiconX + XtCIconX + XtRInt + + + XtNiconY + XtCIconY + XtRInt + + + XtNinitialState + XtCInitialState + XtRInitialState + + + XtNinput + XtCInput + XtRBool + + + XtNmaxAspectX + XtCMaxAspectX + XtRInt + + + XtNmaxAspectY + XtCMaxAspectY + XtRInt + + + XtNmaxHeight + XtCMaxHeight + XtRInt + + + XtNmaxWidth + XtCMaxWidth + XtRInt + + + XtNminAspectX + XtCMinAspectX + XtRInt + + + XtNminAspectY + XtCMinAspectY + XtRInt + + + XtNminHeight + XtCMinHeight + XtRInt + + + XtNminWidth + XtCMinWidth + XtRInt + + + XtNtitle + XtCTitle + XtRString + + + XtNtitleEncoding + XtCTitleEncoding + XtRAtom + + + XtNtransient + XtCTransient + XtRBoolean + + + XtNwaitforwm, XtNwaitForWm + XtCWaitforwm, XtCWaitForWm + XtRBoolean + + + XtNwidthInc + XtCWidthInc + XtRInt + + + XtNwindowRole + XtCWindowRole + XtRString + + + XtNwinGravity + XtCWinGravity + XtRGravity + + + XtNwindowGroup + XtCWindowGroup + XtRWindow + + + XtNwmTimeout + XtCWmTimeout + XtRInt + + + XtNurgency + XtCUrgency + XtRBoolean + + + _ + + + + + + +The class resource list for +VendorShell +is implementation-defined. + + + +The resource names, classes, and representation types that are specified in the +transient\%ShellClassRec +resource list are: + + + + + + + + + + + Name + Class + Representation + + + + + XtNtransientFor + XtCTransientFor + XtRWidget + + + + + + +The resource names, classes, and representation types that are specified in the +topLevelShellClassRec +resource list are: + + + + + + + + + + + Name + Class + Representation + + + + + XtNiconName + XtCIconName + XtRString + + + XtNiconNameEncoding + XtCIconNameEncoding + XtRAtom + + + XtNiconic + XtCIconic + XtRBoolean + + + + + + +The resource names, classes, and representation types that are specified in the +application\%ShellClassRec +resource list are: + + + + + + + + + + + Name + Class + Representation + + + + + XtNargc + XtCArgc + XtRInt + + + XtNargv + XtCArgv + XtRStringArray + + + + + + +The resource names, classes, and representation types that are specified +in the +sessionShellClassRec +resource list are: + + + + + + + + + + + Name + Class + Representation + + + + + XtNcancelCallback + XtCCallback + XtRCallback + + + XtNcloneCommand + XtCCloneCommand + XtRCommandArgArray + + + XtNconnection + XtCConnection + XtRSmcConn + + + XtNcurrentDirectory + XtCCurrentDirectory + XtRDirectoryString + + + XtNdieCallback + XtCCallback + XtRCallback + + + XtNdiscardCommand + XtCDiscardCommand + XtRCommandArgArray + + + XtNenvironment + XtCEnvironment + XtREnvironmentArray + + + XtNerrorCallback + XtCCallback + XtRCallback + + + XtNinteractCallback + XtCCallback + XtRCallback + + + XtNjoinSession + XtCJoinSession + XtRBoolean + + + XtNprogramPath + XtCProgramPath + XtRString + + + XtNresignCommand + XtCResignCommand + XtRCommandArgArray + + + XtNrestartCommand + XtCRestartCommand + XtRCommandArgArray + + + XtNrestartStyle + XtCRestartStyle + XtRRestartStyle + + + XtNsaveCallback + XtCCallback + XtRCallback + + + XtNsaveCompleteCallback + XtCCallback + XtRCallback + + + XtNsessionID + XtCSessionID + XtRString + + + XtNshutdownCommand + XtCShutdownCommand + XtRCommandArgArray + + + + + + + + +ShellPart Default Values + +The default values for fields common to all classes of public shells +(filled in by the +Shell +resource lists and the +Shell +initialize procedures) are: + + + + + + + + + + Field + Default Value + + + + + geometry + NULL + + + create_popup_child_proc + NULL + + + grab_kind + (none) + + + spring_loaded + (none) + + + popped_up + False + + + allow_shell_resize + False + + + client_specified + (internal) + + + save_under + True + for OverrideShell and TransientShell, + False + otherwise + + + override_redirect + True + for OverrideShell, + False + otherwise + + + popup_callback + NULL + + + popdown_callback + NULL + + + visual + CopyFromParent + + + + + + +The geometry field specifies the size and position +and is usually given only on a command line or in a defaults file. +If the geometry field is non-NULL when +a widget of class WMShell +is realized, the geometry specification is parsed using +XWMGeometry +with a default geometry +string constructed from the values of x, y, width, +height, width_inc, +and height_inc and the size and position flags in the window manager +size hints are set. If the geometry specifies an x or y position, +then +USPosition +is set. If the geometry specifies a width or height, then +USSize +is set. Any fields in the geometry specification +override the corresponding values in the +Core x, y, width, and height fields. +If geometry is NULL or contains only a partial specification, then the +Core x, y, width, and height fields are used and +PPosition +and +PSize +are set as appropriate. +The geometry string is not copied by any of the Intrinsics +Shell classes; a client specifying the string in an arglist +or varargs list must ensure +that the value remains valid until the shell widget is realized. +For further information on the geometry string, see + +in Xlib — C Language X Interface. + + + +The create_popup_child_proc procedure is called by the + +procedure and may remain NULL. +The grab_kind, spring_loaded, +and popped_up fields maintain widget +state information as described under +, +, +, +and +. +The allow_shell_resize field controls whether the widget contained +by the shell is allowed to try to resize itself. +If allow_shell_resize is +False, +any geometry requests made by the child will always return +XtGeometryNo +without interacting with the window manager. +Setting save_under +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 override_redirect +True +determines +whether the window manager can intercede when the shell window +is mapped. +For further information on override_redirect, +see in +Xlib — C Language X Interface +and + and + in the +Inter-Client Communication Conventions Manual. +The pop-up and pop-down callbacks are called during + +and +. +The default value of the visual resource is the symbolic value +CopyFromParent. +The Intrinsics do not need to query the parent's visual type when the +default value is used; if a client using + +to examine the visual type receives the value +CopyFromParent, +it must then use +XGetWindowAttributes +if it needs the actual visual type. + + + +The default values for Shell fields in +WMShell +and its subclasses are: + + + + + + + + + + Field + Default Value + + + + + title + Icon name, if specified, otherwise the application's name + + + wm_timeout + Five seconds, in units of milliseconds + + + wait_for_wm + True + + + transient + True + for TransientShell, + False + otherwise + + + urgency + False + + + client_leader + NULL + + + window_role + NULL + + + min_width + XtUnspecifiedShellInt + + + min_height + XtUnspecifiedShellInt + + + max_width + XtUnspecifiedShellInt + + + max_height + XtUnspecifiedShellInt + + + width_inc + XtUnspecifiedShellInt + + + height_inc + XtUnspecifiedShellInt + + + min_aspect_x + XtUnspecifiedShellInt + + + min_aspect_y + XtUnspecifiedShellInt + + + max_aspect_x + XtUnspecifiedShellInt + + + max_aspect_y + XtUnspecifiedShellInt + + + input + False + + + initial_state + Normal + + + icon_pixmap + None + + + icon_window + None + + + icon_x + XtUnspecifiedShellInt + + + icon_y + XtUnspecifiedShellInt + + + icon_mask + None + + + window_group + XtUnspecifiedWindow + + + base_width + XtUnspecifiedShellInt + + + base_height + XtUnspecifiedShellInt + + + win_gravity + XtUnspecifiedShellInt + + + title_encoding + See text + + + + + + +The title and +title_encoding fields are stored in the +WM_NAME +property on the shell's window by the WMShell realize procedure. +If the title_encoding field is +None, +the title string is assumed to be in the encoding of the current +locale and the encoding of the +WM_NAME +property is set to +XStdICCTextStyle. +If a language procedure has not been set +the default value of title_encoding is +XA_STRING, otherwise the default value is +None. +The wm_timeout 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 wait_for_wm to +False +(later events may reset this value). +When wait_for_wm is +False, +the shell does not wait for a response, but relies on asynchronous +notification. +If transient is +True, +the +WM_TRANSIENT_FOR +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 +Inter-Client Communication Conventions Manual +for more details. + + + +The realize and set_values procedures of WMShell store the +WM_CLIENT_LEADER +property on the shell window. +When client_leader 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 client_leader is NULL and the shell widget has a NULL parent, +the widget's window is used as the value of the +property. +When client_leader is NULL and the shell widget has a non-NULL parent, +a search is made for the closest shell ancestor +with a non-NULL client_leader, +and if none is found the shell ancestor with a NULL parent is the result. +If the resulting widget is realized, the property is created +with the value of the widget's window. + + + +When the value of window_role is not NULL, the +realize and set_values procedures store the +WM_WINDOW_ROLE +property on the shell's window with the value of the resource. + + + +All other resources specify fields in the window manager hints +and the window manager size hints. +The realize and set_values procedures of +WMShell +set the corresponding flag bits in the +hints if any of the fields contain nondefault values. In addition, if +a flag bit is set that refers to a field with the value +XtUnspecifiedShellInt, +the value of the field is modified as follows: + + + + + + + + + + Field + Replacement + + + + + base_width, base_height + 0 + + + width_inc, height_inc + 1 + + + max_width, max_height + 32767 + + + min_width, min_height + 1 + + + min_aspect_x, min_aspect_y + -1 + + + max_aspect_x, max_aspect_y + -1 + + + icon_x, icon_y + -1 + + + win_gravity + Value returned by + XWMGeometry + if called, + else NorthWestGravity + + + + + + +If the shell widget has a non-NULL parent, then the +realize and set_values procedures replace the value +XtUnspecifiedWindow +in the window_group field with the window id of the root widget +of the widget tree if the +root widget is realized. The symbolic constant +XtUnspecifiedWindowGroup +may be used to indicate that the window_group hint flag bit is not +to be set. If transient is +True, +the shell's class is not a subclass of +TransientShell, +and window_group is not +XtUnspecifiedWindowGroup, +the WMShell realize and set_values procedures then store the +WM_TRANSIENT_FOR +property with the value of window_group. + + + +Transient +shells have the following additional resource: + + + + + + + + + + Field + Replacement + + + + + transient_for + NULL + + + + + + +The realize and set_values procedures of +TransientShell +store the +WM_TRANSIENT_FOR +property on the shell window if transient is +True. +If transient_for is non-NULL and the widget specified by +transient_for is realized, then its window is used as the value of the +WM_TRANSIENT_FOR +property; otherwise, the value of window_group is used. + + + +TopLevel +shells have the the following additional resources: + + + + + + + + + + + Field + Default Value + + + + + icon_name + Shell widget's name + + + iconic + False + + + icon_name_encoding + See text + + + + + + +The icon_name +and icon_name_encoding fields are stored in the +WM_ICON_NAME +property on the shell's window by the TopLevelShell realize +procedure. +If the icon_name_encoding field is +None, +the icon_name string is assumed to be in the encoding of the +current locale and the encoding of the +WM_ICON_NAME +property is set to +XStdICCTextStyle. +If a language procedure has not been set, +the default value of icon_name_encoding is +XA_STRING, otherwise the default value is +None. +The iconic 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 +WM_CHANGE_STATE +message (as specified by the Inter-Client Communication Conventions Manual) +if this resource is changed from +False +to +True +and will call + +specifying grab_kind as +XtGrabNone +if iconic is changed from +True +to +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 initial_state to +IconicState +if iconic is +True. + + + +Application +shells have the following additional resources: + + + + + + + + + + Field + Default Value + + + + + argc + 0 + + + argv + NULL + + + + + + +The argc and argv fields are used to initialize +the standard property +WM_COMMAND. See the +Inter-Client Communication Conventions Manual +for more information. + + + +The default values for the SessionShell instance fields, +which are filled in from the resource lists and by the +initialize procedure, are + + + + + + + + + + Field + Default Value + + + + + cancel_callbacks + NULL + + + clone_command + See text + + + connection + NULL + + + current_dir + NULL + + + die_callbacks + NULL + + + discard_command + NULL + + + environment + NULL + + + error_callbacks + NULL + + + interact_callbacks + NULL + + + join_session + True + + + program_path + NULL + + + resign_command + NULL + + + restart_command + See text + + + restart_style + SmRestartIfRunning + + + save_callbacks + NULL + + + save_complete_callbacks + NULL + + + session_id + NULL + + + shutdown_command + NULL + + + + + + +The connection field contains the session connection object or NULL +if a session connection is not being managed by this widget. + + + +The session_id is an identification assigned to the session +participant by the session manager. +The session_id 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 session_id field. +When not NULL, the session_id 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 +SM_CLIENT_ID +property on the client leader's window. + + + +If join_session is +False, +the widget will not attempt to establish a +connection to the session manager at shell creation time. +See and + +for more information on the functionality of this resource. + + + +The restart_command, clone_command, discard_command, +resign_command, shutdown_command, environment, +current_dir, program_path, and +restart_style fields contain standard session properties. + + + +When a session connection is established or newly managed by the shell, +the shell initialize and set_values methods check the values of the +restart_command, +clone_command, +and program_path +resources. At that time, if restart_command is NULL, the value +of the argv resource will be copied to restart_command. +Whether or not restart_command was NULL, +if "-xtsessionID" "<session id>" does not +already appear in the restart_command, it will be added by the +initialize and set_values methods at the beginning of the command arguments; +if the "-xtsessionID" argument already appears with an incorrect +session id in the following argument, that argument +will be replaced with the current session id. + + + +After this, the shell initialize and set_values procedures check the +clone_command. If clone_command is NULL, +restart_command will be copied to clone_command, +except the "-xtsessionID" and following argument will not be copied. + + + +Finally, the shell initialize and set_values procedures check the +program_path. If program_path is NULL, the +first element of restart_command is copied to program_path. + + + +The possible values of restart_style are +SmRestartIfRunning, +SmRestartAnyway, +SmRestartImmediately, +and +SmRestartNever. +A resource converter is registered for this resource; +for the strings that it recognizes, +see . + + + +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. + + + + + +Session Participation + +Applications can participate in a user's session, exchanging messages +with the session manager as described in the +X Session Management Protocol and the +X Session Management Library. + + + +When a widget of +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. + + + +Joining a Session + +When a Session shell is created, +if connection is NULL, +and if join_session is +True, +and if argv or restart_command is not NULL, +and if in POSIX environments the +SESSION_MANAGER +environment variable is defined, +the shell will attempt to establish a new connection with the session manager. + + + +To transfer management of an existing session connection from an +application to the shell at widget creation time, pass the existing +session connection ID as the connection 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. + + + +In the Session shell set_values procedure, +if join_session changes from +False +to +True +and connection is NULL and when in POSIX environments the +SESSION_MANAGER +environment variable is defined, +the shell will attempt to open a connection to the session manager. +If connection changes from NULL to non-NULL, the +Session shell +will take over management of that session connection and will set +join_session to +True. +If join_session changes from +False +to +True +and connection is not NULL, the +Session shell will take over management of the session connection. + + + +When a successful connection has been established, connection +contains the session connection ID for the session participant. +When the shell begins to manage the connection, it will call + +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 connection is set to NULL. + + + +While the connection is being managed, if a +SaveYourself, +SaveYourselfPhase2, +Interact, +ShutdownCancelled, +SaveComplete, +or +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 +SaveYourselfPhase2Request, +InteractRequest, +InteractDone, +SaveYourselfDone, +and +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 +SetProperties +or a +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. + + + + +Saving Application State + +The session manager instigates an application checkpoint by sending a +SaveYourself +request. +Applications are responsible for saving their state in response to the +request. + + + +When the +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 call_data parameter. + + + +The checkpoint token in the call_data parameter is of type +XtCheckpointToken. + + + +typedef struct { + int save_type; + int interact_style; + Boolean shutdown; + Boolean fast; + Boolean cancel_shutdown + int phase; + int interact_dialog_type; /* return */ + Boolean request_cancel; /* return */ + Boolean request_next_phase; /* return */ + Boolean save_success; /* return */ +} XtCheckpointTokenRec, *XtCheckpointToken; + + + +The save_type, interact_style, shutdown, and fast +fields of the token contain the parameters of the +SaveYourself +message. +The possible values of save_type are +SmSaveLocal, +SmSaveGlobal, +and +SmSaveBoth; +these indicate the type of information to be saved. +The possible values of interact_style are +SmInteractStyleNone, +SmInteractStyleErrors, +and +SmInteractStyleAny; +these indicate whether user interaction would be permitted +and, if so, what kind of interaction. +If shutdown is +True, +the checkpoint is being performed in preparation for the end of the session. +If fast is +True, +the client should perform the checkpoint as quickly as possible. +If cancel_shutdown is +True, +a +ShutdownCancelled +message has been received for the current save operation. +(See .) +The phase is used by manager clients, such as a window manager, +to distinguish between the first and second phase of a save operation. +The phase will be either 1 or 2. +The remaining fields in the checkpoint token structure are provided for +the application to communicate with the shell. + + + +Upon entry to the first application save callback procedure, the return +fields in the token have the following initial values: +interact_dialog_type is +SmDialogNormal; +request_cancel is +False; +request_next_phase is +False; +and save_success is +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. + + + +The purpose of the token's save_success field is to +indicate the outcome of the entire operation to the +session manager and ultimately, to the user. +Returning +False +indicates some portion of the application state +could not be successfully saved. If any token is returned +to the shell with save_success +False, +tokens subsequently received +by the application for the current save operation will show +save_success as +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 save_success +False. + + + +Session participants that manage and save the state of other clients +should structure their save or interact callbacks to +set request_next_phase to +True +when phase is 1, which will cause the shell to send the +SaveYourselfPhase2Request +when the first phase is complete. When the +SaveYourselfPhase2 +message is received, the shell will invoke the save callbacks a +second time with phase equal to 2. +Manager clients should save the state of other clients +when the callbacks are invoked the second time and phase equal to 2. + + + +The application may request additional tokens while a checkpoint is under way, +and these additional tokens must be returned by an explicit call. + + + +To request an additional token for a save callback response that has a +deferred outcome, use +. + + + + +XtCheckpointToken XtSessionGetToken + Widget widget + + + + + + + widget + + + +Specifies the Session shell widget which manages session participation. + + + + + + + +The + +function will return NULL if no checkpoint operation is currently under way. + + + +To indicate the completion of checkpoint processing including user +interaction, the application must signal the Session shell +by returning all tokens. +(See and +). +To return a token, use +. + + + + +void XtSessionReturnToken + XtCheckpointToken token + + + + + + + token + + + +Specifies a token that was received as the call_data by a procedure +on the interact callback list or a token that was received by a call to +. + + + + + + + +Tokens passed as call_data to save callbacks are implicitly +returned when the save callback procedure returns. +A save callback procedure should not call + +on the token passed in its call_data. + + + +Requesting Interaction + +When the token interact_style 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 + +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 +InteractRequest +to the session manager when an interact request is not already outstanding +for the application. + + + +The type of interaction dialog that will be requested is specified by +the interact_dialog_type field in the checkpoint token. +The possible values for interact_dialog_type are +SmDialogError +and +SmDialogNormal. +If a token is returned with interact_dialog_type containing +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. + + + +When a token is returned with save_success +False +or interact_dialog_type +SmDialogError, +tokens subsequently passed to callbacks during the same active +SaveYourself +response will reflect these changed values, indicating that +an error condition has occurred during the checkpoint. + + + +The request_cancel 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 request_cancel field is not examined by the shell. +This is also true of tokens received through a call to +. + + + + +Interacting with the User during a Checkpoint + +When the session manager grants the application's request for user interaction, +the Session shell receives an +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 call_data. +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 +. +Returning the token completes the current step and triggers the next step +in the sequence. + + + +During interaction the client may request cancellation of a shutdown. +When a token passed as call_data to an interact procedure is returned, +if shutdown is +True +and cancel_shutdown is +False, +request_cancel indicates whether the +application requests that the pending shutdown be cancelled. +If request_cancel is +True, +the field will also be +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 +InteractDone +message is sent to the session manager, indicating whether +a pending session shutdown is requested to be cancelled. + + + + +Responding to a Shutdown Cancellation + +Callbacks registered on the cancel callback list are invoked when the +Session shell processes a +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 +SaveComplete +or a +Die +message. +The call_data for these callbacks is NULL. + + + +When the shell notices that a pending shutdown has been cancelled, +the token cancel_shutdown field will be +True +in tokens subsequently given to the application. + + + +Receiving notice of a shutdown cancellation does not cancel the +pending execution of save callbacks or interact callbacks. +After the cancel callbacks execute, if interact_style is not +SmInteractStyleNone +and the interact list is not empty, +the procedures on the interact callback list will be executed +and passed a token with interact_style +SmInteractStyleNone. +The application should not interact with the user, and the Session shell +will not send an +InteractDone +message. + + + + +Completing a Save + +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 + +have been returned by corresponding calls to +. +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 +. +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. + + + +When the application has finished saving state, +the Session shell will report the result to the session manager by +sending the +SaveYourselfDone +message. +If the session is continuing, the shell will receive the +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 call_data for these callbacks is NULL. + + + + + +Responding to a Shutdown + +Callbacks registered on the die callback list are invoked when the +session manager sends a +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 call_data for these callbacks is NULL. + + + + +Resigning from a Session + +When the Session shell widget is destroyed, the destroy method will +close the connection to the session manager by sending a +ConnectionClosed +protocol message and will remove the input callback +that was watching for session protocol messages. + + + +When + +is used to set join_session to +False, +the set_values method of the Session shell will close the +connection to the session manager if one exists by sending a +ConnectionClosed +message, and connection will be set to NULL. + + + +Applications that exit in response to user actions and that do not +wait for phase 2 destroy to complete on +the Session shell should set join_session to +False +before exiting. + + + +When + +is used to set connection to NULL, +the Session shell will stop managing the connection, if one exists. +However, that session connection will not be closed. + + + +Applications that wish to ensure continuation of a session connection +beyond the destruction of the shell should first retrieve the +connection resource value, +then set the connection resource to NULL, +and then they may safely destroy the widget without losing control +of the session connection. + + + +The error callback list will be called if an unrecoverable +communications error occurs while the shell is managing the connection. +The shell will close the connection, set connection to NULL, +remove the input callback, and +call the procedures registered on the error callback list. +The call_data for these callbacks is NULL. + + + + diff --git a/libXt/specs/CH05 b/libXt/specs/CH05 deleted file mode 100644 index 4f15beab0..000000000 --- a/libXt/specs/CH05 +++ /dev/null @@ -1,783 +0,0 @@ -.\" $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/libXt/specs/CH05.xml b/libXt/specs/CH05.xml new file mode 100644 index 000000000..2c09455ed --- /dev/null +++ b/libXt/specs/CH05.xml @@ -0,0 +1,1063 @@ + +Pop-Up Widgets + +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. +Therefore, pop-ups are created and attached differently to their widget parent +than normal widget children. + + + +A parent of a pop-up widget does not actively manage its pop-up children; +in fact, it usually does not operate upon them in any way. +The popup_list field in the +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 + +to look for all extant children. + + + +A +composite +widget can have both normal and pop-up children. +A pop-up can be popped up from almost anywhere, not just by its parent. +The term child always refers to a normal, geometry-managed widget +on the composite widget's list of children, and the term +pop-up child always refers to a +widget on the pop-up list. + + + +Pop-Up Widget Types + +There are three kinds of pop-up widgets: + + + + + +Modeless pop-ups + + +A modeless pop-up (for example, a dialog box that does not prevent +continued interaction with the rest of the application) +can usually be manipulated by the window manager +and looks like any other application window from the +user's point of view. +The application main window itself is a special case of a modeless pop-up. + + + + +Modal pop-ups + + +A modal pop-up (for example, a dialog box that requires user input to +continue) +can sometimes be manipulated by the window manager, +and except for events that occur in the dialog box, +it disables user-event distribution to the rest of the application. + + + + +Spring-loaded pop-ups + + +A spring-loaded pop-up (for example, a menu) +can seldom be manipulated by the window manager, +and except for events that occur in the pop-up or its descendants, +it disables user-event distribution to all other applications. + + + + +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 Intrinsics. +Furthermore, all user input remap events occurring outside the spring-loaded +pop-up (e.g., in a descendant) are also delivered to the spring-loaded +pop-up after they have been dispatched to the appropriate descendant, so +that, for example, button-up can take down a spring-loaded pop-up no +matter where the +button-up occurs. + + + +Any kind of pop-up, in turn, can pop up other widgets. +Modal and spring-loaded pop-ups can constrain user events to +the most recent such pop-up or allow user events to be dispatched +to any of the modal or spring-loaded pop-ups +currently mapped. + + + +Regardless of their type, +all pop-up widget classes are responsible for communicating with the +X window manager and therefore are subclasses of +one of the +Shell +widget classes. + + + + +Creating a Pop-Up Shell + +For a widget to be popped up, +it must be the child of a pop-up shell widget. +None of the Intrinsics-supplied shells will +simultaneously manage more than one child. +Both the shell and child taken together are referred to as the pop-up. +When you need to use a pop-up, +you always refer to the pop-up by the pop-up shell, +not the child. + + + +To create a pop-up shell, use +. + + + + +Widget XtCreatePopupShell + String name + WidgetClass widget_class + Widget parent + ArgList args + Cardinal num_args + + + + + + + name + + + +Specifies the instance name for the created shell widget. + + + + + + widget_class + + + +Specifies the widget class pointer for the created shell widget. + + + + + + parent + + + +Specifies the parent widget. Must be of class Core or any subclass thereof. + + + + + + args + + + +Specifies the argument list to override any other resource specifications. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +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 +children list, +attaches the shell to the parent's popup_list directly. + + + +The screen resource for this widget is determined by first scanning +args for the XtNscreen argument. If no XtNscreen argument is +found, the resource database associated with the parent's screen +is queried for the resource name.screen, class +Class.Screen where Class is the class_name +field from the +CoreClassPart +of the specified widget_class. +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 +args. + + + +A spring-loaded pop-up invoked from a translation table via + +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. + + + +To create a pop-up shell using varargs lists, use +. + + + + +Widget XtVaCreatePopupShell + String name + WidgetClass widget_class + Widget parent + ... + + + + + + + name + + + +Specifies the instance name for the created shell widget. + + + + + + widget_class + + + +Specifies the widget class pointer for the created shell widget. + + + + + + parent + + + +Specifies the parent widget. Must be of class Core or any subclass thereof. + + + + + ... + + +Specifies the variable argument list to override any other +resource specifications. + + + + + + + + +is identical in function to + +with the args and num_args parameters replaced by a varargs list as +described in Section 2.5.1. + + + + +Creating Pop-Up Children + +Once a pop-up shell is created, +the single child of the pop-up shell can be created +either statically or dynamically. + + + +At startup, +an application can create the child of the pop-up shell, +which is appropriate for pop-up children composed of a fixed set +of widgets. +The application can change the state of the subparts of +the pop-up child as the application state changes. +For example, if an application creates a static menu, +it can call + +(or, in general, +) +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 + +on the pop-up shell at startup. +When the menu is needed, +all the widgets that make up the menu already exist and need only be mapped. +The menu should pop up as quickly as the X server can respond. + + + +Alternatively, +an application can postpone the creation of the child until it is needed, +which minimizes application startup time and allows the pop-up child to +reconfigure itself each time it is popped up. +In this case, +the pop-up child creation routine might poll the application +to find out if it should change the sensitivity of any of its subparts. + + + +Pop-up child creation does not map the pop-up, +even if you create the child and call + +on the pop-up shell. + + + +All shells have pop-up and pop-down callbacks, +which provide the opportunity either to make last-minute changes to a +pop-up child before it is popped up or to change it after it is popped down. +Note that excessive use of pop-up callbacks can make +popping up occur more slowly. + + + + +Mapping a Pop-Up Widget + +Pop-ups can be popped up through several mechanisms: + + + + +A call to + +or +. + + + + +One of the supplied callback procedures +, +, +or +. + + + + +The standard translation action +. + + + + + +Some of these routines take an argument of type +XtGrabKind, +which is defined as + + +typedef enum {XtGrabNone, XtGrabNonexclusive, XtGrabExclusive} XtGrabKind; + + + +The create_popup_child_proc procedure pointer +in the shell widget instance record is of type +. + + + + +void *XtCreatePopupChildProc + Widget w + + + + + + + w + + + +Specifies the shell widget being popped up. + + + + + + + +To map a pop-up from within an application, use +. + + + + +void XtPopup + Widget popup_shell + XtGrabKind grab_kind + + + + + + + popup_shell + + + +Specifies the shell widget. + + + + + + grab_kind + + + +Specifies the way in which user events should be constrained. + + + + + + +The + +function performs the following: + + + + +Calls + +to ensure popup_shell's class is a subclass of +shellWidgetClass. + + + + +Raises the window and returns if the shell's popped_up field is already +True. + + + + +Calls the callback procedures on the shell's popup_callback list, +specifying a pointer to the value of grab_kind as the call_data +argument. + + + + +Sets the shell popped_up field to +True, +the shell spring_loaded field to +False, +and the shell grab_kind field from grab_kind. + + + + +If the shell's create_popup_child_proc field is non-NULL, + +calls it with popup_shell as the parameter. + + + + +If grab_kind is either +XtGrabNonexclusive +or +XtGrabExclusive, +it calls + + +XtAddGrab(popup_shell, (grab_kind == XtGrabExclusive), False) + + + + +Calls + +with popup_shell specified. + + + + +Calls +XMapRaised +with the window of popup_shell. + + + + +To map a spring-loaded pop-up from within an application, use +. + + + + +void XtPopupSpringLoaded + Widget popup_shell + + + + + + + popup_shell + + + +Specifies the shell widget to be popped up. + + + + + + +The + +function performs exactly as + +except that it sets the shell spring_loaded field to +True +and always calls + +with exclusive +True +and spring-loaded +True. + + + +To map a pop-up from a given widget's callback list, +you also can register one of the +, +, +or + +convenience routines as callbacks, using the pop-up shell widget as the +client data. + + + + +void XtCallbackNone + Widget w + XtPointer client_data + XtPointer call_data + + + + + + + w + + + +Specifies the widget. + + + + + + client_data + + + +Specifies the pop-up shell. + + + + + + call_data + + + +Specifies the callback data argument, +which is not used by this procedure. + + + + + + + + +void XtCallbackNonexclusive + Widget w + XtPointer client_data + XtPointer call_data + + + + + + + w + + + +Specifies the widget. + + + + + + client_data + + + +Specifies the pop-up shell. + + + + + + call_data + + + +Specifies the callback data argument, +which is not used by this procedure. + + + + + + + + +void XtCallbackExclusive + Widget w + XtPointer client_data + XtPointer call_data + + + + + + + w + + + +Specifies the widget. + + + + + + client_data + + + +Specifies the pop-up shell. + + + + + + call_data + + + +Specifies the callback data argument, +which is not used by this procedure. + + + + + + +The +, +, +and + +functions call + +with the shell specified by the client_data argument +and grab_kind set as the name specifies. +, +, +and + +specify +XtGrabNone, +XtGrabNonexclusive, +and +XtGrabExclusive, +respectively. +Each function then sets the widget that executed the callback list +to be insensitive by calling +. +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. + + + +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 +, +or its synonym, +MenuPopup. +From a translation writer's point of view, +the definition for this translation action is + + + + +void XtMenuPopup + String shell_name + + + + + + + shell_name + + + +Specifies the name of the shell widget to pop up. + + + + + + + +is known to the translation manager, +which registers the corresponding built-in action procedure +XtMenuPopupAction +using + +specifying owner_events +True, +event_mask +ButtonPressMask +| +ButtonReleaseMask, +and pointer_mode and keyboard_mode +GrabModeAsync. + + + +If + +is invoked on +ButtonPress, +it calls + +on the specified shell widget. +If + +is invoked on +KeyPress +or +EnterWindow, +it calls + +on the specified shell widget with grab_kind set to +XtGrabNonexclusive. +Otherwise, the translation manager generates a +warning message and ignores the action. + + + + +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 + +gets to the application top-level shell widget and has not +found a matching shell, it generates a warning and returns immediately. + + + + +Unmapping a Pop-Up Widget + +Pop-ups can be popped down through several mechanisms: + + + + +A call to + + + + + +The supplied callback procedure + + + + + +The standard translation action + + + + + +To unmap a pop-up from within an application, use +. + + + + +void XtPopdown + Widget popup_shell + + + + + + + popup_shell + + + +Specifies the shell widget to pop down. + + + + + + +The + +function performs the following: + + + + +Calls + +to ensure popup_shell's class is a subclass of +shellWidgetClass. + + + + +Checks that the popped_up field of popup_shell is +True; +otherwise, it returns immediately. + + + + +Unmaps popup_shell's window and, if override_redirect is +False, +sends a synthetic +UnmapNotify +event as specified by the Inter-Client Communication Conventions Manual. + + + + +If popup_shell's grab_kind is either +XtGrabNonexclusive +or +XtGrabExclusive, +it calls +. + + + + +Sets popup_shell's popped_up field to +False. + + + + +Calls the callback procedures on the shell's popdown_callback list, +specifying a pointer to the value of the shell's grab_kind field +as the call_data argument. + + + + +To pop down a pop-up from a callback list, you may use the callback +. + + + + +void XtCallbackPopdown + Widget w + XtPointer client_data + XtPointer call_data + + + + + + + w + + + +Specifies the widget. + + + + + + client_data + + + +Specifies a pointer to the +XtPopdownID +structure. + + + + + + call_data + + + +Specifies the callback data argument, +which is not used by this procedure. + + + + + + +The + +function casts the client_data parameter to a pointer of type +XtPopdownID. + + +typedef struct { + Widget shell_widget; + Widget enable_widget; +} XtPopdownIDRec, *XtPopdownID; + + +The shell_widget is the pop-up shell to pop down, +and the enable_widget is usually the widget that was used to pop it up +in one of the pop-up callback convenience procedures. + + + + +calls + +with the specified shell_widget +and then calls + +to resensitize enable_widget. + + + +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 + +or its synonym, +MenuPopdown. +From a translation writer's point of view, +the definition for this translation action is + + + + +void XtMenuPopdown + String shell_name + + + + + + + shell_name + + + +Specifies the name of the shell widget to pop down. + + + + + + +If a shell name is not given, + +calls + +with the widget for which the translation is specified. +If shell_name is specified in the translation table, + +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 + +gets to the application top-level shell widget +and cannot find a matching shell, +it generates a warning and returns immediately. + + + diff --git a/libXt/specs/CH06 b/libXt/specs/CH06 deleted file mode 100644 index 34c2861b0..000000000 --- a/libXt/specs/CH06 +++ /dev/null @@ -1,1110 +0,0 @@ -.\" $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/libXt/specs/CH06.xml b/libXt/specs/CH06.xml new file mode 100644 index 000000000..7ff51bfb4 --- /dev/null +++ b/libXt/specs/CH06.xml @@ -0,0 +1,1369 @@ + +Geometry Management + + +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. + + + +To resolve physical layout conflicts between sibling widgets and between +a widget and its parent, the Intrinsics provide the geometry management mechanism. +Almost all +composite +widgets have a geometry manager specified in the geometry_manager 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. + + + +Initiating Geometry Changes + + +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 +XtMove\%Widget, +, +or +. +A child must ask its parent for a geometry change by calling + +or +. +An application or other client code initiates a geometry change by calling + +on the appropriate geometry fields, +thereby giving the widget the opportunity to modify or reject the client +request before it gets propagated to the parent and the opportunity +to respond appropriately to the parent's reply. + + + +When a widget that needs to change its size, position, 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. + + + +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 +. +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 +. +The requesting child may be given special treatment; see +. +It can simultaneously move and resize a child with a single call to +. + + + +Often, geometry managers find that they can satisfy a request only if +they can reconfigure a widget that they are not in control of; in particular, +the +composite +widget may want to change its own size. +In this case, +the geometry manager makes a request to its parent's geometry manager. +Geometry requests can cascade this way to arbitrary depth. + + + +Because such cascaded arbitration of widget geometry can involve extended +negotiation, +windows are not actually allocated to widgets at application +startup until all widgets are satisfied with their geometry; +see and +. + + + + + + +The Intrinsics treatment of stacking requests is deficient in several areas. +Stacking requests for unrealized widgets are granted but will have no effect. +In addition, there is no way to do an + +that will generate a stacking geometry request. + + + + +After a successful geometry request (one that returned +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. + + + + + + + +General Geometry Manager Requests + +When making a geometry request, the child specifies an +XtWidgetGeometry +structure. + + + +typedef unsigned long XtGeometryMask; +typedef struct { + XtGeometryMask request_mode; + Position x, y; + Dimension width, height; + Dimension border_width; + Widget sibling; + int stack_mode; +} XtWidgetGeometry; + + + +To make a general geometry manager request from a widget, use +. + + + + +XtGeometryResult XtMakeGeometryRequest + Widget w + XtWidgetGeometry *request + XtWidgetGeometry *reply_return + + + + + + + w + + + +Specifies the widget making the request. Must be of class RectObj or any subclass thereof. + + + + + + request + + + +Specifies the desired widget geometry (size, position, border width, +and stacking order). + + + + + + reply_return + + + +Returns the allowed widget size, or may be NULL +if the requesting widget is not interested in handling +XtGeometryAlmost. + + + + + + + +Depending on the condition, + +performs the following: + + + + + +If the widget is unmanaged or the widget's parent is not realized, +it makes the changes and returns +XtGeometryYes. + + + + +If the parent's class is not a subclass of +compositeWidgetClass +or the parent's geometry_manager field is NULL, +it issues an error. + + + + +If the widget's being_destroyed field is +True, +it returns +XtGeometryNo. + + + + +If the widget x, y, width, height, and +border_width fields are +all equal to the requested values, +it returns +XtGeometryYes; +otherwise, it calls the parent's geometry_manager procedure +with the given parameters. + + + + +If the parent's geometry manager returns +XtGeometryYes +and if +XtCWQueryOnly +is not set in request->request_mode +and if the widget is realized, + +calls the +XConfigureWindow +Xlib function to reconfigure the widget's window (set its size, location, +and stacking order as appropriate). + + + + +If the geometry manager returns +XtGeometryDone, +the change has been approved and actually has been done. +In this case, + +does no configuring and returns +XtGeometryYes. + +never returns +XtGeometryDone. + + + + +Otherwise, + +just returns the resulting value from the parent's geometry manager. + + + + + +Children of primitive widgets are always unmanaged; therefore, + +always returns +XtGeometryYes +when called by a child of a primitive widget. + + + +The return codes from geometry managers are + + + +typedef enum { + XtGeometryYes, + XtGeometryNo, + XtGeometryAlmost, + XtGeometryDone +} XtGeometryResult; + + + +The request_mode definitions are from +<X11/X.h>. + + + + + + + + + + + #define + CWX + (1<<0) + + + #define + CWY + (1<<1) + + + #define + CWWidth + (1<<2) + + + #define + CWHeight + (1<<3) + + + #define + CWBorderWidth + (1<<4) + + + #define + CWSibling + (1<<5) + + + #define + CWStackMode + (1<<6) + + + + + + +The Intrinsics also support the following value. + + + + + + + + + + + #define + XtCWQueryOnly + (1<<7) + + + + + + +XtCWQueryOnly +indicates that the corresponding geometry request is only a query +as to what would happen if this geometry request were made +and that no widgets should actually be changed. + + + +, +like the +XConfigureWindow +Xlib function, uses request_mode to determine which fields in the +XtWidgetGeometry +structure the caller wants to specify. + + + +The stack_mode definitions are from +<X11/X.h>: + + + + + + + + + + + #define + Above + 0 + + + #define + Below + 1 + + + #define + TopIf + 2 + + + #define + BottomIf + 3 + + + #define + Opposite + 4 + + + + + + +The Intrinsics also support the following value. + + + + + + + + + + + #define + XtSMDontChange + 5 + + + + + + +For definition and behavior of +Above, +Below, +TopIf, +BottomIf, +and +Opposite, +BLAH +in Xlib — C Language X Interface.. +XtSMDontChange +indicates that the widget wants its current stacking order preserved. + + + + +Resize Requests + +To make a simple resize request from a widget, you can use + +as an alternative to +. + + + + +typedef XtGeometryResult XtMakeResizeRequest + Widget w + Dimension width + Dimension *width_return + + + + + + + w + + + +Specifies the widget making the request. Must be of class RectObj or any subclass thereof. + + + + + + width + + + +Specify the desired widget width and height. + + + + + + height + + + + + + + + width_return + + + +Return the allowed widget width and height. + + + + + + height_return + + + + + + + + + +The + +function, a simple interface to +, +creates an +XtWidgetGeometry +structure and specifies that width and height should change +by setting request_mode to +CWWidth +| +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 +XtGeometryAlmost, +width_return and height_return contain a compromise width and height. +If these are acceptable, +the widget should immediately call + +again and request that the compromise width and height be applied. +If the widget is not interested in +XtGeometryAlmost +replies, +it can pass NULL for width_return and height_return. + + + + +Potential Geometry Changes + +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 +XtCWQueryOnly +in the intermediate request. + + + +When +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 +XtGeometryAlmost, +the geometry manager needs to cache the entire +reply geometry in the event the child accepts the parent's compromise. + + + +If the grandparent's response was +XtGeometryAlmost, +it may also be necessary to cache the entire reply geometry from +the grandparent when +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. + + + +Note that a compromise geometry returned with +XtGeometryAlmost +is guaranteed only for the next call to the same widget; +therefore, a cache of size 1 is sufficient. + + + + +Child Geometry Management: The geometry_manager Procedure + +The geometry_manager procedure pointer in a composite widget class is of type +. + + + + +XtGeometryResult *XtGeometryHandler + Widget w + XtWidgetGeometry *request + XtWidgetGeometry *geometry_return + + + + + + + w + + + +Passes the widget making the request. + + + + + + request + + + +Passes the new geometry the child desires. + + + + + + geometry_return + + + +Passes a geometry structure in which the geometry manager may store a +compromise. + + + + + + +A class can inherit its superclass's geometry manager during class +initialization. + + + +A bit set to zero in the request's request_mode +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. + + + +If the geometry manager can satisfy all changes requested +and if +XtCWQueryOnly +is not specified, +it updates the widget's x, y, width, height, +and border_width fields +appropriately. +Then, it returns +XtGeometryYes, +and the values pointed to by the geometry_return argument are undefined. +The widget's window is moved and resized automatically by +. + + + +Homogeneous composite widgets often find it convenient to treat the widget +making the request the same as any other widget, including reconfiguring +it using + +or + +as part of its layout process, unless +XtCWQueryOnly +is specified. +If it does this, +it should return +XtGeometryDone +to inform + +that it does not need to do the configuration itself. + + + + +To remain +compatible with layout techniques used in older widgets (before +XtGeometryDone +was added to the Intrinsics), a geometry manager should avoid using + +or + +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. + + + + +Although + +resizes the widget's window +(if the geometry +manager returns +XtGeometryYes ), +it does not call the widget class's resize procedure. +The requesting widget must perform whatever +resizing calculations are needed explicitly. + + + +If the geometry manager disallows the request, +the widget cannot change its geometry. +The values pointed to by geometry_return are undefined, +and the geometry manager returns +XtGeometryNo. + + + +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 +geometry_return with the actual changes +it is willing to make, including an appropriate request_mode mask, and returns +XtGeometryAlmost. +If a bit in geometry_return->request_mode is zero, +the geometry manager agrees not to change the corresponding value +if geometry_return is used immediately +in a new request. +If a bit is 1, +the geometry manager does change that element to the corresponding +value in geometry_return. +More bits may be set in geometry_return->request_mode +than in the original request if +the geometry manager intends to change other fields should the +child accept the compromise. + + + +When +XtGeometryAlmost +is returned, +the widget must decide if the compromise suggested in geometry_return +is acceptable. +If it is, the widget must not change its geometry directly; +rather, it must make another call to +. + + + +If the next geometry request from this child uses the +geometry_return values filled in by the geometry manager with an +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 +XtGeometryYes. +However, +dynamic behavior in +the user's window manager may affect the final outcome. + + + +To return +XtGeometryYes, +the geometry manager frequently rearranges the position of other managed +children by calling +. +However, a few geometry managers may sometimes change the +size of other managed children by calling + +or +. +If +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. + + + +Geometry managers must not assume that the request +and geometry_return 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. + + + + +Widget Placement and Sizing + +To move a sibling widget of the child making the geometry request, +the parent uses +. + + + + +void XtMoveWidget + Widget w + Position x + Position y + + + + + + + w + + + +Specifies the widget. Must be of class RectObj or any subclass thereof. + + + + + + x + + + + + + + + y + + + +Specify the new widget x and y coordinates. + + + + + + +The + +function returns immediately if the specified geometry fields +are the same as the old values. +Otherwise, + +writes the new x and y values into the object +and, if the object is a widget and is realized, issues an Xlib +XMoveWindow +call on the widget's window. + + + +To resize a sibling widget of the child making the geometry request, +the parent uses +. + + + + +void XtResizeWidget + Widget w + Dimension width + Dimension height + Dimension border_width + + + + + + + w + + + +Specifies the widget. Must be of class RectObj or any subclass thereof. + + + + + + width + + + + + + + + height + + + + + + + + border_width + + + +Specify the new widget size. + + + + + + +The + +function returns immediately if the specified geometry fields +are the same as the old values. +Otherwise, + +writes the new width, height, and border_width values into +the object and, if the object is a widget and is realized, issues an +XConfigureWindow +call on the widget's window. + + + +If the new width or height is different from the old values, + +calls the object's resize procedure to notify it of the size change. + + + +To move and resize the sibling widget of the child making the geometry request, +the parent uses +. + + + + +void XtConfigureWidget + Widget w + Position x + Position y + Dimension width + Dimension height + Dimension border_width + + + + + + + w + + + +Specifies the widget. Must be of class RectObj or any subclass thereof. + + + + + + x + + + + + + + + y + + + +Specify the new widget x and y coordinates. + + + + + + width + + + + + + + + height + + + + + + + + border_width + + + +Specify the new widget size. + + + + + + +The + +function returns immediately if the specified new geometry fields +are all equal to the current values. +Otherwise, + +writes the new x, y, width, height, +and border_width values +into the object and, if the object is a widget and is realized, makes an Xlib +XConfigureWindow +call on the widget's window. + + + +If the new width or height is different from its old value, + +calls the object's resize procedure to notify it of the size change; +otherwise, it simply returns. + + + +To resize a child widget that already has the new values of its width, +height, and border width, the parent uses +. + + + + +void XtResizeWindow + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + +The + +function calls the +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. + + + +There are very few times to use +; +instead, the parent should use +. + + + + +Preferred Geometry + +Some parents may be willing to adjust their layouts to accommodate the +preferred geometries of their children. +They can use + +to obtain the preferred geometry +and, as they see fit, can use or ignore any portion of the response. + + + +To query a child widget's preferred geometry, use +. + + + + +XtGeometryResult XtQueryGeometry + Widget w + XtWidgetGeometry *intended + XtWidgetGeometry *preferred_return + + + + + + + w + + + +Specifies the widget. Must be of class RectObj or any subclass thereof. + + + + + + intended + + + +Specifies the new geometry the parent plans to give to the child, or +NULL. + + + + + + preferred_return + + + +Returns the child widget's preferred geometry. + + + + + + +To discover a child's preferred geometry, +the child's parent stores the new +geometry in the corresponding fields of +the intended structure, sets the corresponding bits in intended.request_mode, +and calls +. +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. + + + + +clears all bits in the preferred_return->request_mode +field and checks the +query_geometry field of the specified widget's class record. +If query_geometry is not NULL, + +calls the query_geometry procedure and passes as arguments the +specified widget, intended, and preferred_return structures. +If the intended argument is NULL, + +replaces it with a pointer to an +XtWidgetGeometry +structure with request_mode equal to zero before calling the +query_geometry procedure. + + + + +If + +is called from within a geometry_manager +procedure for the widget that issued + +or +, +the results +are not guaranteed to be consistent with the requested changes. The +change request passed to the geometry manager takes precedence over +the preferred geometry. + + + + +The query_geometry procedure pointer is of type +. + + + + +typedef XtGeometryResult (*XtGeometryHandler) + Widget w + XtWidgetGeometry *request + XtWidgetGeometry *preferred_return + + + + + + + w + + + +Passes the child widget whose preferred geometry is required. + + + + + + request + + + +Passes the geometry changes that the parent plans to make. + + + + + + preferred_return + + + +Passes a structure in which the child returns its preferred geometry. + + + + + + +The query_geometry procedure is expected to examine the bits set in +request->request_mode, evaluate the preferred geometry of the widget, +and store the result in preferred_return +(setting the bits in preferred_return->request_mode corresponding +to those geometry fields that it cares about). +If the proposed geometry change is acceptable without modification, +the query_geometry procedure should return +XtGeometryYes. +If at least one field in preferred_return +with a bit set in preferred_return->request_mode +is different +from the corresponding field in request +or if a bit was set in preferred_return->request_mode +that was not set in the request, +the query_geometry procedure should return +XtGeometryAlmost. +If the preferred geometry is identical to the current geometry, +the query_geometry procedure should return +XtGeometryNo. + + + +The query_geometry procedure may assume +that no + +or + +is in progress +for the specified widget; that is, it is not required to construct +a reply consistent with the requested geometry if such a request +were actually outstanding. + + + +After calling the query_geometry procedure +or if the query_geometry field is NULL, + +examines all the unset bits in preferred_return->request_mode +and sets the corresponding fields in preferred_return +to the current values from the widget instance. +If +CWStackMode +is not set, +the stack_mode field is set to +XtSMDontChange. + +returns the value returned by the query_geometry procedure or +XtGeometryYes +if the query_geometry field is NULL. + + + +Therefore, the caller can interpret a return of +XtGeometryYes +as not needing to evaluate the contents of the reply and, more important, +not needing to modify its layout plans. +A return of +XtGeometryAlmost +means either that both the parent and the child expressed interest +in at least one common field and the child's preference does not match +the parent's intentions or that the child expressed interest in a field that +the parent might need to consider. +A return value of +XtGeometryNo +means that both the parent and the child expressed interest in a field and +that the child suggests that the field's current value 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 preferred_return structure contains complete +geometry information for the child. + + + +Parents are expected to call + +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. + + + + +Size Change Management: The resize Procedure + +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 +, +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 +. + + + +If a class need not recalculate anything when a widget is resized, +it can specify NULL for the resize field in its class record. +This is an unusual case and should occur only for widgets +with very trivial display semantics. +The resize procedure takes a widget as its only argument. +The x, y, width, height, +and border_width 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 + +or + +call from its resize procedure. + + + diff --git a/libXt/specs/CH07 b/libXt/specs/CH07 deleted file mode 100644 index 07b36746b..000000000 --- a/libXt/specs/CH07 +++ /dev/null @@ -1,3555 +0,0 @@ -.\" $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 -#define XtExposeCompressMaximal -.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 -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/libXt/specs/CH07.xml b/libXt/specs/CH07.xml new file mode 100644 index 000000000..7ea72596e --- /dev/null +++ b/libXt/specs/CH07.xml @@ -0,0 +1,4989 @@ + +Event Management + +While Xlib allows the reading and processing of events anywhere in an application, +widgets in the X Toolkit 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. + + + +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 Intrinsics is +. + + + +The event manager is a collection of functions to perform the following tasks: + + + + +Add or remove event sources other than X server events (in particular, +timer interrupts, file input, or POSIX signals). + + + + +Query the status of event sources. + + + + +Add or remove procedures to be called when an event occurs for a particular +widget. + + + + +Enable and +disable the dispatching of user-initiated events (keyboard and pointer events) +for a particular widget. + + + + +Constrain the dispatching of events to a cascade of pop-up widgets. + + + + +Register procedures to be called when specific events arrive. + + + + +Register procedures to be called when the Intrinsics will block. + + + + +Enable safe operation in a multi-threaded environment. + + + + +Most widgets do not need to call any of the event handler functions explicitly. +The normal interface to X events is through the higher-level +translation manager, +which maps sequences of X events, with modifiers, into procedure calls. +Applications rarely use any of the event manager routines besides +. + + +Adding and Deleting Additional Event Sources + +While most applications are driven only by X events, +some applications need to incorporate other sources of input +into the Intrinsics event-handling mechanism. +The event manager provides routines to integrate notification of timer events +and file data pending into this mechanism. + + + +The next section describes functions that provide input gathering from files. +The application registers the files with the Intrinsics read routine. +When input is pending on one of the files, +the registered callback procedures are invoked. + + +Adding and Removing Input Sources + +To register a new file as an input source for a given application context, use +. + + + + +XtInputId XtAppAddInput + XtAppContext app_context + int source + XtPointer condition + XtInputCallbackProc proc + XtPointer client_data + + + + + + + app_context + + + +Specifies the application context that identifies the application. + + + + + + source + + + +Specifies the source file descriptor on a POSIX-based system +or other operating-system-dependent device specification. + + + + + + condition + + + +Specifies the mask that indicates a read, write, or exception condition +or some other operating-system-dependent condition. + + + + + + proc + + + +Specifies the procedure to be called when the condition is found. + + + + + + client_data + + + +Specifies an argument passed to the specified procedure +when it is called. + + + + + + +The + +function registers with the Intrinsics read routine a new source of events, +which is usually file input but can also be file output. +Note that file should be loosely interpreted to mean any sink +or source of data. + +also specifies the conditions under which the source can generate events. +When an event is pending on this source, +the callback procedure is called. + + + +The legal values for the condition argument are operating-system-dependent. +On a POSIX-based system, +source is a file number and the condition is some union of the following: + + + + XtInputReadMask + + + +Specifies that proc is to be called when source has data to be read. + + + + + + XtInputWriteMask + + + +Specifies that proc is to be called when source is ready +for writing. + + + + + + XtInputExceptMask + + + +Specifies that proc is to be called when source has +exception data. + + + + + + + +Callback procedure pointers used to handle file events are of +type +. + + + + +typedef void (*XtInputCallbackProc) + XtPointer client_data + int *source + XtInputId *id + + + + + + + client_data + + + +Passes the client data argument that was registered for this procedure in +XtApp\%AddInput. + + + + + + source + + + +Passes the source file descriptor generating the event. + + + + + + id + + + +Passes the id returned from the corresponding + +call. + + + + + + +See +for information regarding the use of + +in multiple threads. + + + +To discontinue a source of input, use +. + + + + +void XtRemoveInput + XtInputId id + + + + + + + id + + + +Specifies the id returned from the corresponding + +call. + + + + + + +The + +function causes the Intrinsics read routine to stop watching for events +from the file source specified by id. + + + +See +for information regarding the use of + +in multiple threads. + + + + +Adding and Removing Blocking Notifications + +Occasionally it is desirable for an application to receive notification +when the Intrinsics event manager detects no pending input from file sources +and no pending input from X server event sources and is about to block +in an operating system call. + + + +To register a hook that is called immediately prior to event blocking, use +. + + + + +XtBlockHookId XtAppAddBlockHook + XtAppContext app_context + XtBlockHookProc proc + XtPointer client_data + + + + + + + app_context + + + +Specifies the application context that identifies the application. + + + + + + proc + + + +Specifies the procedure to be called before blocking. + + + + + + client_data + + + +Specifies an argument passed to the specified procedure when it is called. + + + + + + +The + +function registers the specified procedure and returns an identifier for it. +The hook procedure proc is called at any time in the future when +the Intrinsics are about to block pending some input. + + + +The procedure pointers used to provide notification of event blocking +are of type +. + + + + +void *XtBlockHookProc + XtPointer client_data + + + + + + + client_data + + + +Passes the client data argument that was registered for this procedure in +XtApp\%AddBlockHook. + + + + + + +To discontinue the use of a procedure for blocking notification, use +. + + + + +void XtRemoveBlockHook + XtBlockHookId id + + + + + + + id + + + +Specifies the identifier returned from the corresponding call to +. + + + + + + +The + +function removes the specified procedure from the list of procedures +that are called by the Intrinsics read routine before blocking on event sources. + + + + +Adding and Removing Timeouts + +The timeout facility notifies the application or the widget +through a callback procedure that a specified time interval has elapsed. +Timeout values are uniquely identified by an interval id. + + + +To register a timeout callback, use +. + + + + +XtIntervalId XtAppAddTimeOut + XtAppContext app_context + unsigned long interval + XtTimerCallbackProc proc + XtPointer client_data + + + + + + + app_context + + + +Specifies the application context for which the timer is to be set. + + + + + + interval + + + +Specifies the time interval in milliseconds. + + + + + + proc + + + +Specifies the procedure to be called when the time expires. + + + + + + client_data + + + +Specifies an argument passed to the specified procedure +when it is called. + + + + + + +The + +function creates a timeout and returns an identifier for it. +The timeout value is set to interval. +The callback procedure proc is called when + +or + +is next called after the time interval elapses, +and then the timeout is removed. + + + +Callback procedure pointers used with timeouts are of +type +. + + + + +void *XtTimerCallbackProc + XtPointer client_data + XtIntervalId *timer + + + + + + + client_data + + + +Passes the client data argument that was registered for this procedure in +XtApp\%AddTimeOut. + + + + + + timer + + + +Passes the id returned from the corresponding + +call. + + + + + + +See +for information regarding the use of + +in multiple threads. + + + +To clear a timeout value, use +. + + + + +void XtRemoveTimeOut + XtIntervalId timer + + + + + + + timer + + + +Specifies the id for the timeout request to be cleared. + + + + + + +The + +function removes the pending timeout. +Note that timeouts are automatically removed once they trigger. + + + +Please refer to Section 7.12 for information regarding the use of + +in multiple threads. + + + + +Adding and Removing Signal Callbacks + +The signal facility notifies the application or the widget through a +callback procedure that a signal or other external asynchronous event +has occurred. The registered callback procedures are uniquely identified +by a signal id. + + + +Prior to establishing a signal handler, the application or widget should +call + +and store the resulting identifier in a place accessible to the signal +handler. When a signal arrives, the signal handler should call + +to notify the Intrinsics that a signal has occured. To register a signal +callback use +. + + + + +XtSignalId XtAppAddSignal + XtAppContext app_context + XtSignalCallbackProc proc + XtPointer client_data + + + + + + + app_context + + + +Specifies the application context that identifies the application. + + + + + + proc + + + +Specifies the procedure to be called when the signal is noticed. + + + + + + client_data + + + +Specifies an argument passed to the specified procedure when it is called. + + + + + + +The callback procedure pointers used to handle signal events are of type +. + + + + +typedef void (*XtSignalCallbackProc) + XtPointer client_data + XtSignalId *id + + + + + + + client_data + + + +Passes the client data argument that was registered for this procedure in +. + + + + + + id + + + +Passes the id returned from the corresponding + +call. + + + + + + +To notify the Intrinsics that a signal has occured, use +. + + + + +void XtNoticeSignal + XtSignalId id + + + + + + + id + + + +Specifies the id returned from the corresponding + +call. + + + + + + +On a POSIX-based system, + +is the only Intrinsics function that can safely be called from a signal handler. +If + +is invoked multiple times before the Intrinsics are able to invoke the +registered callback, the callback is only called once. +Logically, the Intrinsics maintain ``pending'' flag for each registered callback. +This flag is initially +False +and is set to +True +by +. +When + +or + +(with a mask including +XtIMSignal) +is called, all registered callbacks with ``pending'' +True +are invoked and the flags are reset to +False. + + + +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 Intrinsics never block signals from being raised, so if a given +signal can be raised multiple times before the Intrinsics can invoke the +callback for that signal, the callback must be designed to deal with +this. In another case, a signal might be raised just after the Intrinsics +sets the pending flag to +False +but before the callback can get control, in which case the pending flag +will still be +True +after the callback returns, and the Intrinsics 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. + + + +To remove a registered signal callback, call +. + + + + +void XtRemoveSignal + XtSignalId id + + + + + + + id + + + +Specifies the id returned by the corresponding call to +. + + + + + + +The client should typically disable the source of the signal before calling +. +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 + +the client can test for signals with + +and process them by calling + +with the mask +XtIMSignal. + + + + + +Constraining Events to a Cascade of Widgets + +Modal widgets are widgets that, except for the input directed to them, +lock out user input to the application. + + + +When a modal menu or modal dialog box is popped up using +, +user events (keyboard and pointer events) that occur outside the modal +widget should be delivered to the modal widget or ignored. +In no case will user events be delivered to a widget outside +the modal widget. + + + +Menus can pop up submenus, and dialog boxes can pop up further dialog +boxes to create a pop-up cascade. +In this case, +user events may be delivered to one of several modal widgets in the cascade. + + + +Display-related events should be delivered outside the modal cascade so that +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 +KeyPress, +KeyRelease, +ButtonPress, +and +ButtonRelease. +The user events ignored when they occur outside the cascade are +MotionNotify +and +EnterNotify. +All other events are delivered normally. +In particular, note that this is one +way in which widgets can receive +LeaveNotify +events without first receiving +EnterNotify +events; they should be prepared to deal with +this, typically by ignoring any unmatched +LeaveNotify +events. + + + + +uses the + +and + +functions to constrain user events to a modal cascade +and subsequently to remove a grab when the modal widget is popped down. + + + +To constrain or redirect user input to a modal widget, use +. + + + + +void XtAddGrab + Widget w + Boolean exclusive + Boolean spring_loaded + + + + + + + w + + + +Specifies the widget to add to the modal cascade. Must be of class Core or any subclass thereof. + + + + + + exclusive + + + +Specifies whether user events should be dispatched exclusively to this widget +or also to previous widgets in the cascade. + + + + + + spring_loaded + + + +Specifies whether this widget was popped up because the user pressed +a pointer button. + + + + + + +The + +function appends the widget to the modal cascade +and checks that exclusive is +True +if spring_loaded is +True. +If this condition is not met, + +generates a warning message. + + + +The modal cascade is used by + +when it tries to dispatch a user event. +When at least one modal widget is in the widget cascade, + +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 exclusive parameter +True. + + + +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 exclusive +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 exclusive +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. + + + +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 spring_loaded +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 Intrinsics do not modify +the contents of the event. + + + +To remove the redirection of user input to a modal widget, use +. + + + + +void XtRemoveGrab + Widget w + + + + + + + w + + + +Specifies the widget to remove from the modal cascade. + + + + + + +The + +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. + + +Requesting Key and Button Grabs + +The Intrinsics provide a set of key and button grab interfaces that +are parallel to those provided by Xlib and that allow the Intrinsics +to modify event dispatching when necessary. X Toolkit applications and +widgets that need to passively grab keys or buttons or actively grab +the keyboard or pointer should use the +following Intrinsics routines rather than the corresponding Xlib +routines. + + + +To passively grab a single key of the keyboard, use +. + + + + +void XtGrabKey + Widget widget + KeyCode keycode + Modifiers modifiers + Boolean owner_events + int pointer_mode + + + + + + + widget + + + +Specifies the widget in whose window the key is to be grabbed. Must be of class Core or any subclass thereof. + + + + + + keycode + + + modifiers + + + owner_events + + + pointer_mode + + + keyboard_mode + + + +Specify arguments to +XGrabKey; +see Section 12.2 +in Xlib — C Language X Interface. + + + + + + + + +calls +XGrabKey +specifying the widget's window as the grab +window if the widget is realized. The remaining arguments are exactly +as for +XGrabKey. +If the widget is not realized, or is later unrealized, the call to +XGrabKey +is performed (again) when +the widget is realized and its window becomes mapped. In the future, +if + +is called with a +KeyPress +event matching the specified keycode and modifiers (which may be +AnyKey +or +AnyModifier, +respectively) for the +widget's window, the Intrinsics will call + +with the timestamp from the +KeyPress +event if either of the following conditions is true: + + + + +There is a modal cascade and the widget is not in +the active subset of the cascade and the keyboard was not previously +grabbed, or + + + + +XFilterEvent +returns +True. + + + + +To cancel a passive key grab, use +. + + + + +void XtUngrabKey + Widget widget + KeyCode keycode + Modifiers modifiers + + + + + + + widget + + + +Specifies the widget in whose window the key was grabbed. + + + + + + keycode + + + modifiers + + + +Specify arguments to +XUngrabKey; +see Section 12.2 +in Xlib — C Language X Interface. + + + + + + +The + +procedure calls +XUngrabKey +specifying the widget's +window as the ungrab window if the widget is realized. The remaining +arguments are exactly as for +XUngrabKey. +If the widget is not realized, + +removes a deferred + +request, if any, for the specified widget, keycode, and modifiers. + + + +To actively grab the keyboard, use +. + + + + +int XtGrabKeyboard + Widget widget + Boolean owner_events + int pointer_mode + Time time + + + + + + + widget + + + +Specifies the widget for whose window the keyboard is to be grabbed. +Must be of class Core or any subclass thereof. + + + + + + owner_events + + + pointer_mode + + + keyboard_mode + + + time + + + +Specify arguments to +XGrabKeyboard; +see Section 12.2 +in Xlib — C Language X Interface. + + + + + + +If the specified widget is realized, + +calls +XGrabKeyboard +specifying the widget's window as the grab window. The remaining +arguments and return value are exactly as for +XGrabKeyboard. +If the widget is not realized, + +immediately returns +GrabNotViewable. +No future automatic ungrab is implied by +. + + + +To cancel an active keyboard grab, use +. + + + + +void XtUngrabKeyboard + Widget widget + Time time + + + + + + + widget + + + +Specifies the widget that has the active keyboard grab. + + + + + + time + + + +Specifies the additional argument to +XUngrabKeyboard; +see Section 12.2 +in Xlib — C Language X Interface. + + + + + + + +calls +XUngrabKeyboard +with the specified time. + + + +To passively grab a single pointer button, use +. + + + + +void XtGrabButton + Widget widget + int button + Modifiers modifiers + Boolean owner_events + unsigned int event_mask + int pointer_mode + Window confine_to + Cursor cursor + + + + + + + widget + + + +Specifies the widget in whose window the button is to be grabbed. Must be of class Core or any subclass thereof. + + + + + + button + + + modifiers + + + owner_events + + + event_mask + + + pointer_mode + + + keyboard_mode + + + confine_to + + + cursor + + + +Specify arguments to +XGrabButton; +see Section 12.1 +in Xlib — C Language X Interface. + + + + + + + +calls +XGrabButton +specifying the widget's window as the +grab window if the widget is realized. The remaining arguments are +exactly as for +XGrabButton. +If the widget is not realized, or is later unrealized, the call to +XGrabButton +is performed (again) +when the widget is realized and its window becomes mapped. In the +future, if + +is called with a +ButtonPress +event matching the specified button and modifiers (which may be +AnyButton +or +AnyModifier, +respectively) +for the widget's window, the Intrinsics will call + +with the timestamp from the +ButtonPress +event if either of the following conditions is true: + + + + +There is a modal cascade and the +widget is not in the active subset of the cascade and the pointer was +not previously grabbed, or + + + + +XFilterEvent +returns +True. + + + + +To cancel a passive button grab, use +. + + + + +void XtUngrabButton + Widget widget + unsigned int button + Modifiers modifiers + + + + + + + widget + + + +Specifies the widget in whose window the button was grabbed. + + + + + + button + + + modifiers + + + +Specify arguments to +XUngrabButton; +see Section 12.1 +in Xlib — C Language X Interface. + + + + + + +The + +procedure calls +XUngrabButton +specifying the +widget's window as the ungrab window if the widget is realized. The +remaining arguments are exactly as for +XUngrabButton. +If the widget is not realized, + +removes a deferred + +request, if any, for the specified widget, button, and modifiers. + + + +To actively grab the pointer, use +. + + + + +int XtGrabPointer + Widget widget + Boolean owner_events + unsigned int event_mask + int pointer_mode + Window confine_to + Cursor cursor + Time time + + + + + + + widget + + + +Specifies the widget for whose window the pointer is to be grabbed. Must be of class Core or any subclass thereof. + + + + + + owner_events + + + event_mask + + + pointer_mode + + + keyboard_mode + + + confine_to + + + cursor + + + time + + + +Specify arguments to +XGrabPointer; +see Section 12.1 +in Xlib — C Language X Interface. + + + + + + +If the specified widget is realized, + +calls +XGrabPointer, +specifying the widget's window as the grab window. The remaining +arguments and return value are exactly as for +XGrabPointer. +If the widget is not realized, + +immediately returns +GrabNotViewable. +No future automatic ungrab is implied by +. + + + +To cancel an active pointer grab, use +. + + + + +void XtUngrabPointer + Widget widget + Time time + + + + + + + widget + + + +Specifies the widget that has the active pointer grab. + + + + + + time + + + +Specifies the time argument to +XUngrabPointer; +see Section 12.1 +in Xlib — C Language X Interface. + + + + + + + +calls +XUngrabPointer +with the specified time. + + + + + +Focusing Events on a Child + +To redirect keyboard input to a normal descendant of a +widget without calling +XSetInputFocus, +use +. + + + + +void XtSetKeyboardFocus + Widget subtree + + + + + + + subtree + + + +Specifies the subtree of the hierarchy for which the keyboard focus is +to be set. Must be of class Core or any subclass thereof. + + + + + + descendant + + + +Specifies either the normal (non-pop-up) descendant of subtree to which +keyboard events are logically directed, or +None. +It is not an error to specify +None +when no input focus was previously set. Must be of class Object or any subclass thereof. + + + + + + + +causes + +to remap keyboard events occurring within the specified subtree +and dispatch them to the specified descendant widget or to an ancestor. +If the descendant's class is not a subclass of Core, the descendant is +replaced by its closest windowed ancestor. + + + +When there is no modal cascade, keyboard events can be 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). + + + + +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 + +with any value of owner_events, or +if the keyboard is actively grabbed by E with owner_events +False +via + +or + +on a previous key press, the event is dispatched to E. + + + + +Beginning with the ancestor of E closest to the root that has +redirected the keyboard focus or E if no such 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. + + + + + + +If E is the final focus target widget F or a descendant of F, the +event is dispatched to E. + + + + +If E is not F, an ancestor of F, or a descendant of F, and the event +activated a grab for E as specified by a call to + +for E, + +is called. + + + + +If E is an ancestor of F, and the event is a key press, and either + + + + + + +E has grabbed the key with + +and owner_events +False, +or + + + + +E has grabbed the key with + +and owner_events +True, +and the coordinates of the event are outside the rectangle specified +by E's geometry, +then the event is dispatched to E. + + + + + + +Otherwise, define A as the closest common ancestor of E and F: + + + + + + +If there is an active keyboard grab for any widget via either + +or + +on a previous key press, or +if no widget between F and A (noninclusive) has grabbed +the key and modifier combination with + +and any value of owner_events, the event is dispatched to F. + + + + +Else, the event is dispatched to the ancestor of F closest to A +that has grabbed the key and modifier combination with +. + + + + + + + + +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 Intrinsics do not modify +the contents of the event. + + + +When subtree 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 +FocusIn +event is generated for the descendant if +FocusChange +events have been selected by the descendant. +Similarly, when subtree loses the X input focus +or the keyboard focus for one of its ancestors, a +FocusOut +event is generated for descendant if +FocusChange +events have been selected by the descendant. + + + +A widget tree may also actively manage the X server input focus. To +do so, a widget class specifies an accept_focus procedure. + + + +The accept_focus procedure pointer is of type +. + + + + +Boolean *XtAcceptFocusProc + + Widget w + Time *time + + + + + + + w + + + +Specifies the widget. + + + + + + time + + + +Specifies the X time of the event causing the accept focus. + + + + + + +Widgets that need the input focus can call +XSetInputFocus +explicitly, pursuant to the restrictions of the Inter-Client Communication Conventions Manual.. +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 +FocusIn +and +FocusOut +events). +Widgets classes that never want the input focus should set the +accept_focus field to NULL. + + + +To call a widget's accept_focus procedure, use +. + + + + +Boolean XtCallAcceptFocus + Widget w + Time *time + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + time + + + +Specifies the X time of the event that is causing the focus change. + + + + + + +The + +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 accept_focus is NULL, + +returns +False. + + +Events for Drawables That Are Not a Widget's Window + +Sometimes an application must handle events for drawables that are not +associated with widgets in its widget tree. Examples include handling +GraphicsExpose +and +NoExpose +events on Pixmaps, and handling +PropertyNotify +events on the root window. + + + +To register a drawable with the Intrinsics event dispatching, use +. + + + + +void XtRegisterDrawable + Display *display + Drawable drawable + Widget widget + + + + + + + display + + + +Specifies the drawable's display. + + + + + + drawable + + + +Specifies the drawable to register. + + + + + + widget + + + +Specifies the widget to register the drawable for. + + + + + + + +associates the specified drawable with the specified widget +so that future calls to + +with the drawable will return the widget. +The default event dispatcher will dispatch future events that +arrive for the drawable to the widget in the same manner as +events that contain the widget's window. + + + +If the drawable is already registered with another widget, or if the +drawable is the window of a widget in the client's widget tree, the +results of calling + +are undefined. + + + +To unregister a drawable with the Intrinsics event dispatching, use +. + + + + +void XtUnregisterDrawable + Display *display + Drawable drawable + + + + + + + display + + + +Specifies the drawable's display. + + + + + + drawable + + + +Specifies the drawable to unregister. + + + + + + + +removes an association created with +. +If the drawable is the window of a widget in the client's widget tree +the results of calling + +are undefined. + + + + + +Querying Event Sources + +The event manager provides several functions to examine and read events +(including file and timer events) that are in the queue. +The next three functions are Intrinsics equivalents of the +XPending, +XPeekEvent, +and +XNextEvent +Xlib calls. + + + +To determine if there are any events on the input queue for a given application, +use +. + + + + +XtInputMask XtAppPending + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context that identifies the application to check. + + + + + + +The + +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 +XtIMXEvent, +XtIMTimer, +XtIMAlternateInput, +and +XtIMSignal +(see +XtAppProcessEvent ). +If there are no events pending, + +flushes the output buffers of each Display in the application context +and returns zero. + + + +To return the event from the head of a given application's input queue +without removing input from the queue, use +. + + + + +Boolean XtAppPeekEvent + XtAppContext app_context + XEvent *event_return + + + + + + + app_context + + + +Specifies the application context that identifies the application. + + + + + + event_return + + + +Returns the event information to the specified event structure. + + + + + + +If there is an X event in the queue, + +copies it into event_return and returns +True. +If no X input is on the queue, + +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, + +fills in event_return and returns +True. +Otherwise, the input is for an input source +registered with +, +and + +returns +False. +The sample implementations provides XtAppPeekEvent as described. Timeout callbacks +are called while blocking for input. If some input for an input source is +available, + +will return +True +without returning an event. + + + +To remove and return the event +from the head of a given application's X event queue, +use +. + + + + +void XtAppNextEvent + XtAppContext app_context + XEvent *event_return + + + + + + + app_context + + + +Specifies the application context that identifies the application. + + + + + + event_return + + + +Returns the event information to the specified event structure. + + + + + + +If the X event queue is empty, + +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 . + + + + +Dispatching Events + +The Intrinsics provide functions that dispatch events +to widgets or other application code. +Every client interested in X events on a widget uses + +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 . + + + +Applications that need direct control of the processing of different types +of input should use +. + + + + +void XtAppProcessEvent + XtAppContext app_context + XtInputMask mask + + + + + + + app_context + + + +Specifies the application context that identifies the +application for which to process input. + + + + + + mask + + + +Specifies what types of events to process. +The mask is the bitwise inclusive OR of any combination of +XtIMXEvent, +XtIMTimer, +XtIMAlternateInput, +and +XtIMSignal. +As a convenience, +Intrinsic.h +defines the symbolic name +XtIMAll +to be the bitwise inclusive OR of these four event types. + + + + + + +The + +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 + +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 +. + +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 +. + + + +When an X event is received, +it is passed to +, +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. + + + +To dispatch an event returned by +, +retrieved directly from the Xlib queue, or synthetically constructed, +to any registered event filters or event handlers, call +. + + + + +Boolean XtDispatchEvent + XEvent *event + + + + + + + event + + + +Specifies a pointer to the event structure to be dispatched +to the appropriate event handlers. + + + + + + +The + +function first calls +XFilterEvent +with the event and the window of the widget to which the +Intrinsics intend to dispatch the event, or the event window if +the Intrinsics would not dispatch the event to any handlers. +If +XFilterEvent +returns +True +and the event activated a server grab as identified +by a previous call to + +or +, + +calls + +or + +with the timestamp from the event and immediately returns +True. +If +XFilterEvent +returns +True +and a grab was not activated, + +just immediately returns +True. +Otherwise, + +sends the event to the event handler functions that +have been previously registered with the dispatch routine. + +returns +True +if +XFilterEvent +returned +True, +or if the event was dispatched to some handler, and +False +if it found no handler to which to dispatch the event. + +records the last timestamp in any event that +contains a timestamp (see +XtLastTimestampProcessed ), +regardless of whether it was filtered or dispatched. +If a modal cascade is active with spring_loaded +True, +and if the event is a remap event as defined by +, + +may dispatch the event a second time. If it does so, + +will call +XFilterEvent +again with the window of the spring-loaded widget prior to the second +dispatch, and if +XFilterEvent +returns +True, +the second dispatch will not be performed. + + + + +The Application Input Loop + +To process all input from a given application in a continuous loop, +use the convenience procedure +. + + + + +void XtAppMainLoop + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context that identifies the application. + + + + + + +The + +function first reads the next incoming X event by calling + +and then dispatches the event to the appropriate registered procedure +by calling +. +This constitutes the main loop of X Toolkit applications. +There is nothing special about +; +it simply calls + +and then + +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 + +and +. + + + +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 +. + + + + +Setting and Checking the Sensitivity State of a Widget + +Many widgets have a mode in which they assume a different appearance +(for example, are grayed out or stippled), do not respond to user events, +and become dormant. + + + +When dormant, +a widget is considered to be insensitive. +If a widget is insensitive, +the event manager does not dispatch any events to the widget +with an event type of +KeyPress, +KeyRelease, +ButtonPress, +ButtonRelease, +MotionNotify, +EnterNotify, +LeaveNotify, +FocusIn, +or +FocusOut. + + + +A widget can be insensitive because its sensitive field is +False +or because one of its ancestors is insensitive and thus the widget's +ancestor_sensitive field also is +False. +A widget can but does not need to distinguish these two cases visually. + + + + +Pop-up shells will have +ancestor_sensitive +False +if the parent was insensitive when the shell +was created. Since + +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. + + + + +To set the sensitivity state of a widget, use +. + + + + +void XtSetSensitive + Widget w + Boolean sensitive + + + + + + + w + + + +Specifies the widget. Must be of class RectObj or any subclass thereof. + + + + + + sensitive + + + +Specifies whether the widget should receive +keyboard, pointer, and focus events. + + + + + + +The + +function first calls + +on the current widget with an argument list specifying the +XtNsensitive resource and the new value. +If sensitive is +False +and the widget's class is a subclass of +Composite, + +recursively propagates the new value +down the child tree by calling + +on each child to set ancestor_sensitive to +False. +If sensitive is +True +and the widget's class is a subclass of +Composite +and the widget's ancestor_sensitive field is +True, + +sets the ancestor_sensitive of each child to +True +and then recursively calls + +on each normal descendant that is now sensitive to set +ancestor_sensitive to +True. + + + + +calls + +to change the sensitive and ancestor_sensitive 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). + + + + +maintains the invariant that, if the parent has either sensitive +or ancestor_sensitive +False, +then all children have ancestor_sensitive +False. + + + +To check the current sensitivity state of a widget, +use +. + + + + +Boolean XtIsSensitive + Widget w + + + + + + + w + + + +Specifies the object. Must be of class Object or any subclass thereof. + + + + + + +The + +function returns +True +or +False +to indicate whether user input events are being dispatched. +If object's class is a subclass of RectObj and +both sensitive and ancestor_sensitive are +True, + +returns +True; +otherwise, it returns +False. + + + + +Adding Background Work Procedures + +The Intrinsics 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 + +or +. +Work procedure pointers are of type +. + + + + +typedef Boolean (*XtWorkProc) + + XtPointer client_data + + + + + + + client_data + + + +Passes the client data specified when the work procedure was registered. + + + + + + +This procedure should return +True +when it is done to indicate that it +should be removed. +If the procedure returns +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. + + + +To register a work procedure for a given application, use +. + + + + +XtWorkProcId XtAppAddWorkProc + XtAppContext app_context + XtWorkProc proc + XtPointer client_data + + + + + + + app_context + + + +Specifies the application context that identifies the application. + + + + + + proc + + + +Specifies the procedure to be called when the application is idle. + + + + + + client_data + + + +Specifies the argument passed to the specified procedure +when it is called. + + + + + + +The + +function adds the specified work procedure for the application identified +by app_context +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. + + + +To remove a work procedure, either return +True +from the procedure when it is called or use + +outside of the procedure. + + + + +void XtRemoveWorkProc + XtWorkProcId id + + + + + + + id + + + +Specifies which work procedure to remove. + + + + + + +The + +function explicitly removes the specified background work procedure. + + + + +X Event Filters + +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. + + +Pointer Motion Compression + +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 compress_motion should be +True. +When a request for an event would return a motion event, +the Intrinsics check if there are any other motion events +for the same widget immediately +following the current one and, if so, skip all but the last of them. + + + + +Enter/Leave Compression + +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 compress_enterleave should be +True. +These enter and leave events are not delivered to the client +if they are found together in the input queue. + + + + +Exposure Compression + +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. + + + +In either case, these widgets do not care about getting partial exposure events. +The compress_exposure field in the widget class +structure specifies the type and number of exposure events that are +dispatched to the widget's expose procedure. This field must be +initialized to one of the following values: + + + +#define XtExposeNoCompress ((XtEnum)False) +#define XtExposeCompressSeries ((XtEnum)True) +#define XtExposeCompressMultiple <implementation-defined> +#define XtExposeCompressMaximal <implementation-defined> + + + +optionally ORed with any combination of the following flags (all with +implementation-defined values): +XtExposeGraphicsExpose, +XtExposeGraphicsExposeMerged, +XtExposeNoExpose, +and +XtExposeNoRegion. + + + +If the compress_exposure field in the widget class structure does not +specify +XtExposeNoCompress, +the event manager calls the widget's expose procedure only +once for a series of exposure events. +In this case, all +Expose +or +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 +XtExposeNoRegion +is specified) the region. +For more information on regions, see +Section 16.5 in +Xlib — C Language X Interface..) + + + +The values have the following interpretation: + + + +XtExposeNoCompress + + + + +No exposure compression is performed; every selected event is +individually dispatched to the expose procedure with a region +argument of NULL. + + + + +XtExposeCompressSeries + + + + +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. + + + + +XtExposeCompressMultiple + + + + +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. + + + + +XtExposeCompressMaximal + + + + +All expose series currently in the queue for the widget +are coalesced into a single +event without regard to intervening nonexposure events. If a +partial series is in the end of the queue, the Intrinsics will +block until the end of the series is received. + + + + +The additional flags have the following meaning: + + + +XtExposeGraphicsExpose + + + + +Specifies that +GraphicsExpose +events are also to be dispatched to +the expose procedure. +GraphicsExpose +events are compressed, if specified, in the same manner as +Expose +events. + + + + +XtExposeGraphicsExposeMerged + + + + +Specifies in the case of +XtExposeCompressMultiple +and +XtExposeCompressMaximal +that series of +GraphicsExpose +and +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 +XtExposeGraphicsExpose. + + + + +XtExposeNoExpose + + + + +Specifies that +NoExpose +events are also to be dispatched to the expose procedure. +NoExpose +events are never coalesced with +other exposure events or with each other. + + + + +XtExposeNoRegion + + + + +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. + + + + + + + +Widget Exposure and Visibility + +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. + + + +Redisplay of a Widget: The expose Procedure + +The expose procedure pointer in a widget class is of type +. + + + + +typedef void (*XtExposeProc) + Widget w + XEvent *event + Region region + + + + + + + w + + + +Specifies the widget instance requiring redisplay. + + + + + + event + + + +Specifies the exposure event giving the rectangle requiring redisplay. + + + + + + region + + + +Specifies the union of all rectangles in this exposure sequence. + + + + + + +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 expose field. +Many composite widgets serve only as containers for their children +and have no expose procedure. + + + + +If the expose procedure is NULL, + +fills in a default bit gravity of +NorthWestGravity +before it calls the widget's realize procedure. + + + + +If the widget's compress_exposure class field specifies +XtExposeNoCompress +or +XtExposeNoRegion, +or if the event type is +NoExpose +(see ), +region is NULL. If +XtExposeNoCompress +is not specified and the event type is not +NoExpose, +the event is the final event in the compressed series +but x, y, width, and height contain +the bounding box for all the compressed events. +The region is created and destroyed by the Intrinsics, but +the widget is permitted to modify the region contents. + + + +A small simple widget (for example, Label) can ignore the bounding box +information in the event and redisplay the entire window. +A more complicated widget (for example, Text) can use the bounding box +information to minimize the amount of calculation and redisplay it does. +A very complex widget uses the region as a clip list in a GC and +ignores the event information. +The expose procedure is not chained and is therefore +responsible for exposure of all superclass data +as well as its own. + + + +However, +it often is possible to anticipate the display needs of several levels +of subclassing. +For example, rather than implement separate display procedures for +the widgets Label, Pushbutton, and Toggle, +you could write a single display routine in Label that uses display state +fields like + + +Boolean invert; +Boolean highlight; +Dimension highlight_width; + + +Label would have invert and highlight always +False +and highlight_width zero. +Pushbutton would dynamically set highlight and highlight_width, +but it would leave invert always +False. +Finally, Toggle would dynamically set all three. +In this case, +the expose procedures for Pushbutton and Toggle inherit +their superclass's expose procedure; +see . + + + + +Widget Visibility + +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. + + + +The visible 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 +True +by the time an +exposure +event is processed if any part of the widget is visible, +but is +False +if the widget is fully obscured. + + + +Widgets can use or ignore the visible hint. +If they ignore it, +they should have visible_interest in their widget class record set +False. +In such cases, +the visible field is initialized +True +and never changes. +If visible_interest is +True, +the event manager asks for +VisibilityNotify +events for the widget and sets visible to +True +on +VisibilityUnobscured +or +VisibilityPartiallyObscured +events and +False +on +VisibilityFullyObscured +events. + + + + + +X Event Handlers + +Event handlers are procedures called when specified events +occur in a widget. +Most widgets need not use event handlers explicitly. +Instead, they use the Intrinsics translation manager. +Event handler procedure pointers are of the type +. + + + + +typedef void (*XtEventHandler) + + Widget w + XtPointer client_data + XEvent *event + Boolean *continue_to_dispatch + + + + + + + w + + + +Specifies the widget for which the event arrived. + + + + + + client_data + + + +Specifies any client-specific information registered with the event handler. + + + + + + event + + + +Specifies the triggering event. + + + + + + continue_to_dispatch + + + +Specifies whether the remaining event +handlers registered for the current event +should be called. + + + + + + +After receiving an event and before calling any event handlers, the +Boolean pointed to by continue_to_dispatch is initialized to +True. +When an event handler is called, it may decide that further processing +of the event is not desirable and may store +False +in this Boolean, in +which case any handlers remaining to be called for the event are +ignored. + + + +The circumstances under which the Intrinsics may add event handlers +to a widget are currently implementation-dependent. Clients must +therefore be aware that storing +False +into the continue_to_dispatch argument can lead to portability problems. + + +Event Handlers That Select Events + +To register an event handler procedure with the dispatch mechanism, use +. + + + + +void XtAddEventHandler + Widget w + EventMask event_mask + Boolean nonmaskable + XtEventHandler proc + XtPointer client_data + + + + + + + w + + + +Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. + + + + + + event_mask + + + +Specifies the event mask for which to call this procedure. + + + + + + nonmaskable + + + +Specifies whether this procedure should be +called on the nonmaskable events +( GraphicsExpose, +NoExpose, +SelectionClear, +SelectionRequest, +SelectionNotify, +ClientMessage, +and +MappingNotify ). + + + + + + proc + + + +Specifies the procedure to be called. + + + + + + client_data + + + +Specifies additional data to be passed to the event handler. + + + + + + +The + +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 client_data +value, +the specified mask augments the existing mask. +If the widget is realized, + +calls +XSelectInput, +if necessary. +The order in which this procedure is called relative to other handlers +registered for the same event is not defined. + + + +To remove a previously registered event handler, use +. + + + + +void XtRemoveEventHandler + Widget w + EventMask event_mask + Boolean nonmaskable + XtEventHandler proc + XtPointer client_data + + + + + + + w + + + +Specifies the widget for which this procedure is registered. Must be of class Core or any subclass thereof. + + + + + + event_mask + + + +Specifies the event mask for which to unregister this procedure. + + + + + + nonmaskable + + + +Specifies whether this procedure should be +removed on the nonmaskable events +( GraphicsExpose, +NoExpose, +SelectionClear, +SelectionRequest, +SelectionNotify, +ClientMessage, +and +MappingNotify ). + + + + + + proc + + + +Specifies the procedure to be removed. + + + + + + client_data + + + +Specifies the registered client data. + + + + + + +The + +function unregisters an event handler registered with + +or + +for the specified events. +The request is ignored if client_data does not match the value given +when the handler was registered. +If the widget is realized and no other event handler requires the event, + +calls +XSelectInput. +If the specified procedure has not been registered +or if it has been registered with a different value of client_data, + +returns without reporting an error. + + + +To stop a procedure registered with + +or + +from receiving all selected events, call + +with an event_mask of +XtAllEvents +and nonmaskable +True. +The procedure will continue to receive any events +that have been specified in calls to + +or +. + + + +To register an event handler procedure that receives events before or +after all previously registered event handlers, use +. + + +typedef enum {XtListHead, XtListTail} XtListPosition; + + + + +void XtInsertEventHandler + Widget w + EventMask event_mask + Boolean nonmaskable + XtEventHandler proc + XtPointer client_data + XtListPosition position + + + + + + + w + + + +Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. + + + + + + event_mask + + + +Specifies the event mask for which to call this procedure. + + + + + + nonmaskable + + + +Specifies whether this procedure should be +called on the nonmaskable events +( GraphicsExpose, +NoExpose, +SelectionClear, +SelectionRequest, +SelectionNotify, +ClientMessage, +and +MappingNotify ). + + + + + + proc + + + +Specifies the procedure to be called. + + + + + + client_data + + + +Specifies additional data to be passed to the client's event handler. + + + + + + position + + + +Specifies when the event handler is to be called +relative to other previously registered handlers. + + + + + + + +is identical to + +with the additional position argument. If position is +XtListHead, +the event +handler is registered so that it is called before any event +handlers that were previously registered for the same widget. If +position is +XtListTail, +the event handler is registered to be called +after any previously registered event handlers. If the procedure is +already registered with the same client_data value, the specified mask +augments the existing mask and the procedure is repositioned in +the list. + + + + +Event Handlers That Do Not Select Events + +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 +. + + + + +void XtAddRawEventHandler + Widget w + EventMask event_mask + Boolean nonmaskable + XtEventHandler proc + XtPointer client_data + + + + + + + w + + + +Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. + + + + + + event_mask + + + +Specifies the event mask for which to call this procedure. + + + + + + nonmaskable + + + +Specifies whether this procedure should be +called on the nonmaskable events +( GraphicsExpose, +NoExpose, +SelectionClear, +SelectionRequest, +SelectionNotify, +ClientMessage, +and +MappingNotify ). + + + + + + proc + + + +Specifies the procedure to be called. + + + + + + client_data + + + +Specifies additional data to be passed to the client's event handler. + + + + + + +The + +function is similar to + +except that it does not affect the widget's event mask and never causes an +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 client_data, +the specified mask augments the existing mask. +The order in which this procedure is called relative to other handlers +registered for the same event is not defined. + + + +To remove a previously registered raw event handler, use +. + + + + +void XtRemoveRawEventHandler + Widget w + EventMask event_mask + Boolean nonmaskable + XtEventHandler proc + XtPointer client_data + + + + + + + w + + + +Specifies the widget for which this procedure is registered. Must be of class Core or any subclass thereof. + + + + + + event_mask + + + +Specifies the event mask for which to unregister this procedure. + + + + + + nonmaskable + + + +Specifies whether this procedure should be +removed on the nonmaskable events +( GraphicsExpose, +NoExpose, +SelectionClear, +SelectionRequest, +SelectionNotify, +ClientMessage, +and +MappingNotify ). + + + + + + proc + + + +Specifies the procedure to be registered. + + + + + + client_data + + + +Specifies the registered client data. + + + + + + +The + +function unregisters an event handler registered with + +or + +for the specified events without changing +the window event mask. +The request is ignored if client_data 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 client_data, + +returns without reporting an error. + + + +To stop a procedure +registered with + +or + +from receiving all nonselected events, call + +with an event_mask of +XtAllEvents +and nonmaskable +True. +The procedure +will continue to receive any events that have been specified in calls to + +or +. + + + +To register an event handler procedure that receives events before or +after all previously registered event handlers without selecting for +the events, use +. + + + + +void XtInsertRawEventHandler + Widget w + EventMask event_mask + Boolean nonmaskable + XtEventHandler proc + XtPointer client_data + XtListPosition position + + + + + + + w + + + +Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. + + + + + + event_mask + + + +Specifies the event mask for which to call this procedure. + + + + + + nonmaskable + + + +Specifies whether this procedure should be +called on the nonmaskable events +( GraphicsExpose, +NoExpose, +SelectionClear, +SelectionRequest, +SelectionNotify, +ClientMessage, +and +MappingNotify ). + + + + + + proc + + + +Specifies the procedure to be registered. + + + + + + client_data + + + +Specifies additional data to be passed to the client's event handler. + + + + + + position + + + +Specifies when the event handler is to be called +relative to other previously registered handlers. + + + + + + +The + +function is similar to + +except that it does not modify the widget's event +mask and never causes an +XSelectInput +for the specified events. If +the procedure is already registered with the same client_data +value, the +specified mask augments the existing mask and the procedure is +repositioned in the list. + + + + +Current Event Mask + +To retrieve the event mask for a given widget, use +. + + + + +EventMask XtBuildEventMask + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + +The + +function returns the event mask representing the logical OR +of all event masks for event handlers registered on the widget with + +and + +and all event translations, including accelerators, +installed on the widget. +This is the same event mask stored into the +XSetWindowAttributes +structure by + +and sent to the server when event handlers and translations are installed or +removed on the realized widget. + + + + +Event Handlers for X11 Protocol Extensions + +To register an event handler procedure with the Intrinsics dispatch +mechanism according to an event type, use +. + + + + +void XtInsertEventTypeHandler + Widget widget + int event_type + XtPointer select_data + XtEventHandler proc + XtPointer client_data + XtListPosition position + + + + + + + widget + + + +Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. + + + + + + event_type + + + +Specifies the event type for which to call this event handler. + + + + + + select_data + + + +Specifies data used to request events of the specified type from the server, +or NULL. + + + + + + proc + + + +Specifies the event handler to be called. + + + + + + client_data + + + +Specifies additional data to be passed to the event handler. + + + + + + position + + + +Specifies when the event handler is to be called relative to other +previously registered handlers. + + + + + + + +registers a procedure with the +dispatch mechanism that is to be called when an event that matches the +specified event_type is dispatched to the specified widget. + + + +If event_type specifies one of the core X protocol events, then +select_data must be a pointer to a value of type +EventMask, +indicating +the event mask to be used to select for the desired event. This event +mask is included in the value returned by +. +If the widget is realized, + +calls +XSelectInput +if necessary. Specifying NULL for select_data is equivalent to +specifying a pointer to an event mask containing 0. This is similar +to the + +function. + + + +If event_type specifies an extension event type, then the semantics of +the data pointed to by select_data are defined by the extension +selector registered for the specified event type. + + + +In either case the Intrinsics are not required to copy the data +pointed to by select_data, so the caller must ensure that it remains +valid as long as the event handler remains registered with this value +of select_data. + + + +The position 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 +XtListTail, +which registers this event handler after any previously +registered handlers for this event type. + + + +Each widget has a single registered event handler list, which will +contain any procedure/client_data pair exactly once if it is +registered with +, +regardless of the manner +in which it is registered and regardless of the value(s) +of select_data. If the procedure is already registered with the +same client_data value, the specified mask augments the existing +mask and the procedure is repositioned in the list. + + + +To remove an event handler registered with +, +use +. + + + + +void XtRemoveEventTypeHandler + Widget widget + int event_type + XtPointer select_data + XtEventHandler proc + XtPointer client_data + + + + + + + widget + + + +Specifies the widget for which the event handler was registered. Must be of class Core or any subclass thereof. + + + + + + event_type + + + +Specifies the event type for which the handler was registered. + + + + + + select_data + + + +Specifies data used to deselect events of the specified type +from the server, or NULL. + + + + + + proc + + + +Specifies the event handler to be removed. + + + + + + client_data + + + +Specifies the additional client data with which the procedure was registered. + + + + + + +The + +function unregisters an event handler +registered with + +for the specified event type. +The request is ignored if client_data does not match the value given +when the handler was registered. + + + +If event_type specifies one of the core X protocol events, +select_data must be a pointer to a value of type +EventMask, indicating the event +mask to be used to deselect for the appropriate event. If the widget +is realized, + +calls +XSelectInput +if necessary. +Specifying NULL for select_data is equivalent to specifying a pointer +to an event mask containing 0. This is similar to the + +function. + + + +If event_type specifies an extension event type, then the semantics of +the data pointed to by select_data are defined by the extension +selector registered for the specified event type. + + + +To register a procedure to select extension events for a widget, use +. + + + + +void XtRegisterExtensionSelector + Display *display + int min_event_type + int max_event_type + XtExtensionSelectProc proc + XtPointer client_data + + + + + + + display + + + +Specifies the display for which the extension selector is to be registered. + + + + + + min_event_type + + + + + + + + max_event_type + + + +Specifies the range of event types for the extension. + + + + + + proc + + + +Specifies the extension selector procedure. + + + + + + client_data + + + +Specifies additional data to be passed to the extension selector. + + + + + + +The + +function registers a procedure to arrange +for the delivery of extension events to widgets. + + + +If min_event_type and max_event_type match the parameters +to a previous call to + +for the same display, then proc and client_data +replace the previously +registered values. If the range specified by min_event_type +and max_event_type overlaps the range of the parameters to a +previous call for the same display in any other way, an error results. + + + +When a widget is realized, +after the core.realize method is called, +the Intrinsics check to see if any event +handler specifies an event type within the range of a registered +extension selector. If so, the Intrinsics call each such selector. +If an event type handler is added or removed, the Intrinsics check to +see if the event type falls within the range of a registered extension +selector, and if it does, calls the selector. In either case the Intrinsics +pass a list of all the widget's event types that are within the +selector's range. The corresponding select data are also passed. The +selector is responsible for enabling the delivery of extension events +required by the widget. + + + +An extension selector is of type +. + + + + +typedef void (*XtExtensionSelectProc) + + Widget widget + int *event_types + XtPointer *select_data + int count + XtPointer client_data + + + + + + + widget + + + +Specifies the widget that is being realized or is having +an event handler added or removed. + + + + + + event_types + + + +Specifies a list of event types that the widget has +registered event handlers for. + + + + + + select_data + + + +Specifies a list of the select_data parameters specified in +. + + + + + + count + + + +Specifies the number of entries in the event_types and select_data +lists. + + + + + + client_data + + + +Specifies the additional client data with which the procedure was registered. + + + + + + +The event_types and select_data lists will always have the +same number of elements, specified by count. +Each event type/select data pair represents one call to +. + + + +To register a procedure to dispatch events of a specific type within +, +use +. + + + + +XtEventDispatchProc XtSetEventDispatcher + Display *display + int event_type + XtEventDispatchProc proc + + + + + + + display + + + +Specifies the display for which the event dispatcher is to be registered. + + + + + + event_type + + + +Specifies the event type for which the dispatcher should be invoked. + + + + + + proc + + + +Specifies the event dispatcher procedure. + + + + + + +The + +function registers the event dispatcher procedure specified by proc +for events with the type event_type. The previously registered +dispatcher (or the default dispatcher if there was no previously registered +dispatcher) is returned. If proc is NULL, the default procedure is +restored for the specified type. + + + +In the future, when + +is called with an event type of event_type, the specified proc +(or the default dispatcher) is invoked to determine a widget +to which to dispatch the event. + + + +The default dispatcher handles the Intrinsics modal cascade and keyboard +focus mechanisms, handles the semantics of compress_enterleave +and compress_motion, and discards all extension events. + + + +An event dispatcher procedure pointer is of type +. + + + + +typedef Boolean (*XtEventDispatchProc) + XEvent *event + + + + + + + event + + + +Passes the event to be dispatched. + + + + + + +The event dispatcher procedure should determine whether this event is of +a type that should be dispatched to a widget. + + + +If the event should be dispatched to a widget, the event dispatcher +procedure should determine the appropriate widget to receive the +event, call +XFilterEvent +with the window of this widget, or +None +if the event is to be discarded, and if +XFilterEvent +returns +False, +dispatch the event to the widget using +. +The procedure should return +True +if either +XFilterEvent +or + +returned +True +and +False +otherwise. + + + +If the event should not be dispatched to a widget, the event +dispatcher procedure should attempt to dispatch the event elsewhere as +appropriate and return +True +if it successfully dispatched the event and +False +otherwise. + + + +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 +. + + + + +Widget XtGetKeyboardFocusWidget + Widget widget + + + + + + + widget + + + +Specifies the widget to get forwarding information for. + + + + + + +The + +function returns the widget that would be the end result of keyboard +event forwarding for a keyboard event for the specified widget. + + + +To dispatch an event to a specified widget, use +. + + + + +Boolean XtDispatchEventToWidget + Widget widget + XEvent *event + + + + + + + widget + + + +Specifies the widget to which to dispatch the event. + + + + + + event + + + +Specifies a pointer to the event to be dispatched. + + + + + + +The + +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 continue_to_dispatch +value returned by each handler. +The Intrinsics behave as if event handlers were registered at the head +of the list for +Expose, +NoExpose, +GraphicsExpose, +and +VisibilityNotify +events to invoke the widget's expose procedure according to the exposure +compression rules and to update the widget's visible field +if visible_interest is +True. +These internal event handlers never set continue_to_dispatch to +False. + + + + +returns +True +if any event handler was called and +False +otherwise. + + + + + +Using the Intrinsics in a Multi-Threaded Environment + +The Intrinsics may be used in environments that offer multiple threads +of execution within the context of a single process. A multi-threaded +application using the Intrinsics must explicitly initialize the toolkit +for mutually exclusive access by calling +. + + +Initializing a Multi-Threaded Intrinsics Application + +To test and initialize Intrinsics support for mutually exclusive thread +access, call +. + + + + +Boolean XtToolkitThreadInitialize + + + + + + +returns True if the Intrinsics support mutually exclusive thread +access, otherwise it returns False. +must be called before +, +, +, +or +XtSetLanguageProc +is called. may be called more than once; +however, the application writer must ensure that it is not called +simultaneously by two or more threads. + + + + +Locking X Toolkit Data Structures + +The Intrinsics employs two levels of locking: application context and +process. Locking an application context ensures mutually exclusive +access by a thread to the state associated with the application context, +including all displays and widgets associated with it. Locking a +process ensures mutually exclusive access by a thread to Intrinsics process +global data. + + + +A client may acquire a lock multiple times and the effect is cumulative. +The client must ensure that the lock is released an equal number of times in +order for the lock to be acquired by another thread. + + + +Most application writers will have little need to use locking as the +Intrinsics 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: + + + ... + XtAppLock(app_context); + XtCvtStringToPixel(dpy, args, num_args, fromVal, toVal, closure_ret); + XtAppUnlock(app_context); + ... + + +When the application relies upon + +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. + + + +Application writers who write their own +utility functions, such as one which retrieves the being_destroyed field from +a widget instance, must lock the application context before accessing +widget internal data. For example: + + +#include <X11/CoreP.h> +Boolean BeingDestroyed (widget) + Widget widget; +{ + Boolean ret; + XtAppLock(XtWidgetToApplicationContext(widget)); + ret = widget->core.being_destroyed; + XtAppUnlock(XtWidgetToApplicationContext(widget)); + return ret; +} + + +A client that wishes to atomically call two or more Intrinsics functions +must lock the application context. For example: + + + ... + XtAppLock(XtWidgetToApplicationContext(widget)); + XtUnmanageChild (widget1); + XtManageChild (widget2); + XtAppUnlock(XtWidgetToApplicationContext(widget)); + ... + + +Locking the Application Context + +To ensure mutual exclusion of application context, display, or +widget internal state, use +XtAppLock. + + + + +void XtAppLock + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context to lock. + + + + + + + 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. + + + +To unlock a locked application context, use +XtAppUnlock. + + + + +void XtAppUnlock + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context that was previously locked. + + + + + + + + +Locking the Process + +To ensure mutual exclusion of X Toolkit process global data, a +widget writer must use +XtProcessLock. + + + + +void XtProcessLock + + + + + + blocks until it is able to acquire the lock. +Widget writers may use XtProcessLock to guarantee mutually exclusive +access to widget static data. + + + +To unlock a locked process, use +. + + + + +void XtProcessUnlock + + + + + +To lock both an application context and the process at the same +time, call + +first and then +. +To release both locks, call + +first and then +. +The order is important to avoid deadlock. + + + + + +Event Management in a Multi-Threaded Environment + +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. + + + +To indicate that the event loop should terminate after the current +event dispatch has completed, use +. + + + + +void XtAppSetExitFlag + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context. + + + + + + + +tests the value of the flag and will return if the flag is True. + + + +Application writers who implement their own main loop may test the +value of the exit flag with +. + + + + +Boolean XtAppGetExitFlag + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context. + + + + + + + +will normally return False, indicating that event processing +may continue. When + +returns True, the loop must terminate and return to the caller, +which might then destroy the application context. + + + +Application writers should be aware that, if a thread is blocked in +, +, +or + +and another thread in the same application context opens a new display, +adds an alternate input, or a timeout, any new source(s) will not +normally be "noticed" by the blocked thread. Any new sources are +"noticed" the next time one of these functions is called. + + + +The Intrinsics manage access to events on a last-in, first-out basis. If +multiple threads in the same application context block in +, +, +or +, +the last thread to call one of these functions is the first +thread to return. + + + + diff --git a/libXt/specs/CH08 b/libXt/specs/CH08 deleted file mode 100644 index 6dfb5290b..000000000 --- a/libXt/specs/CH08 +++ /dev/null @@ -1,452 +0,0 @@ -.\" $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/libXt/specs/CH08.xml b/libXt/specs/CH08.xml new file mode 100644 index 000000000..2f24e6555 --- /dev/null +++ b/libXt/specs/CH08.xml @@ -0,0 +1,613 @@ + +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 destroy_callbacks +list is called to notify clients of the widget's impending doom. + + + +Every widget has an XtNdestroyCallbacks callback list resource. +Widgets can define additional callback lists as they see fit. +For example, the Pushbutton widget has a callback +list to notify clients when the button has been activated. + + + +Except where otherwise noted, it is the intent that all Intrinsics +functions may be called at any time, including from within callback +procedures, action routines, and event handlers. + + +Using Callback Procedure and Callback List Definitions + +Callback procedure pointers for use in callback lists are of type +. + + + + +typedef void (*XtCallbackProc) + Widget w + XtPointer client_data + XtPointer call_data + + + + + + + w + + + +Specifies the widget owning the list in which the callback is registered. + + + + + + client_data + + + +Specifies additional data supplied by the client when the procedure +was registered. + + + + + + call_data + + + +Specifies any callback-specific data the widget wants to pass to the client. +For example, when Scrollbar executes its XtNthumbChanged callback list, +it passes the new position of the thumb. + + + + + + +The client_data 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 client_data value may be NULL +if all necessary information is in the widget. +The call_data argument is a convenience to avoid having simple +cases where the client could otherwise always call + +or a widget-specific function to retrieve data from the widget. +Widgets should generally avoid putting complex state information +in call_data. +The client can use the more general data retrieval methods, if necessary. + + + +Whenever a client wants to pass a callback list as an argument in an +, +, +or + +call, it should specify the address +of a NULL-terminated array of type +XtCallbackList. + + +typedef struct { + XtCallbackProc callback; + XtPointer closure; +} XtCallbackRec, *XtCallbackList; + + +For example, the callback list for procedures A and B with client data +clientDataA and clientDataB, respectively, is + + +static XtCallbackRec callbacks[] = { + {A, (XtPointer) clientDataA}, + {B, (XtPointer) clientDataB}, + {(XtCallbackProc) NULL, (XtPointer) NULL} +}; + + +Although callback lists are passed by address in arglists +and varargs lists, +the Intrinsics recognize callback lists +through the widget resource list and will copy the contents +when necessary. +Widget initialize and set_values procedures +should not allocate memory for the callback list contents. +The Intrinsics automatically do this, +potentially using a different structure for their +internal representation. + + + + +Identifying Callback Lists + +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 + +check +to see that the requested callback list is indeed implemented by the widget. + + + +For the Intrinsics to find and correctly handle callback lists, +they must be declared with a resource type of +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 +XtCallbackStatus +XtCallbackHasNone ), +access to callback list resources must be made +through other Intrinsics procedures. + + + + +Adding Callback Procedures + +To add a callback procedure to a widget's callback list, use +. + + + + +void XtAddCallback + Widget w + String callback_name + XtCallbackProc callback + XtPointer client_data + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + callback_name + + + +Specifies the callback list to which the procedure is to be appended. + + + + + + callback + + + +Specifies the callback procedure. + + + + + + client_data + + + +Specifies additional data to be passed to the specified procedure +when it is invoked, +or NULL. + + + + + + +A callback will be invoked as many times as it occurs in the callback list. + + + +To add a list of callback procedures to a given widget's callback list, use +. + + + + +void XtAddCallbacks + Widget w + String callback_name + XtCallbackList callbacks + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + callback_name + + + +Specifies the callback list to which the procedures are to be appended. + + + + + + callbacks + + + +Specifies the null-terminated list of callback procedures and corresponding +client data. + + + + + + + + + +Removing Callback Procedures + +To delete a callback procedure from a widget's callback list, use +. + + + + +void XtRemoveCallback + Widget w + String callback_name + XtCallbackProc callback + XtPointer client_data + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + callback_name + + + +Specifies the callback list from which the procedure is to be deleted. + + + + + + callback + + + +Specifies the callback procedure. + + + + + + client_data + + + +Specifies the client data to match with the registered callback entry. + + + + + + +The + +function removes a callback only if both the procedure and the client +data match. + + + +To delete a list of callback procedures from a given widget's callback list, use +. + + + + +void XtRemoveCallbacks + Widget w + String callback_name + XtCallbackList callbacks + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + callback_name + + + +Specifies the callback list from which the procedures are to be deleted. + + + + + + callbacks + + + +Specifies the null-terminated list of callback procedures and corresponding +client data. + + + + + + +To delete all callback procedures from a given widget's callback list +and free all storage associated with the callback list, use +. + + + + +void XtRemoveAllCallbacks + Widget w + String callback_name + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + callback_name + + + +Specifies the callback list to be cleared. + + + + + + + + + +Executing Callback Procedures + +To execute the procedures in a given widget's callback list, +specifying the callback list by resource name, use +. + + + + +void XtCallCallbacks + Widget w + String callback_name + XtPointer call_data + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + callback_name + + + +Specifies the callback list to be executed. + + + + + + call_data + + + +Specifies a callback-list-specific data value to pass to each of the callback +procedure in the list, or NULL. + + + + + + + + +calls each of the callback procedures in the list +named by callback_name in the specified widget, passing the client +data registered with the procedure and call-data. + + + +To execute the procedures in a callback list, specifying the callback +list by address, use +. + + + + +void XtCallCallbackList + Widget widget + XtCallbackList callbacks + XtPointer call_data + + + + + + + widget + + + +Specifies the widget instance that contains the callback list. Must be of class Object or any subclass thereof. + + + + + + callbacks + + + +Specifies the callback list to be executed. + + + + + + call_data + + + +Specifies a callback-list-specific data value to pass +to each of the callback procedures in the list, or NULL. + + + + + + +The callbacks parameter must specify the contents of a widget or +object resource declared with representation type +XtRCallback. +If callbacks is NULL, + +returns immediately; otherwise it calls each of the callback +procedures in the list, passing the client data and call_data. + + + + +Checking the Status of a Callback List + +To find out the status of a given widget's callback list, use +. + + + +typedef enum {XtCallbackNoList, XtCallbackHasNone, XtCallbackHasSome} XtCallbackStatus; + + + + +XtCallbackStatus XtHasCallbacks + Widget w + String callback_name + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + callback_name + + + +Specifies the callback list to be checked. + + + + + + +The + +function first checks to see if the widget has a callback list identified +by callback_name. +If the callback list does not exist, + +returns +XtCallbackNoList. +If the callback list exists but is empty, +it returns +XtCallbackHasNone. +If the callback list exists and has at least one callback registered, +it returns +XtCallbackHasSome. + + + diff --git a/libXt/specs/CH09 b/libXt/specs/CH09 deleted file mode 100644 index 9538651bc..000000000 --- a/libXt/specs/CH09 +++ /dev/null @@ -1,3211 +0,0 @@ -.\" $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/libXt/specs/CH09.xml b/libXt/specs/CH09.xml new file mode 100644 index 000000000..1f64de593 --- /dev/null +++ b/libXt/specs/CH09.xml @@ -0,0 +1,4326 @@ + +Resource Management + +A resource is a field in the widget record with a corresponding +resource entry in the resources list of the widget or any of its +superclasses. +This means that the field is +settable by + +(by naming the field in the argument list), by an +entry in a resource file (by using either the name or class), and by +. +In addition, it is readable by +. +Not all fields in a widget record are resources. +Some are for bookkeeping use by the +generic routines (like managed and being_destroyed). +Others can be for local bookkeeping, +and still others are derived from resources +(many graphics contexts and pixmaps). + + + +Widgets typically need to obtain a large set of resources at widget +creation time. +Some of the resources come from the argument list supplied in the call to +, +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. + + +Resource Lists + +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 +XtResource +structure is + + +typedef struct { + String resource_name; + String resource_class; + String resource_type; + Cardinal resource_size; + Cardinal resource_offset; + String default_type; + XtPointer default_addr; +} XtResource, *XtResourceList; + + +When the resource list is specified as the +CoreClassPart, +ObjectClassPart, +RectObjClassPart, +or +ConstraintClassPart +resources field, the strings pointed to by resource_name, +resource_class, resource_type, and default_type must +be permanently allocated prior to or during the execution of the class +initialization procedure and must not be subsequently deallocated. + + + +The resource_name field contains the name used by clients to access the field +in the widget. +By convention, it starts with a lowercase letter +and is spelled exactly like the field name, +except all underscores (_) are deleted and the next letter is replaced by its +uppercase counterpart. +For example, the resource name for background_pixel becomes backgroundPixel. +Resource names beginning with the two-character +sequence ``xt'', and resource classes beginning with the two-character +sequence ``Xt'' are reserved to the Intrinsics for future standard and +implementation-dependent uses. +Widget header files typically contain a symbolic name for each resource name. +All resource names, classes, and types used by the Intrinsics are named in +<X11/StringDefs.h>. +The Intrinsics's symbolic resource names begin with +``XtN'' +and are followed by the string name (for example, XtNbackgroundPixel +for backgroundPixel). + + + +The resource_class field contains the class string used in resource +specification files to identify the field. +A resource class provides two functions: + + + + +It isolates an application from different representations that widgets +can use for a similar resource. + + + + +It lets you specify values for several actual resources with a single name. +A resource class should be chosen to span a group of closely related fields. + + + + +For example, +a widget can have several pixel resources: background, foreground, +border, block cursor, pointer 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. + + + +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: + + +*Background: ivory +*Foreground: darkblue + + +Similarly, a widget may have several font resources (such as normal and bold), +but all fonts should have the class Font. +Thus, changing all fonts simply requires only a single line in the +default resource file: + + +*Font: 6x13 + + +By convention, +resource classes are always spelled starting with a capital letter +to distinguish them from resource names. +Their symbolic names are preceded with +``XtC'' +(for example, XtCBackground). + + + +The resource_type 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 +String) +or the format of the resource default value +(almost anything, but often +String) +to the desired +physical representation (see ). +The Intrinsics define the following resource types: + + + + + + + + + + Resource Type + Structure or Field Type + + + + + XtRAcceleratorTable + XtAccelerators + + + XtRAtom + Atom + + + XtRBitmap + Pixmap, depth=1 + + + XtRBoolean + Boolean + + + XtRBool + Bool + + + XtRCallback + XtCallbackList + + + XtRCardinal + Cardinal + + + XtRColor + XColor + + + XtRColormap + Colormap + + + XtRCommandArgArray + String* + + + XtRCursor + Cursor + + + XtRDimension + Dimension + + + XtRDirectoryString + String + + + XtRDisplay + Display* + + + XtREnum + XtEnum + + + XtREnvironmentArray + String* + + + XtRFile + FILE* + + + XtRFloat + float + + + XtRFont + Font + + + XtRFontSet + XFontSet + + + XtRFontStruct + XFontStruct* + + + XtRFunction + (*)() + + + XtRGeometry + char*, format as defined by + XParseGeometry + + + XtRGravity + int + + + XtRInitialState + int + + + XtRInt + int + + + XtRLongBoolean + long + + + XtRObject + Object + + + XtRPixel + Pixel + + + XtRPixmap + Pixmap + + + XtRPointer + XtPointer + + + XtRPosition + Position + + + XtRRestartStyle + unsigned char + + + XtRScreen + Screen* + + + XtRShort + short + + + XtRSmcConn + XtPointer + + + XtRString + String + + + XtRStringArray + String* + + + XtRStringTable + String* + + + XtRTranslationTable + XtTranslations + + + XtRUnsignedChar + unsigned char + + + XtRVisual + Visual* + + + XtRWidget + Widget + + + XtRWidgetClass + WidgetClass + + + XtRWidgetList + WidgetList + + + XtRWindow + Window + + + + + + +<X11/StringDefs.h> +also defines the following resource types as a +convenience for widgets, although they do not have any corresponding +data type assigned: +XtREditMode, +XtRJustify, +and +XtROrientation. + + + +The resource_size field is the size of the physical representation in bytes; +you should specify it as +sizeof(type) so that the +compiler fills in the value. +The resource_offset field is the offset in bytes of the field +within the widget. +You should use the + +macro to retrieve this value. +The default_type field is the representation type of the default +resource value. +If default_type is different from resource_type and the default value +is needed, +the resource manager invokes a conversion procedure from default_type +to resource_type. +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, +XtDefaultForeground +for a pixel resource). +The default_addr field specifies the address of the default resource value. +As a special case, if default_type is +XtRString, +then the value in the default_addr field is the pointer to +the string rather than a pointer to the pointer. +The default is used if a resource is not specified in the argument list +or in the resource database or if the conversion from the representation +type stored in the resource database fails, +which can happen for various reasons (for example, a misspelled entry in a +resource file). + + + +Two special representation types +(XtRImmediate +and +XtRCallProc) +are usable only as default resource types. +XtRImmediate +indicates that the value in the default_addr 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 +XtPointer. +No conversion is possible, since there is no source representation type. +XtRCallProc +indicates that the value in the default_addr field is a procedure +pointer. +This procedure is automatically invoked with the widget, +resource_offset, and a pointer to an +XrmValue +in which to store the result. +XtRCallProc +procedure pointers are of type +. + + + + +typedef void (*XtResourceDefaultProc) + Widget w + int offset + XrmValue *value + + + + + + + w + + + +Specifies the widget whose resource value is to be obtained. + + + + + + offset + + + +Specifies the offset of the field in the widget record. + + + + + + value + + + +Specifies the resource value descriptor to return. + + + + + + +The + +procedure should fill in the value->addr field with a pointer +to the resource value in its correct representation type. + + + +To get the resource list structure for a particular class, use +. + + + + +void XtGetResourceList + + WidgetClass class + XtResourceList *resources_return + Cardinal *num_resources_return + + + + + + + class + + + +Specifies the object class to be queried. It must be +objectClass +or any subclass thereof. + + + + + + resources_return + + + +Returns the resource list. + + + + + + num_resources_return + + + +Returns the number of entries in the resource list. + + + + + + +If + +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, + +returns a merged resource list that includes the resources +for all superclasses. +The list returned by + +should be freed using + +when it is no longer needed. + + + +To get the constraint resource list structure for a particular widget +class, use +. + + + + +void XtGetConstraintResourceList + WidgetClass class + XtResourceList *resources_return + Cardinal *num_resources_return + + + + + + + class + + + +Specifies the object class to be queried. It must be +objectClass +or any subclass thereof. + + + + + + resources_return + + + +Returns the constraint resource list. + + + + + + num_resources_return + + + +Returns the number of entries in the constraint resource list. + + + + + + +If + +is called before the widget class is +initialized, the resource list as specified in the widget +class Constraint part is returned. If + +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 +constraintWidgetClass, +*resources_return is set to NULL +and *num_resources_return is set to zero. +The list returned by + +should be freed using + +when it is no longer needed. + + + +The routines + +and + +also use the resource list to set and get widget state; +see and +. + + + +Here is an abbreviated version of a possible resource list for a Label widget: + + +/* Resources specific to Label */ +static XtResource resources[] = { +{XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel), + XtOffsetOf(LabelRec, label.foreground), XtRString, XtDefaultForeground}, +{XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*), + XtOffsetOf(LabelRec, label.font), XtRString, XtDefaultFont}, +{XtNlabel, XtCLabel, XtRString, sizeof(String), + XtOffsetOf(LabelRec, label.label), XtRString, NULL}, + . + . + . +} + + +The complete resource name for a field of a widget instance is the +concatenation of the application shell name (from +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 +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. + + + + +Byte Offset Calculations + +To determine the byte offset of a field within a structure type, use +. + + + + +Cardinal XtOffsetOf + Type structure_type + Field field_name + + + + + + + + + structure_type + + + +Specifies a type that is declared as a structure. + + + + + + field_name + + + +Specifies the name of a member within the structure. + + + + + + +The + +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 +, +which serves the same function. + + + +To determine the byte offset of a field within a structure pointer type, use +. + + + + +Cardinal XtOffset + Type pointer_type + Field field_name + + + + + + + pointer_type + + + +Specifies a type that is declared as a pointer to a structure. + + + + + + field_name + + + +Specifies the name of a member within the structure. + + + + + + +The + +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. + +is less portable than +. + + + + +Superclass-to-Subclass Chaining of Resource Lists + +The + +function gets resources as a superclass-to-subclass chained operation. +That is, the resources specified in the +objectClass +resource list are fetched, +then those in +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. + + + +In general, if a widget resource field is declared in a superclass, +that field is included in the superclass's resource list and need not be +included in the subclass's resource list. +For example, the +Core +class contains a resource entry for background_pixel. +Consequently, +the implementation of Label need not also have a resource entry +for background_pixel. +However, a subclass, +by specifying a resource entry for that field in its own resource list, +can override the resource entry for any field declared in a superclass. +This is most often done to override the defaults provided in the +superclass with new ones. +At class initialization time, +resource lists for that class are scanned from the superclass down +to the class to look for resources with the same offset. +A matching resource in a subclass will be reordered to override +the superclass entry. +If reordering is necessary, a copy of the superclass resource list is made to +avoid affecting other subclasses of the superclass. + + + +Also at class initialization time, the Intrinsics produce an +internal representation of the resource list to optimize access time +when creating widgets. In order to save memory, the Intrinsics may +overwrite the storage allocated for the resource list in the class +record; therefore, widgets must allocate resource lists in writable +storage and must not access the list contents directly after the +class_initialize procedure has returned. + + + + +Subresources + +A widget does not do anything to retrieve its own resources; +instead, + +does this automatically before calling the class initialize procedure. + + + +Some widgets have subparts that are not widgets but for which the widget +would like to fetch resources. +Such widgets call + +to accomplish this. + + + + +void XtGetSubresources + Widget w + XtPointer base + String name + String class + XtResourceList resources + Cardinal num_resources + ArgList args + Cardinal num_args + + + + + + + w + + + +Specifies the object used to qualify the subpart resource name and +class. Must be of class Object or any subclass thereof. + + + + + + base + + + +Specifies the base address of the subpart data structure into which the +resources will be written. + + + + + + name + + + +Specifies the name of the subpart. + + + + + + class + + + +Specifies the class of the subpart. + + + + + + resources + + + +Specifies the resource list for the subpart. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + args + + + +Specifies the argument list to override any other resource specifications. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +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 name and class 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 args is NULL, +num_args must be zero. +However, if num_args is zero, +the argument list is not referenced. + + + + +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 + +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. + + + +To fetch resources for widget subparts using varargs lists, use +. + + + + +void XtVaGetSubresources + Widget w + XtPointer base + String name + String class + XtResourceList resources + Cardinal num_resources + + + + + + + w + + + +Specifies the object used to qualify the subpart resource name and +class. Must be of class Object or any subclass thereof. + + + + + + base + + + +Specifies the base address of the subpart data structure into which the +resources will be written. + + + + + + name + + + +Specifies the name of the subpart. + + + + + + class + + + +Specifies the class of the subpart. + + + + + + resources + + + +Specifies the resource list for the subpart. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + ... + + + +Specifies the variable argument list to override any other +resource specifications. + + + + + + + +is identical in function to + +with the args and num_args parameters replaced by a varargs list, as +described in Section 2.5.1. + + + + +Obtaining Application Resources + +To retrieve resources that are not specific to a widget +but apply to the overall application, use +. + + + + +void XtGetApplicationResources + Widget w + XtPointer base + XtResourceList resources + Cardinal num_resources + ArgList args + Cardinal num_args + + + + + + + w + + + +Specifies the object that identifies the resource database to search +(the database is that associated with the display for this object). Must be of class Object or any subclass thereof. + + + + + + base + + + +Specifies the base address into which +the resource values will be written. + + + + + + resources + + + +Specifies the resource list. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + args + + + +Specifies the argument list to override any other resource specifications. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +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, + +copies the resources into the addresses +obtained by adding base to each offset in the resource list. +If args is NULL, +num_args must be zero. +However, if num_args 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 base argument. + + + + +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 + +will not be freed from the resource cache until the display is closed. + + + +To retrieve resources for the overall application using varargs lists, use +. + + + + +void XtVaGetApplicationResources + Widget w + XtPointer base + XtResourceList resources + Cardinal num_resources + + + + + + + w + + + +Specifies the object that identifies the resource database to search +(the database is that associated with the display for this object). Must be of class Object or any subclass thereof. + + + + + + base + + + +Specifies the base address into which +the resource values will be written. + + + + + + resources + + + +Specifies the resource list for the subpart. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + ... + + + +Specifies the variable argument list to override any other +resource specifications. + + + + + + + +is identical in function to + +with the args and num_args parameters +replaced by a varargs list, as described in Section 2.5.1. + + + + +Resource Conversions + +The Intrinsics provide a mechanism for registering representation converters that +are automatically invoked by the resource-fetching routines. +The Intrinsics additionally provide and register several commonly used converters. +This resource conversion mechanism serves several purposes: + + + + +It permits user and application resource files to contain textual +representations of nontextual values. + + + + +It allows textual or other representations of default resource values that +are dependent on the display, screen, or colormap, and thus must be +computed at runtime. + + + + +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. + + + + +Predefined Resource Converters + +The Intrinsics define all the representations used in the +Object, +RectObj, +Core, +Composite, +Constraint, +and +Shell +widget classes. +The Intrinsics register the following resource converters that accept +input values of representation type +XtRString. + + + + + + + + + + + Target Representation + Converter Name + Additional Args + + + + + XtRAcceleratorTable + XtCvtStringToAcceleratorTable + + + XtRAtom + XtCvtStringToAtom + Display* + + + XtRBoolean + XtCvtStringToBoolean + + + XtRBool + XtCvtStringToBool + + + XtRCommandArgArray + XtCvtStringToCommandArgArray + + + XtRCursor + XtCvtStringToCursor + Display* + + + XtRDimension + XtCvtStringToDimension + + + XtRDirectoryString + XtCvtStringToDirectoryString + + + XtRDisplay + XtCvtStringToDisplay + + + XtRFile + XtCvtStringToFile + + + XtRFloat + XtCvtStringToFloat + + + XtRFont + XtCvtStringToFont + Display* + + + XtRFontSet + XtCvtStringToFontSet + Display*, String locale + + + XtRFontStruct + XtCvtStringToFontStruct + Display* + + + XtRGravity + XtCvtStringToGravity + + + XtRInitialState + XtCvtStringToInitialState + + + XtRInt + XtCvtStringToInt + + + XtRPixel + XtCvtStringToPixel + colorConvertArgs + + + XtRPosition + XtCvtStringToPosition + + + XtRRestartStyle + XtCvtStringToRestartStyle + + + XtRShort + XtCvtStringToShort + + + XtRTranslationTable + XtCvtStringToTranslationTable + + + XtRUnsignedChar + XtCvtStringToUnsignedChar + + + XtRVisual + XtCvtStringToVisual + Screen*, Cardinal depth + + + + + + +The String-to-Pixel conversion has two predefined constants that are +guaranteed to work and contrast with each other: +XtDefaultForeground +and +XtDefaultBackground. +They evaluate to the black and white pixel values of the widget's screen, +respectively. +If the application resource reverseVideo is +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 +XtDefaultFont +and evaluate this in the following manner: + + + + +Query the resource database for the resource whose full name +is ``xtDefaultFont'', class ``XtDefaultFont'' (that is, no widget +name/class prefixes), and use a type +XtRString +value returned as the font name or a type +XtRFont +or +XtRFontStruct +value directly as the resource value. + + + + +If the resource database does not contain a value for xtDefaultFont, +class XtDefaultFont, or if the returned font name cannot be +successfully opened, an implementation-defined font in ISO8859-1 +character set encoding is opened. (One possible algorithm is to +perform an +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".) + + + + +If no suitable ISO8859-1 font can be found, issue a warning message +and return +False. + + + + +The String-to-FontSet converter recognizes the constant +XtDefaultFontSet +and evaluate this in the following manner: + + + + +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 +XtRString +value returned as the base font name list or a type +XtRFontSet +value directly as the resource value. + + + + +If the resource database does not contain a value for xtDefaultFontSet, +class XtDefaultFontSet, or if a font set cannot be +successfully created from this resource, +an implementation-defined font set is created. +(One possible algorithm is to +perform an +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-*-*-*-*".) + + + + +If no suitable font set can be created, issue a warning message +and return +False. + + + + +If a font set is created but missing_charset_list is not +empty, a warning is issued and the partial font set is returned. +The Intrinsics register the String-to-FontSet converter with +a conversion argument list that extracts the current process +locale at the time the converter is invoked. This ensures +that the converter is invoked again if the same conversion +is required in a different locale. + + + +The String-to-Gravity conversion accepts string values that are the +names of window and bit gravities and their numerical equivalents, +as defined in Xlib — C Language X Interface.: +ForgetGravity, +UnmapGravity, +NorthWestGravity, +NorthGravity, +NorthEastGravity, +WestGravity, +CenterGravity, +EastGravity, +SouthWestGravity, +SouthGravity, +SouthEastGravity, +and +StaticGravity. +Alphabetic case is not significant in the conversion. + + + +The String-to-CommandArgArray conversion parses a String into an +array of strings. +White space characters separate elements of the command line. +The converter recognizes the backslash character ``\\'' as an escape +character to allow the following white space character to be part of the +array element. + + + +The String-to-DirectoryString conversion recognizes the +string ``XtCurrentDirectory'' and returns the result of a call +to the operating system to get the current directory. + + + +The String-to-RestartStyle conversion accepts the values +RestartIfRunning, +RestartAnyway, +RestartImmediately, +and +RestartNever +as defined by the X Session Management Protocol. + + + +The String-to-InitialState conversion accepts the values +NormalState +or +IconicState +as defined by the Inter-Client Communication Conventions Manual.. + + + +The String-to-Visual conversion calls +XMatchVisualInfo +using the +screen and depth 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 +XtRVisual +after the depth resource. +The allowed string values are the visual class names defined in X Window System Protocol, +Section 8; +StaticGray, +StaticColor, +TrueColor, +GrayScale, +PseudoColor, +and +DirectColor. + + + +The Intrinsics register the following resource converter that accepts +an input value of representation type +XtRColor. + + + + + + + + + + + Target Representation + Converter Name + Additional Args + + + + + XtRPixel + XtCvtColorToPixel + + + + + + +The Intrinsics register the following resource converters that accept +input values of representation type +XtRInt. + + + + + + + + + + + Target Representation + Converter Name + Additional Args + + + + + XtRBoolean + XtCvtIntToBoolean + + + XtRBool + XtCvtIntToBool + + + XtRColor + XtCvtIntToColor + colorConvertArgs + + + XtRDimension + XtCvtIntToDimension + + + XtRFloat + XtCvtIntToFloat + + + XtRFont + XtCvtIntToFont + + + XtRPixel + XtCvtIntToPixel + + + XtRPixmap + XtCvtIntToPixmap + + + XtRPosition + XtCvtIntToPosition + + + XtRShort + XtCvtIntToShort + + + XtRUnsignedChar + XtCvtIntToUnsignedChar + + + + + + +The Intrinsics register the following resource converter that accepts +an input value of representation type +XtRPixel. + + + + + + + + + + + Target Representation + Converter Name + Additional Args + + + + + XtRColor + XtCvtPixelToColor + + + + + + + +New Resource Converters + +Type converters use pointers to +XrmValue +structures (defined in +<X11/Xresource.h>; +see Section 15.4 in +Xlib — C Language X Interface.) +for input and output values. + + +typedef struct { + unsigned int size; + XPointer addr; +} XrmValue, *XrmValuePtr; + + +The addr field specifies the address of the data, and the size +field gives the total number of significant bytes in the data. +For values of type +String, +addr is the address of the first character and size +includes the NULL-terminating byte. + + + +A resource converter procedure pointer is of type +. + + + + +typedef Boolean (*XtTypeConverter) + Display *display + XrmValue *args + Cardinal *num_args + XrmValue *from + XrmValue *to + XtPointer *converter_data + + + + + + + display + + + +Specifies the display connection with which this conversion is associated. + + + + + + args + + + +Specifies a list of additional +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 display, +and the String-to-Pixel converter needs the widget's screen and colormap. + + + + + + num_args + + + +Specifies the number of entries in args. + + + + + + from + + + +Specifies the value to convert. + + + + + + to + + + +Specifies a descriptor for a location into which to store the converted value. + + + + + + converter_data + + + +Specifies a location into which the converter may +store converter-specific data associated +with this conversion. + + + + + + +The display argument is normally used only when generating error +messages, to identify the application context (with the function +XtDisplayToApplicationContext ). + + + +The to argument specifies the size and location into which the +converter should store the converted value. If the addr field is NULL, +the converter should allocate appropriate storage and store the size +and location into the to 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 +addr field is not NULL, the converter must check the size field to +ensure that sufficient space has been allocated before storing the +converted value. If insufficient space is specified, the converter +should update the size field with the number of bytes required and +return +False +without modifying the data at the specified location. +If sufficient space was allocated by the caller, the converter should +update the size field with the number of bytes actually occupied by the +converted value. For converted values of type +XtRString, +the size should +include the NULL-terminating byte, if any. +The converter may store any value in the location specified +in converter_data; this value will be passed to the destructor, if any, +when the resource is freed by the Intrinsics. + + + +The converter must return +True +if the conversion was successful and +False +otherwise. If the conversion cannot be performed because of an +improper source value, a warning message should also be issued with +. + + + +Most type converters just take the data described by the specified from +argument and return data by writing into the location specified in +the to argument. +A few need other information, which is available in args. +A type converter can invoke another type converter, +which allows differing sources that may convert into a common intermediate +result to make maximum use of the type converter cache. + + + +Note that if an address is written into to->addr, 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, +, +or + +in an implementation-defined manner; however, insertion of new entries +or changes to existing entries is allowed and will not directly cause +an error. + + + +The following is an example of a converter that takes a +string +and converts it to a +Pixel. +Note that the display parameter is +used only to generate error messages; the +Screen +conversion argument is +still required to inform the Intrinsics that the converted value is +a function of the particular display (and colormap). + + + +#define done(type, value) \\ + { \\ + if (toVal->addr != NULL) { \\ + if (toVal->size < sizeof(type)) { \\ + toVal->size = sizeof(type); \\ + return False; \\ + } \\ + *(type*)(toVal->addr) = (value); \\ + } \\ + else { \\ + static type static_val; \\ + static_val = (value); \\ + toVal->addr = (XPointer)&static_val; \\ + } \\ + toVal->size = sizeof(type); \\ + return True; \\ + } +static Boolean CvtStringToPixel(dpy, args, num_args, fromVal, toVal, converter_data) + Display *dpy; + XrmValue *args; + Cardinal *num_args; + XrmValue *fromVal; + XrmValue *toVal; + XtPointer *converter_data; +{ + static XColor screenColor; + XColor exactColor; + Screen *screen; + Colormap colormap; + Status status; + if (*num_args != 2) + XtAppWarningMsg(XtDisplayToApplicationContext(dpy), + "wrongParameters", "cvtStringToPixel", "XtToolkitError", + "String to pixel conversion needs screen and colormap arguments", + (String *)NULL, (Cardinal *)NULL); + screen = *((Screen**) args[0].addr); + colormap = *((Colormap *) args[1].addr); + if (CompareISOLatin1(str, XtDefaultBackground) == 0) { + *closure_ret = False; + done(Pixel, WhitePixelOfScreen(screen)); + } + if (CompareISOLatin1(str, XtDefaultForeground) == 0) { + *closure_ret = False; + done(Pixel, BlackPixelOfScreen(screen)); + } + status = XAllocNamedColor(DisplayOfScreen(screen), colormap, (char*)fromVal->addr, + &screenColor, &exactColor); + if (status == 0) { + String params[1]; + Cardinal num_params = 1; + params[0] = (String)fromVal->addr; + XtAppWarningMsg(XtDisplayToApplicationContext(dpy), + "noColormap", "cvtStringToPixel", "XtToolkitError", + "Cannot allocate colormap entry for \\"%s\\"", params,\ + &num_params); + *converter_data = (char *) False; + return False; + } else { + *converter_data = (char *) True; + done(Pixel, &screenColor.pixel); + } +} + + + +All type converters should define some set of conversion values for which they +are guaranteed to succeed so these can be used in the resource defaults. +This issue arises only with conversions, such as fonts and colors, +where there is no string representation that all server implementations +will necessarily recognize. +For resources like these, +the converter should define a symbolic constant +in the same manner as +XtDefaultForeground, +XtDefaultBackground, +and +XtDefaultFont. + + + +To allow the Intrinsics to deallocate resources produced by type +converters, a resource destructor procedure may also be provided. + + + +A resource destructor procedure pointer is of type +. + + + + + typedef void (*XtDestructor) + XtAppContext app + XrmValue *to + XtPointer converter_data + XrmValue *args + Cardinal *num_args + + + + + + + app + + + +Specifies an application context in which the resource is being freed. + + + + + + to + + + +Specifies a descriptor for the resource produced by the type converter. + + + + + + converter_data + + + +Specifies the converter-specific data returned by the type converter. + + + + + + args + + + +Specifies the additional converter arguments as passed +to the type converter when the conversion was performed. + + + + + + num_args + + + +Specifies the number of entries in args. + + + + + + +The destructor procedure is responsible for freeing the resource +specified by the to argument, including any auxiliary storage +associated with that resource, but not the memory directly addressed +by the size and location in the to argument or the memory specified +by args. + + + + +Issuing Conversion Warnings + +The + +procedure is a convenience routine for resource type converters +that convert from string values. + + + + +void XtDisplayStringConversionWarning + Display *display + String from_value + + + + + + + display + + + +Specifies the display connection with which the conversion is associated. + + + + + + from_value + + + +Specifies the string that could not be converted. + + + + + + to_type + + + +Specifies the target representation type requested. + + + + + + +The + +procedure issues a warning message using + +with name ``conversionError'', +type ``string'', class ``XtToolkitError'', and the default message +``Cannot convert "from_value" to type to_type''. + + + +To issue other types of warning or error messages, the type converter +should use + +or +. + + + +To retrieve the application context associated with a given +display connection, use +. + + + + +XtAppContext XtDisplayToApplicationContext + Display *display + + + + + + + display + + + +Specifies an open and initialized display connection. + + + + + + +The + +function returns the application +context in which the specified display was initialized. If the +display is not known to the Intrinsics, an error message is issued. + + + + +Registering a New Resource Converter + +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 XtCacheType +argument. + + +typedef int XtCacheType; + + + +An XtCacheType +field may contain one of the following values: + + + +XtCacheNone + + + + +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. + + + + +XtCacheAll + + + + +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. + + + + +XtCacheByDisplay + + + + +Specifies that the results of a previous conversion +should be used as for +XtCacheAll +but the destructor will be called, if specified, if + +is called +for the display connection associated with the converted value, and +the value will be removed from the conversion cache. + + + + +The qualifier +XtCacheRefCount +may be ORed with any of the above values. If +XtCacheRefCount +is specified, calls to +, +, +, +and + +that use the converted value will be counted. When a widget using the +converted value is destroyed, the count is decremented, and, if the +count reaches zero, the destructor procedure will be called and the +converted value will be removed from the conversion cache. + + + +To register a type converter for all application contexts in a +process, use +, +and to register a type converter in a single application context, use +. + + + + +void XtSetTypeConverter + String from_type + String to_type + XtTypeConverter converter + XtConvertArgList convert_args + Cardinal num_args + XtCacheType cache_type + XtDestructor destructor + + + + + + + from_type + + + +Specifies the source type. + + + + + + to_type + + + +Specifies the destination type. + + + + + + converter + + + +Specifies the resource type converter procedure. + + + + + + convert_args + + + +Specifies additional conversion arguments, or NULL. + + + + + + num_args + + + +Specifies the number of entries in convert_args. + + + + + + cache_type + + + +Specifies whether or not resources produced by this +converter are sharable or display-specific and when +they should be freed. + + + + + + destructor + + + +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. + + + + + + + + + XtAppSetTypeConverter + XtAppContext app_context + String from_type + String to_type + XtTypeConverter converter + XtConvertArgList convert_args + Cardinal num_args + XtCacheType cache_type + XtDestructor destructor + + + + + + + app_context + + + +Specifies the application context. + + + + + + from_type + + + +Specifies the source type. + + + + + + to_type + + + +Specifies the destination type. + + + + + + converter + + + +Specifies the resource type converter procedure. + + + + + + convert_args + + + +Specifies additional conversion arguments, or NULL. + + + + + + num_args + + + +Specifies the number of entries in convert_args. + + + + + + cache_type + + + +Specifies whether or not resources produced by this +converter are sharable or display-specific and when +they should be freed. + + + + + + destructor + + + +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. + + + + + + + +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. + +registers the specified type converter in the +single application context specified. If the same from_type and +to_type are specified in multiple calls to either function, the most +recent overrides the previous ones. + + + +For the few type converters that need additional arguments, +the Intrinsics conversion mechanism provides a method of specifying +how these arguments should be computed. +The enumerated type +XtAddressMode +and the structure +XtConvertArgRec +specify how each argument is derived. +These are defined in +<X11/Intrinsic.h>. + + +typedef enum { + /* address mode parameter representation */ + XtAddress, /* address */ + XtBaseOffset, /* offset */ + XtImmediate, /* constant */ + XtResourceString, /* resource name string */ + XtResourceQuark, /* resource name quark */ + XtWidgetBaseOffset, /* offset */ + XtProcedureArg /* procedure to call */ +} XtAddressMode; + +typedef struct { + XtAddressMode address_mode; + XtPointer address_id; + Cardinal size; +} XtConvertArgRec, *XtConvertArgList; + + +The size field specifies the length of the data in bytes. +The address_mode field specifies how the address_id field should be +interpreted. +XtAddress +causes address_id to be interpreted as the address of the data. +XtBaseOffset +causes address_id to be interpreted as the offset from the widget base. +XtImmediate +causes address_id to be interpreted as a constant. +XtResourceString +causes address_id to be interpreted as the name of a resource +that is to be converted into an offset from the widget base. +XtResourceQuark +causes address_id to be interpreted as the result of an +XrmStringToQuark +conversion on the name of a resource, +which is to be converted into an offset from the widget base. +XtWidgetBaseOffset +is similar to +XtBaseOffset +except that it +searches for the closest windowed ancestor if the object is not +of a subclass of +Core +(see ). +XtProcedureArg +specifies that address_id is a pointer to a procedure to +be invoked to return the conversion argument. If +XtProcedureArg +is specified, address_id must contain +the address of a function of type +. + + + + +typedef void (*XtConvertArgProc) + XtAppContext app + XrmValue *to + XtPointer converter_data + XrmValue *args + Cardinal *num_args + + + + + + + app + + + +Specifies an application context in which the resource is being freed. + + + + + + to + + + +Specifies a descriptor for the resource produced by the type converter. + + + + + + converter_data + + + +Specifies the converter-specific data returned by the type converter. + + + + + + args + + + +Specifies the additional converter arguments as passed +to the type converter when the conversion was performed. + + + + + + num_args + + + +Specifies the number of entries in args. + + + + + + +The destructor procedure is responsible for freeing the resource +specified by the to argument, including any auxiliary storage +associated with that resource, but not the memory directly addressed +by the size and location in the to argument or the memory specified +by args. + + + + +Resource Converter Invocation + +All resource-fetching routines (for example, +, +, +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. + + + +To invoke explicit resource conversions, use + +or +. + + +typedef XtPointer XtCacheRef; + + + + +Boolean XtCallConverter + Display* display + XtTypeConverter converter + XrmValuePtr conversion_args + Cardinal num_args + XrmValuePtr from + XrmValuePtr to_in_out + XtCacheRef *cache_ref_return + + + + + + + display + + + +Specifies the display with which the conversion is to be associated. + + + + + + converter + + + +Specifies the conversion procedure to be called. + + + + + + conversion_args + + + +Specifies the additional conversion arguments needed +to perform the conversion, or NULL. + + + + + + num_args + + + +Specifies the number of entries in conversion_args. + + + + + + from + + + +Specifies a descriptor for the source value. + + + + + + to_in_out + + + +Returns the converted value. + + + + + + cache_ref_return + + + +Returns a conversion cache id. + + + + + + +The + +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 +XtCacheAll +or +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, + +returns +False +immediately; +otherwise it checks the size specified in the to 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 +to->addr, stores the cache size into to->size, and returns +True. +If the size specified in the to argument is smaller than the size stored +in the cache, + +copies the cache size into to->size and returns +False. +If the converter was registered with cache type +XtCacheNone +or no value was found in the conversion cache, + +calls the converter, and if it was not registered with cache type +XtCacheNone, +enters the result in the cache. + +then returns what the converter returned. + + + +The cache_ref_return field specifies storage allocated by the caller in which +an opaque value will be stored. If the type converter has been +registered with the +XtCacheRefCount +modifier and if the value returned +in cache_ref_return is non-NULL, then the caller should store the +cache_ref_return value in order to decrement the reference count when +the converted value is no longer required. The cache_ref_return +argument should be +NULL if the caller is unwilling or unable to store the +value. + + + +To explicitly decrement the reference counts for resources obtained +from +, +use +. + + + + +void XtAppReleaseCacheRefs + XtAppContext app_context + XtCacheRef *refs + + + + + + + app_context + + + +Specifies the application context. + + + + + + refs + + + +Specifies the list of cache references to be released. + + + + + + + +decrements the reference count for the +conversion entries identified by the refs argument. +This argument is a +pointer to a NULL-terminated list of +XtCacheRef +values. If any reference +count reaches zero, the destructor, if any, will be called and +the resource removed from the conversion cache. + + + +As a convenience to clients needing to explicitly decrement reference +counts via a callback function, the Intrinsics define two callback +procedures, + +and +. + + + + +void XtCallbackReleaseCacheRef + Widget object + XtPointer client_data + XtPointer call_data + + + + + + + object + + + +Specifies the object with which the resource is associated. + + + + + + client_data + + + +Specifies the conversion cache entry to be released. + + + + + + call_data + + + +Is ignored. + + + + + + +This callback procedure may be added to a callback list to release a +previously returned +XtCacheRef +value. When adding the callback, the +callback client_data argument must be specified as the value of the +XtCacheRef +data cast to type +XtPointer. + + + + +void XtCallbackReleaseCacheRefList + Widget object + XtPointer client_data + XtPointer call_data + + + + + + + object + + + +Specifies the object with which the resources are associated. + + + + + + client_data + + + +Specifies the conversion cache entries to be released. + + + + + + call_data + + + +Is ignored. + + + + + + +This callback procedure may be added to a callback list to release a +list of previously returned +XtCacheRef +values. When adding the +callback, the callback client_data argument must be specified as a +pointer to a NULL-terminated list of +XtCacheRef +values. + + + +To lookup and call a resource converter, copy the resulting value, +and free a cached resource when a widget is destroyed, use +. + + + + +Boolean XtConvertAndStore + Widget object + String from_type + XrmValuePtr from + String to_type + XrmValuePtr to_in_out + + + + + + + object + + + +Specifies the object to use for additional arguments, if any are needed, +and the destroy callback list. Must be of class Object or any subclass thereof. + + + + + + from_type + + + +Specifies the source type. + + + + + + from + + + +Specifies the value to be converted. + + + + + + to_type + + + +Specifies the destination type. + + + + + + to_in_out + + + +Specifies a descriptor for storage into which the converted value +will be returned. + + + + + + +The + +function looks up the type converter registered +to convert from_type to to_type, computes any additional arguments +needed, and then calls + +(or + +if an old-style converter was registered with + +or +; +see Appendix C) with the from and to_in_out arguments. The +to_in_out 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 size field will be modified on return to indicate the actual +size of the converted data. +If the conversion succeeds, + +returns +True; +otherwise, it returns +False. + + + + +adds + +to the destroyCallback list of the specified object if the conversion +returns an +XtCacheRef +value. The resulting resource should not be referenced +after the object has been destroyed. + + + + +performs processing equivalent to + +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. + + + +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 +Boolean +resource +XtNinitialResourcesPersistent, +class +XtCInitialResourcesPersistent. + + + +When + +is called, if this resource is not specified as +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 +True; +thus clients that expect to destroy one or +more objects and want resources deallocated must explicitly specify +False +for +XtNinitialResourcesPersistent. + + + +The resources are still freed and destructors called when + +is called if the conversion was registered as +XtCacheByDisplay. + + + + + +Reading and Writing Widget State + +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. + + +Obtaining Widget State + +To retrieve the current values of resources associated with a +widget instance, use +. + + + + +void XtGetValues + Widget object + ArgList args + Cardinal num_args + + + + + + + object + + + +Specifies the object whose resource values are to be returned. Must be of class Object or any subclass thereof. + + + + + + args + + + +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. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +function starts with the resources specified for the Object class +and proceeds down the subclass chain to the class of the object. +The value 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 +Intrinsics-defined resources, the following lifetimes apply: + + + + +Not valid following any operation that modifies the resource: + + + + + + +XtNchildren resource of composite widgets. + + + + +All resources of representation type XtRCallback. + + + + + + +Remain valid at least until the widget is destroyed: + + + + + + +XtNaccelerators, XtNtranslations. + + + + + + +Remain valid until the Display is closed: + + + + + + +XtNscreen. + + + + + + +It is the caller's responsibility +to allocate and deallocate storage for the copied data +according to the size of the +resource representation type used within the object. + + + +If the class of the object's parent is a subclass of +constraintWidgetClass, + +then fetches the values for any constraint resources requested. +It starts with the constraint resources specified for +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. +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 +. +Finally, if the object's parent is a +subclass of +constraintWidgetClass, +and if any of the parent's class or +superclass records have declared +ConstraintClassExtension +records in +the Constraint class part extension field with a record type of +NULLQUARK, +and if the get_values_hook field in the extension record is non-NULL, + +calls the get_values_hook procedures in superclass-to-subclass order. +This permits a Constraint parent to provide +nonresource data via +. + + + +Get_values_hook procedures may modify the data stored at the +location addressed by the value field, including (but not +limited to) making a copy of data whose resource representation is a +pointer. None of the Intrinsics-defined object classes copy +data in this manner. Any operation that modifies the queried +object resource may invalidate the pointed-to data. + + + +To retrieve the current values of resources associated with a widget +instance using varargs lists, use +. + + + + +void XtVaGetValues + Widget object + ... + + + + + + + object + + + +Specifies the object whose resource values are to be returned. Must be of class Object or any subclass thereof. + + + + + + ... + + + +Specifies the variable argument list for the resources to +be returned. + + + + + + + +is identical in function to + +with the args +and num_args 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 +XtVaTypedArg +is specified, the type argument +specifies the representation desired by the caller and the 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. + + +Widget Subpart Resource Data: The get_values_hook Procedure + +Widgets that have subparts can return resource values from them through + +by supplying a get_values_hook procedure. +The get_values_hook procedure pointer is of type +. + + + + +typedef void (*XtArgsProc) + + Widget w + ArgList args + Cardinal *num_args + + + + + + + w + + + +Specifies the widget whose subpart resource values are to be retrieved. + + + + + + args + + + +Specifies the argument list that was passed to + +or the transformed varargs list passed to +. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The widget with subpart resources should call + +in the get_values_hook procedure +and pass in its subresource list and the args and num_args parameters. + + + +Widget Subpart State + +To retrieve the current values of subpart resource data associated with a +widget instance, use +. +For a discussion of subpart resources, +see . + + + + +void XtGetSubvalues + XtPointer base + XtResourceList resources + Cardinal num_resources + ArgList args + Cardinal num_args + + + + + + + base + + + +Specifies the base address of the subpart data structure for which the +resources should be retrieved. + + + + + + resources + + + +Specifies the subpart resource list. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + args + + + +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. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +function obtains resource values from the structure identified by base. +The value 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. + + + +To retrieve the current values of subpart resources associated with +a widget instance using varargs lists, use +. + + + + +void XtVaGetSubvalues + XtPointer base + XtResourceList resources + Cardinal num_resources + ... + + + + + + + base + + + +Specifies the base address of the subpart data structure for which the +resources should be retrieved. + + + + + + resources + + + +Specifies the subpart resource list. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + ... + + + +Specifies a variable argument list of name/address pairs that +contain the resource names and the addresses into which the resource +values are to be stored. + + + + + + + +is identical in function to + +with the +args and num_args parameters replaced by a varargs list, as described +in Section 2.5.1. +XtVaTypedArg +is not supported for +. +If +XtVaTypedArg +is specified in the list, a warning message is issued +and the entry is then ignored. + + + + + +Setting Widget State + +To modify the current values of resources associated with a widget +instance, use +. + + + + +void XtSetValues + Widget object + ArgList args + Cardinal num_args + + + + + + + object + + + +Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof. + + + + + + args + + + +Specifies the argument list of name/value pairs that contain the +resources to be modified and their new values. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +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 object resource fields with any values +specified in the argument list. + +then calls the set_values procedures for the object in superclass-to-subclass +order. +If the object has any non-NULL set_values_hook fields, +these are called immediately after the +corresponding set_values procedure. +This procedure permits subclasses to set subpart data via +. + + + +If the class of the object's parent is a subclass of +constraintWidgetClass, + +also updates the object's constraints. +It starts with the constraint resources specified for +constraintWidgetClass +and proceeds down the subclass chain to the parent's class. +At each stage, it replaces the constraint resource fields with any +values specified in the argument list. +It then calls the constraint set_values procedures from +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. + + + +If the object is of a subclass of +RectObj, + +determines if a geometry request is needed by comparing the old object to +the new object. +If any geometry changes are required, + +restores the original geometry and makes the request on behalf of the widget. +If the geometry manager returns +XtGeometryYes, + +calls the object's resize procedure. +If the geometry manager returns +XtGeometryDone, + +continues, as the object's resize procedure should have been called +by the geometry manager. +If the geometry manager returns +XtGeometryNo, + +ignores the geometry request and continues. +If the geometry manager returns +XtGeometryAlmost, + +calls the set_values_almost procedure, +which determines what should be done. + +then repeats this process, +deciding once more whether the geometry manager should be called. + + + +Finally, if any of the set_values procedures returned +True, +and the widget is realized, + +causes the widget's expose procedure to be invoked by calling +XClearArea +on the widget's window. + + + +To modify the current values of resources associated with a widget +instance using varargs lists, use +. + + + + +void XtVaSetValues + Widget object + ... + + + + + + + object + + + +Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof. + + + + + + ... + + + +Specifies the variable argument list of name/value pairs that +contain the resources to be modified and their new values. + + + + + + + +is identical in function to + +with the args and num_args parameters replaced by a varargs list, as +described in Section 2.5.1. + + +Widget State: The set_values Procedure + +The set_values procedure pointer in a widget class is of type +. + + + + +typedef Boolean (*XtSetValuesFunc) + + Widget current + Widget request + Widget new + ArgList args + Cardinal *num_args + + + + + + + current + + + +Specifies a copy of the widget as it was before the + +call. + + + + + + request + + + +Specifies a copy of the widget with all values changed as asked for by the + +call before any class set_values procedures have been called. + + + + + + new + + + +Specifies the widget with the new values that are actually allowed. + + + + + + args + + + +Specifies the argument list passed to + +or the transformed argument list passed to +. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The set_values procedure should recompute any field +derived from resources that are changed +(for example, many GCs depend on foreground and background pixels). +If no 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 set_values field in the class record. + + + +Like the initialize procedure, +set_values mostly deals only with the fields defined in the subclass, +but it has to resolve conflicts with its superclass, +especially conflicts over width and height. + + + +Sometimes a subclass may want to overwrite values filled in by its +superclass. +In particular, size calculations of a superclass are often +incorrect for a subclass, and, in this case, +the subclass must modify or recalculate fields declared +and computed by its superclass. + + + +As an example, +a subclass can visually surround its 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? + + + +The request and new parameters provide the necessary information. +The request widget is a copy of the widget, updated as originally requested. +The new 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 request widget +unless it must resolve conflicts between the current and new widgets. +Any changes the widget needs to make, including geometry changes, +should be made in the new widget. + + + +In the above example, +the subclass with the visual surround can see +if the width and height in the request widget are zero. +If so, +it adds its surround size to the width and +height fields in the new widget. +If not, it must make do with the size originally specified. +In this case, zero is a special value defined by the class to permit +the application to invoke this behavior. + + + +The new widget is the actual widget instance record. +Therefore, +the set_values procedure should do all its work on the new widget; +the request widget should never be modified. +If the set_values procedure needs to call any routines that operate on +a widget, it should specify new as the widget instance. + + + +Before calling the set_values procedures, the Intrinsics modify the +resources of the request 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 args. + + + +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 +True; +the X server will eventually generate an +Expose +event, if necessary. +After calling all the set_values procedures, + +forces a redisplay by calling +XClearArea +if any of the set_values procedures returned +True. +Therefore, a set_values procedure should not try to do its own redisplaying. + + + +Set_values procedures should not do any work in response to changes in +geometry because + +eventually will perform a geometry request, and that request might be denied. +If the widget actually changes size in response to a +call to +, +its resize procedure is called. +Widgets should do any geometry-related work in their resize procedure. + + + +Note that it is permissible to call + +before a widget is realized. +Therefore, the set_values procedure must not assume that the widget is realized. + + + +Widget State: The set_values_almost Procedure + +The set_values_almost procedure pointer in the widget class record is of type +. + + + + +typedef void (*XtAlmostProc) + + Widget old + Widget new + XtWidgetGeometry *request + XtWidgetGeometry *reply + + + + + + + old + + + +Specifies a copy of the object as it was before the + +call. + + + + + + new + + + +Specifies the object instance record. + + + + + + request + + + +Specifies the original geometry request that was sent to the geometry +manager that caused +XtGeometryAlmost +to be returned. + + + + + + reply + + + +Specifies the compromise geometry that was returned by the geometry +manager with +XtGeometryAlmost. + + + + + + +Most classes inherit the set_values_almost procedure from their superclass by +specifying +XtInheritSetValuesAlmost +in the class initialization. +The +set_values_almost procedure in +rectObjClass +accepts the compromise suggested. + + + +The set_values_almost procedure is called when a client tries to set a widget's +geometry by means of a call to + +and the geometry manager cannot +satisfy the request but instead returns +XtGeometryNo +or +XtGeometryAlmost +and a compromise geometry. +The new object is the actual instance record. The x, y, +width, height, +and border_width fields contain the original values as they were +before the + +call, and all other fields contain the new +values. The request parameter contains the new geometry request that +was made to the parent. The reply parameter contains +reply->request_mode equal to zero if the parent returned +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 request 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 reply geometry into the request geometry; to attempt an +alternative geometry, the procedure may modify any part of the request +argument; to terminate the geometry negotiation and retain the +original geometry, the procedure must set request->request_mode to +zero. The geometry fields of the old and new instances must not be modified +directly. + + + +Widget State: The ConstraintClassPart set_values Procedure + +The constraint set_values procedure pointer is of type +. +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 set_values field of the +ConstraintPart +if it need not compute anything. + + + +The constraint set_values procedure should recompute any constraint fields +derived from constraint resources that are changed. +Furthermore, it may modify other widget fields as appropriate. +For example, if a constraint for the maximum height of a widget is changed +to a value smaller than the widget's current height, +the constraint set_values procedure may reset the height field in the +widget. + + + +Widget Subpart State + +To set the current values of subpart resources associated with a +widget instance, use +. +For a discussion of subpart resources, +see . + + + + +void XtSetSubvalues + XtPointer base + XtResourceList resources + Cardinal num_resources + ArgList args + Cardinal num_args + + + + + + + base + + + +Specifies the base address of the subpart data structure into which the +resources should be written. + + + + + + resources + + + +Specifies the subpart resource list. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + args + + + +Specifies the argument list of name/value pairs that contain the +resources to be modified and their new values. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +function updates the resource fields of the structure identified by +base. Any specified arguments that do not match an entry in the +resource list are silently ignored. + + + +To set the current values of subpart resources associated with +a widget instance using varargs lists, use +. + + + + +void XtVaSetSubvalues + XtPointer base + XtResourceList resources + Cardinal num_resources + + + + + + + base + + + +Specifies the base address of the subpart data structure into which the +resources should be written. + + + + + + resources + + + +Specifies the subpart resource list. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + ... + + + +Specifies the variable argument list of name/value pairs that +contain the resources to be modified and their new values. + + + + + + + +is identical in function to + +with the args and num_args parameters replaced by a varargs list, as +described in Section 2.5.1. +XtVaTypedArg +is not supported for +. +If an entry containing +XtVaTypedArg +is specified in the list, a warning message is issued +and the entry is ignored. + + + + +Widget Subpart Resource Data: The set_values_hook Procedure + +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. + + + +Widgets that have a subpart can set the subpart resource values through + +by supplying a set_values_hook procedure. +The set_values_hook procedure pointer in a widget class is of type +. + + + + +typedef Boolean (*XtArgsFunc) + Widget w + Arglist args + Cardinal *num_args + + + + + + + w + + + +Specifies the widget whose subpart resource values are to be changed. + + + + + + args + + + +Specifies the argument list that was passed to + +or the transformed varargs list passed to +. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The widget with subpart resources may call + +from the set_values_hook procedure +and pass in its subresource list and the +args and num_args parameters. + + + + + diff --git a/libXt/specs/CH10 b/libXt/specs/CH10 deleted file mode 100644 index b7c0139ca..000000000 --- a/libXt/specs/CH10 +++ /dev/null @@ -1,1521 +0,0 @@ -.\" $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 = - ": Highlight()\\n\\ - : Unhighlight()\\n\\ - : Set()\\n\\ - : 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/libXt/specs/CH10.xml b/libXt/specs/CH10.xml new file mode 100644 index 000000000..a96d2c427 --- /dev/null +++ b/libXt/specs/CH10.xml @@ -0,0 +1,2211 @@ + +Translation Management + +Except under unusual circumstances, +widgets do not hardwire the mapping of user events into widget behavior +by using the event manager. +Instead, they provide a default mapping of events into behavior +that you can override. + + + +The translation manager provides an interface to specify and manage the +mapping of X event sequences into widget-supplied functionality, +for example, calling procedure Abc when the y key +is pressed. + + + +The translation manager uses two kinds of tables to perform translations: + + + + +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. + + + + +A translation table, which is in the widget class structure, +specifies the mapping of event sequences to procedure name strings. + + + + +You can override the translation table in the class 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 . + + +Action Tables + +All widget class records contain an action table, +an array of +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 +. + + + + +typedef void (*XtActionProc) + Widget w + XEvent *event + String *params + Cardinal *num_params + + + + + + + w + + + +Specifies the widget that caused the action to be called. + + + + + + event + + + +Specifies the event that caused the action to be called. +If the action is called after a sequence of events, +then the last event in the sequence is used. + + + + + + params + + + +Specifies a pointer to the list of strings that were specified +in the translation table as arguments to the action, or NULL. + + + + + + num_params + + + +Specifies the number of entries in params. + + + + + + +typedef struct _XtActionsRec { + String string; + XtActionProc proc; +} XtActionsRec, *XtActionList; + + +The string field is the name used in translation tables to access +the procedure. +The proc field is a pointer to a procedure that implements +the functionality. + + + +When the action list is specified as the +CoreClassPart +actions field, the string pointed to by string must be +permanently allocated prior to or during the execution of the class +initialization procedure and must not be subsequently deallocated. + + + +Action procedures should not assume that the widget in which they +are invoked is realized; an accelerator specification can cause +an action procedure to be called for a widget that does not yet +have a window. Widget writers should also note which of a widget's +callback lists are invoked from action procedures and warn clients +not to assume the widget is realized in those callbacks. + + + +For example, a Pushbutton widget has procedures to take the following actions: + + + + +Set the button to indicate it is activated. + + + + +Unset the button back to its normal mode. + + + + +Highlight the button borders. + + + + +Unhighlight the button borders. + + + + +Notify any callbacks that the button has been activated. + + + + +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: + + +XtActionsRec actionTable[] = { + {"Set", Set}, + {"Unset", Unset}, + {"Highlight", Highlight}, + {"Unhighlight", Unhighlight} + {"Notify", Notify}, +}; + + +The Intrinsics reserve all action names and parameters starting with +the characters ``Xt'' for future standard enhancements. Users, +applications, and widgets should not declare action names or pass +parameters starting with these characters except to invoke specified +built-in Intrinsics functions. + + +Action Table Registration + +The actions and num_actions fields of +CoreClassPart +specify the actions implemented by a widget class. These are +automatically registered with the Intrinsics when the class is initialized +and must be allocated in writable storage prior to Core class_part +initialization, and never deallocated. To save memory and optimize +access, the Intrinsics may overwrite the storage in order to compile the +list into an internal representation. + + + +To declare an action table within an application +and register it with the translation manager, use +. + + + + +void XtAppAddActions + XtAppContext app_context + XtActionList actions + Cardinal num_actions + + + + + + + app_context + + + +Specifies the application context. + + + + + + actions + + + +Specifies the action table to register. + + + + + + num_actions + + + +Specifies the number of entries in this action table. + + + + + + +If more than one action is registered with the same name, +the most recently registered action is used. +If duplicate actions exist in an action table, +the first is used. +The Intrinsics register an action table containing + +and + +as part of +. + + + + +Action Names to Procedure Translations + +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: + + + + +The widget's class and all superclass action tables, in subclass-to-superclass +order. + + + + +The parent's class and all superclass action tables, in subclass-to-superclass +order, then on up the ancestor tree. + + + + +The action tables registered with + +and + +from the most recently added table to the oldest table. + + + + +As soon as it finds a name, +the translation manager stops the search. +If it cannot find a name, +the translation manager generates a warning message. + + + + +Action Hook Registration + +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 +. + + + + +typedef void (*XtActionHookProc) + Widget w + XtPointer client_data + String action_name + XEvent* event + String* params + Cardinal* num_params + + + + + + + + + w + + + +Specifies the widget whose action is about to be dispatched. + + + + + + client_data + + + +Specifies the application-specific closure that was passed to +XtAppAddActionHook. + + + + + + action_name + + + +Specifies the name of the action to be dispatched. + + + + + + event + + + +Specifies the event argument that will be passed to the action routine. + + + + + + params + + + +Specifies the action parameters that will be passed to the action routine. + + + + + + num_params + + + +Specifies the number of entries in params. + + + + + + +Action hooks should not modify any of the data pointed to by the +arguments other than the client_data argument. + + + +To add an action hook, use +. + + + + +XtActionHookId XtAppAddActionHook + XtAppContext app + XtActionHookProc proc + XtPointer client_data + + + + + + + app + + + +Specifies the application context. + + + + + + proc + + + +Specifies the action hook procedure. + + + + + + client_data + + + +Specifies application-specific data to be passed to the action hook. + + + + + + + +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 +, +the action hook procedures will be called in reverse +order of registration just prior to invoking the action routine. + + + +Action hook procedures are removed automatically and the +XtActionHookId is +destroyed when the application context in which +they were added is destroyed. + + + +To remove an action hook procedure without destroying the application +context, use +. + + + + +void XtRemoveActionHook + XtActionHookId id + + + + + + + id + + + +Specifies the action hook id returned by +. + + + + + + + +removes the specified action hook procedure from +the list in which it was registered. + + + + + +Translation Tables + +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. + + + +As an example, the default behavior of Pushbutton is + + + + +Highlight on enter window. + + + + +Unhighlight on exit window. + + + + +Invert on left button down. + + + + +Call callbacks and reinvert on left button up. + + + + +The following illustrates Pushbutton's default translation table: + + +static String defaultTranslations = + "<EnterWindow>: Highlight()\\n\\ + <LeaveWindow>: Unhighlight()\\n\\ + <Btn1Down>: Set()\\n\\ + <Btn1Up>: Notify() Unset()"; + + +The tm_table field of the +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 +XtInheritTranslations +into tm_table. +In Core's class part initialization procedure, +the Intrinsics compile this translation table into an efficient internal form. +Then, at widget creation time, +this default translation table is +combined with the XtNtranslations +and XtNbaseTranslations resources; see +. + + + +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 +. + + + +The Intrinsics use the compiled form of the translation table to register the +necessary events with the event manager. +Widgets need do nothing other than specify the action and translation tables +for events to be processed by the translation manager. + + +Event Sequences + +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. + + + +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. + + + + +Action Sequences + +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. + + + + +Multi-Click Time + +Translation table entries may specify actions that are taken when two +or more identical events occur consecutively within a short time +interval, called the multi-click time. The multi-click time value may +be specified as an application resource with name ``multiClickTime'' and +class ``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 +. +If no value is specified, the initial value is 200 milliseconds. + + + +To set the multi-click time dynamically, use +. + + + + +void XtSetMultiClickTime + Display *display + int time + + + + + + + display + + + +Specifies the display connection. + + + + + + time + + + +Specifies the multi-click time in milliseconds. + + + + + + + +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 +ButtonPress +events) must be less than the +multi-click time in order for the translation actions to be taken. + + + +To read the multi-click time, use +. + + + + +int XtGetMultiClickTime + Display *display + + + + + + + display + + + +Specifies the display connection. + + + + + + + +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. + + + + + +Translation Table Management + +Sometimes an application needs to merge +its own translations with a widget's translations. +For example, a window manager provides functions to move a window. +The window manager wishes to bind this operation to a specific +pointer button in the title bar without the possibility of user +override and bind it to other buttons that may be overridden by the user. + + + +To accomplish this, +the window manager should first create the title bar +and then should merge the two translation tables into +the title bar's translations. +One translation table contains the translations that the window manager +wants only if the user has not specified a translation for a particular event +or event sequence (i.e., those that may be overridden). +The other translation table contains the translations that the +window manager wants regardless of what the user has specified. + + + +Three Intrinsics functions support this merging: + + + + + + XtParseTranslationTable + + + Compiles a translation table. + + + + + XtAugmentTranslations + + + Merges a compiled translation table into a widget's + compiled translation table, ignoring any new translations that + conflict with existing translations. + + + + + + XtOverrideTranslations + + + Merges a compiled translation table into a widget's + compiled translation table, replacing any existing translations that + conflict with new translations. + + + + + + +To compile a translation table, use +. + + + + +XtTranslations XtParseTranslationTable + String table + + + + + + + table + + + +Specifies the translation table to compile. + + + + + + +The + +function compiles the translation table, provided in the format given +in Appendix B, into an opaque internal representation +of type +XtTranslations. +Note that if an empty translation table is required for any purpose, +one can be obtained by calling + +and passing an empty string. + + + +To merge additional translations into an existing translation table, use +. + + + + +void XtAugmentTranslations + Widget w + XtTranslations translations + + + + + + + w + + + +Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof. + + + + + + translations + + + +Specifies the compiled translation table to merge in. + + + + + + +The + +function merges the new translations into the existing widget +translations, ignoring any +#replace, +#augment, +or +#override +directive that may have been specified +in the translation string. The translation table specified by +translations is not altered by this process. + +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. + + + +To overwrite existing translations with new translations, use +. + + + + +void XtOverrideTranslations + Widget w + XtTranslations translations + + + + + + + w + + + +Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof. + + + + + + translations + + + +Specifies the compiled translation table to merge in. + + + + + + +The + +function merges the new translations into the existing widget +translations, ignoring any +#replace, +#augment, +or +#override +directive that may have been +specified in the translation string. The translation table +specified by translations is not altered by this process. + +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. + + + +To replace a widget's translations completely, use + +on the XtNtranslations resource and specify a compiled translation table +as the value. + + + +To make it possible for users to easily modify translation tables in their +resource files, +the string-to-translation-table resource type converter +allows the string to specify whether the table should replace, +augment, or override any +existing translation table in the widget. +To specify this, +a pound sign (#) is given as the first character of the 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. + + + +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 translations 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 translations field. If the XtNtranslations +resource specified ``#replace'', no merge is done. +If neither XtNbaseTranslations or XtNtranslations are specified, +the class translation table is copied into the widget instance. + + + +To completely remove existing translations, use +. + + + + +void XtUninstallTranslations + Widget w + + + + + + + w + + + +Specifies the widget from which the translations are to be removed. Must be of class Core or any subclass thereof. + + + + + + +The + +function causes the entire translation table for the widget to be removed. + + + + +Using Accelerators + +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 Intrinsics provide a facility, called accelerators, that lets you +accomplish this. +An accelerator table is a translation table that is bound with its +actions in the context of a particular widget, the source widget. +The accelerator table can then be installed on one or more destination 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. + + + +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 +. + + + + +typedef void (*XtStringProc) + Widget w + String string + + + + + + + w + + + +Specifies the source widget that supplied the accelerators. + + + + + + string + + + +Specifies the string representation of the accelerators for this widget. + + + + + + +Accelerators can be specified in resource files, +and the string representation is the same as for a translation table. +However, +the interpretation of the +#augment +and +#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 +#augment, +which means that the accelerator translations have lower priority +than the destination translations. +The +#replace +directive is ignored for accelerator tables. + + + +To parse an accelerator table, use +. + + + + +XtAccelerators XtParseAcceleratorTable + String source + + + + + + + source + + + +Specifies the accelerator table to compile. + + + + + + +The + +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. + + + +To install accelerators from a widget on another widget, use +. + + + + +void XtInstallAccelerators + Widget destination + Widget source + + + + + + + destination + + + +Specifies the widget on which the accelerators are to be installed. Must be of class Core or any subclass thereof. + + + + + + source + + + +Specifies the widget from which the accelerators are to come. Must be of class Core or any subclass thereof. + + + + + + +The + +function installs the accelerators resource value from +source onto destination +by merging the source accelerators into the destination translations. +If the source display_accelerator field is non-NULL, + +calls it with the source widget and a string representation +of the accelerator table, +which indicates that its accelerators have been installed +and that it should display them appropriately. +The string representation of the accelerator table is its +canonical translation table representation. + + + +As a convenience for installing all accelerators from a widget and all its +descendants onto one destination, use +. + + + + +void XtInstallAllAccelerators + Widget destination + Widget source + + + + + + + destination + + + +Specifies the widget on which the accelerators are to be installed. Must be of class Core or any subclass thereof. + + + + + + source + + + +Specifies the root widget of the widget tree +from which the accelerators are to come. Must be of class Core or any subclass thereof. + + + + + + +The + +function recursively descends the widget tree rooted at source +and installs the accelerators resource value +of each widget encountered onto destination. +A common use is to call + +and pass the application main window as the source. + + + + +KeyCode-to-KeySym Conversions + +The translation manager provides support for automatically translating +KeyCodes in incoming key events into KeySyms. +KeyCode-to-KeySym translator procedure pointers are of type +. + + + + +typedef void (*XtKeyProc) + Display *display + KeyCode keycode + Modifiers modifiers + Modifiers *modifiers_return + KeySym *keysym_return + + + + + + + display + + + +Specifies the display that the KeyCode is from. + + + + + + keycode + + + +Specifies the KeyCode to translate. + + + + + + modifiers + + + +Specifies the modifiers to the KeyCode. + + + + + + modifiers_return + + + +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. + + + + + + keysym_return + + + +Specifies a location in which to store the resulting KeySym. + + + + + + +This procedure takes a KeyCode and modifiers and produces a KeySym. +For any given key translator function and keyboard encoding, +modifiers_return will be a constant per KeyCode that indicates +the subset of all modifiers that are examined by the key translator +for that KeyCode. + + + +The KeyCode-to-KeySym translator procedure +must be implemented such that multiple calls with the same +display, keycode, and modifiers return the same +result until either a new case converter, an +, +is installed or a +MappingNotify +event is received. + + + +The Intrinsics maintain tables internally to map KeyCodes to KeySyms +for each open display. Translator procedures and other clients may +share a single copy of this table to perform the same mapping. + + + +To return a pointer to the KeySym-to-KeyCode mapping table for a +particular display, use +. + + + + +KeySym *XtGetKeysymTable + Display *display + KeyCode *min_keycode_return + int *keysyms_per_keycode_return + + + + + + + display + + + +Specifies the display whose table is required. + + + + + + min_keycode_return + + + +Returns the minimum KeyCode valid for the display. + + + + + + keysyms_per_keycode_return + + + +Returns the number of KeySyms stored for each KeyCode. + + + + + + + +returns a pointer to the Intrinsics' copy of the +server's KeyCode-to-KeySym table. This table must not be modified. +There are keysyms_per_keycode_return KeySyms associated with each +KeyCode, located in the table with indices starting at index + + + (test_keycode - min_keycode_return) * keysyms_per_keycode_return + + +for KeyCode test_keycode. Any entries that have no KeySyms associated +with them contain the value +NoSymbol. +Clients should not cache the KeySym table but should call + +each time the value is +needed, as the table may change prior to dispatching each event. + + + +For more information on this table, see +Section 12.7 in +Xlib — C Language X Interface.. + + + +To register a key translator, use +. + + + + +void XtSetKeyTranslator + Display *display + XtKeyProc proc + + + + + + + display + + + +Specifies the display from which to translate the events. + + + + + + proc + + + +Specifies the procedure to perform key translations. + + + + + + +The + +function sets the specified procedure as the current key translator. +The default translator is +XtTranslateKey, +an + +that uses the Shift, Lock, numlock, and group modifiers +with the interpretations defined in X Window System Protocol, Section 5. +It is provided so that new translators can call it to get default +KeyCode-to-KeySym translations and so that the default translator +can be reinstalled. + + + +To invoke the currently registered KeyCode-to-KeySym translator, +use +. + + + + +void XtTranslateKeycode + Display *display + KeyCode keycode + Modifiers modifiers + Modifiers *modifiers_return + KeySym *keysym_return + + + + + + + display + + + +Specifies the display that the KeyCode is from. + + + + + + keycode + + + +Specifies the KeyCode to translate. + + + + + + modifiers + + + +Specifies the modifiers to the KeyCode. + + + + + + modifiers_return + + + +Returns a mask that indicates the modifiers actually used +to generate the KeySym. + + + + + + keysym_return + + + +Returns the resulting KeySym. + + + + + + +The + +function passes the specified arguments +directly to the currently registered KeyCode-to-KeySym translator. + + + +To handle capitalization of nonstandard KeySyms, the Intrinsics allow +clients to register case conversion routines. +Case converter procedure pointers are of type +. + + + + +typedef void (*XtCaseProc) + Display *display + KeySym keysym + KeySym *lower_return + KeySym *upper_return + + + + + + + display + + + +Specifies the display connection for which the conversion is required. + + + + + + keysym + + + +Specifies the KeySym to convert. + + + + + + lower_return + + + +Specifies a location into which to store the lowercase equivalent for +the KeySym. + + + + + + upper_return + + + +Specifies a location into which to store the uppercase equivalent for +the KeySym. + + + + + + +If there is no case distinction, +this procedure should store the KeySym into both return values. + + + +To register a case converter, use +. + + + + +void XtRegisterCaseConverter + Display *display + XtCaseProc proc + KeySym start + KeySym stop + + + + + + + display + + + +Specifies the display from which the key events are to come. + + + + + + proc + + + +Specifies the + +to do the conversions. + + + + + + start + + + +Specifies the first KeySym for which this converter is valid. + + + + + + stop + + + +Specifies the last KeySym for which this converter is valid. + + + + + + +The + +registers the specified case converter. +The start and stop 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 Intrinsics refresh the keyboard state if necessary. +The default converter understands case conversion for all +Latin KeySyms defined in X Window System Protocol, Appendix A. + + + +To determine uppercase and lowercase equivalents for a KeySym, use +. + + + + +void XtConvertCase + Display *display + KeySym keysym + KeySym *lower_return + KeySym *upper_return + + + + + + + display + + + +Specifies the display that the KeySym came from. + + + + + + keysym + + + +Specifies the KeySym to convert. + + + + + + lower_return + + + +Returns the lowercase equivalent of the KeySym. + + + + + + upper_return + + + +Returns the uppercase equivalent of the KeySym. + + + + + + +The + +function calls the appropriate converter and returns the results. +A user-supplied + +may need to use this function. + + + + +Obtaining a KeySym in an Action Procedure + +When an action procedure is invoked on a +KeyPress +or +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 +Intrinsics 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. + + + +To retrieve the KeySym and modifiers that matched the final event +specification in the translation table entry, use +. + + + + +KeySym XtGetActionKeysym + XEvent *event + Modifiers *modifiers_return + + + + + + + event + + + +Specifies the event pointer passed to the action procedure by the Intrinsics. + + + + + + modifiers_return + + + +Returns the modifiers that caused the match, if non-NULL. + + + + + + +If + +is called after an action procedure has been +invoked by the Intrinsics 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 +KeyPress +or +KeyRelease +event, then + +returns the KeySym that matched the final +event specification in the translation table and, if modifiers_return +is non-NULL, the modifier state actually used to generate this KeySym; +otherwise, if the event is a +KeyPress +or +KeyRelease +event, then + +calls + +and returns the results; +else it returns +NoSymbol +and does not examine modifiers_return. + + + +Note that if an action procedure invoked by the Intrinsics +invokes a subsequent action procedure (and so on) via +, +the nested action procedure may also call + +to retrieve the Intrinsics' KeySym and modifiers. + + + + +KeySym-to-KeyCode Conversions + +To return the list of KeyCodes that map to a particular KeySym in +the keyboard mapping table maintained by the Intrinsics, use +. + + + + +void XtKeysymToKeycodeList + Display *display + KeySym keysym + KeyCode **keycodes_return + Cardinal *keycount_return + + + + + + + display + + + +Specifies the display whose table is required. + + + + + + keysym + + + +Specifies the KeySym for which to search. + + + + + + keycodes_return + + + +Returns a list of KeyCodes that have keysym +associated with them, or NULL if keycount_return is 0. + + + + + + keycount_return + + + +Returns the number of KeyCodes in the keycode list. + + + + + + +The + +procedure returns all the KeyCodes that have keysym +in their entry for the keyboard mapping table associated with display. +For each entry in the +table, the first four KeySyms (groups 1 and 2) are interpreted as +specified by X Window System Protocol, Section 5. If no KeyCodes map to the +specified KeySym, keycount_return is zero and *keycodes_return is NULL. + + + +The caller should free the storage pointed to by keycodes_return using + +when it is no longer useful. If the caller needs to examine +the KeyCode-to-KeySym table for a particular KeyCode, it should call +. + + + + +Registering Button and Key Grabs for Actions + +To register button and key grabs for a widget's window according to the +event bindings in the widget's translation table, use +. + + + + +void XtRegisterGrabAction + XtActionProc action_proc + Boolean owner_events + unsigned int event_mask + int pointer_mode + + + + + + + action_proc + + + +Specifies the action procedure to search for in translation tables. + + + + + + owner_events + + + + + + + + + event_mask + + + + + + + + + pointer_mode + + + + + + + + keyboard_mode + + + +Specify arguments to + +or +. + + + + + + + +adds the specified action_proc 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 +ButtonPress +or +KeyPress +events as the only or final event +in a sequence, the Intrinsics will call + +or + +for the widget with every button or KeyCode which maps to the +event detail field, passing the specified owner_events, event_mask, +pointer_mode, and keyboard_mode. For +ButtonPress +events, the modifiers +specified in the grab are determined directly from the translation +specification and confine_to and cursor are specified as +None. +For +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 + +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 event_mask 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 +ButtonPress +and +KeyPress +events, don't-care modifiers are ignored unless the translation entry +explicitly specifies ``Any'' in the modifiers field. + + + +If the specified action_proc 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. + + + +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 + +or +. + + + + +Invoking Actions Directly + +Normally action procedures are invoked by the Intrinsics when an +event or event sequence arrives for a widget. To +invoke an action procedure directly, without generating +(or synthesizing) events, use +. + + + + +void XtCallActionProc + Widget widget + String action + XEvent *event + String *params + Cardinal num_params + + + + + + + widget + + + +Specifies the widget in which the action is to be invoked. Must be of class Core or any subclass thereof. + + + + + + action + + + +Specifies the name of the action routine. + + + + + + event + + + +Specifies the contents of the event passed to the action routine. + + + + + + params + + + +Specifies the contents of the params passed to the action routine. + + + + + + num_params + + + +Specifies the number of entries in params. + + + + + + + +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 +. +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 event, params, and num_params 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, + +generates a warning message and returns. + + + + +Obtaining a Widget's Action List + +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 +actions field, use +. + + + + +void XtGetActionList + WidgetClass widget_class + XtActionList *actions_return + Cardinal *num_actions_return + + + + + + + widget_class + + + +Specifies the widget class whose actions are to be returned. + + + + + + actions_return + + + +Returns the action list. + + + + + + num_actions_return + + + +Returns the number of action procedures declared by the class. + + + + + + + +returns the action table defined by the specified +widget class. This table does not include actions defined by the +superclasses. If widget_class is not initialized, or is not +coreWidgetClass +or a subclass thereof, or if the class does not define any actions, +*actions_return will be NULL and *num_actions_return +will be zero. +If *actions_return is non-NULL the client is responsible for freeing +the table using + +when it is no longer needed. + + + diff --git a/libXt/specs/CH11 b/libXt/specs/CH11 deleted file mode 100644 index 55b8d92f3..000000000 --- a/libXt/specs/CH11 +++ /dev/null @@ -1,3566 +0,0 @@ -.\" $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/libXt/specs/CH11.xml b/libXt/specs/CH11.xml new file mode 100644 index 000000000..92e46dc57 --- /dev/null +++ b/libXt/specs/CH11.xml @@ -0,0 +1,5538 @@ + +Utility Functions + +The Intrinsics provide a number of utility functions that you can use to + + + + +Determine the number of elements in an array. + + + + +Translate strings to widget instances. + + + + +Manage memory usage. + + + + +Share graphics contexts. + + + + +Manipulate selections. + + + + +Merge exposure events into a region. + + + + +Translate widget coordinates. + + + + +Locate a widget given a window id. + + + + +Handle errors. + + + + +Set the WM_COLORMAP_WINDOWS property. + + + + +Locate files by name with string substitutions. + + + + +Register callback functions for external agents. + + + + +Locate all the displays of an application context. + + + + + +Determining the Number of Elements in an Array + +To determine the number of elements in a fixed-size array, use +. + + + + +Cardinal XtNumber + ArrayType array + + + + + + + array + + + +Specifies a fixed-size array of arbitrary type. + + + + + + +The + +macro returns the number of elements allocated to the array. + + + + +Translating Strings to Widget Instances + +To translate a widget name to a widget instance, use +. + + + + +Widget XtNameToWidget + Widget reference + String names + + + + + + + reference + + + +Specifies the widget from which the search is to start. Must be of class Core or any subclass thereof. + + + + + + names + + + +Specifies the partially qualified name of the desired widget. + + + + + + +The + +function searches for a descendant of the reference +widget whose name matches the specified names. The names parameter +specifies a simple object name or a series of simple object name +components separated by periods or asterisks. + +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 : + + + + +Enumerate the object subtree rooted at the reference widget in +breadth-first order, qualifying the name of each object with the +names of all its ancestors up to, but not including, the reference +widget. The ordering between children of a common parent is +not defined. + + + + +Return the first object in the enumeration that matches the +specified name, where each component of names matches exactly the +corresponding component of the qualified object name and asterisk +matches any series of components, including none. + + + + +If no match is found, return NULL. + + + + +Since breadth-first traversal is specified, the descendant with the +shortest matching name (i.e., the fewest number of components), if any, +will always be returned. However, since the order of enumeration of +children is undefined and since the Intrinsics do not require that all +children of a widget have unique names, + +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. + + + + +Managing Memory Usage + +The Intrinsics 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 +malloc, +calloc, +realloc, +and +free +with the following added functionality: + + + + +, +, +and + +give an error if there is not enough memory. + + + + + +simply returns if passed a NULL pointer. + + + + + +simply allocates new storage if passed a NULL pointer. + + + + +See the standard C library documentation on +malloc, +calloc, +realloc, +and +free +for more information. + + + +To allocate storage, use +. + + + + +char * XtMalloc + Cardinal size + + + + + + + size + + + +Specifies the number of bytes desired. + + + + + + +The + +function returns a pointer to a block of storage of at least +the specified size bytes. +If there is insufficient memory to allocate the new block, + +calls +. + + + +To allocate and initialize an array, use +. + + + + +char * XtCalloc + Cardinal num + Cardinal size + + + + + + + num + + + +Specifies the number of array elements to allocate. + + + + + + size + + + +Specifies the size of each array element in bytes. + + + + + + +The + +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, + +calls +. + +returns the address of the allocated storage. + + + +To change the size of an allocated block of storage, use +. + + + + +char *XtRealloc + char *ptr + Cardinal num + + + + + + + ptr + + + +Specifies a pointer to the old storage allocated with +, +, +or +, +or NULL. + + + + + + num + + + +Specifies number of bytes desired in new storage. + + + + + + +The + +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, + +calls +. +If ptr is NULL, + +simply calls +. + +then returns the address of the new block. + + + +To free an allocated block of storage, use +. + + + + +void XtFree + char *ptr + + + + + + + ptr + + + +Specifies a pointer to a block of storage allocated with +, +, +or +, +or NULL. + + + + + + +The + +function returns storage, allowing it to be reused. +If ptr is NULL, + +returns immediately. + + + +To allocate storage for a new instance of a type, use +. + + + + + +type XtNew + type t + + + + + + + type + + + +Specifies a previously declared type. + + + + + + + +returns a pointer to the allocated storage. +If there is insufficient memory to allocate the new block, + +calls +. + +is a convenience macro that calls + +with the following arguments specified: + + +((type *) XtMalloc((unsigned) sizeof(type))) + + +The storage allocated by + +should be freed using +. + + + +To copy an instance of a string, use +. + + + + +String XtNewString + String string + + + + + + + string + + + +Specifies a previously declared string. + + + + + + + +returns a pointer to the allocated storage. +If there is insufficient memory to allocate the new block, + +calls +. + +is a convenience macro that calls + +with the following arguments specified: + + +(strcpy(XtMalloc((unsigned)strlen(str) + 1), str)) + + +The storage allocated by + +should be freed using +. + + + + +Sharing Graphics Contexts + +The Intrinsics provide a mechanism whereby cooperating objects can share a +graphics context (GC), thereby reducing both the number of GCs +created and the total number of server calls in any given application. +The mechanism is a simple caching scheme +and allows for clients to declare both modifiable and nonmodifiable +fields of the shared GCs. + + + +To obtain a shareable GC with modifiable fields, use +. + + + + +GC XtAllocateGC + Widget object + Cardinal depth + XtGCMask value_mask + XGCValues *values + XtGCMask dynamic_mask + XtGCMask unused_mask + + + + + + + object + + + +Specifies an object, giving the screen for which the +returned GC is valid. Must be of class Object or any subclass thereof. + + + + + + depth + + + +Specifies the depth for which the returned GC is valid, or 0. + + + + + + value_mask + + + +Specifies fields of the GC that are initialized from values. + + + + + + values + + + +Specifies the values for the initialized fields. + + + + + + dynamic_mask + + + +Specifies fields of the GC that will be modified by the caller. + + + + + + unused_mask + + + +Specifies fields of the GC that will not be needed by the caller. + + + + + + +The + +function returns a shareable GC that may be +modified by the client. The screen field of the specified +widget or of the nearest widget ancestor of the specified +object and the specified depth argument supply +the root and drawable depths for which the GC is to be +valid. If depth is zero, the depth is taken from the +depth field of the specified widget or of the nearest +widget ancestor of the specified object. + + + +The value_mask argument specifies fields of the GC +that are initialized with the respective member of the +values structure. The dynamic_mask 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 unused_mask 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 unused_mask. The caller may assume +that at all times all fields not specified in either +dynamic_mask or unused_mask have their default value if not +specified in value_mask or the value specified by values. +If a field is specified in both value_mask and dynamic_mask, +the effect is as if it were specified only in dynamic_mask +and then immediately set to the value in values. If a field +is set in unused_mask and also in either value_mask or +dynamic_mask, the specification in unused_mask is ignored. + + + + +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. + +may modify and return an existing GC if it was allocated with a +nonzero unused_mask. + + + +To obtain a shareable GC with no modifiable fields, use +. + + + + +GC XtGetGC + Widget object + XtGCMask value_mask + XGCValues *values + + + + + + + object + + + +Specifies an object, giving the screen and depth for which the +returned GC is valid. Must be of class Object or any subclass thereof. + + + + + + value_mask + + + +Specifies which fields of the values structure are specified. + + + + + + values + + + +Specifies the actual values for this GC. + + + + + + +The + +function returns a shareable, read-only GC. +The parameters to this function are the same as those for +XCreateGC +except that an Object is passed instead of a Display. + +is equivalent to + +with depth, dynamic_mask, and unused_mask all zero. + + + + +shares only GCs in which all values in the GC returned by +XCreateGC +are the same. +In particular, it does not use the value_mask provided to +determine which fields of the GC a widget considers relevant. +The value_mask is used only to tell the server which fields should be +filled in from values and which it should fill in with default values. + + + +To deallocate a shared GC when it is no longer needed, use +. + + + + +void XtReleaseGC + Widget object + GC gc + + + + + + + object + + + +Specifies any object on the Display for which the GC was created. Must be of class Object or any subclass thereof. + + + + + + gc + + + +Specifies the shared GC obtained with either + +or +. + + + + + + +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. + + + + +Managing Selections + +Arbitrary widgets in multiple applications can communicate +with each other by means of the Intrinsics global selection mechanism, +which conforms to the specifications in the Inter-Client Communication Conventions Manual.. +The Intrinsics supply functions for providing and receiving selection data in +one logical piece (atomic transfers) +or in smaller logical segments (incremental transfers). + + + +The incremental interface is provided for a selection owner or +selection requestor that cannot or prefers not to pass the selection +value to and from the Intrinsics in a single call. For instance, +either an application that is running on a machine with limited memory +may not be able to store the entire selection value in memory or a +selection owner may already have the selection value available in +discrete chunks, and it would be more efficient not to have to +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 Intrinsics is not +required to match the underlying +transport protocol between the application and the X server; +the Intrinsics 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. + + + +Setting and Getting the Selection Timeout Value + +To set the Intrinsics selection timeout, use +. + + + + +void XtAppSetSelectionTimeout + XtAppContext app_context + unsigned long timeout + + + + + + + app_context + + + +Specifies the application context. + + + + + + timeout + + + +Specifies the selection timeout in milliseconds. + + + + + + +To get the current selection timeout value, use +. + + + + +unsigned long XtAppGetSelectionTimeout + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context. + + + + + + +The + +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 +application resource as retrieved by +. +If +selectionTimeout +is not specified, +the default is five seconds. + + + + +Using Atomic Transfers + +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. + + + +Atomic Transfer Procedures + +The following procedures are used by the selection owner when +providing selection data in a single unit. + + + +The procedure pointer specified by the owner to supply the selection +data to the Intrinsics is of type +. + + + + +typedef Boolean (*XtConvertSelectionProc) + Widget w + Atom *selection + Atom *target + Atom *type_return + XtPointer *value_return + unsigned long *length_return + int *format_return + + + + + + + w + + + +Specifies the widget that currently owns this selection. + + + + + + selection + + + +Specifies the atom naming the selection requested +(for example, +XA_PRIMARY +or +XA_SECONDARY ). + + + + + + target + + + +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). + + + + + + type_return + + + +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 +XA_STRING. + + + + + + value_return + + + +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 + +for the selection, +this storage is owned by the selection owner; +otherwise, it is owned by the Intrinsics selection mechanism, +which frees it by calling + +when it is done with it. + + + + + + length_return + + + +Specifies a pointer into which the number of elements in value_return, +each of size indicated by format_return, is to be stored. + + + + + + format_return + + + +Specifies a pointer into which the size in bits of the data elements +of the selection value is to be stored. + + + + + + +This procedure is called by the Intrinsics selection mechanism +to get the value of a selection as a given type +from the current selection owner. +It returns +True +if the owner successfully converted the selection to the target type or +False +otherwise. +If the procedure returns +False, +the values of the return arguments are undefined. +Each + +should respond to target value +TARGETS +by returning a value containing the list of the targets +into which it is +prepared to convert the selection. +The value returned in +format_return must be one of 8, 16, or 32 to allow the server to +byte-swap the data if necessary. + + + +This procedure does not need to worry about responding to the +MULTIPLE or the TIMESTAMP target values (see + +in the Inter-Client Communication Conventions Manual.). +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 Intrinsics using the time specified in the +call to + +or +. + + + +To retrieve the +SelectionRequest +event that triggered the + +procedure, use +. + + + + +XSelectionRequestEvent *XtGetSelectionRequest + Widget w + Atom selection + XtRequestId request_id + + + + + + + w + + + +Specifies the widget that currently owns this selection. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the selection being processed. + + + + + + request_id + + + +Specifies the requestor id in the case of incremental +selections, or NULL in the case of atomic transfers. + + + + + + + +may be called only from within an + +procedure and returns a pointer to the +SelectionRequest +event that caused the conversion procedure to be invoked. +Request_id specifies a unique id for the individual request in the +case that multiple incremental transfers are outstanding. For atomic +transfers, request_id must be specified as NULL. If no +SelectionRequest +event is being processed for the specified +widget, selection, and request_id, + +returns NULL. + + + +The procedure pointer specified by the owner when it desires +notification upon losing ownership is of type +. + + + + +typedef void (*XtLoseSelectionProc) + Widget w + Atom *selection + + + + + + + w + + + +Specifies the widget that has lost selection ownership. + + + + + + selection + + + +Specifies the atom naming the selection. + + + + + + +This procedure is called by the Intrinsics 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. + + + +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 +. + + + + +typedef void (*XtSelectionDoneProc) + Widget w + Atom *selection + Atom *target + + + + + + + w + + + +Specifies the widget that owns the converted selection. + + + + + + selection + + + +Specifies the atom naming the selection that was converted. + + + + + + target + + + +Specifies the target type to which the conversion was done. + + + + + + +This procedure is called by the Intrinsics selection mechanism +to inform the selection owner that a selection requestor has successfully +retrieved a selection value. +If the selection owner has registered an +, +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 +, +it also owns the storage containing the converted +selection value. + + + +Getting the Selection Value + +The procedure pointer specified by the requestor to receive the +selection data from the Intrinsics is of type +. + + + + +typedef void (*XtSelectionCallbackPro) + Widget w + XtPointer client_data + Atom *selection + Atom *type + XtPointer value + unsigned long *length + int *format + + + + + + + w + + + +Specifies the widget that requested the selection value. + + + + + + client_data + + + +Specifies a value passed in by the widget when it requested the +selection. + + + + + + selection + + + +Specifies the name of the selection that was requested. + + + + + + type + + + +Specifies the representation type of the selection value (for example, +XA_STRING ). +Note that it is not the target that was requested (which the client +must remember for itself), but the type that +is used to represent the target. +The special symbolic constant +XT_CONVERT_FAIL +is used to indicate that the selection conversion failed because the +selection owner did not respond within the Intrinsics selection timeout +interval. + + + + + + value + + + +Specifies a pointer to the selection value. +The requesting client owns this storage and is responsible for freeing it +by calling + +when it is done with it. + + + + + + length + + + +Specifies the number of elements in value. + + + + + + format + + + +Specifies the size in bits of the data in each element of value. + + + + + + +This procedure is called by the Intrinsics selection mechanism to deliver the +requested selection to the requestor. + + + +If the +SelectionNotify +event returns a property of +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. + + + +To obtain the selection value in a single logical unit, use + +or +. + + + + +void XtGetSelectionValue + Widget w + Atom selection + Atom target + XtSelectionCallbackProc callback + XtPointer client_data + Time time + + + + + + + w + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the particular selection desired; for example, +XA_PRIMARY. + + + + + + target + + + +Specifies the type of information needed about the selection. + + + + + + callback + + + +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. + + + + + + client_data + + + +Specifies additional data to be passed to the specified procedure +when it is called. + + + + + + time + + + +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 +CurrentTime +is not acceptable. + + + + + + +The + +function requests the value of the selection converted to +the target type. +The specified callback is called at some time after + +is called, when the selection value is received from the X server. +It may be called before or after + +returns. +For more information about selection, +target, and +time, see +Section 2.6 in the +Inter-Client Communication Conventions Manual.. + + + + +void XtGetSelectionValues + Widget w + Atom selection + Atom *targets + int count + XtSelectionCallbackProc callback + XtPointer *client_data + Time time + + + + + + + w + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the particular selection desired (that is, primary or secondary). + + + + + + targets + + + +Specifies the types of information needed about the selection. + + + + + + count + + + +Specifies the length of the targets and client_data lists. + + + + + + callback + + + +Specifies the callback procedure +to be called with each selection value obtained. +Note that this is how the selection values are communicated back to the +client. + + + + + + client_data + + + +Specifies 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. + + + + + + time + + + +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 +CurrentTime +is not acceptable. + + + + + + +The + +function is similar to multiple calls to + +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 selection, target, and +time, see +section 2.6 +in the Inter-Client Communication Conventions Manual.. + + + +Setting the Selection Owner + +To set the selection owner and indicate that the selection value will +be provided in one piece, use +. + + + + +Boolean XtOwnSelection + Widget w + Atom selection + Time time + XtConvertSelectionProc convert_proc + XtLoseSelectionProc lose_selection + XtSelectionDoneProc done_proc + + + + + + + w + + + +Specifies the widget that wishes to become the owner. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the name of the selection (for example, +XA_PRIMARY ). + + + + + + time + + + +Specifies the timestamp that indicates when the ownership request was +initiated. +This should be the timestamp of the event that triggered ownership; +the value +CurrentTime +is not acceptable. + + + + + + convert_proc + + + +Specifies the procedure to be called whenever a client requests the +current value of the selection. + + + + + + lose_selection + + + +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. + + + + + + done_proc + + + +Specifies the procedure called +after the requestor has received the selection value, or NULL if the +owner is not +interested in being called back. + + + + + + +The + +function informs the Intrinsics selection mechanism that a +widget wishes to own a selection. +It returns +True +if the widget successfully becomes the owner and +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. + + + +If a done_proc is specified, the client owns the storage allocated +for passing the value to the Intrinsics. If done_proc is NULL, +the convert_proc must allocate storage using +, +, +or +, +and the value specified is freed by the +Intrinsics when the transfer is complete. + + + +Usually, a selection owner maintains ownership indefinitely until some +other widget requests ownership, at which time +the Intrinsics selection mechanism informs the previous owner that it +has lost ownership of the selection. +However, in response to some user actions +(for example, when a user deletes the information selected), +the application may wish to explicitly inform the Intrinsics +by using + +that it no longer is to be the selection owner. + + + + +void XtDisownSelection + Widget w + Atom selection + Time time + + + + + + + w + + + +Specifies the widget that wishes to relinquish ownership. + + + + + + selection + + + +Specifies the atom naming the selection being given up. + + + + + + time + + + +Specifies the timestamp that indicates when the request to +relinquish selection ownership was initiated. + + + + + + +The + +function informs the Intrinsics 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, + +does nothing. + + + +After a widget has called +, +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 + +finishes after the call to +. + + + + + +Using Incremental Transfers + +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 +request_id argument, which is an identifier that is guaranteed to be +unique among all incremental requests that are active concurrently. + + + +For example, consider the following: + + + + +Upon receiving a request for the selection value, the owner sends +the first segment. + + + + +While waiting to be called to provide the next segment value but +before sending it, the owner receives another request from a +different requestor for the same selection value. + + + + +To distinguish between the requests, the owner uses the request_id +value. This allows the owner to distinguish between the first +requestor, which is asking for the second segment, and the second +requestor, which is asking for the first segment. + + + + +Incremental Transfer Procedures + +The following procedures are used by selection owners who wish to +provide the selection data in multiple segments. + + + +The procedure pointer specified by the incremental owner to supply the +selection data to the Intrinsics is of type +. + + +typedef XtPointer XtRequestId; + + + + +typedef Boolean (*XtConvertSelectionIncrProc) + Widget w + Atom *selection + Atom *target + Atom *type_return + XtPointer *value_return + unsigned long *length_return + int *format_return + unsigned long *max_length + XtPointer client_data + XtRequestId *request_id + + + + + + + w + + + +Specifies the widget that currently owns this selection. + + + + + + selection + + + +Specifies the atom that names the selection requested. + + + + + + target + + + +Specifies the type of information required about the selection. + + + + + + type_return + + + +Specifies a pointer to an atom into which the property +type of the converted value of the selection is to be +stored. + + + + + + value_return + + + +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. + + + + + + length_return + + + +Specifies a pointer into which the number of elements +in value_return, each of size indicated by +format_return, is to be stored. + + + + + + format_return + + + +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. + + + + + + max_length + + + +Specifies the maximum number of bytes which may be +transferred at any one time. + + + + + + client_data + + + +Specifies the value passed in by the widget when it +took ownership of the selection. + + + + + + request_id + + + +Specifies an opaque identification for a specific request. + + + + + + +This procedure is called repeatedly by the Intrinsics selection mechanism to get +the next incremental chunk of data from a selection owner who has +called +. +It must return +True +if the procedure has succeeded in converting the selection data or +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 Intrinsics; +that is, a fixed transfer area may be allocated and returned in value_return +for each segment to be transferred. This procedure should store a +non-NULL value in value_return and zero in length_return to indicate that the +entire selection has been delivered. After returning this final +segment, the request id may be reused by the Intrinsics to begin a +new transfer. + + + +To retrieve the +SelectionRequest +event that triggered the selection conversion procedure, use +, +described in Section 11.5.2.1. + + + +The procedure pointer specified by the incremental selection owner +when it desires notification upon no longer having ownership is of +type +. + + + + +typedef void (*XtLoseSelectionIncrProc) + Widget w + Atom *selection + XtPointer client_data + + + + + + + w + + + +Specifies the widget that has lost the selection ownership. + + + + + + selection + + + +Specifies the atom that names the selection. + + + + + + client_data + + + +Specifies the value passed in by the widget when it +took ownership of the selection. + + + + + + +This procedure, which is optional, is called by the Intrinsics to +inform the selection owner that it no longer owns the selection. + + + +The procedure pointer specified by the incremental selection owner +when it desires notification of receipt of the data or when it manages +the storage containing the data is of type +. + + + + +typedef void (*XtSelectionDoneIncrProc) + Widget w + Atom *selection + Atom *target + XtRequestId *request_id + XtPointer client_data + + + + + + + w + + + +Specifies the widget that owns the selection. + + + + + + selection + + + +Specifies the atom that names the selection being transferred. + + + + + + target + + + +Specifies the target type to which the conversion was done. + + + + + + request_id + + + +Specifies an opaque identification for a specific request. + + + + + + client_data + + + +Specified the value passed in by the widget when it +took ownership of the selection. + + + + + + +This procedure, which is optional, is called by the Intrinsics after +the requestor has retrieved the final (zero-length) segment of the +incremental transfer to indicate that the entire transfer is complete. +If this procedure is not specified, the Intrinsics will free only the +final value returned by the selection owner using +. + + + +The procedure pointer specified by the incremental selection owner to +notify it if a transfer should be terminated prematurely is of type +. + + + + +typedef void (*XtCancelConvertSelectionProc) + Widget w + Atom *selection + Atom *target + XtRequestId *request_id + XtPointer client_data + + + + + + + w + + + +Specifies the widget that owns the selection. + + + + + + selection + + + +Specifies the atom that names the selection being transferred. + + + + + + target + + + +Specifies the target type to which the conversion was done. + + + + + + request_id + + + +Specifies an opaque identification for a specific request. + + + + + + client_data + + + +Specifies the value passed in by the widget when it took ownership of +the selection. + + + + + + +This procedure is called by the Intrinsics when it has been determined +by means of a timeout or other mechanism that any remaining segments +of the selection no longer need to be transferred. Upon receiving +this callback, the selection request is considered complete and the +owner can free the memory and any other resources that have been +allocated for the transfer. + + + +Getting the Selection Value Incrementally + +To obtain the value of the selection using incremental transfers, use + +or +. + + + + +void XtGetSelectionValueIncremental + Widget w + Atom selection + Atom target + XtSelectionCallbackProc selection_callback + XtPointer client_data + Time time + + + + + + + w + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the particular selection desired. + + + + + + target + + + +Specifies the type of information needed +about the selection. + + + + + + selection_callback + + + +Specifies the callback procedure to be +called to receive each data segment. + + + + + + client_data + + + +Specifies client-specific data to be passed to +the specified callback procedure when it is invoked. + + + + + + time + + + +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 +CurrentTime +is not acceptable. + + + + + + +The + +function is similar to + +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 +selection_callback 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 +XT_CONVERT_FAIL +so that the requestor can dispose +of the partial selection value it has collected up until that point. +Upon receiving +XT_CONVERT_FAIL, +the requesting client must determine +for itself whether or not a partially completed data transfer is meaningful. +For more information about selection, +target, and +time, see + in the +Inter-Client Communication Conventions Manual. + + + + +void XtGetSelectionValuesIncremental + Widget w + Atom selection + Atom *targets + int count + XtSelectionCallbackProc selection_callback + XtPointer *client_data + Time time + + + + + + + w + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the particular selection desired. + + + + + + targets + + + +Specifies the types of information needed about +the selection. + + + + + + count + + + +Specifies the length of the targets and client_data lists. + + + + + + selection_callback + + + +Specifies the callback procedure to be called +to receive each selection value. + + + + + + client_data + + + +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. + + + + + + time + + + +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 +CurrentTime +is not acceptable. + + + + + + +The + +function is similar to + +except that it takes a list of targets and client data. + +is equivalent to calling + +successively for each target/client_data pair except that + +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 + +repeatedly. +For more information about selection, target, and +time, see +Section 2.6 in the +Inter-Client Communication Conventions Manual. + + + +Setting the Selection Owner for Incremental Transfers + +To set the selection owner when using incremental transfers, use +. + + + + +Boolean XtOwnSelectionIncremental + Widget w + Atom selection + Time time + XtConvertSelectionIncrProc convert_callback + XtLoseSelectionIncrProc lose_callback + XtSelectionDoneIncrProc done_callback + XtCancelConvertSelectionProc cancel_callback + XtPointer client_data + + + + + + + w + + + +Specifies the widget that wishes to become the owner. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the atom that names the selection. + + + + + + time + + + +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 +CurrentTime +is not acceptable. + + + + + + convert_callback + + + +Specifies the procedure to be called whenever +the current value of the selection is requested. + + + + + + lose_callback + + + +Specifies the procedure to be called whenever +the widget has lost selection ownership, or NULL if the +owner is not interested in being notified. + + + + + + done_callback + + + +Specifies the procedure called after the +requestor has received the entire selection, or NULL if +the owner is not interested in being notified. + + + + + + cancel_callback + + + +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. + + + + + + client_data + + + +Specifies the argument to be passed to each of +the callback procedures when they are called. + + + + + + +The + +procedure informs the Intrinsics +incremental selection mechanism that the specified widget wishes to +own the selection. It returns +True +if the specified widget successfully becomes the selection owner or +False +otherwise. +For more information about selection, target, and +time, see +Section 2.6 in the +Inter-Client Communication Conventions Manual. + + + +If a done_callback procedure is specified, the client owns the storage allocated +for passing the value to the Intrinsics. If done_callback is NULL, +the convert_callback procedure must allocate storage using +, +, +or +, +and the final value specified is freed by the +Intrinsics when the transfer is complete. After a selection transfer +has started, only one of the done_callback or cancel_callback +procedures is invoked to indicate completion of the transfer. + + + +The lose_callback procedure does not indicate completion of any in-progress +transfers; it is invoked at the time a +SelectionClear +event is dispatched regardless of any active transfers, which are still +expected to continue. + + + +A widget that becomes the selection owner using + +may use + +to relinquish selection ownership. + + + + + +Setting and Retrieving Selection Target Parameters + +To specify target parameters for a selection request with a single target, +use +. + + + + +void XtSetSelectionParameters + Widget requestor + Atom selection + Atom type + XtPointer value + unsigned long length + int format + + + + + + + requestor + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the atom that names the selection. + + + + + + type + + + +Specifies the type of the property in which the parameters are passed. + + + + + + value + + + +Specifies a pointer to the parameters. + + + + + + length + + + +Specifies the number of elements containing data in value, +each element of a size indicated by format. + + + + + + format + + + +Specifies the size in bits of the data in the elements of value. + + + + + + +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 + +or to + +specifying the same requestor widget and selection atom will generate a +ConvertSelection +request referring to the property containing the parameters. If + +is called more than once with the same widget and selection without +a call to specify a request, the most recently specified parameters +are used in the subsequent request. + + + +The possible values of format are 8, 16, or 32. If the format is 8, +the elements of value are assumed to be sizeof(char); +if 16, sizeof(short); if 32, sizeof(long). + + + +To generate a MULTIPLE +target request with parameters for any of the multiple targets of the +selection request, precede individual calls to + +and + +with corresponding individual calls to +, +and enclose these all within + +and +XtSendSelectionRequest. + +and + +cannot be used to make selection requests with parameterized targets. + + + +To retrieve any target parameters needed to perform a selection conversion, +the selection owner calls +. + + + + +void XtGetSelectionParameters + Widget owner + Atom selection + XtRequestId request_id + Atom *type_return + XtPointer *value_return + unsigned long *length_return + int *format_return + + + + + + + owner + + + +Specifies the widget that owns the specified selection. + + + + + + selection + + + +Specifies the selection being processed. + + + + + + request_id + + + +Specifies the requestor id in the case of incremental selections, +or NULL in the case of atomic transfers. + + + + + + type_return + + + +Specifies a pointer to an atom in which the property type +of the parameters is stored. + + + + + + value_return + + + +Specifies a pointer into which a pointer to the parameters is to be stored. +A NULL is stored if no parameters accompany the request. + + + + + + length_return + + + +Specifies a pointer into which the number of data elements +in value_return of size indicated by format_return are stored. + + + + + + format_return + + + +Specifies a pointer into which the size in bits of the parameter data +in the elements of value is stored. + + + + + + + +may be called only from within an + +or from within the first call to an + +with a new request_id. + + + +It is the responsibility of the caller to free the returned parameters using + +when the parameters are no longer needed. + + + + +Generating MULTIPLE Requests + +To have the Intrinsics bundle multiple calls to make selection requests into +a single request using a MULTIPLE target, use + +and +. + + + + +void XtCreateSelectionRequest + Widget requestor + Atom selection + + + + + + + requestor + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the particular selection desired. + + + + + + +When + +is called, subsequent calls to +, +, +, +and +, +with the requestor and selection as specified to +, +are bundled into a single selection request with +multiple targets. The request is made by calling +. + + + + +void XtSendSelectionRequest + Widget requestor + Atom selection + Time time + + + + + + + requestor + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the particular selection desired. + + + + + + time + + + +Specifies the timestamp that indicates when the selection request was +initiated. The value +CurrentTime +is not acceptable. + + + + + + +When + +is called with a value of requestor and selection matching +a previous call to +, +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 +, +, +, +and + +are invoked. + + + +Multi-threaded applications should lock the application context before +calling + +and release the lock after calling + +to ensure that the thread assembling the request is safe from interference +by another thread assembling a different request naming the same widget +and selection. + + + +To relinquish the composition of a MULTIPLE request without sending it, use +. + + + + +void XtCancelSelectionRequest + Widget requestor + Atom selection + + + + + + + requestor + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the particular selection desired. + + + + + + +When + +is called, any requests queued since the last call to + +for the same widget and selection are discarded +and any resources reserved are released. +A subsequent call to + +will not result in any request being made. +Subsequent calls to +, +, +, +or + +will not be deferred. + + + + +Auxiliary Selection Properties + +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 Intrinsics provides two interfaces for acquiring temporary property names. + + + +To acquire a temporary property name atom for use in a selection +request, the client may call +. + + + + +Atom XtReservePropertyAtom + Widget w + + + + + + + w + + + +Specifies the widget making a selection request. + + + + + + + +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. + + + +To return a temporary property name atom for reuse and to delete +the property named by that atom, use +. + + + + +void XtReleasePropertyAtom + Widget w + Atom atom + + + + + + + w + + + +Specifies the widget used to reserve the property name atom. + + + + + + atom + + + +Specifies the property name atom returned by + +that is to be released for reuse. + + + + + + + +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 atom does not +specify a value returned by + +for the specified widget, the results are undefined. + + + + +Retrieving the Most Recent Timestamp + +To retrieve the timestamp from the most recent call to + +that contained a timestamp, use +. + + + + +Time XtLastTimestampProcessed + Display *display + + + + + + + display + + + +Specifies an open display connection. + + + + + + +If no +KeyPress, +KeyRelease, +ButtonPress, +ButtonRelease, +MotionNotify, +EnterNotify, +LeaveNotify, +PropertyNotify, +or +SelectionClear +event has yet been passed to + +for the specified display, + +returns zero. + + + + +Retrieving the Most Recent Event + +To retrieve the event from the most recent call to + +for a specific display, use +. + + + + +XEvent *XtLastEventProcessed + Display *display + + + + + + + display + + + +Specifies the display connection from which to retrieve the event. + + + + + + +Returns the last event passed to + +for the specified display. Returns NULL if there is no such event. +The client must not modify the contents of the returned event. + + + + + +Merging Exposure Events into a Region + +The Intrinsics provide an + +utility function that merges +Expose +and +GraphicsExpose +events into a region for clients to process at once +rather than processing individual rectangles. +For further information about regions, +see +in +Xlib — C Language X Interface.. + + + +To merge +Expose +and +GraphicsExpose +events into a region, use +. + + + + +void XtAddExposureToRegion + XEvent *event + Region region + + + + + + + event + + + +Specifies a pointer to the +Expose +or +GraphicsExpose +event. + + + + + + region + + + +Specifies the region object (as defined in +<X11/Xutil.h>). + + + + + + +The + +function computes the union of the rectangle defined by the exposure +event and the specified region. +Then it stores the results back in region. +If the event argument is not an +Expose +or +GraphicsExpose +event, + +returns without an error and without modifying region. + + + +This function is used by the exposure compression mechanism; +see + + + + +Translating Widget Coordinates + +To translate an x-y coordinate pair from widget coordinates to root +window absolute coordinates, use +. + + + + +void XtTranslateCoords + Widget w + Position x + Position *rootx_return + + + + + + + w + + + +Specifies the widget. Must be of class RectObj or any subclass thereof. + + + + + + x + + + + + + + + y + + + +Specify the widget-relative x and y coordinates. + + + + + + rootx_return + + + + + + + + rooty_return + + + +Return the root-relative x and y coordinates. + + + + + + +While + +is similar to the Xlib +XTranslateCoordinates +function, it does not generate a server request because all the required +information already is in the widget's data structures. + + + + +Translating a Window to a Widget + +To translate a given window and display pointer into a widget instance, use +. + + + + +Widget XtWindowToWidget + Display *display + Window window + + + + + + + display + + + +Specifies the display on which the window is defined. + + + + + + window + + + +Specifies the drawable for which you want the widget. + + + + + + +If there is a realized widget whose window is the specified drawable on +the specified display, + +returns that widget. +If not and if the drawable has been associated with a widget through +, + +returns the widget associated with the drawable. In other cases it +returns NULL. + + + + +Handling Errors + +The Intrinsics allow a client to register procedures that are called +whenever a fatal or nonfatal error occurs. +These facilities are intended for both error reporting and logging +and for error correction or recovery. + + + +Two levels of interface are provided: + + + + +A high-level interface that takes an error +name and class and retrieves the error message text from +an error resource database. + + + + +A low-level interface that takes a simple string to display. + + + + +The high-level functions construct a string to pass to the lower-level +interface. +The strings may be specified in application code and are +overridden by the contents of an external systemwide file, +the "error database file". The location and name of this file are +implementation-dependent. + + + +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. + + + + +To obtain the error database (for example, to merge with +an application- or widget-specific database), use +. + + + + XrmDatabase *XtAppGetErrorDatabase + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context. + + + + + + +The + +function returns the address of the error database. +The Intrinsics do a lazy binding of the error database and do not merge in the +database file until the first call to +. + + + +For a complete listing of all errors and warnings +that can be generated by the Intrinsics, see + + + +The high-level error and warning handler procedure pointers are of type +. + + + + +typedef void (*XtErrorMsgHandler) + String name + String type + String class + String defaultp + String *params + Cardinal *num_params + + + + + + + name + + + +Specifies the name to be concatenated with the specified type to form +the resource name of the error message. + + + + + + type + + + +Specifies the type to be concatenated with the name to form the +resource name of the error message. + + + + + + class + + + +Specifies the resource class of the error message. + + + + + + defaultp + + + +Specifies the default message to use if no error database entry is found. + + + + + + params + + + +Specifies a pointer to a list of parameters to be substituted in the message. + + + + + + num_params + + + +Specifies the number of entries in params. + + + + + + +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 +printf +notation is used to substitute the parameters into the message. + + + +An error message handler can obtain the error database text for an +error or a warning by calling +. + + + + +void XtAppGetErrorDatabaseText + XtAppContext app_context + String name + String default + String buffer_return + int nbytes + XrmDatabase database + + + + + + + app_context + + + +Specifies the application context. + + + + + + name + + + type + + + +Specify the name and type concatenated to form the resource name +of the error message. + + + + + + class + + + +Specifies the resource class of the error message. + + + + + + default + + + +Specifies the default message to use if an error database entry is not found. + + + + + + buffer_return + + + +Specifies the buffer into which the error message is to be returned. + + + + + + nbytes + + + +Specifies the size of the buffer in bytes. + + + + + + database + + + +Specifies the name of the alternative database to be used, +or NULL if the application context's error database is to be used. + + + + + + +The + +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 name and type are concatenated with a single "." +between them and the class is concatenated with itself with a +single "." if it does not already contain a ".". + + + +To return the application name and class as passed to + +for a particular Display, use +. + + + + +void XtGetApplicationNameAndClass + Display* display + String* name_return + String* class_return + + + + + + + display + + + +Specifies an open display connection that has been initialized with +. + + + + + + name_return + + + +Returns the application name. + + + + + + class_return + + + +Returns the application class. + + + + + + + +returns the application name and class passed to + +for the specified display. If the display was +never initialized or has been closed, the result is undefined. The +returned strings are owned by the Intrinsics and must not be modified +or freed by the caller. + + + +To register a procedure to be called on fatal error conditions, use +. + + + + +XtErrorMsgHandler XtAppSetErrorMsgHandler + XtAppContext app_context + XtErrorMsgHandler msg_handler + + + + + + + app_context + + + +Specifies the application context. + + + + + + msg_handler + + + +Specifies the new fatal error procedure, which should not return. + + + + + + + +returns a pointer to the previously +installed high-level fatal error handler. +The default high-level fatal error handler provided by the Intrinsics is named +_XtDefaultErrorMsg +and constructs a string from the error resource database and calls +. +Fatal error message handlers should not return. +If one does, +subsequent Intrinsics behavior is undefined. + + + +To call the high-level error handler, use +. + + + + +void XtAppErrorMsg + XtAppContext app_context + String name + String type + String class + String default + String *params + Cardinal *num_params + + + + + + + app_context + + + +Specifies the application context. + + + + + + name + + + +Specifies the general kind of error. + + + + + + type + + + +Specifies the detailed name of the error. + + + + + + class + + + +Specifies the resource class. + + + + + + default + + + +Specifies the default message to use if an error database entry is not found. + + + + + + params + + + +Specifies a pointer to a list of values to be stored in the message. + + + + + + num_params + + + +Specifies the number of entries in params. + + + + + + +The Intrinsics internal errors all have class +"XtToolkitError". + + + +To register a procedure to be called on nonfatal error conditions, use +. + + + + +XtErrorMsgHandler XtAppSetWarningMsgHandler + XtAppContext app_context + XtErrorMsgHandler msg_handler + + + + + + + app_context + + + +Specifies the application context. + + + + + + msg_handler + + + +Specifies the new nonfatal error procedure, which usually returns. + + + + + + + +returns a pointer to the previously +installed high-level warning handler. +The default high-level warning handler provided by the Intrinsics is named +_XtDefaultWarningMsg +and constructs a string +from the error resource database and calls +. + + + +To call the installed high-level warning handler, use +. + + + + +void XtAppWarningMsg + XtAppContext app_context + String name + String type + String class + String default + String *params + Cardinal *num_params + + + + + + + app_context + + + +Specifies the application context. + + + + + + name + + + +Specifies the general kind of error. + + + + + + type + + + +Specifies the detailed name of the error. + + + + + + class + + + +Specifies the resource class. + + + + + + default + + + +Specifies the default message to use if an error database entry is not found. + + + + + + params + + + +Specifies a pointer to a list of values to be stored in the message. + + + + + + num_params + + + +Specifies the number of entries in params. + + + + + + +The Intrinsics internal warnings all have class +"XtToolkitError". + + + +The low-level error and warning handler procedure pointers are of type +. + + + + +typedef void (*XtErrorHandler) + String message + + + + + + + message + + + +Specifies the error message. + + + + + + +The error handler should display the message string in some appropriate fashion. + + + +To register a procedure to be called on fatal error conditions, use +. + + + + +XtErrorHandler XtAppSetErrorHandler + XtAppContext app_context + XtErrorHandler handler + + + + + + + app_context + + + +Specifies the application context. + + + + + + handler + + + +Specifies the new fatal error procedure, which should not return. + + + + + + + +returns a pointer to the previously installed +low-level fatal error handler. +The default low-level error handler provided by the Intrinsics is +_XtDefaultError. +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 Intrinsics behavior is undefined. + + + +To call the installed fatal error procedure, use +. + + + + +void XtAppError + XtAppContext app_context + String message + + + + + + + app_context + + + +Specifies the application context. + + + + + + message + + + +Specifies the message to be reported. + + + + + + +Most programs should use +, +not +, +to provide for customization and internationalization of error messages. + + + +To register a procedure to be called on nonfatal error conditions, use +. + + + + +XtErrorHandler XtAppSetWarningHandler + XtAppContext app_context + XtErrorHandler handler + + + + + + + app_context + + + +Specifies the application context. + + + + + + handler + + + +Specifies the new nonfatal error procedure, which usually returns. + + + + + + + +returns a pointer to the previously installed +low-level warning handler. +The default low-level warning handler provided by the Intrinsics is +_XtDefaultWarning. +On POSIX-based systems, +it prints the message to standard error and returns to the caller. + + + +To call the installed nonfatal error procedure, use +. + + + + +void XtAppWarning + XtAppContext app_context + String message + + + + + + + app_context + + + +Specifies the application context. + + + + + + message + + + +Specifies the nonfatal error message to be reported. + + + + + + +Most programs should use +, +not +, +to provide for customization and internationalization of warning messages. + + + + +Setting WM_COLORMAP_WINDOWS + +A client may set the value of the WM_COLORMAP_WINDOWS +property on a widget's window by calling +. + + + + +void XtSetWMColormapWindows + Widget widget + Widget* list + Cardinal count + + + + + + + widget + + + +Specifies the widget on whose window the WM_COLORMAP_WINDOWS +property is stored. Must be of class Core or any subclass thereof. + + + + + + list + + + +Specifies a list of widgets whose windows are potentially to be +listed in the WM_COLORMAP_WINDOWS property. + + + + + + count + + + +Specifies the number of widgets in list. + + + + + + + +returns immediately if widget is not realized or if count is 0. +Otherwise, + +constructs an ordered list of windows +by examining each widget in list in turn and +ignoring the widget if it is not realized, or +adding the widget's window to the window list if the widget is realized +and if its colormap resource is different from the colormap +resources of all widgets whose windows are already on the window list. + + + +Finally, + +stores the resulting window list in the WM_COLORMAP_WINDOWS +property on the specified widget's window. +Refer to Section 4.1.8 in the Inter-Client Communication Conventions Manual. for details of +the semantics of the WM_COLORMAP_WINDOWS property. + + + + +Finding File Names + +The Intrinsics provide procedures to look for a file by name, allowing +string substitutions in a list of file specifications. Two +routines are provided for this: + +and +. + +uses an arbitrary set of client-specified substitutions, and + +uses a set of standard substitutions corresponding +to the X/Open Portability Guide language localization conventions. +Most applications should use +. + + + +A string substitution is defined by a list of +Substitution +entries. + + +typedef struct { + char match; + String substitution; +} SubstitutionRec, *Substitution; + + +File name evaluation is handled in an operating-system-dependent +fashion by an + +procedure. + + + + +typedef Boolean (*XtFilePredicate) + String filename + + + + + + + filename + + + +Specifies a potential filename. + + + + + + +A file predicate procedure is called with a string that is +potentially a file name. It should return +True +if this string specifies a file that is appropriate for the intended use and +False +otherwise. + + + +To search for a file using substitutions in a path list, use +. + + + + +String XtFindFile + String path + Substitution substitutions + Cardinal num_substitutions + XtFilePredicate predicate + + + + + + + path + + + +Specifies a path of file names, including substitution characters. + + + + + + substitutions + + + +Specifies a list of substitutions to make into the path. + + + + + + num_substitutions + + + +Specifies the number of substitutions passed in. + + + + + + predicate + + + +Specifies a procedure called to judge each potential file name, or NULL. + + + + + + +The path 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, + +looks through the +specified substitutions for that character in the match field +and, if found, +replaces the percent and match characters with the string in the +corresponding substitution field. A substitution 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, + +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 + +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 +True; +this string is the return value for +. +If no string yields a +True +return from the predicate, + +returns NULL. + + + +If the predicate parameter is NULL, an internal procedure that checks +if the file exists, is readable, and is not a directory is used. + + + +It is the responsibility of the caller to free the returned string using + +when it is no longer needed. + + + +To search for a file using standard substitutions in a path list, use +. + + + + +String XtResolvePathname + Display *display + String type + Substitution substitutions + Cardinal num_substitutions + XtFilePredicate predicate + + + + + + + display + + + +Specifies the display to use to find the language for language substitutions. + + + + + + type + + + + + + + + + filename + + + + + + + + suffix + + + +Specify values to substitute into the path. + + + + + + path + + + +Specifies the list of file specifications, or NULL. + + + + + + substitutions + + + +Specifies a list of additional substitutions to make into the path, or NULL. + + + + + + num_substitutions + + + +Specifies the number of entries in substitutions. + + + + + + predicate + + + +Specifies a procedure called to judge each potential file name, or NULL. + + + + + + +The substitutions specified by + +are determined from the value of the language string retrieved by + +for the specified display. +To set the +language for all applications specify "*xnlLanguage: lang" in the +resource database. +The format and content of the language string are +implementation-defined. One suggested syntax is to compose +the language string of three parts; a "language part", a +"territory part" and a "codeset part". The manner in which +this composition is accomplished is implementation-defined, +and the Intrinsics make no interpretation of the parts other +than to use them in substitutions as described below. + + + + + +calls + +with the following substitutions +in addition to any passed by the caller and returns the value returned by +: + + + + + + + +%N + + + +The value of the filename parameter, or the application's +class name if filename is NULL. + + + + + +%T + + + +The value of the type parameter. + + + + + +%S + + + +The value of the suffix parameter. + + + + + +%L + + + +The language string associated with the specified display. + + + + + +%l + + + +The language part of the display's language string. + + + + + +%t + + + +The territory part of the display's language string. + + + + + +%c + + + +The codeset part of the display's language string. + + + + + +%C + + + +The customization string retrieved from the resource +database associated with display. + + + + + +%D + + + +The value of the implementation-specific default path. + + + + + + + + +If a path is passed to +, +it is passed along to +. +If the path argument is NULL, the value of the +XFILESEARCHPATH +environment variable is passed to +. +If XFILESEARCHPATH +is not defined, an implementation-specific default path is used +that contains at least six entries. These entries +must contain the following substitutions: + + + + + + +1. %C, %N, %S, %T, %L or %C, %N, %S, %T, %l, %t, %c +2. %C, %N, %S, %T, %l +3. %C, %N, %S, %T +4. %N, %S, %T, %L or %N, %S, %T, %l, %t, %c +5. %N, %S, %T, %l +6. %N, %S, %T + + + +The order of these six entries within the path must be as given above. +The order and use of substitutions within a given entry +are implementation-dependent. +If the path begins +with a colon, it is preceded by %N%S. If the path includes two +adjacent colons, %N%S is inserted between them. + + + +The type parameter is intended to be a category of files, usually +being translated into a directory in the pathname. Possible values +might include "app-defaults", "help", and "bitmap". + + + +The suffix parameter is intended to be appended to the file name. +Possible values might include ".txt", ".dat", and ".bm". + + + +A suggested value for the default path on POSIX-based systems is + + + /usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:\ + /usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:\ + /usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S + + + + +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 type +parameter is used as a subdirectory of the language directory or of +/usr/lib/X11, and suffix is appended to the file name. + + + +The %D substitution allows the addition of path +elements to the implementation-specific default path, typically to +allow additional directories to be searched without preventing +resources in the system directories from being found. For example, a +user installing resource files under a directory called "ourdir" +might set +XFILESEARCHPATH +to + + + %D:ourdir/%T/%N%C:ourdir/%T/%N + + + +The customization string is obtained by querying the resource database +currently associated with the display (the database returned by +XrmGetDatabase) +for the resource application_name.customization, class +application_class.Customization, where application_name +and application_class are the values returned by +. +If no value is specified in the database, the empty string is used. + + + +It is the responsibility of the caller to free the returned string using + +when it is no longer needed. + + + + + + +Hooks for External Agents + +Applications may register +functions that are called at a particular control points in the Intrinsics. +These functions are intended to be used to provide notification +of an "X Toolkit event", such as widget creation, to an external agent, +such as an interactive resource editor, drag-and-drop server, or +an aid for physically challenged users. +The control points containing such registration hooks are identified +in a "hook registration" object. + + + +To retrieve the hook registration widget, use +. + + + + +Widget XtHooksOfDisplay + Display *display + + + + + + + display + + + +Specifies the desired display. + + + + + + +The class of this object is a private, implementation-dependent +subclass of +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. + + + +The following procedures can be called with the hook registration object +as an argument: + + + + +, +, +, +, +, +, +, + + + + + +, +XtSuperclass, +, +, +XtIsObject, +XtIsRectObj, +XtIsWidget, +XtIsComposite, +XtIsConstraint, +XtIsShell, +XtIsOverrideShell, +XtIsWMShell, +XtIsVendorShell, +XtIsTransientShell, +XtIsToplevelShell, +XtIsApplicationShell, +XtIsSessionShell + + + + + + + + + +, +XtParent, +, + + + + + +, +, +, + + + + + + +Hook Object Resources + +The resource names, classes, and representation types that are specified +in the hook object resource list are: + + + + + + + + + Name + Class + Representation + + + + + XtNcreateHook + XtCCallback + XtRCallback + + + XtNchangeHook + XtCCallback + XtRCallback + + + XtNconfigureHook + XtCCallback + XtRCallback + + + XtNgeometryHook + XtCCallback + XtRCallback + + + XtNdestroyHook + XtCCallback + XtRCallback + + + XtNshells + XtCReadOnly + XtRWidgetList + + + XtNnumShells + XtCReadOnly + XtRCardinal + + + + + + + +Descriptions of each of these resources: + + + +The XtNcreateHook callback list is called from: +, +, +, +, +and their corresponding varargs versions. + + + +The call_data parameter in a createHook callback may be +cast to type +XtCreateHookData. + + +typedef struct { + String type; + Widget widget; + ArgList args; + Cardinal num_args; +} XtCreateHookDataRec, *XtCreateHookData; + + +The type is set to +XtHcreate, +widget is the newly created widget, and args and num_args +are the arguments passed to the create function. The callbacks are +called before returning from the create function. + + + +The XtNchangeHook callback list is called from: + + + + +, + + + + + +, +, +, + + + + + +, + + + + + +, +, +XtAddCallbacks, +, + + + + + +, +, + + + + + +, + + + + + +, +, + + + + + +, +, + + + + + + +The call_data parameter in a changeHook callback may +be cast to type +XtChangeHookData. + + +typedef struct { + String type; + Widget widget; + XtPointer event_data; + Cardinal num_event_data; +} XtChangeHookDataRec, *XtChangeHookData; + + +When the changeHook callbacks are called as a result of a call to + +or +, +type is set to +XtHsetValues, +widget is the new widget passed to the set_values procedure, and +event_data may be cast to type +XtChangeHookSetValuesData. + + +typedef struct { + Widget old, req; + ArgList args; + Cardinal num_args; +} XtChangeHookSetValuesDataRec, *XtChangeHookSetValuesData; + + +The old, req, args, and num_args are the +parameters passed to the set_values procedure. The callbacks are called +after the set_values and constraint set_values procedures have been called. + + + +When the changeHook callbacks are called as a result of a call to + +or +, +type is set to +XtHmanageChildren, +widget is the parent, event_data may be cast to type +WidgetList and is the list of children being managed, and +num_event_data is the length of the widget list. +The callbacks are called after the children have been managed. + + + +When the changeHook callbacks are called as a result of a call to + +or +, +type is set to +XtHunmanageChildren, +widget is the parent, event_data may be cast to type +WidgetList and is a list of the children being unmanaged, and +num_event_data is the length of the widget list. +The callbacks are called after the children have been unmanaged. + + + +The changeHook callbacks are called twice as a result of a call to +, +once after unmanaging and again after managing. +When the callbacks are called the first time, type is set to +XtHunmanageSet, +widget is the parent, event_data may be cast to type +WidgetList and is a list of the children being unmanaged, and +num_event_data is the length of the widget list. +When the callbacks are called the second time, the type is set to +XtHmanageSet, +widget is the parent, event_data may be cast to type +WidgetList and is a list of the children being managed, and +num_event_data is the length of the widget list. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHrealizeWidget +and widget is the widget being realized. +The callbacks are called after the widget has been realized. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHunrealizeWidget, +and widget is the widget being unrealized. +The callbacks are called after the widget has been unrealized. + + + +When the changeHook callbacks are called as a result of a call to +, +type is set to +XtHaddCallback, +widget is the widget to which the callback is being added, and +event_data may be cast to type String and is the name of the +callback being added. +The callbacks are called after the callback has been added to the widget. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHaddCallbacks, +widget is the widget to which the callbacks are being added, and +event_data may be cast to type String and is the name of the +callbacks being added. +The callbacks are called after the callbacks have been added to the widget. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHremoveCallback, +widget is the widget from which the callback is being removed, and +event_data may be cast to type String and is the name of +the callback being removed. The callbacks are called after the callback +has been removed from the widget. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHremoveCallbacks, +widget is the widget from which the callbacks are being removed, and +event_data 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. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHremoveAllCallbacks +and widget is the widget from which the callbacks are being removed. +The callbacks are called after the callbacks have been removed from the +widget. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHaugmentTranslations +and widget is the widget whose translations are being modified. +The callbacks are called after the widget's translations have been +modified. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHoverrideTranslations +and widget is the widget whose translations are being modified. +The callbacks are called after the widget's translations have been +modified. + + + +When the changeHook callbacks are called as a result of a call to +, +The type is +XtHuninstallTranslations +and widget is the widget whose translations are being uninstalled. +The callbacks are called after the widget's translations have been +uninstalled. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHsetKeyboardFocus +and event_data may be cast to type Widget and is the value of +the descendant argument passed to . The +callbacks are called before returning from . + + + +When the changeHook callbacks are called as a result of a call to +, +type is set to +XtHsetWMColormapWindows, +event_data may be cast to type WidgetList and is the value of +the list argument passed to , and +num_event_data is the length of the list. The callbacks are +called before returning from . + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHsetMappedWhenManaged +and event_data may be cast to type Boolean and is the value of +the mapped_when_managed argument passed to . +The callbacks are called after setting the widget's mapped_when_managed +field and before realizing or unrealizing the widget. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHmapWidget +and widget is the widget being mapped. +The callbacks are called after mapping the widget. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHunmapWidget +and widget is the widget being unmapped. +The callbacks are called after unmapping the widget. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHpopup, +widget is the widget being popped up, and event_data may +be cast to type XtGrabKind and is the value of the grab_kind argument +passed to . +The callbacks are called before returning from . + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHpopupSpringLoaded +and widget is the widget being popped up. +The callbacks are called +before returning from . + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHpopdown +and widget is the widget being popped down. +The callbacks are called +before returning from . + + + +A widget set that exports interfaces that change application state +without employing the Intrinsics library should invoke the change hook +itself. This is done by: + + + + XtCallCallbacks(XtHooksOfDisplay(dpy), XtNchangeHook, call_data); + + +The XtNconfigureHook callback list is called any time the Intrinsics +move, resize, or configure a widget and when + +is called. + + + +The call_data parameter may be cast to type +XtConfigureHookData. + + +typedef struct { + String type; + Widget widget; + XtGeometryMask changeMask; + XWindowChanges changes; +} XtConfigureHookDataRec, *XtConfigureHookData; + + +When the configureHook callbacks are called, the type is +XtHconfigure, +widget is the widget being configured, and changeMask and +changes reflect the changes made to the widget. The callbacks +are called after changes have been made to the widget. + + + +The XtNgeometryHook callback list is called from + +and + +once before and once after geometry negotiation occurs. + + + +The call_data parameter may be cast to type +XtGeometryHookData. + + + +typedef struct { + String type; + Widget widget; + XtWidgetGeometry* request; + XtWidgetGeometry* reply; + XtGeometryResult result; +} XtGeometryHookDataRec, *XtGeometryHookData; + + +When the geometryHook callbacks are called prior to geometry negotiation, +the type is +XtHpreGeometry, +widget is the widget for which the request is being made, and +request is the requested geometry. +When the geometryHook callbacks +are called after geometry negotiation, the type is +XtHpostGeometry, +widget is the widget for which the request was made, request +is the requested geometry, reply is the resulting geometry granted, +and result is the value returned from the geometry negotiation. + + + +The XtNdestroyHook callback list is called when a widget is destroyed. +The call_data parameter may be cast to type +XtDestroyHookData. + + +typedef struct { + String type; + Widget widget; +} XtDestroyHookDataRec, *XtDestroyHookData; + + +When the destroyHook callbacks are called as a result of a call to +, +the type is +XtHdestroy +and widget is the widget being destroyed. The callbacks are +called upon completion of phase one destroy for a widget. + + + +The XtNshells and XtnumShells are read-only resources that report a +list of all parentless shell widgets associated with a display. + + + +Clients who use these hooks must exercise caution in calling Intrinsics +functions in order to avoid recursion. + + + + +Querying Open Displays + +To retrieve a list of the Displays associated with an application context, +use +. + + + + +void XtGetDisplays + XtAppContext app_context + Display ***dpy_return + Cardinal *num_dpy_return + + + + + + + app_context + + + +Specifies the application context. + + + + + + dpy_return + + + +Returns a list of open Display connections in the specified application +context. + + + + + + num_dpy_return + + + +Returns the count of open Display connections in dpy_return. + + + + + + + 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 +. + + + + + diff --git a/libXt/specs/CH12 b/libXt/specs/CH12 deleted file mode 100644 index 34e8ec77e..000000000 --- a/libXt/specs/CH12 +++ /dev/null @@ -1,1067 +0,0 @@ -.\" $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/libXt/specs/CH12.xml b/libXt/specs/CH12.xml new file mode 100644 index 000000000..3ae6542ab --- /dev/null +++ b/libXt/specs/CH12.xml @@ -0,0 +1,1166 @@ + +Nonwidget Objects + + +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 (unnamed), +and members of these classes +are referred to generically as objects. By convention, the term +widget refers only to objects that are a subclass of +Core, +and the term nonwidget 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 widget 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 Intrinsics routines. + + +Data Structures + +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. + + + + +Object Objects + +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 +ObjectClassPart +and +ObjectPart +structures. + + +ObjectClassPart Structure + +The common fields for all object classes are defined in the +ObjectClassPart +structure. All fields have the same purpose, +function, and restrictions as the corresponding fields in +CoreClassPart; +fields whose +names are objn for some integer n 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 +objn fields with NULL or zero as appropriate to the type. + + +typedef struct _ObjectClassPart { + WidgetClass superclass; + String class_name; + Cardinal widget_size; + XtProc class_initialize; + XtWidgetClassProc class_part_initialize; + XtEnum class_inited; + XtInitProc initialize; + XtArgsProc initialize_hook; + XtProc obj1; + XtPointer obj2; + Cardinal obj3; + XtResourceList resources; + Cardinal num_resources; + XrmClass xrm_class; + Boolean obj4; + XtEnum obj5; + Boolean obj6; + Boolean obj7; + XtWidgetProc destroy; + XtProc obj8; + XtProc obj9; + XtSetValuesFunc set_values; + XtArgsFunc set_values_hook; + XtProc obj10; + XtArgsProc get_values_hook; + XtProc obj11; + XtVersionType version; + XtPointer callback_private; + String obj12; + XtProc obj13; + XtProc obj14; + XtPointer extension; +} ObjectClassPart; + + +The extension record defined for +ObjectClassPart +with a record_type equal to +NULLQUARK +is +ObjectClassExtensionRec. + + +typedef struct { + XtPointer next_extension; See + XrmQuark record_type; See + long version; See + Cardinal record_size; See + XtAllocateProc allocate; See . + XtDeallocateProc deallocate; See . +} ObjectClassExtensionRec, *ObjectClassExtension; + + +The prototypical +ObjectClass +consists of just the +ObjectClassPart. + + +typedef struct _ObjectClassRec { + ObjectClassPart object_class; +} ObjectClassRec, *ObjectClass; + + +The predefined class record and pointer for +ObjectClassRec +are + + + +In +IntrinsicP.h: + + +extern ObjectClassRec objectClassRec; + + +In +Intrinsic.h: + + +extern WidgetClass objectClass; + + +The opaque types +Object +and +ObjectClass +and the opaque variable +objectClass +are defined for generic actions on objects. +The symbolic constant for the +ObjectClassExtension +version identifier is +XtObjectExtensionVersion +(see ). +Intrinsic.h +uses an incomplete structure definition to ensure that the +compiler catches attempts to access private data: + + +typedef struct _ObjectClassRec* ObjectClass; + + + + + +ObjectPart Structure + +The common fields for all object instances are defined in the +ObjectPart +structure. All fields have the same meaning as the +corresponding fields in +CorePart. + + +typedef struct _ObjectPart { + Widget self; + WidgetClass widget_class; + Widget parent; + Boolean being_destroyed; + XtCallbackList destroy_callbacks; + XtPointer constraints; +} ObjectPart; + + +All object instances have the +Object +fields as their first component. The prototypical type +Object +is defined with only this set of fields. +Various routines can cast object pointers, as needed, to specific +object types. + + + +In +IntrinsicP.h: + + +typedef struct _ObjectRec { + ObjectPart object; +} ObjectRec, *Object; + + +In +Intrinsic.h: + + +typedef struct _ObjectRec *Object; + + + + + +Object Resources + +The resource names, classes, and representation types specified in the +objectClassRec +resource list are: + + + + + + + + + + + Name + Class + Representation + + + + + XtNdestroyCallback + XtCCallback + XtRCallback + + + + + + + +ObjectPart Default Values + +All fields in +ObjectPart +have the same default values as the corresponding fields in +CorePart. + + + + +Object Arguments to Intrinsics Routines + +The WidgetClass arguments to the following procedures may be +objectClass +or any subclass: + + + +XtInitializeWidgetClass, +XtCreateWidget, +XtVaCreateWidget +XtIsSubclass, +XtCheckSubclass +XtGetResourceList, +XtGetConstraintResourceList + + + +The Widget arguments to the following procedures may be of class +Object +or any subclass: + + + + +, + + + + + +, +, +, +, +, +, +, + + + + + +, +XtSuperclass, +, +, +XtIsObject, +XtIsRectObj, +XtIsWidget, +XtIsComposite, +XtIsConstraint, +XtIsShell, +XtIsOverrideShell, +XtIsWMShell, +XtIsVendorShell, +XtIsTransientShell, +XtIsToplevelShell, +XtIsApplicationShell, +XtIsSessionShell + + + + +, + +(both will return +False +if argument is not a subclass of +RectObj) + + + + + +(returns the state of the nearest windowed ancestor +if class of argument is not a subclass of +Core) + + + + + + + + + + + + + + +XtParent, +, +, + + + + + + +(descendant) + + + + +, + + + + + + + + + + +, +, +, + + + + + +, +, +, + + + + + +, + + + + + +The return value of the following procedures will be of class +Object +or a subclass: + + + + +, + + + + + +XtParent + + + + + + + + + +The return value of the following procedures will be +objectClass +or a subclass: + + + + +, +XtSuperclass + + + + + + +Use of Objects + +The +Object +class exists to enable programmers to use the Intrinsics' +classing and resource-handling mechanisms for things smaller +and simpler than widgets. +Objects make obsolete many common uses of subresources as described in +Sections 9.4, 9.7.2.4, and 9.7.2.5. + + + +Composite +widget classes that wish to accept nonwidget children must +set the accepts_objects field in the +CompositeClassExtension +structure to +True. + +will otherwise generate an error message on an attempt to create a +nonwidget child. + + + +Of the classes defined by the Intrinsics, +ApplicationShell +and +SessionShell +accept nonwidget children, and the class of any nonwidget child +must not be +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. + + + + + +Rectangle Objects + +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 +to avoid conflict with the Xlib +Rectangle +data type. + + +RectObjClassPart Structure + +As with the +ObjectClassPart +structure, all fields in the +RectObjClassPart +structure have the same +purpose and function as the corresponding fields in +CoreClassPart; +fields whose names are rectn for some integer +n 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 +rectn fields with NULL or zero as appropriate to the type. + + +typedef struct _RectObjClassPart { + WidgetClass superclass; + String class_name; + Cardinal widget_size; + XtProc class_initialize; + XtWidgetClassProc class_part_initialize; + XtEnum class_inited; + XtInitProc initialize; + XtArgsProc initialize_hook; + XtProc rect1; + XtPointer rect2; + Cardinal rect3; + XtResourceList resources; + Cardinal num_resources; + XrmClass xrm_class; + Boolean rect4; + XtEnum rect5; + Boolean rect6; + Boolean rect7; + XtWidgetProc destroy; + XtWidgetProc resize; + XtExposeProc expose; + XtSetValuesFunc set_values; + XtArgsFunc set_values_hook; + XtAlmostProc set_values_almost; + XtArgsProc get_values_hook; + XtProc rect9; + XtVersionType version; + XtPointer callback_private; + String rect10; + XtGeometryHandler query_geometry; + XtProc rect11; + XtPointer extension ; +} RectObjClassPart; + + +The +RectObj +class record consists of just the +RectObjClassPart. + + +typedef struct _RectObjClassRec { + RectObjClassPart rect_class; +} RectObjClassRec, *RectObjClass; + + +The predefined class record and pointer for +RectObjClassRec +are + + + +In +Intrinsic.h: + + +extern RectObjClassRec rectObjClassRec; + + +In +Intrinsic.h: + + +extern WidgetClass rectObjClass; + + +The opaque types +RectObj +and +RectObjClass +and the opaque variable +rectObjClass +are defined for generic actions on objects +whose class is RectObj or a subclass of +RectObj. +Intrinsic.h +uses an incomplete structure definition to ensure that the compiler +catches attempts to access private data: + + +typedef struct _RectObjClassRec* RectObjClass; + + + + + +RectObjPart Structure + +In addition to the +ObjectPart +fields, +RectObj +objects have the following fields defined in the +RectObjPart +structure. All fields have the same meaning as the corresponding field in +CorePart. + + +typedef struct _RectObjPart { + Position x, y; + Dimension width, height; + Dimension border_width; + Boolean managed; + Boolean sensitive; + Boolean ancestor_sensitive; +} RectObjPart; + + +RectObj +objects have the RectObj fields immediately following the Object fields. + + +typedef struct _RectObjRec { + ObjectPart object; + RectObjPart rectangle; +} RectObjRec, *RectObj; + + +In +Intrinsic.h: + + +typedef struct _RectObjRec* RectObj; + + + + + +RectObj Resources + +The resource names, classes, and representation types that are specified in the +rectObjClassRec +resource list are: + + + + + + + + + Name + Class + Representation + + + + + XtNancestorSensitive + XtCSensitive + XtRBoolean + + + XtNborderWidth + XtCBorderWidth + XtRDimension + + + XtNheight + XtCHeight + XtRDimension + + + XtNsensitive + XtCSensitive + XtRBoolean + + + XtNwidth + XtCWidth + XtRDimension + + + XtNx + XtCPosition + XtRPosition + + + XtNy + XtCPosition + XtRPosition + + + + + + + + +RectObjPart Default Values + +All fields in +RectObjPart +have the same default values as the corresponding fields in +CorePart. + + + + +Widget Arguments to Intrinsics Routines + +The WidgetClass arguments to the following procedures may be +rectObjClass +or any subclass: + + + + +, + + + + + +The Widget arguments to the following procedures may be of class +RectObj +or any subclass: + + + + +, +, + + + + + +, + + + + + +, +, +, +, + + + + + + + + + + + + + + + + + + + + +The return value of the following procedures will be of class +RectObj +or a subclass: + + + + +, + + + + + + + +Use of Rectangle Objects + +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, rectobj refers only to objects +whose class is RectObj or a subclass of +RectObj, +but not Core or a subclass of +Core. + + + +Composite +widget classes that wish to accept rectobj children must set +the accepts_objects field in the +CompositeClassExtension +extension structure to +True. + +or + +will otherwise generate an error if called to create a nonwidget child. +If the composite widget supports only children of class +RectObj +or a subclass (i.e., not of the general Object class), it +must declare an insert_child procedure and check the subclass of each +new child in that procedure. None of the classes defined by the +Intrinsics accept rectobj children. + + + +If gadgets are defined in an object set, the parent is responsible for +much more than the parent of a widget. The parent must request and handle +input events that occur for the gadget and is responsible for making +sure that when it receives an exposure event the gadget children get +drawn correctly. +Rectobj children may +have expose procedures +specified in their class records, but the parent is free to +ignore them, instead drawing the contents of the child itself. This +can potentially save graphics context switching. The precise contents +of the exposure event and region arguments to the RectObj expose +procedure are not specified by the Intrinsics; 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. + + + +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. + + + +The Intrinsics will clear areas of a parent window obscured by +rectobj children, causing exposure events, under the following +circumstances: + + + + +A rectobj child is managed or unmanaged. + + + + +In a call to + +on a rectobj child, one or more of the set_values procedures returns +True. + + + + +In a call to + +on a rectobj child, areas will +be cleared corresponding to both the old and the new child +geometries, including the border, if the geometry changes. + + + + +In a call to + +on a rectobj child, areas will be +cleared corresponding to both the old and the new child +geometries, including the border, if the geometry changes. + + + + +In a call to + +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. + + + + +In a call to + +(or +) +on a rectobj child with +XtQueryOnly +not set, if the manager returns +XtGeometryYes, +two rectangles will be cleared corresponding to both the old and +the new child geometries. + + + + +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. + + + +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. + + + + + +Undeclared Class + +The Intrinsics define an unnamed class between +RectObj +and +Core +for possible future use by the X Consortium. The only assumptions that +may be made about the unnamed class are + + + + +The core_class.superclass field of +coreWidgetClassRec +contains a pointer to the unnamed class record. + + + + +A pointer to the unnamed class record when dereferenced as an +ObjectClass +will contain a pointer to +rectObjClassRec +in its object_class.superclass field. + + + + +Except for the above, the contents of the class record for this class +and the result of an attempt to subclass or to create a widget of this +unnamed class are undefined. + + + + +Widget Arguments to Intrinsics Routines + +The WidgetClass arguments to the following procedures must be of class +Shell +or a subclass: + + + + +, +, +, +, +, + + + + + +The Widget arguments to the following procedures must be of class +Core +or any subclass: + + + + +, + + + + + +, +, +, +, +, + +, +, + + + + + + + + + + +, +, +, +, +, +, +, +, +, + + + + + + + + + + +, +XtDisplay, +, + + + + + + + + + + +, +, +, +, +, +, +, + + + + + +, + +(both destination and source) + + + + +, +, +, + + + + + +, + + + + + +, + + + + + + + + + + +, + +(subtree) + + + + + + + + + + + + + + +The Widget arguments to the following procedures must be of class +Composite +or any subclass: + + + + +, + + + + + +The Widget arguments to the following procedures must be of a subclass of +Shell: + + + + +, +, +, +, +, +, + + + + + +The return value of the following procedure will be of class +Core +or a subclass: + + + + + + + + + +The return value of the following procedures will be of a subclass of +Shell: + + + + +, +, +, +, +, + + + + + + diff --git a/libXt/specs/CH13 b/libXt/specs/CH13 deleted file mode 100644 index 8c944a615..000000000 --- a/libXt/specs/CH13 +++ /dev/null @@ -1,805 +0,0 @@ -.\" $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/libXt/specs/CH13.xml b/libXt/specs/CH13.xml new file mode 100644 index 000000000..0216b3434 --- /dev/null +++ b/libXt/specs/CH13.xml @@ -0,0 +1,770 @@ + +Evolution of the Intrinsics + + +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. + + + +The Intrinsics 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. + + + +In particular, widget programmers may wish to conform to the convention +described in when defining class extension records. + + +Determining Specification Revision Level + +Widget and application developers who wish to maintain a common source +pool that will build properly with implementations of the Intrinsics +at different revision levels of these specifications but that take +advantage of newer features added in later revisions may use the +symbolic macro +XtSpecificationRelease. + + +#define XtSpecificationRelease 6 + + +As the symbol +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. + + + + +Release 3 to Release 4 Compatibility + +At the data structure level, Release 4 retains binary compatibility +with Release 3 (the first X Consortium standard release) for all data +structures except +WMShellPart, +TopLevelShellPart, +and +TransientShellPart. +Release 4 changed the argument type to most procedures that now take +arguments of type +XtPointer +and structure members that are now of type +XtPointer +in order to avoid potential ANSI C conformance problems. It is +expected that most implementations will be binary compatible with the +previous definition. + + + +Two fields in +CoreClassPart +were changed from +Boolean +to +XtEnum +to allow implementations additional freedom in specifying the +representations of each. This change should require no source +modification. + + +Additional Arguments + +Arguments were added to the procedure definitions for +, +, +and + +to provide more information and to +allow event handlers to abort further dispatching of the current event +(caution is advised!). The added arguments to + +and + +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. + + + + +set_values_almost Procedures + +The use of the arguments by a set_values_almost procedure was poorly +described in Release 3 and was inconsistent with other conventions. + + + +The current specification for the manner in which a set_values_almost +procedure returns information to the Intrinsics 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. + + + +No known implementation of the Intrinsics correctly implemented the +Release 3 interface, so it is expected that the impact of this +specification change is small. + + + + +Query Geometry + +A composite widget layout routine that calls + +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. + + + + +unrealizeCallback Callback List + +In order to provide a mechanism for widgets to be notified when they +become unrealized through a call to +, +the callback +list name ``unrealizeCallback'' has been defined by the Intrinsics. A +widget class that requires notification on unrealize may declare a +callback list resource by this name. No class is required to declare +this resource, but any class that did so in a prior revision may find +it necessary to modify the resource name if it does not wish to use the new +semantics. + + + + +Subclasses of WMShell + +The formal adoption of the Inter-Client Communication Conventions Manual. as +an X Consortium standard has meant the addition of four fields to +WMShellPart +and one field to +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. + + + +To provide more convenience for TransientShells, a field was added +to the previously empty +TransientShellPart. +On some architectures the size of the part structure will not +have changed as a result of this. + + + +Any widget implementation whose class is a subclass of +TopLevelShell +or +TransientShell +must at minimum be +recompiled with the new data structure declarations. Because +WMShellPart +no longer contains a contiguous +XSizeHints +data structure, +a subclass that expected to do a single structure assignment of an +XSizeHints +structure to the size_hints field of +WMShellPart +must be revised, though the old fields remain at the same positions within +WMShellPart. + + + + +Resource Type Converters + +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. + + + +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 + +was incomplete. + + + + +KeySym Case Conversion Procedure + +The specification for the + +function type has been changed +to match the Release 3 implementation, which included necessary +additional information required by the function (a pointer to the +display connection), and corrects the argument type of the source +KeySym parameter. No known implementation of the Intrinsics +implemented the previously documented interface. + + + + +Nonwidget Objects + +Formal support for nonwidget objects is new to Release 4. A +prototype implementation was latent in at least one Release 3 +implementation of the Intrinsics, but the specification has changed +somewhat. The most significant change is the requirement for a +composite widget to declare the +CompositeClassExtension +record with the accepts_objects field set to +True +in order to permit a client to create a nonwidget child. + + + +The addition of this extension field ensures that composite widgets +written under Release 3 will not encounter 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 +accepts_objects field allows a composite widget to declare that it +is not prepared to do so. + + + + + +Release 4 to Release 5 Compatibility + +At the data structure level, Release 5 retains complete binary +compatibility with Release 4. The specification of the +ObjectPart, +RectObjPart, +CorePart, +CompositePart, +ShellPart, +WMShellPart, +TopLevelShellPart, +and +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 +XrmValue +and +XrmOptionDescRec +was updated to use a new type, +XPointer, +for the addr and value fields, respectively, to avoid +ANSI C conformance problems. The definition of +XPointer +is binary compatible with the previous implementation. + + +baseTranslations Resource + +A new pseudo-resource, XtNbaseTranslations, was defined to permit +application developers to specify translation tables in application +defaults files while still giving end users the ability to augment +or override individual event sequences. This change will affect +only those applications that wish to take advantage of the new +functionality or those widgets that may have previously defined +a resource named ``baseTranslations''. + + + +Applications wishing to take advantage of the new functionality +would change their application defaults file, e.g., from + + app.widget.translations: value +to + app.widget.baseTranslations: value + +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. + + + + +Resource File Search Path + +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 +XFILESEARCHPATH +and +XUSERFILESEARCHPATH +values when overriding the system defaults. + + + + +Customization Resource + + +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. + + + + +Per-Screen Resource Database + +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 Intrinsics +database initialization. Such applications will need to be aware +of the particular screen on which each shell widget is to be created. + + + +Although the wording of the specification changed 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 +. + + + + +Internationalization of Applications + +Internationalization as defined by ANSI is a technology that +allows support of an application in a single locale. In +adding support for internationalization to the Intrinsics +the restrictions of this model have been followed. +In particular, the new Intrinsics interfaces are designed not to +preclude an application from using other alternatives. +For this reason, no Intrinsics routine makes a call to establish the +locale. However, a convenience routine to establish the +locale at initialize time has been provided, in the form +of a default procedure that must be explicitly installed +if the application desires ANSI C locale behavior. + + + +As many objects in X, particularly resource databases, now inherit +the global locale when they are created, applications wishing to use +the ANSI C locale model should use the new function +XtSetLanguageProc +to do so. + + + +The internationalization additions also define event filters +as a part of the Xlib Input Method specifications. The +Intrinsics enable the use of event filters through additions to +. +Applications that may not be dispatching all events through + +should be reviewed in the context of this new input method mechanism. + + + +In order to permit internationalization of error messages, the name +and path of the error database file are now allowed to be +implementation-dependent. +No adequate standard mechanism has yet been suggested to +allow the Intrinsics to locate the database from localization information +supplied by the client. + + + +The previous specification for the syntax of the language string +specified by +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. + + + + +Permanently Allocated Strings + +In order to permit additional memory savings, an Xlib interface was +added to allow the resource manager to avoid copying certain string +constants. The Intrinsics specification was updated to explicitly require +the Object class_name, resource_name, resource_class, +resource_type, default_type in resource tables, Core actions +string field, and Constraint resource_name, resource_class, +resource_type, and default_type resource fields to be +permanently allocated. This explicit requirement is expected to +affect only applications that may create and destroy classes +on the fly. + + + + +Arguments to Existing Functions + +The args argument to +, +, +, +, +and + +were changed from +Cardinal* +to int* to conform to pre-existing convention and avoid otherwise +annoying typecasting in ANSI C environments. + + + + + +Release 5 to Release 6 Compatibility + +At the data structure level, Release 6 retains binary compatibility +with Release 5 for all data structures except +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. + + +Widget Internals + +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. + + + +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. + + + +As a convenience, an interface to locate a widget class extension +record on a linked list, +, +has been added. + + + +A new option to allow bundled changes to the managed set of a Composite +widget is introduced in the Composite class extension record. +Widgets that define a change_managed procedure that can accommodate +additions and deletions to the managed set of children in a single +invocation should set allows_change_managed_set to True in the +extension record. + + + +The wording of the process followed by + +has changed slightly to better handle changes to the managed set +during phase 2 destroy processing. + + + +A new exposure event compression flag, +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 Intrinsics need not +compute the region. + + + + +General Application Development + + +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, +, +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. + + + +The toolkit initialization function + +may be called multiple times without penalty. + + + +In order to optimize changes in geometry to a set of geometry-managed +children, a new interface, +, +has been added. + + + + +Communication with Window and Session Managers + +The revision of the Inter-Client Communication Conventions Manual. as an X Consortium standard has resulted +in the addition of three fields to the specification of +WMShellPart. +These are urgency, client_leader, and window_role. + + + +The adoption of the X Session Management Protocol as an X Consortium +standard has resulted in the addition of a new shell widget, +SessionShell, +and an accompanying subclass verification interface, +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 +ApplicationShell, +the +ApplicationShell +was subclassed to create the new widget class. +The session protocol requires a modal response to certain checkpointing +operations by participating applications. The +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 + +and +. +There is also a new command line argument, -xtsessionID, which facilitates +the session manager in restarting applications based on the Intrinsics. + + + +The resource name and class strings defined by the Intrinsics shell +widgets in +<X11/Shell.h> +are now listed in Appendix E. The addition of a new symbol +for the +WMShell +wait_for_wm resource was made to bring the external symbol +and the string it represents into agreement. The actual resource name +string in +WMShell +has not changed. +The resource representation type of the XtNwinGravity resource of the +WMShell +was changed to XtRGravity in order to register a type +converter so that window gravity resource values could be specified by name. + + + + +Geometry Management + +A clarification to the specification was made to indicate that geometry +requests may include current values along with the requested changes. + + + + +Event Management + +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 + +and +. +Since the mechanism to indicate selection of extension events is specific +to the extension being used, the Intrinsics introduces +, +which allows the application to select for the events of interest. +In order to change the dispatching algorithm to accommodate extension events +as well as core X protocol events, +the Intrinsics event dispatcher may now be replaced or enveloped +by the application with +. +The dispatcher may wish to call + +to determine the widget with the current Intrinsics keyboard focus. +A dispatcher, after determining the destination widget, may use + +to cause the event to be dispatched to the event handlers registered +by a specific widget. + + + +To permit the dispatching of events +for nonwidget drawables, such as pixmaps that are not associated +with a widget's window, + +and + +have been added to the library. A related update was made to +the description of +. + + + +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 +, +, +, +, +and +. +Widget writers may also use + +and +. + + + +Safe handling of POSIX signals and other asynchronous notifications +is now provided by use of +, +, +and +. + + + +The application can receive notification of an impending block +in the Intrinsics event manager by registering interest through + +and +. + + + + +returns the most recent event passed to + +for a specified display. + + + + +Resource Management + +Resource converters are registered by the Intrinsics for window gravity +and for three new resource types associated with session participation: +RestartStyle, CommandArgArray and DirectoryString. + + + +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. + + + + +Translation Management + +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. + + + + +Selections + +The targets of selection requests may be parameterized, as described +by the revised Inter-Client Communication Conventions Manual.. +When such requests are made, + +is used by the requestor to specify the target parameters and + +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, +, +, +and + +are used to envelop the assembly of the request. +When the parameters themselves are the names of properties, +the Intrinsics provides support for the economical use of property atom names; +see + +and +. + + + + +External Agent Hooks + +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 +, +which returns the hook registration widget, and +, +which returns a list of the X displays associated with an application context. + + + + diff --git a/libXt/specs/Makefile.am b/libXt/specs/Makefile.am index 887eb7e1e..c922dbb8e 100644 --- a/libXt/specs/Makefile.am +++ b/libXt/specs/Makefile.am @@ -1,24 +1,37 @@ -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 + +if ENABLE_SPECS + +# Main DocBook/XML files (DOCTYPE book) +docbook = intrinsics.xml + +# Included chapters, appendix, images +chapters = \ + acknowledgement.xml \ + preface.xml \ + CH01.xml \ + CH02.xml \ + CH03.xml \ + CH04.xml \ + CH05.xml \ + CH06.xml \ + CH07.xml \ + CH08.xml \ + CH09.xml \ + CH10.xml \ + CH11.xml \ + CH12.xml \ + CH13.xml \ + appA.xml \ + appB.xml \ + appC.xml \ + appD.xml \ + appE.xml \ + appF.xml + +# The location where the DocBook/XML files and their generated formats are installed +shelfdir = $(docdir) + +# Generate DocBook/XML output formats with or without stylesheets +include $(top_srcdir)/docbook.am + +endif ENABLE_SPECS diff --git a/libXt/specs/Makefile.in b/libXt/specs/Makefile.in new file mode 100644 index 000000000..06964a911 --- /dev/null +++ b/libXt/specs/Makefile.in @@ -0,0 +1,601 @@ +# Makefile.in generated by automake 1.11.1 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, +# Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# +# Generate output formats for a single DocBook/XML with/without chapters +# +# Variables set by the calling Makefile: +# shelfdir: the location where the docs/specs are installed. Typically $(docdir) +# docbook: the main DocBook/XML file, no chapters, appendix or image files +# chapters: all files pulled in by an XInclude statement and images. +# + +# +# This makefile is intended for Users Documentation and Functional Specifications. +# Do not use for Developer Documentation which is not installed and does not require olink. +# Refer to http://www.x.org/releases/X11R7.6/doc/xorg-docs/ReleaseNotes.html#id2584393 +# for an explanation on documents classification. +# + +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +DIST_COMMON = $(am__dist_shelf_DATA_DIST) $(srcdir)/Makefile.am \ + $(srcdir)/Makefile.in $(top_srcdir)/docbook.am +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@am__append_1 = $(docbook:.xml=.html) +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TEXT_TRUE@@HAVE_XMLTO_TRUE@am__append_2 = $(docbook:.xml=.txt) +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@am__append_3 = $(docbook:.xml=.pdf) \ +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(docbook:.xml=.ps) +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@am__append_4 = $(docbook:.xml=.html.db) \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(docbook:.xml=.pdf.db) +subdir = specs +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/m4/ax_define_dir.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_GEN = $(am__v_GEN_$(V)) +am__v_GEN_ = $(am__v_GEN_$(AM_DEFAULT_VERBOSITY)) +am__v_GEN_0 = @echo " GEN " $@; +AM_V_at = $(am__v_at_$(V)) +am__v_at_ = $(am__v_at_$(AM_DEFAULT_VERBOSITY)) +am__v_at_0 = @ +SOURCES = +DIST_SOURCES = +am__dist_shelf_DATA_DIST = intrinsics.xml acknowledgement.xml \ + preface.xml CH01.xml CH02.xml CH03.xml CH04.xml CH05.xml \ + CH06.xml CH07.xml CH08.xml CH09.xml CH10.xml CH11.xml CH12.xml \ + CH13.xml appA.xml appB.xml appC.xml appD.xml appE.xml appF.xml +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__installdirs = "$(DESTDIR)$(shelfdir)" "$(DESTDIR)$(shelfdir)" +DATA = $(dist_shelf_DATA) $(shelf_DATA) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +ADMIN_MAN_DIR = @ADMIN_MAN_DIR@ +ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +APP_MAN_DIR = @APP_MAN_DIR@ +APP_MAN_SUFFIX = @APP_MAN_SUFFIX@ +AR = @AR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BASE_CFLAGS = @BASE_CFLAGS@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CC_FOR_BUILD = @CC_FOR_BUILD@ +CFLAGS = @CFLAGS@ +CFLAGS_FOR_BUILD = @CFLAGS_FOR_BUILD@ +CHANGELOG_CMD = @CHANGELOG_CMD@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CWARNFLAGS = @CWARNFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DLLTOOL = @DLLTOOL@ +DRIVER_MAN_DIR = @DRIVER_MAN_DIR@ +DRIVER_MAN_SUFFIX = @DRIVER_MAN_SUFFIX@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +FGREP = @FGREP@ +FILE_MAN_DIR = @FILE_MAN_DIR@ +FILE_MAN_SUFFIX = @FILE_MAN_SUFFIX@ +FOP = @FOP@ +GLIB_CFLAGS = @GLIB_CFLAGS@ +GLIB_LIBS = @GLIB_LIBS@ +GREP = @GREP@ +INSTALL = @INSTALL@ +INSTALL_CMD = @INSTALL_CMD@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LDFLAGS_FOR_BUILD = @LDFLAGS_FOR_BUILD@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIB_MAN_DIR = @LIB_MAN_DIR@ +LIB_MAN_SUFFIX = @LIB_MAN_SUFFIX@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MALLOC_DEBUG_ENV = @MALLOC_DEBUG_ENV@ +MALLOC_ZERO_CFLAGS = @MALLOC_ZERO_CFLAGS@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MAN_SUBSTS = @MAN_SUBSTS@ +MISC_MAN_DIR = @MISC_MAN_DIR@ +MISC_MAN_SUFFIX = @MISC_MAN_SUFFIX@ +MKDIR_P = @MKDIR_P@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +PKG_CONFIG = @PKG_CONFIG@ +RANLIB = @RANLIB@ +RAWCPP = @RAWCPP@ +RAWCPPFLAGS = @RAWCPPFLAGS@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRICT_CFLAGS = @STRICT_CFLAGS@ +STRINGSABIOPTIONS = @STRINGSABIOPTIONS@ +STRIP = @STRIP@ +STYLESHEET_SRCDIR = @STYLESHEET_SRCDIR@ +VERSION = @VERSION@ +XFILESEARCHPATHDEFAULT = @XFILESEARCHPATHDEFAULT@ +XMALLOC_ZERO_CFLAGS = @XMALLOC_ZERO_CFLAGS@ +XMLTO = @XMLTO@ +XORG_MALLOC_DEBUG_ENV = @XORG_MALLOC_DEBUG_ENV@ +XORG_MAN_PAGE = @XORG_MAN_PAGE@ +XORG_SGML_PATH = @XORG_SGML_PATH@ +XSLTPROC = @XSLTPROC@ +XSL_STYLESHEET = @XSL_STYLESHEET@ +XTMALLOC_ZERO_CFLAGS = @XTMALLOC_ZERO_CFLAGS@ +XT_CFLAGS = @XT_CFLAGS@ +XT_LIBS = @XT_LIBS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +appdefaultdir = @appdefaultdir@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ + +# Main DocBook/XML files (DOCTYPE book) +@ENABLE_SPECS_TRUE@docbook = intrinsics.xml + +# Included chapters, appendix, images +@ENABLE_SPECS_TRUE@chapters = \ +@ENABLE_SPECS_TRUE@ acknowledgement.xml \ +@ENABLE_SPECS_TRUE@ preface.xml \ +@ENABLE_SPECS_TRUE@ CH01.xml \ +@ENABLE_SPECS_TRUE@ CH02.xml \ +@ENABLE_SPECS_TRUE@ CH03.xml \ +@ENABLE_SPECS_TRUE@ CH04.xml \ +@ENABLE_SPECS_TRUE@ CH05.xml \ +@ENABLE_SPECS_TRUE@ CH06.xml \ +@ENABLE_SPECS_TRUE@ CH07.xml \ +@ENABLE_SPECS_TRUE@ CH08.xml \ +@ENABLE_SPECS_TRUE@ CH09.xml \ +@ENABLE_SPECS_TRUE@ CH10.xml \ +@ENABLE_SPECS_TRUE@ CH11.xml \ +@ENABLE_SPECS_TRUE@ CH12.xml \ +@ENABLE_SPECS_TRUE@ CH13.xml \ +@ENABLE_SPECS_TRUE@ appA.xml \ +@ENABLE_SPECS_TRUE@ appB.xml \ +@ENABLE_SPECS_TRUE@ appC.xml \ +@ENABLE_SPECS_TRUE@ appD.xml \ +@ENABLE_SPECS_TRUE@ appE.xml \ +@ENABLE_SPECS_TRUE@ appF.xml + + +# The location where the DocBook/XML files and their generated formats are installed +@ENABLE_SPECS_TRUE@shelfdir = $(docdir) + +# DocBook/XML generated output formats to be installed +@ENABLE_SPECS_TRUE@shelf_DATA = $(am__append_1) $(am__append_2) \ +@ENABLE_SPECS_TRUE@ $(am__append_3) $(am__append_4) + +# DocBook/XML file with chapters, appendix and images it includes +@ENABLE_SPECS_TRUE@dist_shelf_DATA = $(docbook) $(chapters) +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_SEARCHPATH_FLAGS = \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --searchpath "$(XORG_SGML_PATH)/X11" \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --searchpath "$(abs_top_builddir)" + +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_HTML_OLINK_FLAGS = \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --stringparam target.database.document=$(XORG_SGML_PATH)/X11/dbs/masterdb.html.xml \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --stringparam current.docid="$(<:.xml=)" + +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_HTML_STYLESHEET_FLAGS = -x $(STYLESHEET_SRCDIR)/xorg-xhtml.xsl +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_HTML_FLAGS = \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_SEARCHPATH_FLAGS) \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_HTML_STYLESHEET_FLAGS) \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_HTML_OLINK_FLAGS) + +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_FO_IMAGEPATH_FLAGS = --stringparam img.src.path=$(abs_builddir)/ +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_PDF_OLINK_FLAGS = \ +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --stringparam target.database.document=$(XORG_SGML_PATH)/X11/dbs/masterdb.pdf.xml \ +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --stringparam current.docid="$(<:.xml=)" + +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_FO_STYLESHEET_FLAGS = -x $(STYLESHEET_SRCDIR)/xorg-fo.xsl +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_FO_FLAGS = \ +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_SEARCHPATH_FLAGS) \ +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_FO_STYLESHEET_FLAGS) \ +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_FO_IMAGEPATH_FLAGS) \ +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_PDF_OLINK_FLAGS) + + +# Generate documents cross-reference target databases +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_SEARCHPATH_FLAGS = \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --path "$(XORG_SGML_PATH)/X11" \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --path "$(abs_top_builddir)" + +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_OLINK_FLAGS = \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --stringparam targets.filename "$@" \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --stringparam collect.xref.targets "only" \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --stringparam olink.base.uri "$(@:.db=)" + +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_HTML_FLAGS = \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(XSLT_SEARCHPATH_FLAGS) \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(XSLT_OLINK_FLAGS) \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --nonet --xinclude \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(STYLESHEET_SRCDIR)/xorg-xhtml.xsl + +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_PDF_FLAGS = \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(XSLT_SEARCHPATH_FLAGS) \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(XSLT_OLINK_FLAGS) \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --nonet --xinclude \ +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(STYLESHEET_SRCDIR)/xorg-fo.xsl + +@ENABLE_SPECS_TRUE@CLEANFILES = $(shelf_DATA) +all: all-am + +.SUFFIXES: +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/docbook.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign specs/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign specs/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +install-dist_shelfDATA: $(dist_shelf_DATA) + @$(NORMAL_INSTALL) + test -z "$(shelfdir)" || $(MKDIR_P) "$(DESTDIR)$(shelfdir)" + @list='$(dist_shelf_DATA)'; test -n "$(shelfdir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(shelfdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(shelfdir)" || exit $$?; \ + done + +uninstall-dist_shelfDATA: + @$(NORMAL_UNINSTALL) + @list='$(dist_shelf_DATA)'; test -n "$(shelfdir)" || list=; \ + files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ + test -n "$$files" || exit 0; \ + echo " ( cd '$(DESTDIR)$(shelfdir)' && rm -f" $$files ")"; \ + cd "$(DESTDIR)$(shelfdir)" && rm -f $$files +install-shelfDATA: $(shelf_DATA) + @$(NORMAL_INSTALL) + test -z "$(shelfdir)" || $(MKDIR_P) "$(DESTDIR)$(shelfdir)" + @list='$(shelf_DATA)'; test -n "$(shelfdir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(shelfdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(shelfdir)" || exit $$?; \ + done + +uninstall-shelfDATA: + @$(NORMAL_UNINSTALL) + @list='$(shelf_DATA)'; test -n "$(shelfdir)" || list=; \ + files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ + test -n "$$files" || exit 0; \ + echo " ( cd '$(DESTDIR)$(shelfdir)' && rm -f" $$files ")"; \ + cd "$(DESTDIR)$(shelfdir)" && rm -f $$files +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile $(DATA) +installdirs: + for dir in "$(DESTDIR)$(shelfdir)" "$(DESTDIR)$(shelfdir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +html-am: + +info: info-am + +info-am: + +install-data-am: install-dist_shelfDATA install-shelfDATA + +install-dvi: install-dvi-am + +install-dvi-am: + +install-exec-am: + +install-html: install-html-am + +install-html-am: + +install-info: install-info-am + +install-info-am: + +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-dist_shelfDATA uninstall-shelfDATA + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + distclean distclean-generic distclean-libtool distdir dvi \ + dvi-am html html-am info info-am install install-am \ + install-data install-data-am install-dist_shelfDATA \ + install-dvi install-dvi-am install-exec install-exec-am \ + install-html install-html-am install-info install-info-am \ + install-man install-pdf install-pdf-am install-ps \ + install-ps-am install-shelfDATA install-strip installcheck \ + installcheck-am installdirs maintainer-clean \ + maintainer-clean-generic mostlyclean mostlyclean-generic \ + mostlyclean-libtool pdf pdf-am ps ps-am uninstall uninstall-am \ + uninstall-dist_shelfDATA uninstall-shelfDATA + +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@%.html: %.xml $(chapters) +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(AM_V_GEN)$(XMLTO) $(XMLTO_HTML_FLAGS) xhtml-nochunks $< +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TEXT_TRUE@@HAVE_XMLTO_TRUE@%.txt: %.xml $(chapters) +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TEXT_TRUE@@HAVE_XMLTO_TRUE@ $(AM_V_GEN)$(XMLTO) $(XMLTO_HTML_FLAGS) txt $< +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@%.pdf: %.xml $(chapters) +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(AM_V_GEN)$(XMLTO) $(XMLTO_FO_FLAGS) --with-fop pdf $< +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@%.ps: %.xml $(chapters) +@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(AM_V_GEN)$(XMLTO) $(XMLTO_FO_FLAGS) --with-fop ps $< +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@%.html.db: %.xml $(chapters) +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(AM_V_GEN)$(XSLTPROC) $(XSLT_HTML_FLAGS) $< +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@%.pdf.db: %.xml $(chapters) +@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(AM_V_GEN)$(XSLTPROC) $(XSLT_PDF_FLAGS) $< + +# Generate DocBook/XML output formats with or without stylesheets + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/libXt/specs/Xtk.intr.front b/libXt/specs/Xtk.intr.front deleted file mode 100644 index 353467fdf..000000000 --- a/libXt/specs/Xtk.intr.front +++ /dev/null @@ -1,333 +0,0 @@ -.\" 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/libXt/specs/acknowledgement.xml b/libXt/specs/acknowledgement.xml new file mode 100644 index 000000000..ea25a5a49 --- /dev/null +++ b/libXt/specs/acknowledgement.xml @@ -0,0 +1,323 @@ + + +Acknowledgments + + +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: + + + + + + + + + + + + Loretta Guarino-Reid (Digital WSL) + Rich Hyde (Digital WSL) + + + Susan Angebranndt (Digital WSL) + Terry Weissman (Digital WSL) + + + Mary Larson (Digital UEG) + Mark Manasse (Digital SRC) + + + Jim Gettys (Digital SRC) + Leo Treggiari (Digital SDT) + + + Ralph Swick (Project Athena and Digital ERP) + Mark Ackerman (Project Athena) + + + Ron Newman (Project Athena) + Bob Scheifler (MIT LCS) + + + + + + + + +The contributors to the X10 toolkit also deserve mention. Although the X11 Intrinsics present an +entirely different programming style, they borrow heavily from the implicit and +explicit concepts in the X10 toolkit. + + + +The design and implementation of the X10 Intrinsics were done by: + + + + + + + + + + + Terry Weissman (Digital WSL) + + + Smokey Wallace (Digital WSL) + + + Phil Karlton (Digital WSL) + + + Charles Haynes (Digital WSL) + + + Frank Hall (HP) + + + + + + + + +The design and implementation of the X10 toolkit’s sample widgets were by +the above, as well as by: + + + + + + + + + + + Ram Rao (Digital UEG) + + + Mary Larson (Digital UEG) + + + Mike Gancarz (Digital UEG) + + + Kathleen Langone (Digital UEG) + + + + + + + + +These widgets provided a checklist of requirements that we had to address in the X11 Intrinsics. + + +Thanks go to Al Mento of Digital’s UEG Documentation Group for formatting and generally +improving this document and to John Ousterhout of Berkeley for extensively reviewing early +drafts of it. + + +Finally, a special thanks to Mike Chow, whose extensive performance analysis of the X10 toolkit +provided the justification to redesign it entirely for X11. + + + +Joel McCormack +Western Software Laboratory +Digital Equipment Corporation +March 1988 + + + + +The current design of the Intrinsics 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 Intrinsics: + + + + + + + + + + + + Steve Pitschke (Stellar) + C.Doug Blewett (AT&T) + + + Bob Miller (HP) + David Schiferl (Tektronix) + + + Fred Taft (HP) + Michael Squires (Sequent) + + + Marcel Meth (AT&T) + JimFulton (MIT) + + + Mike Collins (Digital) + Kerry Kimbrough (Texas Instruments) + + + Scott McGregor (Digital) + Phil Karlton (Digital) + + + Julian Payne (ESS) + Jacques Davy (Bull) + + + Gabriel Beged-Dov (HP) + GlennWidener (Tektronix) + + + + + + + + +Thanks go to each of them for the countless hours spent reviewing drafts and code. + + + +Ralph R. Swick +External Research Group +Digital Equipment Corporation +MIT Project Athena +June 1988 + + + + +From Release 3 to Release 4, several new members joined the design team. We greatly appreciate +the thoughtful comments, suggestions, lengthy discussions, and in some cases implementation +code contributed by each of the following: + + + + + + + + + + + + Don Alecci (AT&T) + EllisCohen (OSF) + + + Donna Converse (MIT) + Clive Feather (IXI) + + + Nayeem Islam (Sun) + Dana Laursen (HP) + + + Keith Packard (MIT) + Chris Peterson (MIT) + + + Richard Probst (Sun) + Larry Cable (Sun) + + + + + + + + +In Release 5, the effort to define the internationalization additions was headed by Bill McMahon +of Hewlett Packard and Frank Rojas of IBM. This has been an educational process for many of +us, and Bill and Frank’s tutelage has carried us through. Vania Joloboff of the OSF also contributed +to the internationalization additions. The implementation efforts of Bill, Gabe Beged-Dov, +and especially Donna Converse for this release are also gratefully acknowledged. + + + +Ralph R. Swick +December 1989 +and +July 1991 + + + +The Release 6 Intrinsics is a result of the collaborative efforts of participants in the X Consortium’s +intrinsics 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: + + + + + + + + + + + + Paul Asente (Adobe) + Larry Cable (SunSoft) + + + Ellis Cohen (OSF) + Daniel Dardailler (OSF) + + + Vania Joloboff (OSF) + KalebKeithley (X Consortium) + + + Courtney Loomis (HP) + Douglas Rand (OSF) + + + Bob Scheifler (X Consortium) + Ajay Vohra (SunSoft) + + + + + + + + +Many others analyzed designs, offered useful comments and suggestions, and participated in a +significant subset of the process. The following people deserve thanks for their 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. + + + +I am especially grateful to two of my colleagues: Ralph Swick for expert editorial guidance, and +Kaleb Keithley for leadership in the implementation and the specification work. + + + +Donna Converse +X Consortium +April 1994 + + + diff --git a/libXt/specs/appA b/libXt/specs/appA deleted file mode 100644 index 57a1890a7..000000000 --- a/libXt/specs/appA +++ /dev/null @@ -1,107 +0,0 @@ -.\" $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 | -Comment = ``!'' {} -IncludeFile = ``#'' WhiteSpace ``include'' WhiteSpace FileName WhiteSpace -FileName = -ResourceSpec = WhiteSpace ResourceName WhiteSpace ``:'' WhiteSpace Value -ResourceName = [Binding] {Component Binding} ComponentName -Binding = ``.'' | ``*'' -WhiteSpace = { | } -Component = ``?'' | ComponentName -ComponentName = NameChar {NameChar} -NameChar = ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' -Value = {} -.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/libXt/specs/appA.xml b/libXt/specs/appA.xml new file mode 100644 index 000000000..daf40eb3c --- /dev/null +++ b/libXt/specs/appA.xml @@ -0,0 +1,112 @@ + +Resource File Format + +A resource file contains text representing the default resource values for an +application or set of applications. + + + +The format of resource files is defined by +Xlib — C Language X Interface. and is reproduced here +for convenience only. + + +The format of a resource specification is + + + + + + + + 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>} + + + + + + +Elements separated by vertical bar (|) are alternatives. +Curly braces ({...}) indicate zero or more repetitions +of the enclosed elements. +Square brackets ([...]) indicate that the enclosed element is optional. +Quotes ("...") are used around literal characters. + + + +If the last character on a line is a backslash (\), +that line is assumed to continue on the next line. + + + +To allow a Value to begin with whitespace, +the two-character sequence "\space" (backslash followed by space) +is recognized and replaced by a space character, +and the two-character sequence "\tab" +(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 "\newline" +(backslash followed by newline) is +recognized and removed from the value. + + +To allow a Value to contain arbitrary character codes, +the four-character sequence "\nnn", +where each n 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/libXt/specs/appB b/libXt/specs/appB deleted file mode 100644 index 3eb9ccc7b..000000000 --- a/libXt/specs/appB +++ /dev/null @@ -1,783 +0,0 @@ -.\" $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 = [ ``^'' | ``$'' | ``\\\\'' ] -event = [modifier_list] ``<''event_type``>'' [ ``('' count[``+''] ``)'' ] {detail} -modifier_list = ( [``!''] [``:''] {modifier} ) | ``None'' -modifier = [``~''] modifier_name -count = (``1'' | ``2'' | ``3'' | ``4'' | ...) -modifier_name = ``@'' | -event_type = -detail = -rhs = { name ``('' [params] ``)'' } -name = namechar { namechar } -namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' } -params = string {``,'' string} -string = quoted_string | unquoted_string -quoted_string = ``"'' { | escape_char} [``\\\\\\\\'' ] ``"'' -escape_char = ``\\\\"'' -unquoted_string = {} -.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, ``:a'' is distinct from ``:A'', -and ``:ShiftA'' is distinct from ``: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, ``A'' and ``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 detail -Any modifiers: detail -Only these modifiers: ! mod1 mod2 detail -These modifiers and any others: mod1 mod2 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 ``@'' 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, 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, 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 = ``@'' | -event_type = -detail = -rhs = { name ``('' [params] ``)'' } -name = namechar { namechar } -namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' } -params = string {``,'' string} -string = quoted_string -quoted_string = ``"'' { | escape_char} [``\\\\\\\\'' ] ``"'' -escape_char = ``\\\\"'' -.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 : twas()\\n\\ - : brillig() -.De -.LP -.IP \(bu 5 -For double-click on Button1 Up with Shift, use this specification: -.IP -.Ds -Shift(2) : and() -.DE -.IP -This is equivalent to the following line with appropriate timers set -between events: -.IP -.Ds -Shift,Shift,Shift,Shift : and() -.De -.IP \(bu 5 -For double-click on Button1 Down with Shift, use this specification: -.IP -.Ds -Shift(2) : the() -.De -.IP -This is equivalent to the following line with appropriate timers set -between events: -.IP -.Ds -Shift,Shift,Shift : 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 -, : 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 -, : toves()\\n\\ - : 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 , Shift Meta: 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 (2+) : and() -.De -.IP \(bu 5 -To indicate -.PN EnterNotify -with any modifiers, use this specification: -.IP -.Ds - : gimble() -.De -.IP \(bu 5 -To indicate -.PN EnterNotify -with no modifiers, use this specification: -.IP -.Ds -None : 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 : the() -.De -.IP \(bu 5 -To indicate -.PN EnterNotify -with Button1 down and Button2 down exclusively, use this specification: -.IP -.Ds -! Button1 Button2 : wabe() -.De -.IP -You do not need to use a tilde (~) with an exclamation point (!). diff --git a/libXt/specs/appB.xml b/libXt/specs/appB.xml new file mode 100644 index 000000000..0afac11e0 --- /dev/null +++ b/libXt/specs/appB.xml @@ -0,0 +1,1181 @@ + +Translation Table Syntax +Notation + + +Syntax is specified in EBNF notation with the following conventions: + + + + + + + + + + [ a ] + Means either nothing or "a" + + + { a } + Means zero or more occurrences of "a" + + + ( a | b ) + Means either "a" or "b" + + + \\n + Is the newline character + + + + + + +All terminals are enclosed in double quotation marks (" "). +Informal descriptions are enclosed in angle brackets (< >). +Syntax + + +The syntax of a translation table is + + + + + + + + translationTable + = [ directive ] { production } + + + directive + = ( "#replace" | "#override" | "#augment" ) "\\\\n" + + + production + = lhs ":" rhs "\\\\n" + + + lhs + = ( event | keyseq ) { "," (event | keyseq) } + + + keyseq + = """ keychar {keychar} """ + + + keychar + = [ "^" | "$" | "\\\\" ] <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", ")">} + + + + + + +The params field is parsed into a list of +String +values that will be passed to the named action procedure. A +quoted string 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". + +Modifier Names + + +The modifier field is used to specify standard X keyboard and button +modifier mask bits. +Modifiers are legal on event types +KeyPress, +KeyRelease, +ButtonPress, +ButtonRelease, +MotionNotify, +EnterNotify, +LeaveNotify, +and their abbreviations. +An error is generated when a translation table +that contains modifiers for any other events is parsed. + + + + + +If the modifier list has no entries and is not "None", +it means "don't care" on all modifiers. + + + + +If an exclamation point (!) is specified at the beginning +of the modifier list, +it means that the listed modifiers must be in the correct state +and no other modifiers can be asserted. + + + + +If any modifiers are specified +and an exclamation point (!) is not specified, +it means that the listed modifiers must be in the +correct state and "don't care" about any other modifiers. + + + + +If a modifier is preceded by a tilde (~), +it means that that modifier must not be asserted. + + + + +If "None" is specified, it means no modifiers can be asserted. + + + + +If a colon (:) is specified at the beginning of the modifier list, +it directs the Intrinsics to apply any standard modifiers in the +event to map the event keycode into a KeySym. +The default standard modifiers are Shift and Lock, +with the interpretation as defined in X Window +System Protocol, 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". + + + + +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. + + + + +If a colon (:) is not specified, +no standard modifiers are applied. +Then, for example, "<Key>A" and "<Key>a" are equivalent. + + + + + +In key sequences, +a circumflex (^) 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: + + + +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 + + + +The use of "None" for a modifier list is identical to the use +of an exclamation point with no modifers. + + + + + + + + + + + Modifier + Abbreviation + Meaning + + + + + Ctrl + c + Control modifier bit + + + Shift + s + Shift modifier bit + + + Lock + l + Lock modifier bit + + + Meta + m + Meta key modifier + + + Hyper + h + Hyper key modifier + + + Super + su + Super key modifier + + + Alt + a + Alt key modifier + + + Mod1 + + Mod1 modifier bit + + + Mod2 + + Mod2 modifier bit + + + Mod3 + + Mod3 modifier bit + + + Mod4 + + Mod4 modifier bit + + + Mod5 + + Mod5 modifier bit + + + Button1 + + Button1 modifier bit + + + Button2 + + Button2 modifier bit + + + Button3 + + Button3 modifier bit + + + Button4 + + Button4 modifier bit + + + Button5 + + Button5 modifier bit + + + None + + No modifiers + + + Any + + Any modifier combination + + + + + + +A key modifier is any modifier bit one of whose 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. + + + +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. + + + +A modifier_list/KeySym combination in a translation matches a +modifiers/KeyCode combination in an event in the following ways: + + + + + +If a colon (:) is used, the Intrinsics call the display's + +with the KeyCode and modifiers. +To match, (modifiers & ~modifiers_return) must equal modifier_list, and +keysym_return must equal the given KeySym. + + + + +If (:) is not used, the Intrinsics mask off all don't-care bits from the +modifiers. +This value must be equal to modifier_list. +Then, for each possible combination of +don't-care modifiers in the modifier list, the Intrinsics call the display's + +with the KeyCode and that combination ORed with the cared-about modifier bits +from the event. +Keysym_return must match the KeySym in the translation. + + + + +Event Types + + +The event-type field describes XEvent types. +In addition to the standard +Xlib symbolic event type names, the following event type synonyms +are defined: + + + + + + + + + + Type + Meaning + + + + + Key + KeyPress + + + KeyDown + KeyPress + + + KeyUp + KeyRelease + + + BtnDown + ButtonPress + + + BtnUp + ButtonRelease + + + Motion + MotionNotify + + + PtrMoved + MotionNotify + + + MouseMoved + MotionNotify + + + Enter + EnterNotify + + + EnterWindow + EnterNotify + + + Leave + LeaveNotify + + + LeaveWindow + LeaveNotify + + + FocusIn + FocusIn + + + FocusOut + FocusOut + + + Keymap + KeymapNotify + + + Expose + Expose + + + GrExp + GraphicsExpose + + + NoExp + NoExpose + + + Visible + VisibilityNotify + + + Create + CreateNotify + + + Destroy + DestroyNotify + + + Unmap + UnmapNotify + + + Map + MapNotify + + + MapReq + MapRequest + + + Reparent + ReparentNotify + + + Configure + ConfigureNotify + + + ConfigureReq + ConfigureRequest + + + Grav + GravityNotify + + + ResReq + ResizeRequest + + + Circ + CirculateNotify + + + CircReq + CirculateRequest + + + Prop + PropertyNotify + + + SelClr + SelectionClear + + + SelReq + SelectionRequest + + + Select + SelectionNotify + + + Clrmap + ColormapNotify + + + Message + ClientMessage + + + Mapping + MappingNotify + + + + + +The supported abbreviations are: + + + + + + + + + + Abbreviation + Event Type + Including + + + + + Ctrl + KeyPress + with Control modifier + + + Meta + KeyPress + with Meta modifier + + + Shift + KeyPress + with Shift modifier + + + Btn1Down + ButtonPress + with Button1 detail + + + Btn1Up + ButtonRelease + with Button1 detail + + + Btn2Down + ButtonPress + with Button2 detail + + + Btn2Up + ButtonRelease + with Button2 detail + + + Btn3Down + ButtonPress + with Button3 detail + + + Btn3Up + ButtonRelease + with Button3 detail + + + Btn4Down + ButtonPress + with Button4 detail + + + Btn4Up + ButtonRelease + with Button4 detail + + + Btn5Down + ButtonPress + with Button5 detail + + + Btn5Up + ButtonRelease + with Button5 detail + + + BtnMotion + MotionNotify + with any button modifier + + + Btn1Motion + MotionNotify + with Button1 modifier + + + Btn2Motion + MotionNotify + with Button2 modifier + + + Btn3Motion + MotionNotify + with Button3 modifier + + + Btn4Motion + MotionNotify + with Button4 modifier + + + Btn5Motion + MotionNotify + with Button5 modifier + + + + + + +The detail field is event-specific and normally corresponds to the +detail field of the corresponding event as described +by X Window System Protocol, Section 11. +The detail field is supported for the following event types: + + + + + + + + + + KeyPress + KeySym from event detail (keycode) + + + KeyRelease + KeySym from event detail (keycode) + + + ButtonPress + button from event detail + + + ButtonRelease + button from event detail + + + MotionNotify + event detail + + + EnterNotify + event mode + + + LeaveNotify + event mode + + + FocusIn + event mode + + + FocusOut + event mode + + + PropertyNotify + atom + + + SelectionClear + selection + + + SelectionRequest + selection + + + SelectionNotify + selection + + + ClientMessage + type + + + MappingNotify + request + + + + + + +If the event type is +KeyPress +or +KeyRelease, +the detail field +specifies a KeySym name in standard format which is matched against +the event as described above, for example, <Key>A. + + + +For the +PropertyNotify, +SelectionClear, +SelectionRequest, +SelectionNotify, +and +ClientMessage +events the detail field is specified +as an atom name; for example, <Message>WM_PROTOCOLS. For the +MotionNotify, +EnterNotify, +LeaveNotify, +FocusIn, +FocusOut, +and +MappingNotify +events, either the symbolic constants as defined by +X Window +System Protocol, Section 11, +or the numeric values may be specified. + + + +If no detail field is specified, then any value in the event detail is +accepted as a match. + + + +A KeySym can be specified as any of the standard KeySym names, +a hexadecimal number prefixed with "0x" or "0X", +an octal number prefixed with "0", or a decimal number. +A 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 +<X11/keysymdef.h> +with the "XK_" prefix removed. + + +Canonical Representation + + +Every translation table has a unique, canonical text representation. This +representation is passed to a widget's +display_accelerator +procedure to describe the accelerators installed on that widget. +The canonical representation of a translation table is (see also +"Syntax") + + + + + + + + + + translationTable + = { production } + + + + production + = lhs ":" rhs "\\n" + + + + lhs + =event { "," event } + + + + event + =[modifier_list] "<"event_type">" [ "(" count["+"] ")" ] {detail} + + + + modifier_list + = ["!"] [":"] {modifier} + + + + modifier + = ["˜"] modifier_name + + + + count + =("1" | "2" | "3" | "4" | ...) + + + + modifier_name + = "@" <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 + = "\\"" + + + + + + +The canonical modifier names are + + + Ctrl Mod1 Button1 + Shift Mod2 Button2 + Lock Mod3 Button3 + Mod4 Button4 + Mod5 Button5 + + +The canonical event types are + + + + + + + + + KeyPress + KeyRelease + + + ButtonPress + ButtonRelease + + + MotionNotify + EnterNotify + + + LeaveNotify + FocusIn + + + FocusOut + KeymapNotify + + + Expose + GraphicsExpose, + + + NoExpose + VisibilityNotify + + + CreateNotify + DestroyNotify + + + UnmapNotify + MapNotify + + + MapRequest + ReparentNotify + + + ConfigureNotify + ConfigureRequest + + + GravityNotify + ResizeRequest + + + CirculateNotify + CirculateRequest + + + PropertyNotify + SelectionClear + + + SelectionRequest + SelectionNotify + + + ColormapNotify + ClientMessage + + + + + +Examples + + + + +Always put more specific events in the table before more general ones: + + + Shift <Btn1Down> : twas()\n\ + <Btn1Down> : brillig() + + + + +For double-click on Button1 Up with Shift, use this specification: + + +Shift<Btn1Up>(2) : and() + + + + +This is equivalent to the following line with appropriate timers set +between events: + + +Shift<Btn1Down>,Shift<Btn1Up>,Shift<Btn1Down>,Shift<Btn1Up> : and() + + + + +For double-click on Button1 Down with Shift, use this specification: + + +Shift<Btn1Down>(2) : the() + + + + +This is equivalent to the following line with appropriate timers set +between events: + + +Shift<Btn1Down>,Shift<Btn1Up>,Shift<Btn1Down> : the() + + + + +Mouse motion is always discarded when it occurs between events in a table +where no motion event is specified: + + +<Btn1Down>,<Btn1Up> : slithy() + + +This is taken, even if the pointer moves a bit between the down and +up events. +Similarly, any motion event specified in a translation matches any number +of motion events. +If the motion event causes an action procedure to be invoked, +the procedure is invoked after each motion event. + + + + +If an event sequence consists of a sequence of events that is also a +noninitial subsequence of another translation, +it is not taken if it occurs in the context of the longer sequence. +This occurs mostly in sequences like the following: + + +<Btn1Down>,<Btn1Up> : toves()\n\ +<Btn1Up> : did() + + +The second translation is taken only if the button release is not +preceded by a button press or if there are intervening events between the +press and the release. +Be particularly aware of this when using the repeat notation, above, +with buttons and keys, +because their expansion includes additional events; +and when specifying motion events, because they are implicitly included +between any two other events. +In particular, +pointer motion and double-click translations cannot coexist in the same +translation table. + + + + +For single click on Button1 Up with Shift and Meta, use this specification: + + + + +Shift Meta <Btn1Down>, Shift Meta<Btn1Up>: gyre() + + + + +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 count-th click and each subsequent one arriving +within the multi-click time interval. For example: + + +Shift <Btn1Up>(2+) : and() + + + + +To indicate +EnterNotify +with any modifiers, use this specification: + + +<Enter> : gimble() + + + + +To indicate +EnterNotify +with no modifiers, use this specification: + + +None <Enter> : in() + + + + +To indicate +EnterNotify +with Button1 Down and Button2 Up and "don't care" about +the other modifiers, use this specification: + + +Button1 ~Button2 <Enter> : the() + + + + +To indicate +EnterNotify +with Button1 down and Button2 down exclusively, use this specification: + + +! Button1 Button2 <Enter> : wabe() + + +You do not need to use a tilde (~) with an exclamation point (!). + + + + diff --git a/libXt/specs/appC b/libXt/specs/appC deleted file mode 100644 index 6f31fd7d5..000000000 --- a/libXt/specs/appC +++ /dev/null @@ -1,1204 +0,0 @@ -.\" $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/libXt/specs/appC.xml b/libXt/specs/appC.xml new file mode 100644 index 000000000..4598ac99e --- /dev/null +++ b/libXt/specs/appC.xml @@ -0,0 +1,1970 @@ + +Compatibility Functions +<footnote> +<para> +This appendix is part of the formal Intrinsics Specification. +</para> +</footnote> + + +In prototype versions of the X Toolkit +each widget class +implemented an Xt<Widget>Create (for example, +XtLabelCreate) +function, in which most of the code was identical from widget to widget. +In the Intrinsics, a single generic + +performs most of the common work and then calls the initialize procedure +implemented for the particular widget class. + + + +Each Composite class also implemented the procedures +Xt<Widget>Add and an Xt<Widget>Delete (for example, +XtButtonBoxAddButton +and +XtButtonBoxDeleteButton). +In the Intrinsics, the Composite generic procedures + +and + +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. + + + +Old-style calls can be implemented in the X Toolkit by defining +one-line procedures or macros that invoke a generic routine. For example, +you could define the macro +XtLabelCreate +as: + + + +#define XtLabelCreate(name, parent, args, num_args) \ + ((LabelWidget) XtCreateWidget(name, labelWidgetClass, parent, args, num_args)) + + + +Pop-up shells in some of the prototypes automatically performed an + +on their child within their insert_child procedure. +Creators of pop-up children need to call + +themselves. + + + + +and + +have been replaced by + +and +. + + + +To initialize the Intrinsics internals, create an application context, +open and initialize a display, and create the initial application shell +instance, an application may use + +or +. + + + + +Widget XtAppInitialize + XtAppContext *app_context_return + String application_class + XrmOptionDescList options + Cardinal num_options + int *argc_in_out + String *argv_in_out + String *fallback_resources + ArgList args + Cardinal num_args + + + + + + + app_context_return + + + +Returns the application context, if non-NULL. + + + + + + application_class + + + +Specifies the class name of the application. + + + + + + options + + + +Specifies the command line options table. + + + + + + num_options + + + +Specifies the number of entries in options. + + + + + + argc_in_out + + + +Specifies a pointer to the number of command line arguments. + + + + + + argv_in_out + + + +Specifies a pointer to the command line arguments. + + + + + + fallback_resources + + + +Specifies resource values to be used if the application class resource +file cannot be opened or read, or NULL. + + + + + + args + + + +Specifies the argument list to override any +other resource specifications for the created shell widget. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +function calls + +followed by +, +then calls + +with display_string NULL and +application_name NULL, and finally calls + +with application_name NULL, widget_class +application\%Shell\%Widget\%Class, +and the specified args and num_args +and returns the created shell. The modified argc and argv returned by + +are returned in argc_in_out and argv_in_out. If +app_context_return 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 + +terminates the application. If fallback_resources is non-NULL, + +is called with the value prior to calling +. + + + + +Widget XtVaAppInitialize + XtAppContext *app_context_return + String application_class + XrmOptionDescList options + Cardinal num_options + int *argc_in_out + String *argv_in_out + String *fallback_resources + + + + + + + app_context_return + + + +Returns the application context, if non-NULL. + + + + + + application_class + + + +Specifies the class name of the application. + + + + + + options + + + +Specifies the command line options table. + + + + + + num_options + + + +Specifies the number of entries in options. + + + + + + argc_in_out + + + +Specifies a pointer to the number of command line arguments. + + + + + + argv_in_out + + + +Specifies the command line arguments array. + + + + + + fallback_resources + + + +Specifies resource values to be used if the application class +resource file cannot be opened, or NULL. + + + + + + ... + + + +Specifies the variable argument list to override any other +resource specifications for the created shell. + + + + + + +The + +procedure is identical in function to + +with the args and num_args parameters replaced by a varargs list, +as described +in Section 2.5.1. + + + +As a convenience to people converting from earlier versions of the toolkit +without application contexts, the following routines exist: +, +, +, +, +, +, +, +, +, +, +, +, +and +. + + + + +Widget XtInitialize + String shell_name + String application_class + XrmOptionDescRec options + Cardinal num_options + int *argc + String argv + + + + + + + shell_name + + + +This parameter is ignored; therefore, you can specify NULL. + + + + + + application_class + + + +Specifies the class name of this application. + + + + + + options + + + +Specifies how to parse the command line for any application-specific resources. +The options argument is passed as a parameter to +XrmParseCommand. + + + + + + num_options + + + +Specifies the number of entries in the options list. + + + + + + argc + + + +Specifies a pointer to the number of command line parameters. + + + + + + argv + + + +Specifies the command line parameters. + + + + + + + +calls + +to initialize the toolkit internals, +creates a default application context for use by the other convenience +routines, calls + +with display_string NULL and application_name NULL, and +finally calls + +with application_name NULL and +returns the created shell. +The semantics of calling + +more than once are undefined. +This routine has been replaced by +. + + + + +void XtMainLoop + void + + + + + +first reads the next alternate input, timer, or X event by calling +. +Then it dispatches this to the appropriate registered procedure by calling +. +This routine has been replaced by +. + + + + +void XtNextEvent + XEvent *event_return + + + + + + + event_return + + + +Returns the event information to the specified event structure. + + + + + + +If no input is on the X input queue for the default application context, + +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 +. + +must be called before using this routine. + + + + +void XtProcessEvent + XtInputMask mask + + + + + + + mask + + + +Specifies the type of input to process. + + + + + + + +processes one X event, timeout, or alternate input source +(depending on the value of mask), blocking if necessary. +It has been replaced by +. + +must be called before using this function. + + + + +Boolean XtPeekEvent + XEvent *event_return + + + + + + + event_return + + + +Returns the event information to the specified event structure. + + + + + + +If there is an event in the queue for the default application context, + +fills in the event and returns a nonzero value. +If no X input is on the queue, + +flushes the output buffer and blocks until input is available, possibly +calling some timeout callbacks in the process. +If the input is an event, + +fills in the event and returns a nonzero value. +Otherwise, the input is for an alternate input source, and + +returns zero. +This routine has been replaced by +. + +must be called before using this routine. + + + + +Boolean 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 +. + +must be called before using this routine. + + + + +XtInputId XtAddInput + int source + XtPointer condition + XtInputCallbackProc proc + XtPointer client_data + + + + + + + source + + + +Specifies the source file descriptor on a POSIX-based system +or other operating-system-dependent device specification. + + + + + + condition + + + +Specifies the mask that indicates either a read, write, or exception condition +or some operating-system-dependent condition. + + + + + + proc + + + +Specifies the procedure called when input is available. + + + + + + client_data + + + +Specifies the parameter to be passed to proc when input is available. + + + + + + +The + +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 file should be loosely interpreted to mean any sink +or source of data.) + +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 +. + +must be called before using this routine. + + + + +XtIntervalId XtAddTimeOut + unsigned long interval + XtTimerCallbackProc proc + XtPointer client_data + + + + + + + interval + + + +Specifies the time interval in milliseconds. + + + + + + proc + + + +Specifies the procedure to be called when time expires. + + + + + + client_data + + + +Specifies the parameter to be passed to proc when it is called. + + + + + + +The + +function creates a timeout in the default application context +and returns an identifier for it. +The timeout value is set to interval. +The callback procedure will be called after +the time interval elapses, after which the timeout is removed. +This routine has been replaced by +. + +must be called before using this routine. + + + + +XtWorkProcId XtAddWorkProc + XtWorkProc proc + XtPointer client_data + + + + + + + proc + + + +Procedure to call to do the work. + + + + + + client_data + + + +Client data to pass to proc when it is called. + + + + + + +This routine registers a work procedure in the default application context. It has +been replaced by +. + +must be called before using this routine. + + + + +Widget XtCreateApplicationShell + String name + WidgetClass widget_class + ArgList args + Cardinal num_args + + + + + + + name + + + +This parameter is ignored; therefore, you can specify NULL. + + + + + + widget_class + + + +Specifies the widget class pointer for the created application shell widget. +This will usually be +topLevelShellWidgetClass +or a subclass thereof. + + + + + + args + + + +Specifies the argument list to override any other resource specifications. + + + + + + num_args + + + +Specifies the number of entries in args. + + + + + + +The procedure + +calls + +with application_name NULL, the application class passed to +, +and the default application context created by +. +This routine has been replaced by +. + + + +An old-format resource type converter procedure pointer is of type +. + + + + +typedef void (*XtConverter) + + XrmValue *args + Cardinal *num_args + XrmValue *from + XrmValue *to + + + + + + + args + + + +Specifies a list of additional +XrmValue +arguments to the converter if additional context is needed +to perform the conversion, or NULL. + + + + + + num_args + + + +Specifies the number of entries in args. + + + + + + from + + + +Specifies the value to convert. + + + + + + to + + + +Specifies the descriptor to use to return the converted value. + + + + + + +Type converters should perform the following actions: + + + + +Check to see that the number of arguments passed is correct. + + + + +Attempt the type conversion. + + + + +If successful, return the size and pointer to the data in the to argument; +otherwise, call + +and return without modifying the to argument. + + + + +Most type converters just take the data described by the specified from +argument and return data by writing into the specified to argument. +A few need other information, which is 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. + + + +Note that the address returned in to->addr cannot be that of a local variable of +the converter because this is not valid after the converter returns. +It should be a pointer to a static variable. + + + +The procedure type + +has been replaced by +. + + + +The + +function is a convenience routine for old-format resource converters +that convert from strings. + + + + +void XtStringConversionWarning + String src + + + + + + + src + + + +Specifies the string that could not be converted. + + + + + + dst_type + + + +Specifies the name of the type to which the string could not be converted. + + + + + + +The + +function issues a warning message with name "conversionError", +type "string", class "XtToolkitError, and the default message string +"Cannot convert "src" to type dst_type". This routine +has been superseded by +. + + + +To register an old-format converter, use + +or +. + + + + +void XtAddConverter + String from_type + String to_type + XtConverter converter + XtConvertArgList convert_args + Cardinal num_args + + + + + + + from_type + + + +Specifies the source type. + + + + + + to_type + + + +Specifies the destination type. + + + + + + converter + + + +Specifies the type converter procedure. + + + + + + convert_args + + + +Specifies how to compute the additional arguments to the converter, or NULL. + + + + + + num_args + + + +Specifies the number of entries in convert_args. + + + + + + + +is equivalent in function to + +with cache_type equal to +XtCacheAll +for old-format type converters. It has been superseded by +. + + + + +void XtAppAddConverter + XtAppContext app_context + String from_type + String to_type + XtConverter converter + XtConvertArgList convert_args + Cardinal num_args + + + + + + + app_context + + + +Specifies the application context. + + + + + + from_type + + + +Specifies the source type. + + + + + + to_type + + + +Specifies the destination type. + + + + + + converter + + + +Specifies the type converter procedure. + + + + + + convert_args + + + +Specifies how to compute the additional arguments to the converter, or NULL. + + + + + + num_args + + + +Specifies the number of entries in convert_args. + + + + + + + +is equivalent in function to + +with cache_type equal to +XtCacheAll +for old-format type converters. It has been superseded by +. + + + +To invoke resource conversions, a client may use + +or, for old-format converters only, +. + + + + +void XtConvert + Widget w + String from_type + XrmValuePtr from + String to_type + XrmValuePtr to_return + + + + + + + w + + + +Specifies the widget to use for additional arguments, if any are +needed. + + + + + + from_type + + + +Specifies the source type. + + + + + + from + + + +Specifies the value to be converted. + + + + + + to_type + + + +Specifies the destination type. + + + + + + to_return + + + +Returns the converted value. + + + + + + + + +void XtDirectConvert + XtConverter converter + XrmValuePtr args + Cardinal num_args + XrmValuePtr from + XrmValuePtr to_return + + + + + + + converter + + + +Specifies the conversion procedure to be called. + + + + + + args + + + +Specifies the argument list that contains the additional arguments +needed to perform the conversion (often NULL). + + + + + + num_args + + + +Specifies the number of entries in args. + + + + + + from + + + +Specifies the value to be converted. + + + + + + to_return + + + +Returns the converted value. + + + + + + +The + +function looks up the type converter registered to convert from_type +to to_type, computes any additional arguments needed, and then calls + +or +. +The + +function looks in the converter cache to see if this conversion procedure +has been called with the specified arguments. +If so, it returns a descriptor for information stored in the cache; +otherwise, it calls the converter and enters the result in the cache. + + + +Before calling the specified converter, + +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 to_return.addr for non-NULL. +The data returned by + +must be copied immediately by the caller, +as it may point to static data in the type converter. + + + + +has been replaced by +, +and + +has been superseded by +. + + + +To deallocate a shared GC when it is no longer needed, use +. + + + + +void XtDestroyGC + Widget w + GC gc + + + + + + + w + + + +Specifies any object on the display for which the shared GC was +created. Must be of class Object or any subclass thereof. + + + + + + gc + + + +Specifies the shared GC to be deallocated. + + + + + + +References to sharable GCs are counted and a free request is generated to the +server when the last user of a given GC destroys it. +Note that some earlier versions of + +had only a gc argument. +Therefore, this function is not very portable, +and you are encouraged to use + +instead. + + + +To declare an action table in the default application context +and register it with the translation manager, use +. + + + + +void XtAddActions + XtActionList actions + Cardinal num_actions + + + + + + + actions + + + +Specifies the action table to register. + + + + + + num_actions + + + +Specifies the number of entries in actions. + + + + + + +If more than one action is registered with the same name, +the most recently registered action is used. +If duplicate actions exist in an action table, +the first is used. +The Intrinsics register an action table for + +and + +as part of X Toolkit initialization. +This routine has been replaced by +. + +must be called before using this routine. + + + +To set the Intrinsics selection timeout in the default application context, use +. + + + + +void XtSetSelectionTimeout + unsigned long timeout + + + + + + + + timeout + + + +Specifies the selection timeout in milliseconds. +This routine has been replaced by +. + +must be called before using this routine. + + + + + + + +To get the current selection timeout value in the default application +context, use +. + + + + +unsigned long XtGetSelectionTimeout + + + + + +The selection timeout is the time within which the two communicating +applications must respond to one another. +If one of them does not respond within this interval, +the Intrinsics abort the selection request. + + + +This routine has been replaced by +. + +must be called before using this routine. + + + +To obtain the global error database (for example, to merge with +an application- or widget-specific database), use +. + + + + +XrmDatabase *XtGetErrorDatabase + + + + + +The + +function returns the address of the error database. +The Intrinsics do a lazy binding of the error database and do not merge in the +database file until the first call to +XtGetErrorDatbaseText. +This routine has been replaced by +. + + + +An error message handler can obtain the error database text for an +error or a warning by calling +. + + + + +void XtGetErrorDatabaseText + String name + String default + String buffer_return + int nbytes + + + + + + + name + + + + + + + + type + + + +Specify the name and type that are concatenated to form the resource name +of the error message. + + + + + + class + + + +Specifies the resource class of the error message. + + + + + + default + + + +Specifies the default message to use if an error database entry is not found. + + + + + + buffer_return + + + +Specifies the buffer into which the error message is to be returned. + + + + + + nbytes + + + +Specifies the size of the buffer in bytes. + + + + + + +The + +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 name and type are concatenated with a single "." +between them and the class is concatenated with itself with a +single "." if it does not already contain a ".". +This routine has been superseded by +. + + + +To register a procedure to be called on fatal error conditions, use +. + + + + +void XtSetErrorMsgHandler + XtErrorMsgHandler msg_handler + + + + + + + msg_handler + + + +Specifies the new fatal error procedure, which should not return. + + + + + + +The default error handler provided by the Intrinsics constructs a +string from the error resource database and calls +. +Fatal error message handlers should not return. +If one does, +subsequent Intrinsics behavior is undefined. +This routine has been superseded by +. + + + +To call the high-level error handler, use +. + + + + +void XtErrorMsg + String name + String type + String class + String default + String *params + Cardinal *num_params + + + + + + + name + + + +Specifies the general kind of error. + + + + + + type + + + +Specifies the detailed name of the error. + + + + + + class + + + +Specifies the resource class. + + + + + + default + + + +Specifies the default message to use if an error database entry is not found. + + + + + + params + + + +Specifies a pointer to a list of values to be stored in the message. + + + + + + num_params + + + +Specifies the number of entries in params. + + + + + + +This routine has been superseded by +. + + + +To register a procedure to be called on nonfatal error conditions, use +. + + + + +void XtSetWarningMsgHandler + XtErrorMsgHandler msg_handler + + + + + + + msg_handler + + + +Specifies the new nonfatal error procedure, which usually returns. + + + + + + +The default warning handler provided by the Intrinsics constructs a string +from the error resource database and calls +. +This routine has been superseded by +. + + + +To call the installed high-level warning handler, use +. + + + + +void XtWarningMsg + String name + String type + String class + String default + String *params + Cardinal *num_params + + + + + + + name + + + +Specifies the general kind of error. + + + + + + type + + + +Specifies the detailed name of the error. + + + + + + class + + + +Specifies the resource class. + + + + + + default + + + +Specifies the default message to use if an error database entry is not found. + + + + + + params + + + +Specifies a pointer to a list of values to be stored in the message. + + + + + + num_params + + + +Specifies the number of entries in params. + + + + + + +This routine has been superseded by +. + + + +To register a procedure to be called on fatal error conditions, use +. + + + + +void XtSetErrorHandler + XtErrorHandler handler + + + + + + + handler + + + +Specifies the new fatal error procedure, which should not return. + + + + + + +The default error handler provided by the Intrinsics is +_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 X Toolkit behavior is undefined. +This routine has been superseded by +. + + + +To call the installed fatal error procedure, use +. + + + + +void XtError + String message + + + + + + + message + + + +Specifies the message to be reported. + + + + + + +Most programs should use +, +not +, +to provide for customization and internationalization of error +messages. This routine has been superseded by +. + + + +To register a procedure to be called on nonfatal error conditions, use +. + + + + +void XtSetWarningHandler + XtErrorHandler handler + + + + + + + handler + + + +Specifies the new nonfatal error procedure, which usually returns. + + + + + + +The default warning handler provided by the Intrinsics is +_XtWarning. +On POSIX-based systems, +it prints the message to standard error and returns to the caller. +This routine has been superseded by +. + + + +To call the installed nonfatal error procedure, use +. + + + + +void XtWarning + String message + + + + + + + message + + + +Specifies the nonfatal error message to be reported. + + + + + + +Most programs should use +, +not +, +to provide for customization and internationalization of warning messages. +This routine has been superseded by +. + + diff --git a/libXt/specs/appD b/libXt/specs/appD deleted file mode 100644 index 5322ff97b..000000000 --- a/libXt/specs/appD +++ /dev/null @@ -1,602 +0,0 @@ -.\" $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/libXt/specs/appD.xml b/libXt/specs/appD.xml new file mode 100644 index 000000000..00acbe79e --- /dev/null +++ b/libXt/specs/appD.xml @@ -0,0 +1,880 @@ + +Intrinsics Error Messages + + +All Intrinsics errors and warnings have class +``XtToolkitError''. +The following two tables summarize the common errors and warnings that can be +generated by the Intrinsics. +Additional implementation-dependent messages are permitted. +Error Messages + + + + + + + + + + + Name + Type + Default Message + + + + + allocError + calloc + Cannot perform calloc + + + allocError + malloc + Cannot perform malloc + + + allocError + realloc + Cannot perform realloc + + + internalError + xtMakeGeometryRequest + internal error; ShellClassExtension is NULL + + + invalidArgCount + xtGetValues + Argument count > 0 on NULL argument list in XtGetValues + + + invalidArgCount + xtSetValues + Argument count > 0 on NULL argument list in XtSetValues + + + invalidClass + applicationShellInsertChild + ApplicationShell does not accept RectObj children; ignored + + + invalidClass + constraintSetValue + Subclass of Constraint required in CallConstraintSetValues + + + invalidClass + xtAppCreateShell + XtAppCreateShell requires non-NULL widget class + + + invalidClass + xtCreatePopupShell + XtCreatePopupShell requires non-NULL widget class + + + invalidClass + xtCreateWidget + XtCreateWidget requires non-NULL widget class + + + invalidClass + xtPopdown + XtPopdown requires a subclass of shellWidgetClass + + + invalidClass + xtPopup + XtPopup requires a subclass of shellWidgetClass + + + invalidDimension + xtCreateWindow + Widget %s has zero width and/or height + + + invalidDimension + shellRealize + Shell widget %s has zero width and/or height + + + invalidDisplay + xtInitialize + Can't open display: %s + + + invalidGetValues + xtGetValues + NULL ArgVal in XtGetValues + + + invalidExtension + shellClassPartInitialize + widget class %s has invalid ShellClassExtension record + + + invalidExtension + xtMakeGeometryRequest + widget class %s has invalid ShellClassExtension record + + + invalidGeometryManager + xtMakeGeometryRequest + XtMakeGeometryRequest - parent has no geometry manager + + + invalidParameter + xtAddInput + invalid condition passed to XtAddInput + + + invalidParameter + xtAddInput + invalid condition passed to XtAppAddInput + + + invalidParent + xtChangeManagedSet + Attempt to manage a child when parent is not Composite + + + invalidParent + xtChangeManagedSet + Attempt to unmanage a child when parent is not Composite + + + invalidParent + xtCreatePopupShell + XtCreatePopupShell requires non-NULL parent + + + invalidParent + xtCreateWidget + XtCreateWidget requires non-NULL parent + + + invalidParent + xtMakeGeometryRequest + non-shell has no parent in XtMakeGeometryRequest + + + invalidParent + xtMakeGeometryRequest + XtMakeGeometryRequest - parent not composite + + + invalidParent + xtManageChildren + Attempt to manage a child when parent is not Composite + + + invalidParent + xtUnmanageChildren + Attempt to unmanage a child when parent is not Composite + + + invalidProcedure + inheritanceProc + Unresolved inheritance operation + + + invalidProcedure + realizeProc + No realize class procedure defined + + + invalidWindow + eventHandler + Event with wrong window + + + missingWidget + fetchDisplayArg + FetchDisplayArg called without a widget to reference + + + nonWidget + xtCreateWidget + attempt to add non-widget child "%s" to parent "%s" which supports only widgets + + + noPerDisplay + closeDisplay + Couldn't find per display information + + + noPerDisplay + getPerDisplay + Couldn't find per display information + + + noSelectionProperties + freeSelectionProperty + internal error: no selection property context for display + + + noWidgetAncestor + windowedAncestor + Object "%s" does not have windowed ancestor + + + nullDisplay + xtRegisterExtensionSelector + XtRegisterExtensionSelector requires a non-NULL display + + + nullProc + insertChild + "%s" parent has NULL insert_child method + + + r2versionMismatch + widget + Widget class %s must be re-compiled. + + + R3versionMismatch + widget + Widget class %s must be re-compiled. + + + R4orR5versionMismatch + widget + Widget class %s must be re-compiled. + + + rangeError + xtRegisterExtensionSelector + Attempt to register multiple selectors for one extension event type + + + sessionManagement + SmcOpenConnection + Tried to connect to session manager, %s + + + subclassMismatch + xtCheckSubclass + Widget class %s found when subclass of %s expected: %s + + + + + +Warning Messages + + + + + + + + + + Name + Type + Default Message + + + + + ambiguousParent + xtChangeManagedSet + Not all children have same parent + + + ambiguousParent + xtManageChildren + Not all children have same parent in XtManageChildren + + + ambiguousParent + xtUnmanageChildren + Not all children have same parent in XtUnmanageChildren + + + badFormat + xtGetSelectionValue + Selection owner returned type INCR property with format != 32 + + + badGeometry + shellRealize + Shell widget "%s" has an invalid geometry specification: "%s" + + + badValue + cvtStringToPixel + Color name "%s" is not defined + + + communicationError + select + Select failed; error code %s + + + conversionError + string + Cannot convert string "%s" to type %s + + + conversionError + stringToVisual + Cannot find Visual of class %s for display %s + + + conversionFailed + xtConvertVarToArgList + Type conversion failed + + + conversionFailed + xtGetTypedArg + Type conversion (%s to %s) failed for widget '%s' + + + displayError + invalidDisplay + Can't find display structure + + + grabError + xtAddGrab + XtAddGrab requires exclusive grab if spring_loaded is TRUE + + + grabError + xtRemoveGrab + XtRemoveGrab asked to remove a widget not on the list + + + initializationError + xtInitialize + Initializing Resource Lists twice + + + insufficientSpace + xtGetTypedArg + Insufficient space for converted type '%s' in widget '%s' + + + internalError + shell + Shell's window manager interaction is broken + + + invalidAddressMode + computeArgs + Conversion arguments for widget '%s' contain an unsupported address mode + + + invalidArgCount + getResources + argument count > 0 on NULL argument list + + + invalidCallbackList + xtAddCallback + Cannot find callback list in XtAddCallback + + + invalidCallbackList + xtAddCallback + Cannot find callback list in XtAddCallbacks + + + invalidCallbackList + xtCallCallback + Cannot find callback list in XtCallCallbacks + + + invalidCallbackList + xtRemoveAllCallback + Cannot find callback list in XtRemoveAllCallbacks + + + invalidCallbackList + xtRemoveCallback + Cannot find callback list in XtRemoveCallbacks + + + invalidChild + xtChangeManagedSet + Null child passed to UnmanageChildren + + + invalidChild + xtManageChildren + null child passed to ManageChildren + + + invalidChild + xtManageChildren + null child passed to XtManageChildren + + + invalidChild + xtUnmanageChildren + Null child passed to XtUnmanageChildren + + + invalidChild + xtUnmanageChildren + Null child found in argument list to unmanage + + + invalidDepth + setValues + Can't change widget depth + + + invalidExtension + xtCreateWidget + widget "%s" class %s has invalid CompositeClassExtension record + + + invalidExtension + xtCreateWidget + widget class %s has invalid ConstraintClassExtension record + + + invalidGrab + ungrabKeyOrButton + Attempt to remove nonexistent passive grab + + + invalidGrabKind + xtPopup + grab kind argument has invalid value; XtGrabNone assumed + + + invalidParameters + freeTranslations + Freeing XtTranslations requires no extra arguments + + + invalidParameters + mergeTranslations + MergeTM to TranslationTable needs no extra arguments + + + invalidParameters + xtMenuPopdown + XtMenuPopdown called with num_params != 0 or 1 + + + invalidParameters + xtMenuPopupAction + MenuPopup wants exactly one argument + + + invalidParent + xtCopyFromParent + CopyFromParent must have non-NULL parent + + + invalidPopup + xtMenuPopup + Can't find popup widget "%s" in XtMenuPopup + + + invalidPopup + xtMenuPopdown + Can't find popup in widget "%s" in XtMenuPopdown + + + invalidPopup + unsupportedOperation + Pop-up menu creation is only supported on ButtonPress, KeyPress or EnterNotify events. + + + invalidPopup + unsupportedOperation + Pop-up menu creation is only supported on Button, Key or EnterNotify events. + + + invalidProcedure + deleteChild + null delete_child procedure for class %s in XtDestroy + + + invalidProcedure + inputHandler + XtRemoveInput: Input handler not found + + + invalidProcedure + set_values_almost + set_values_almost procedure shouldn't be NULL + + + invalidResourceCount + getResources + resource count > 0 on NULL resource list + + + invalidResourceName + computeArgs + Cannot find resource name %s as argument to conversion + + + invalidShell + xtTranslateCoords + Widget has no shell ancestor + + + invalidSizeOverride + xtDependencies + Representation size %d must match superclass's to override %s + + + missingCharsetList + cvtStringToFontSet + Missing charsets in String to FontSet conversion + + + noActionProc + xtCallActionProc + No action proc named "%s" is registered for widget "%s" + + + noColormap + cvtStringToPixel + Cannot allocate colormap entry for "%s" + + + noFont + cvtStringToFont + Unable to load any usable ISO8859-1 font + + + noFont + cvtStringToFontSet + Unable to load any usable fontset + + + noFont + cvtStringToFontStruct + Unable to load any usable ISO8859-1 font + + + notInConvertSelection + xtGetSelectionRequest + XtGetSelectionRequest or XtGetSelectionParameters called for widget "%s" outside of ConvertSelection proc + + + notRectObj + xtChangeManagedSet + child "%s", class %s is not a RectObj + + + notRectObj + xtManageChildren + child "%s", class %s is not a RectObj + + + nullWidget + xtConvertVarToArgList + XtVaTypedArg conversion needs non-NULL widget handle + + + r3versionMismatch + widget + Shell Widget class %s binary compiled for R3 + + + translationError + nullTable + Can't remove accelerators from NULL table + + + translationError + nullTable + Tried to remove nonexistent accelerators + + + translationError + ambiguousActions + Overriding earlier translation manager actions. + + + translationError + newActions + New actions are:%s + + + translationError + nullTable + table to (un)merge must not be null + + + translationError + nullTable + Can't translate event through NULL table + + + translationError + oldActions + Previous entry was: %s %s + + + translationError + unboundActions + Actions not found: %s + + + translationError + xtTranslateInitialize + Initializing Translation manager twice. + + + translationParseError + missingComma + ... possibly due to missing ',' in event sequence. + + + translationParseError + nonLatin1 + ... probably due to non-Latin1 character in quoted string + + + translationParseError + parseError + translation table syntax error: %s + + + translationParseError + parseString + Missing '"'. + + + translationParseError + showLine + ... found while parsing '%s' + + + typeConversionError + noConverter + No type converter registered for '%s' to '%s' conversion. + + + unknownType + xtConvertVarToArgList + Unable to find type of resource for conversion + + + unknownType + xtGetTypedArg + Unable to find type of resource for conversion + + + versionMismatch + widget + Widget class %s version mismatch (recompilation needed):\\n widget %d vs. intrinsics %d. + + + wrongParameters + cvtIntOrPixelToXColor + Pixel to color conversion needs screen and colormap arguments + + + wrongParameters + cvtIntToBool + Integer to Bool conversion needs no extra arguments + + + wrongParameters + cvtIntToBoolean + Integer to Boolean conversion needs no extra arguments + + + wrongParameters + cvtIntToFloat + Integer to Float conversion needs no extra arguments + + + wrongParameters + cvtIntToFont + Integer to Font conversion needs no extra arguments + + + wrongParameters + cvtIntToPixel + Integer to Pixel conversion needs no extra arguments + + + wrongParameters + cvtIntToPixmap + Integer to Pixmap conversion needs no extra arguments + + + wrongParameters + cvtIntToShort + Integer to Short conversion needs no extra arguments + + + wrongParameters + cvtIntToUnsignedChar + Integer to UnsignedChar conversion needs no extra arguments + + + wrongParameters + cvtStringToAcceleratorTable + String to AcceleratorTable conversion needs no extra arguments + + + wrongParameters + cvtStringToAtom + String to Atom conversion needs Display argument + + + wrongParameters + cvtStringToBool + String to Bool conversion needs no extra arguments + + + wrongParameters + cvtStringToBoolean + String to Boolean conversion needs no extra arguments + + + wrongParameters + cvtStringToCommandArgArray + String to CommandArgArray conversion needs no extra arguments + + + wrongParameters + cvtStringToCursor + String to cursor conversion needs display argument + + + wrongParameters + cvtStringToDimension + String to Dimension conversion needs no extra arguments + + + wrongParameters + cvtStringToDirectoryString + String to DirectoryString conversion needs no extra arguments + + + wrongParameters + cvtStringToDisplay + String to Display conversion needs no extra arguments + + + wrongParameters + cvtStringToFile + String to File conversion needs no extra arguments + + + wrongParameters + cvtStringToFloat + String to Float conversion needs no extra arguments + + + wrongParameters + cvtStringToFont + String to font conversion needs display argument + + + wrongParameters + cvtStringToFontSet + String to FontSet conversion needs display and locale arguments + + + wrongParameters + cvtStringToFontStruct + String to font conversion needs display argument + + + wrongParameters + cvtStringToGravity + String to Gravity conversion needs no extra arguments + + + wrongParameters + cvtStringToInitialState + String to InitialState conversion needs no extra arguments + + + wrongParameters + cvtStringToInt + String to Integer conversion needs no extra arguments + + + wrongParameters + cvtStringToPixel + String to pixel conversion needs screen and colormap arguments + + + wrongParameters + cvtStringToRestartStyle + String to RestartStyle conversion needs no extra arguments + + + wrongParameters + cvtStringToShort + String to Integer conversion needs no extra arguments + + + wrongParameters + cvtStringToTranslationTable + String to TranslationTable conversion needs no extra arguments + + + wrongParameters + cvtStringToUnsignedChar + String to Integer conversion needs no extra arguments + + + wrongParameters + cvtStringToVisual + String to Visual conversion needs screen and depth arguments + + + wrongParameters + cvtXColorToPixel + Color to Pixel conversion needs no extra arguments + + + wrongParameters + freeCursor + Free Cursor requires display argument + + + wrongParameters + freeDirectoryString + Free Directory String requires no extra arguments + + + wrongParameters + freeFile + Free File requires no extra arguments + + + wrongParameters + freeFont + Free Font needs display argument + + + wrongParameters + freeFontSet + FreeFontSet needs display and locale arguments + + + wrongParameters + freeFontStruct + Free FontStruct requires display argument + + + wrongParameters + freePixel + Freeing a pixel requires screen and colormap arguments + + + + + diff --git a/libXt/specs/appE b/libXt/specs/appE deleted file mode 100644 index 1ce7270bf..000000000 --- a/libXt/specs/appE +++ /dev/null @@ -1,606 +0,0 @@ -.\" $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/libXt/specs/appE.xml b/libXt/specs/appE.xml new file mode 100644 index 000000000..574cf1534 --- /dev/null +++ b/libXt/specs/appE.xml @@ -0,0 +1,1703 @@ + +Defined Strings + + +The StringDefs.h +header file contains definitions for the following resource name, +class, and representation type symbolic constants. + + +Resource names: + + + + + + + + Symbol + Definition + + + + + XtNaccelerators + "accelerators" + + + XtNallowHoriz + "allowHoriz" + + + XtNallowVert + "allowVert" + + + XtNancestorSensitive + "ancestorSensitive" + + + XtNbackground + "background" + + + XtNbackgroundPixmap + "backgroundPixmap" + + + XtNbitmap + "bitmap" + + + XtNborder + "borderColor" + + + XtNborderColor + "borderColor" + + + XtNborderPixmap + "borderPixmap" + + + XtNborderWidth + "borderWidth" + + + XtNcallback + "callback" + + + XtNchangeHook + "changeHook" + + + XtNchildren + "children" + + + XtNcolormap + "colormap" + + + XtNconfigureHook + "configureHook" + + + XtNcreateHook + "createHook" + + + XtNdepth + "depth" + + + XtNdestroyCallback + "destroyCallback" + + + XtNdestroyHook + "destroyHook" + + + XtNeditType + "editType" + + + XtNfile + "file" + + + XtNfont + "font" + + + XtNfontSet + "fontSet" + + + XtNforceBars + "forceBars" + + + XtNforeground + "foreground" + + + XtNfunction + "function" + + + XtNgeometryHook + "geometryHook" + + + XtNheight + "height" + + + XtNhighlight + "highlight" + + + XtNhSpace + "hSpace" + + + XtNindex + "index" + + + XtNinitialResourcesPersistent + "initialResourcesPersistent" + + + XtNinnerHeight + "innerHeight" + + + XtNinnerWidth + "innerWidth" + + + 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" + + + + + +Resource classes: + + + + + + + + Symbol + Definition + + + + + XtCAccelerators + "Accelerators" + + + XtCBackground + "Background" + + + XtCBitmap + "Bitmap" + + + XtCBoolean + "Boolean" + + + XtCBorderColor + "BorderColor" + + + XtCBorderWidth + "BorderWidth" + + + XtCCallback + "Callback" + + + XtCColormap + "Colormap" + + + XtCColor + "Color" + + + XtCCursor + "Cursor" + + + XtCDepth + "Depth" + + + XtCEditType + "EditType" + + + XtCEventBindings + "EventBindings" + + + XtCFile + "File" + + + XtCFont + "Font" + + + XtCFontSet + "FontSet" + + + XtCForeground + "Foreground" + + + XtCFraction + "Fraction" + + + XtCFunction + "Function" + + + XtCHeight + "Height" + + + XtCHSpace + "HSpace" + + + XtCIndex + "Index" + + + XtCInitialResourcesPersistent + "InitialResourcesPersistent" + + + XtCInsertPosition + "InsertPosition" + + + XtCInterval + "Interval" + + + XtCJustify + "Justify" + + + XtCKnobIndent + "KnobIndent" + + + XtCKnobPixel + "KnobPixel" + + + XtCLabel + "Label" + + + XtCLength + "Length" + + + XtCMappedWhenManaged + "MappedWhenManaged" + + + XtCMargin + "Margin" + + + XtCMenuEntry + "MenuEntry" + + + XtCNotify + "Notify" + + + XtCOrientation + "Orientation" + + + XtCParameter + "Parameter" + + + XtCPixmap + "Pixmap" + + + XtCPosition + "Position" + + + XtCReadOnly + "ReadOnly" + + + XtCResize + "Resize" + + + XtCReverseVideo + "ReverseVideo" + + + XtCScreen + "Screen" + + + XtCScrollProc + "ScrollProc" + + + XtCScrollDCursor + "ScrollDCursor" + + + XtCScrollHCursor + "ScrollHCursor" + + + XtCScrollLCursor + "ScrollLCursor" + + + XtCScrollRCursor + "ScrollRCursor" + + + XtCScrollUCursor + "ScrollUCursor" + + + XtCScrollVCursor + "ScrollVCursor" + + + XtCSelection + "Selection" + + + XtCSelectionArray + "SelectionArray" + + + XtCSensitive + "Sensitive" + + + XtCSession + "Session" + + + XtCSpace + "Space" + + + XtCString + "String" + + + XtCTextOptions + "TextOptions" + + + XtCTextPosition + "TextPosition" + + + XtCTextSink + "TextSink" + + + XtCTextSource + "TextSource" + + + XtCThickness + "Thickness" + + + XtCThumb + "Thumb" + + + XtCTranslations + "Translations" + + + XtCValue + "Value" + + + XtCVSpace + "VSpace" + + + XtCWidth + "Width" + + + XtCWindow + "Window" + + + XtCX + "X" + + + XtCY + "Y" + + + + + +Resource representation types: + + + + + + + + + Symbol + Definition + + + + + XtRAcceleratorTable + "AcceleratorTable" + + + XtRAtom + "Atom" + + + XtRBitmap + "Bitmap" + + + XtRBool + "Bool" + + + XtRBoolean + "Boolean" + + + XtRCallback + "Callback" + + + XtRCallProc + "CallProc" + + + XtRCardinal + "Cardinal" + + + XtRColor + "Color" + + + XtRColormap + "Colormap" + + + XtRCommandArgArray + "CommandArgArray" + + + XtRCursor + "Cursor" + + + XtRDimension + "Dimension" + + + XtRDirectoryString + "DirectoryString" + + + XtRDisplay + "Display" + + + XtREditMode + "EditMode" + + + XtREnum + "Enum" + + + XtREnvironmentArray + "EnvironmentArray" + + + XtRFile + "File" + + + XtRFloat + "Float" + + + XtRFont + "Font" + + + XtRFontSet + "FontSet" + + + XtRFontStruct + "FontStruct" + + + XtRFunction + "Function" + + + XtRGeometry + "Geometry" + + + XtRGravity + "Gravity" + + + XtRImmediate + "Immediate" + + + XtRInitialState + "InitialState" + + + XtRInt + "Int" + + + XtRJustify + "Justify" + + + XtRLongBoolean + XtRBool + + + XtRObject + "Object" + + + XtROrientation + "Orientation" + + + XtRPixel + "Pixel" + + + XtRPixmap + "Pixmap" + + + XtRPointer + "Pointer" + + + XtRPosition + "Position" + + + XtRRestartStyle + "RestartStyle" + + + XtRScreen + "Screen" + + + XtRShort + "Short" + + + XtRSmcConn + "SmcConn" + + + XtRString + "String" + + + XtRStringArray + "StringArray" + + + XtRStringTable + "StringTable" + + + XtRUnsignedChar + "UnsignedChar" + + + XtRTranslationTable + "TranslationTable" + + + XtRVisual + "Visual" + + + XtRWidget + "Widget" + + + XtRWidgetClass + "WidgetClass" + + + XtRWidgetList + "WidgetList" + + + XtRWindow + "Window" + + + + + +Boolean enumeration constants: + + + + + + + + Symbol + Definition + + + + + XtEoff + "off" + + + XtEfalse + "false" + + + XtEno + "no" + + + XtEon + "on" + + + XtEtrue + "true" + + + XtEyes + "yes" + + + + + +Orientation enumeration constants: + + + + + + + + Symbol + Definition + + + + + XtEvertical + "vertical" + + + XtEhorizontal + "horizontal" + + + + + +Text edit enumeration constants: + + + + + + + + + Symbol + Definition + + + + + XtEtextRead + "read" + + + XtEtextAppend + "append" + + + XtEtextEdit + "edit" + + + + + +Color enumeration constants: + + + + + + + + Symbol + Definition + + + + + XtExtdefaultbackground + "xtdefaultbackground" + + + XtExtdefaultforeground + "xtdefaultforeground" + + + + + +Font constant: + + + + + + + + Symbol + Definition + + + + + XtExtdefaultfont + "xtdefaultfont" + + + + + +Hooks for External Agents constants: + + + + + + + + Symbol + Definition + + + + + XtHcreate + "Xtcreate" + + + XtHsetValues + "Xtsetvalues" + + + XtHmanageChildren + "XtmanageChildren" + + + XtHunmanageChildren + "XtunmanageChildren" + + + XtHmanageSet + "XtmanageSet" + + + XtHunmanageSet + "XtunmanageSet" + + + XtHrealizeWidget + "XtrealizeWidget" + + + XtHunrealizeWidget + "XtunrealizeWidget" + + + XtHaddCallback + "XtaddCallback" + + + XtHaddCallbacks + "XtaddCallbacks" + + + XtHremoveCallback + "XtremoveCallback" + + + XtHremoveCallbacks + "XtremoveCallbacks" + + + XtHremoveAllCallbacks + "XtremoveAllCallbacks" + + + XtHaugmentTranslations + "XtaugmentTranslations" + + + XtHoverrideTranslations + "XtoverrideTranslations" + + + XtHuninstallTranslations + "XtuninstallTranslations" + + + XtHsetKeyboardFocus + "XtsetKeyboardFocus" + + + XtHsetWMColormapWindows + "XtsetWMColormapWindows" + + + XtHmapWidget + "XtmapWidget" + + + XtHunmapWidget + "XtunmapWidget" + + + XtHpopup + "Xtpopup" + + + XtHpopupSpringLoaded + "XtpopupSpringLoaded" + + + XtHpopdown + "Xtpopdown" + + + XtHconfigure + "Xtconfigure" + + + XtHpreGeometry + "XtpreGeometry" + + + XtHpostGeometry + "XtpostGeometry" + + + XtHdestroy + "Xtdestroy" + + + + + + +The +Shell.h +header file contains definitions for the following resource name, +class, and representation type symbolic constants. + + +Resource names: + + + + + + + + Symbol + Definition + + + + + XtNallowShellResize + "allowShellResize" + + + XtNargc + "argc" + + + XtNargv + "argv" + + + XtNbaseHeight + "baseHeight" + + + XtNbaseWidth + "baseWidth" + + + XtNcancelCallback + "cancelCallback" + + + XtNclientLeader + "clientLeader" + + + XtNcloneCommand + "cloneCommand" + + + XtNconnection + "connection" + + + XtNcreatePopupChildProc + "createPopupChildProc" + + + XtNcurrentDirectory + "currentDirectory" + + + XtNdieCallback + "dieCallback" + + + XtNdiscardCommand + "discardCommand" + + + XtNenvironment + "environment" + + + XtNerrorCallback + "errorCallback" + + + XtNgeometry + "geometry" + + + XtNheightInc + "heightInc" + + + XtNiconMask + "iconMask" + + + XtNiconName + "iconName" + + + XtNiconNameEncoding + "iconNameEncoding" + + + XtNiconPixmap + "iconPixmap" + + + XtNiconWindow + "iconWindow" + + + XtNiconX + "iconX" + + + XtNiconY + "iconY" + + + XtNiconic + "iconic" + + + XtNinitialState + "initialState" + + + XtNinput + "input" + + + XtNinteractCallback + "interactCallback" + + + XtNjoinSession + "joinSession" + + + XtNmaxAspectX + "maxAspectX" + + + XtNmaxAspectY + "maxAspectY" + + + XtNmaxHeight + "maxHeight" + + + XtNmaxWidth + "maxWidth" + + + XtNminAspectX + "minAspectX" + + + XtNminAspectY + "minAspectY" + + + XtNminHeight + "minHeight" + + + XtNminWidth + "minWidth" + + + XtNoverrideRedirect + "overrideRedirect" + + + XtNprogramPath + "programPath" + + + XtNresignCommand + "resignCommand" + + + XtNrestartCommand + "restartCommand" + + + XtNrestartStyle + "restartStyle" + + + XtNsaveCallback + "saveCallback" + + + XtNsaveCompleteCallback + "saveCompleteCallback" + + + XtNsaveUnder + "saveUnder" + + + XtNsessionID + "sessionID" + + + XtNshutdownCommand + "shutdownCommand" + + + XtNtitle + "title" + + + XtNtitleEncoding + "titleEncoding" + + + XtNtransient + "transient" + + + XtNtransientFor + "transientFor" + + + XtNurgency + "urgency" + + + XtNvisual + "visual" + + + XtNwaitForWm + "waitforwm" + + + XtNwaitforwm + "waitforwm" + + + XtNwidthInc + "widthInc" + + + XtNwindowGroup + "windowGroup" + + + XtNwindowRole + "windowRole" + + + XtNwinGravity + "winGravity" + + + XtNwmTimeout + "wmTimeout" + + + + + +Resource classes: + + + + + + + + Symbol + Definition + + + + + XtCAllowShellResize + "allowShellResize" + + + XtCArgc + "Argc" + + + XtCArgv + "Argv" + + + XtCBaseHeight + "BaseHeight" + + + XtCBaseWidth + "BaseWidth" + + + XtCClientLeader + "ClientLeader" + + + XtCCloneCommand + "CloneCommand" + + + XtCConnection + "Connection" + + + XtCCreatePopupChildProc + "CreatePopupChildProc" + + + XtCCurrentDirectory + "CurrentDirectory" + + + XtCDiscardCommand + "DiscardCommand" + + + XtCEnvironment + "Environment" + + + XtCGeometry + "Geometry" + + + XtCHeightInc + "HeightInc" + + + XtCIconMask + "IconMask" + + + XtCIconName + "IconName" + + + XtCIconNameEncoding + "IconNameEncoding" + + + XtCIconPixmap + "IconPixmap" + + + XtCIconWindow + "IconWindow" + + + XtCIconX + "IconX" + + + XtCIconY + "IconY" + + + XtCIconic + "Iconic" + + + XtCInitialState + "InitialState" + + + XtCInput + "Input" + + + XtCJoinSession + "JoinSession" + + + XtCMaxAspectX + "MaxAspectX" + + + XtCMaxAspectY + "MaxAspectY" + + + XtCMaxHeight + "MaxHeight" + + + XtCMaxWidth + "MaxWidth" + + + XtCMinAspectX + "MinAspectX" + + + XtCMinAspectY + "MinAspectY" + + + XtCMinHeight + "MinHeight" + + + XtCMinWidth + "MinWidth" + + + XtCOverrideRedirect + "OverrideRedirect" + + + XtCProgramPath + "ProgramPath" + + + XtCResignCommand + "ResignCommand" + + + XtCRestartCommand + "RestartCommand" + + + XtCRestartStyle + "RestartStyle" + + + XtCSaveUnder + "SaveUnder" + + + XtCSessionID + "SessionID" + + + XtCShutdownCommand + "ShutdownCommand" + + + XtCTitle + "Title" + + + XtCTitleEncoding + "TitleEncoding" + + + XtCTransient + "Transient" + + + XtCTransientFor + "TransientFor" + + + XtCUrgency + "Urgency" + + + XtCVisual + "Visual" + + + XtCWaitForWm + "Waitforwm" + + + XtCWaitforwm + "Waitforwm" + + + XtCWidthInc + "WidthInc" + + + XtCWindowGroup + "WindowGroup" + + + XtCWindowRole + "WindowRole" + + + XtCWinGravity + "WinGravity" + + + XtCWmTimeout + "WmTimeout" + + + + + +Resource representation types: + + + + + + + + + Symbol + Definition + + + + + XtRAtom + "Atom" + + + + + diff --git a/libXt/specs/appF b/libXt/specs/appF deleted file mode 100644 index b74cf4a3e..000000000 --- a/libXt/specs/appF +++ /dev/null @@ -1,125 +0,0 @@ -.\" $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/libXt/specs/appF.xml b/libXt/specs/appF.xml new file mode 100644 index 000000000..49f054bb7 --- /dev/null +++ b/libXt/specs/appF.xml @@ -0,0 +1,103 @@ + +Resource Configuration Management + +Setting and changing resources in X applications can be difficult for +both the application programmer and the end user. Resource +Configuration Management (RCM) addresses this problem by changing +the X Intrinsics 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. + + + +The main difference between RCM and the Editres +protocol is that the RCM +customizing hooks reside in the Intrinsics and thus are linked with +other toolkits such as Motif and the Athena widgets. However, the +EditRes protocol requires the application to link with the +EditRes +routines in the Xmu library and Xmu is not used by all applications that +use Motif. Also, the EditRes protocol uses ClientMessage, +whereas the +RCM Intrinsics hooks use PropertyNotify events. + + + +X Properties and the PropertyNotify events are used +to implement RCM and +allow on-the-fly resource customization. When the X Toolkit is +initialized, two atoms are interned with the strings +Custom Init and +Custom Data. Both +_XtCreatePopupShell +and +_XtAppCreateShell +register a PropertyNotify event handler to handle these properties. + + + +A customization tool uses the Custom Init property to ping an +application to get the application's toplevel window. When the +application's property notify event handler is invoked, the handler +deletes the property. No data is transferred in this property. + + + +A customization tool uses the Custom Data 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 XA_STRING and +the format of the string is: + + + + +The length of the resource name (the number of bytes in +the resource name) + + + + +One space character + + + + +The resource name + + + + +One space character + + + + +The resource value + + + + +When setting the application's resource, the event handler calls +functions to walk the application's widget tree, determining which +widgets are affected by the resource string, and then applying the value +with +. +As the widget tree is recursively descended, at +each level in the widget tree a resource part is tested for a match. +When the entire resource string has been matched, the value is applied +to the widget or widgets. + + + +Before a value is set on a widget, it is first determined if the last +part of the resource is a valid resource for that widget. It must also +add the resource to the application's resource database and then query +it using specific resource strings that is builds from the widget +information. + + diff --git a/libXt/specs/intr.idxmac.t b/libXt/specs/intr.idxmac.t deleted file mode 100644 index 9a3572d2e..000000000 --- a/libXt/specs/intr.idxmac.t +++ /dev/null @@ -1,3 +0,0 @@ -.eh '\fBX Toolkit Intrinsics\fP''\fBX11 Release \*(Rn\fP' -.oh '\fBX Toolkit Intrinsics\fP''\fBX11 Release \*(Rn\fP' -.so index.pageno diff --git a/libXt/specs/intrinsics.xml b/libXt/specs/intrinsics.xml new file mode 100644 index 000000000..4c4169530 --- /dev/null +++ b/libXt/specs/intrinsics.xml @@ -0,0 +1,128 @@ + + %defs; +]> + + + + + X Toolkit Intrinsics - C Language Interface + X Window System + X Version 11, Release &fullrelvers; + First Revision - April, 1994 + + + JoelMcCormack + + Digital Equipment Corporation + Western Software Laboratory + + + + PaulAsente + + Digital Equipment Corporation + Western Software Laboratory + + + + RalphR. + Swick + + Digital Equipment Corporation + External Research Group + + + + version 6 edited by Donna Converse X Consortium, Inc. + + +XWindow System is a trademark of X Consortium, Inc. + + +Copyright © 1985, 1986, 1987, 1988, 1991, 1994 X Consortium + + + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated 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 © 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/libXt/specs/postproc b/libXt/specs/postproc deleted file mode 100644 index 588b1de2c..000000000 --- a/libXt/specs/postproc +++ /dev/null @@ -1,19 +0,0 @@ -.\" $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/libXt/specs/preface.xml b/libXt/specs/preface.xml new file mode 100644 index 000000000..c5ac3cde6 --- /dev/null +++ b/libXt/specs/preface.xml @@ -0,0 +1,51 @@ + +About This Manual + + +X Toolkit Intrinsics — C Language Interface is intended to be read by both application programmers +who will use one or more of the many widget sets built with the Intrinsics and by widget +programmers who will use the Intrinsics to build widgets for one of the widget sets. Not all the +information in this manual, however, applies to both audiences. That is, because the application +programmer is likely to use only a number of the Intrinsics functions in writing an application and +because the widget programmer is likely to use many more, if not all, of the Intrinsics functions +in building a widget, an attempt has been made to highlight those areas of information that are +deemed to be of special interest for the application programmer. (It is assumed the widget programmer +will have to be familiar with all the information.) Therefore, all entries in the table of +contents that are printed in bold indicate the information that +should be of special interest to an application programmer. + + +It is also assumed that, as application programmers become more familiar with the concepts discussed +in this manual, they will find it more convenient to implement portions of their applications +as special-purpose or custom widgets. It is possible, nonetheless, to use widgets without +knowing how to build them. + + +Conventions Used in this Manual +This document uses the following conventions: + + + +Global symbols are printed in this special 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 italics. + + + + +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. + + + + +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 +specifies or, in the case of multiple arguments, the word specify. The explanations for all +arguments that are returned to you start with the word returns or, in +the case of multiple arguments, the word return. + + + + diff --git a/libXt/specs/strings.mit b/libXt/specs/strings.mit deleted file mode 100644 index 87cc71081..000000000 --- a/libXt/specs/strings.mit +++ /dev/null @@ -1,16 +0,0 @@ -.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 -- cgit v1.2.3