summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--specs/CH012471
-rw-r--r--specs/CH023165
-rw-r--r--specs/CH031031
-rw-r--r--specs/CH041998
-rw-r--r--specs/CH05783
-rw-r--r--specs/CH061110
-rw-r--r--specs/CH073555
-rw-r--r--specs/CH08452
-rw-r--r--specs/CH093211
-rw-r--r--specs/CH101521
-rw-r--r--specs/CH113566
-rw-r--r--specs/CH121067
-rw-r--r--specs/CH13805
-rw-r--r--specs/Xtk.intr.front333
-rw-r--r--specs/appA107
-rw-r--r--specs/appB783
-rw-r--r--specs/appC1204
-rw-r--r--specs/appD602
-rw-r--r--specs/appE606
-rw-r--r--specs/appF125
-rw-r--r--specs/intr.idxmac.t3
-rw-r--r--specs/postproc19
-rw-r--r--specs/strings.mit16
23 files changed, 0 insertions, 28533 deletions
diff --git a/specs/CH01 b/specs/CH01
deleted file mode 100644
index 8445733..0000000
--- a/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 <X11/Label.h>
-
-/* New representation types used by the Label widget */
-#define XtRJustify "Justify"
-
-/* New fields for the Label widget record */
-typedef struct {
-/* Settable resources */
- Pixel foreground;
- XFontStruct *font;
- String label; /* text to display */
- XtJustify justify;
- Dimension internal_width; /* # pixels horizontal border */
- Dimension internal_height; /* # pixels vertical border */
-
-/* Data derived from resources */
- GC normal_GC;
- GC gray_GC;
- Pixmap gray_pixmap;
- Position label_x;
- Position label_y;
- Dimension label_width;
- Dimension label_height;
- Cardinal label_len;
- Boolean display_sensitive;
-} LabelPart;
-.De
-.sp
-.Ds
-.TA .5i 3i
-.ta .5i 3i
-/* Full instance record declaration */
-typedef struct _LabelRec {
- CorePart core;
- LabelPart label;
-} LabelRec;
-
-/* Types for Label class methods */
-typedef void (*LabelSetTextProc)();
- /* Widget w */
- /* String text */
-
-typedef String (*LabelGetTextProc)();
- /* Widget w */
-
-/* New fields for the Label widget class record */
-typedef struct {
- LabelSetTextProc set_text;
- LabelGetTextProc get_text;
- XtPointer extension;
-} LabelClassPart;
-
-/* Full class record declaration */
-typedef struct _LabelClassRec {
- CoreClassPart core_class;
- LabelClassPart label_class;
-} LabelClassRec;
-
-/* Class record variable */
-extern LabelClassRec labelClassRec;
-
-#define LabelInheritSetText((LabelSetTextProc)_XtInherit)
-#define LabelInheritGetText((LabelGetTextProc)_XtInherit)
-#endif LABELP_H
-.De
-.LP
-To accommodate operating systems with file name length restrictions,
-the name of the private .h file is the first nine characters of the
-widget class followed by a capital P.
-For example,
-the private .h file for the
-Constraint
-widget class is
-.PN ConstrainP.h .
-
-.NH 3
-Widget Subclassing in .c Files
-.XS
-\*(SN Widget Subclassing in .c Files
-.XE
-.LP
-The .c file for a widget contains the structure initializer
-for the class record variable,
-which contains the following parts:
-.IP \(bu 5
-Class information (for example, \fIsuperclass\fP, \fIclass_name\fP,
-\fIwidget_size\fP,
-\fIclass_initialize\fP, and \fIclass_inited\fP).
-.IP \(bu 5
-Data constants (for example, \fIresources\fP and \fInum_resources\fP,
-\fIactions\fP and \fInum_actions\fP, \fIvisible_interest\fP,
-\fIcompress_motion\fP,
-\fIcompress_exposure\fP, and \fIversion\fP).
-.IP \(bu 5
-Widget operations (for example, \fIinitialize\fP, \fIrealize\fP, \fIdestroy\fP,
-\fIresize\fP, \fIexpose\fP, \fIset_values\fP, \fIaccept_focus\fP,
-and any new operations specific to
-the widget).
-.LP
-.IN "superclass" "" "@DEF@"
-The \fIsuperclass\fP field points to the superclass
-global class
-record, declared in the superclass private .h file.
-For direct subclasses of the generic core widget,
-\fIsuperclass\fP should be initialized to the address of the
-.PN widgetClassRec
-structure.
-The superclass is used for class chaining operations and for
-inheriting or enveloping a superclass's operations
-(see Sections 1.6.7, 1.6.9, and 1.6.10).
-.LP
-.IN "class_name" "" "@DEF@"
-The \fIclass_name\fP field contains the text name for this class,
-which is used by
-the resource manager.
-For example, the Label widget has the string ``Label''.
-More than one widget class can share the same text class name.
-This string must be permanently allocated prior to or during the
-execution of the class initialization procedure and must not be
-subsequently deallocated.
-
-.LP
-.IN "widget_size" "" "@DEF@"
-The \fIwidget_size\fP field is the size of the corresponding widget
-instance structure
-(not the size of the class structure).
-.LP
-.IN "version" "" "@DEF@"
-The \fIversion\fP field indicates the toolkit
-implementation version number and is used for
-runtime consistency checking of the \*(tk and widgets in an application.
-Widget writers must set it to the
-implementation-defined symbolic value
-.PN XtVersion
-in the widget class structure initialization.
-Those widget writers who believe that their widget binaries are compatible
-with other implementations of the \*(xI can put the special value
-.PN XtVersionDontCheck
-in the \fIversion\fP field to disable version checking for those widgets.
-If a widget needs to compile alternative code for different
-revisions of the \*(xI interface definition, it may use the symbol
-.PN XtSpecificationRelease ,
-as described in Chapter 13.
-Use of
-.PN XtVersion
-allows the \*(xI implementation to recognize widget binaries
-that were compiled with older implementations.
-.LP
-The \fIextension\fP field is for future upward compatibility.
-If the widget programmer adds fields to class parts,
-all subclass structure layouts change,
-requiring complete recompilation.
-To allow clients to avoid recompilation,
-an extension field at the end of each class part can point to a record
-that contains any additional class information required.
-.LP
-All other fields are described in their respective sections.
-.LP
-The .c file also contains the declaration of the global class
-structure pointer variable used to create instances of the class.
-The following is an abbreviated version of the .c file
-for a Label widget.
-The resources table is described in Chapter 9.
-.LP
-.Ds
-.TA .5i 1.5i 3i
-.ta .5i 1.5i 3i
-
-/* Resources specific to Label */
-static XtResource resources[] = {
- {XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel),
- XtOffset(LabelWidget, label.foreground), XtRString,
- XtDefaultForeground},
- {XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct *),
- XtOffset(LabelWidget, label.font),XtRString,
- XtDefaultFont},
- {XtNlabel, XtCLabel, XtRString, sizeof(String),
- XtOffset(LabelWidget, label.label), XtRString, NULL},
- .
- .
- .
-}
-
-/* Forward declarations of procedures */
-static void ClassInitialize();
-static void Initialize();
-static void Realize();
-static void SetText();
-static void GetText();
- .
- .
- .
-.De
-.sp
-.Ds
-.TA .5i 2i 3i
-.ta .5i 2i 3i
-/* Class record constant */
-LabelClassRec labelClassRec = {
- {
- /* core_class fields */
- /* superclass */ (WidgetClass)&coreClassRec,
- /* class_name */ "Label",
- /* widget_size */ sizeof(LabelRec),
- /* class_initialize */ ClassInitialize,
- /* class_part_initialize */ NULL,
- /* class_inited */ False,
- /* initialize */ Initialize,
- /* initialize_hook */ NULL,
- /* realize */ Realize,
- /* actions */ NULL,
- /* num_actions */ 0,
- /* resources */ resources,
- /* num_resources */ XtNumber(resources),
- /* xrm_class */ NULLQUARK,
- /* compress_motion */ True,
- /* compress_exposure */ True,
- /* compress_enterleave */ True,
- /* visible_interest */ False,
- /* destroy */ NULL,
- /* resize */ Resize,
- /* expose */ Redisplay,
- /* set_values */ SetValues,
- /* set_values_hook */ NULL,
- /* set_values_almost */ XtInheritSetValuesAlmost,
- /* get_values_hook */ NULL,
- /* accept_focus */ NULL,
- /* version */ XtVersion,
- /* callback_offsets */ NULL,
- /* tm_table */ NULL,
- /* query_geometry */ XtInheritQueryGeometry,
- /* display_accelerator */ NULL,
- /* extension */ NULL
- },
- {
- /* Label_class fields */
- /* get_text */ GetText,
- /* set_text */ SetText,
- /* extension */ NULL
- }
-};
-
-/* Class record pointer */
-WidgetClass labelWidgetClass = (WidgetClass) &labelClassRec;
-
-/* New method access routines */
-void LabelSetText(w, text)
- Widget w;
- String text;
-{
- LabelWidgetClass lwc = (Label WidgetClass)XtClass(w);
- XtCheckSubclass(w, labelWidgetClass, NULL);
- *(lwc->label_class.set_text)(w, text)
-}
-/* Private procedures */
- .
- .
- .
-.De
-
-.NH 3
-Widget Class and Superclass Look Up
-.XS
-\*(SN Widget Class and Superclass Look Up
-.XE
-.LP
-To obtain the class of a widget, use
-.PN XtClass .
-.IN "XtClass" "" "@DEF@"
-.LP
-.sM
-.FD 0
-WidgetClass XtClass(\fIw\fP)
-.br
- Widget \fIw\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget. \*(oI
-.LP
-.eM
-The
-.PN XtClass
-function returns a pointer to the widget's class structure.
-.sp
-.LP
-To obtain the superclass of a widget, use
-.PN XtSuperclass .
-.IN "XtSuperclass" "" "@DEF@"
-.LP
-.sM
-.FD 0
-WidgetClass XtSuperclass(\fIw\fP)
-.br
- Widget \fIw\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget. \*(oI
-.LP
-.eM
-The
-.PN XtSuperclass
-function returns a pointer to the widget's superclass class structure.
-
-.NH 3
-Widget Subclass Verification
-.XS
-\*(SN Widget Subclass Verification
-.XE
-.LP
-To check the subclass to which a widget belongs, use
-.PN XtIsSubclass .
-.IN "XtIsSubclass" "" "@DEF@"
-.LP
-.sM
-.FD 0
-Boolean XtIsSubclass(\fIw\fP, \fIwidget_class\fP)
-.br
- Widget \fIw\fP;
-.br
- WidgetClass \fIwidget_class\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget or object instance whose class is to be checked. \*(oI
-.IP \fIwidget_class\fP 1i
-Specifies the widget class for which to test. \*(oC
-.LP
-.eM
-The
-.PN XtIsSubclass
-function returns
-.PN True
-if the class of the specified widget is equal to
-or is a subclass of the specified class.
-The widget's class can be any number of subclasses down the chain
-and need not be an immediate subclass of the specified class.
-Composite widgets that need to restrict the class of the items they
-contain can use
-.PN XtIsSubclass
-to find out if a widget belongs to the desired class of objects.
-.sp
-.LP
-To test if a given widget belongs to a subclass of an \*(xI-defined
-class, the \*(xI define macros or functions equivalent to
-.PN XtIsSubclass
-for each of the built-in classes. These procedures are
-.PN XtIsObject ,
-.PN XtIsRectObj ,
-.PN XtIsWidget ,
-.PN XtIsComposite ,
-.PN XtIsConstraint ,
-.PN XtIsShell ,
-.PN XtIsOverrideShell ,
-.PN XtIsWMShell ,
-.PN XtIsVendorShell ,
-.PN XtIsTransientShell ,
-.PN XtIsTopLevelShell ,
-.PN XtIsApplicationShell ,
-and
-.PN XtIsSessionShell .
-.IN "XtIsObject" "" "@DEF@"
-.IN "XtIsRectObj" "" "@DEF@"
-.IN "XtIsWidget" "" "@DEF@"
-.IN "XtIsComposite" "" "@DEF@"
-.IN "XtIsConstraint" "" "@DEF@"
-.IN "XtIsShell" "" "@DEF@"
-.IN "XtIsOverrideShell" "" "@DEF@"
-.IN "XtIsWMShell" "" "@DEF@"
-.IN "XtIsVendorShell" "" "@DEF@"
-.IN "XtIsTransientShell" "" "@DEF@"
-.IN "XtIsTopLevelShell" "" "@DEF@"
-.IN "XtIsApplicationShell" "" "@DEF@"
-.IN "XtIsSessionShell" "" "@DEF@"
-.LP
-All these macros and functions have the same argument description.
-.LP
-.sM
-.FD 0
-Boolean XtIs\fI<class>\fP (\fIw\fP)
-.br
- Widget \fIw\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget or object instance whose class is to be checked. \*(oI
-.LP
-.eM
-These procedures may be faster than calling
-.PN XtIsSubclass
-directly for the built-in classes.
-.sp
-.LP
-To check a widget's class
-and to generate a debugging error message, use
-.PN XtCheckSubclass ,
-defined in
-.Pn < X11/IntrinsicP.h >:
-.IN "XtCheckSubclass" "" "@DEF@"
-.LP
-.sM
-.FD 0
-void XtCheckSubclass(\fIw\fP, \fIwidget_class\fP, \fImessage\fP)
-.br
- Widget \fIw\fP;
-.br
- WidgetClass \fIwidget_class\fP;
-.br
- String \fImessage\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget or object whose class is to be checked. \*(oI
-.IP \fIwidget_class\fP 1i
-Specifies the widget class for which to test. \*(oC
-.ds Me used
-.IP \fImessage\fP 1i
-Specifies the message to be used.
-.LP
-.eM
-The
-.PN XtCheckSubclass
-macro determines if the class of the specified widget is equal to
-or is a subclass of the specified class.
-The widget's class can be any number of subclasses down the chain
-and need not be an immediate subclass of the specified class.
-If the specified widget's class is not a subclass,
-.PN XtCheckSubclass
-constructs an error message from the supplied message,
-the widget's actual class, and the expected class and calls
-.PN XtErrorMsg .
-.PN XtCheckSubclass
-should be used at the entry point of exported routines to ensure
-that the client has passed in a valid widget class for the exported operation.
-.LP
-.PN XtCheckSubclass
-is only executed when the module has been compiled with the compiler symbol
-DEBUG defined; otherwise, it is defined as the empty string
-and generates no code.
-
-.NH 3
-Superclass Chaining
-.XS
-\*(SN Superclass Chaining
-.XE
-.LP
-.IN "Chaining" "superclass"
-.IN "Chaining" "Subclass"
-.IN "Superclass Chaining" "" "@DEF@"
-.IN "Subclass Chaining" "" "@DEF@"
-.IN "Inheritance"
-While most fields in a widget class structure are self-contained,
-some fields are linked to their corresponding fields in their superclass
-structures.
-With a linked field,
-the \*(xI access the field's value only after accessing its corresponding
-superclass value (called downward superclass chaining) or
-before accessing its corresponding superclass value (called upward superclass
-chaining). The self-contained fields are
-.sp
-.ta 2i
-In all widget classes: \fIclass_name\fP
-.br
- \fIclass_initialize\fP
-.br
- \fIwidget_size\fP
-.br
- \fIrealize\fP
-.br
- \fIvisible_interest\fP
-.br
- \fIresize\fP
-.br
- \fIexpose\fP
-.br
- \fIaccept_focus\fP
-.br
- \fIcompress_motion\fP
-.br
- \fIcompress_exposure\fP
-.br
- \fIcompress_enterleave\fP
-.br
- \fIset_values_almost\fP
-.br
- \fItm_table\fP
-.br
- \fIversion\fP
-.br
- \fIallocate\fP
-.br
- \fIdeallocate\fP
-.sp
-In Composite widget classes: \fIgeometry_manager\fP
-.br
- \fIchange_managed\fP
-.br
- \fIinsert_child\fP
-.br
- \fIdelete_child\fP
-.br
- \fIaccepts_objects\fP
-.br
- \fIallows_change_managed_set\fP
-.sp
-In Constraint widget classes: \fIconstraint_size\fP
-.sp
-In Shell widget classes: \fIroot_geometry_manager\fP
-.sp
-.LP
-With downward superclass chaining,
-the invocation of an operation first accesses the field from the
-Object,
-RectObj,
-and
-Core
-class structures, then from the subclass structure, and so on down the class chain to
-that widget's class structure. These superclass-to-subclass fields are
-.sp
-.ta 1i
-.br
- \fIclass_part_initialize\fP
-.br
- \fIget_values_hook\fP
-.br
- \fIinitialize\fP
-.br
- \fIinitialize_hook\fP
-.br
- \fIset_values\fP
-.br
- \fIset_values_hook\fP
-.br
- \fIresources\fP
-.sp
-.LP
-In addition, for subclasses of
-Constraint,
-the following fields of the
-.PN ConstraintClassPart
-and
-.PN ConstraintClassExtensionRec
-structures are chained from the
-Constraint
-class down to the subclass:
-.ta 1i
-.br
- \fIresources\fP
-.br
- \fIinitialize\fP
-.br
- \fIset_values\fP
-.br
- \fIget_values_hook\fP
-.sp
-.LP
-With upward superclass chaining,
-the invocation of an operation first accesses the field from the widget
-class structure, then from the superclass structure,
-and so on up the class chain to the
-Core,
-RectObj,
-and
-Object
-class structures.
-The subclass-to-superclass fields are
-.sp
-.ta 1i
-.br
- \fIdestroy\fP
-.br
- \fIactions\fP
-.sp
-.LP
-For subclasses of
-Constraint,
-the following field of
-.PN ConstraintClassPart
-is chained from the subclass up to the
-Constraint class:
-.sp
-.ta 1i
-.br
- \fIdestroy\fP
-
-.NH 3
-Class Initialization: class_initialize and class_part_initialize Procedures
-.XS
-\*(SN Class Initialization: class_initialize and class_part_initialize Procedures
-.XE
-.LP
-.IN "Class Initialization"
-.IN "Initialization"
-Many class records can be initialized completely at compile or link time.
-In some cases, however,
-a class may need to register type converters or perform other sorts of
-once-only runtime initialization.
-.LP
-Because the C language does not have initialization procedures
-that are invoked automatically when a program starts up,
-a widget class can declare a class_initialize procedure
-that will be automatically called exactly once by the \*(xI.
-A class initialization procedure pointer is of type
-.PN XtProc :
-.IN "class_initialize procedure" "" "@DEF@"
-.IN "XtProc" "" "@DEF@"
-.LP
-.sM
-.FD 0
-typedef void (*XtProc)(void);
-.FN
-.LP
-.eM
-A widget class indicates that it has no class initialization procedure by
-specifying NULL in the \fIclass_initialize\fP field.
-.LP
-In addition to the class initialization that is done exactly once,
-some classes perform initialization for fields in their parts
-of the class record.
-These are performed not just for the particular class,
-but for subclasses as well, and are
-done in the class's class part initialization procedure,
-a pointer to which is stored in the \fIclass_part_initialize\fP field.
-The class_part_initialize procedure pointer is of type
-.PN XtWidgetClassProc .
-.IN "XtWidgetClassProc" "" "@DEF@"
-.LP
-.sM
-.FD 0
-typedef void (*XtWidgetClassProc)(WidgetClass);
-.br
- WidgetClass \fIwidget_class\fP;
-.FN
-.IP \fIwidget_class\fP 1i
-Points to the class structure for the class being initialized.
-.LP
-.eM
-During class initialization,
-the class part initialization procedures for the class and all its superclasses
-are called in superclass-to-subclass order on the class record.
-These procedures have the responsibility of doing any dynamic initializations
-necessary to their class's part of the record.
-The most common is the resolution of any inherited methods defined in the
-class.
-For example,
-if a widget class C has superclasses
-Core,
-Composite,
-A, and B, the class record for C first is passed to
-Core 's
-class_part_initialize procedure.
-This resolves any inherited Core methods and compiles the textual
-representations of the resource list and action table that are defined in the
-class record.
-Next, Composite's
-class_part_initialize procedure is called to initialize the
-composite part of C's class record.
-Finally, the class_part_initialize procedures for A, B, and C, in that order,
-are called.
-For further information,
-see Section 1.6.9.
-Classes that do not define any new class fields
-or that need no extra processing for them can specify NULL
-in the \fIclass_part_initialize\fP field.
-.LP
-All widget classes, whether they have a class initialization procedure or not,
-must start with their \fIclass_inited\fP field
-.PN False .
-.LP
-The first time a widget of a class is created,
-.PN XtCreateWidget
-ensures that the widget class and all superclasses are initialized, in
-superclass-to-subclass order, by checking each \fIclass_inited\fP field and,
-if it is
-.PN False ,
-by calling the class_initialize and the class_part_initialize procedures
-for the class and all its superclasses.
-The \*(xI then set the \fIclass_inited\fP field to a nonzero value.
-After the one-time initialization,
-a class structure is constant.
-.LP
-The following example provides the class initialization procedure for a Label class.
-.LP
-.Ds
-.TA .5i 2i
-.ta .5i 2i
-static void ClassInitialize()
-{
- XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify,
- NULL, 0, XtCacheNone, NULL);
-}
-.De
-
-.NH 3
-Initializing a Widget Class
-.XS
-\fB\*(SN Initializing a Widget Class\fP
-.XE
-.IN "Widget" "class initialization"
-.LP
-A class is initialized when the first widget of that class or any
-subclass is created.
-To initialize a widget class without creating any widgets, use
-.PN XtInitializeWidgetClass .
-.IN "XtInitializeWidgetClass" "" "@DEF@"
-.LP
-.sM
-.FD 0
-void XtInitializeWidgetClass(\fIobject_class\fP)
-.br
- WidgetClass \fIobject_class\fP;
-.br
-.FN
-.IP \fIobject_class\fP 1i
-Specifies the object class to initialize. May be
-.PN objectClass
-or any subclass thereof.
-.LP
-.eM
-If the specified widget class is already initialized,
-.PN XtInitializeWidgetClass
-returns immediately.
-.LP
-If the class initialization procedure registers type converters,
-these type converters are not available until the first object
-of the class or subclass is created or
-.PN XtInitializeWidgetClass
-is called
-(see Section 9.6).
-
-.NH 3
-Inheritance of Superclass Operations
-.XS
-\*(SN Inheritance of Superclass Operations
-.XE
-.LP
-A widget class is free to use any of its superclass's self-contained
-operations rather than implementing its own code.
-The most frequently inherited operations are
-.IP
-expose
-.IP
-realize
-.IP
-insert_child
-.IP
-delete_child
-.IP
-geometry_manager
-.IP
-set_values_almost
-.LP
-To inherit an operation \fIxyz\fP,
-specify the constant
-.PN XtInherit \fIXyz\fP
-in your class record.
-.LP
-Every class that declares a new procedure in its widget class part must
-provide for inheriting the procedure in its class_part_initialize
-procedure.
-The chained operations declared in Core
-and Constraint
-records are never inherited.
-Widget classes that do nothing beyond what their superclass does
-specify NULL for chained procedures
-in their class records.
-.LP
-Inheriting works by comparing the value of the field with a known, special
-value and by copying in the superclass's value for that field if a match
-occurs.
-This special value, called the inheritance constant,
-is usually the \*(xI internal value
-.PN _XtInherit
-cast to the appropriate type.
-.PN _XtInherit
-is a procedure that issues an error message if it is actually called.
-.LP
-For example,
-.PN CompositeP.h
-contains these definitions:
-.LP
-.Ds
-.TA .25i 1.5i 3i
-.ta .25i 1.5i 3i
-#define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit)
-#define XtInheritChangeManaged ((XtWidgetProc) _XtInherit)
-#define XtInheritInsertChild ((XtArgsProc) _XtInherit)
-#define XtInheritDeleteChild ((XtWidgetProc) _XtInherit)
-.De
-.LP
-Composite's class_part_initialize procedure begins as follows:
-.LP
-.Ds
-.TA .2i 1.5i 3i
-.ta .2i 1.5i 3i
-static void CompositeClassPartInitialize(widgetClass)
- WidgetClass widgetClass;
-{
- CompositeWidgetClass wc = (CompositeWidgetClass)widgetClass;
- CompositeWidgetClass super = (CompositeWidgetClass)wc->core_class.superclass;
-
- if (wc->composite_class.geometry_manager == XtInheritGeometryManager) {
- wc->composite_class.geometry_manager = super->composite_class.geometry_manager;
- }
-
- if (wc->composite_class.change_managed == XtInheritChangeManaged) {
- wc->composite_class.change_managed = super->composite_class.change_managed;
- }
- .
- .
- .
-.De
-.LP
-Nonprocedure fields may be inherited in the same manner as procedure
-fields. The class may declare any reserved value it wishes for
-the inheritance constant for its new fields. The following inheritance
-constants are defined:
-.LP
-For Object:
-.IP
-.PN XtInheritAllocate
-.IP
-.PN XtInheritDeallocate
-.LP
-For Core:
-.IP
-.PN XtInheritRealize
-.IP
-.PN XtInheritResize
-.IP
-.PN XtInheritExpose
-.IP
-.PN XtInheritSetValuesAlmost
-.IP
-.PN XtInheritAcceptFocus
-.IP
-.PN XtInheritQueryGeometry
-.IP
-.PN XtInheritTranslations
-.IP
-.PN XtInheritDisplayAccelerator
-.LP
-For Composite:
-.IP
-.PN XtInheritGeometryManager
-.IP
-.PN XtInheritChangeManaged
-.IP
-.PN XtInheritInsertChild
-.IP
-.PN XtInheritDeleteChild
-.LP
-For Shell:
-.IP
-.PN XtInheritRootGeometryManager
-
-.NH 3
-Invocation of Superclass Operations
-.XS
-\*(SN Invocation of Superclass Operations
-.XE
-.LP
-A widget sometimes needs to call a superclass operation
-that is not chained.
-For example,
-a widget's expose procedure might call its superclass's \fIexpose\fP
-and then perform a little more work on its own.
-For example, a Composite
-class with predefined managed children can implement insert_child
-by first calling its superclass's \fIinsert_child\fP
-.IN "insert_child procedure"
-and then calling
-.PN XtManageChild
-to add the child to the managed set.
-.LP
-.NT
-A class method should not use
-.PN XtSuperclass
-but should instead call the class method of its own specific superclass
-directly through the superclass record.
-That is, it should use its own class pointers only,
-not the widget's class pointers,
-as the widget's class may be a subclass of the
-class whose implementation is being referenced.
-.NE
-This technique is referred to as \fIenveloping\fP the superclass's operation.
-
-.NH 3
-Class Extension Records
-.XS
-\*(SN Class Extension Records
-.XE
-.IN "Widget" "class extension records"
-.LP
-It may be necessary at times to add new fields to already existing
-widget class structures. To permit this to be done without requiring
-recompilation of all subclasses, the last field in a class part structure
-should be an extension pointer. If no extension fields for a class
-have yet been defined, subclasses should initialize the value of the
-extension pointer to NULL.
-.LP
-If extension fields exist, as is the case with the
-Composite,
-Constraint,
-and
-Shell
-classes, subclasses can provide values for these fields by setting the
-\fIextension\fP pointer for the appropriate part in their class structure to
-point to a statically declared extension record containing the
-additional fields.
-Setting the \fIextension\fP field is never mandatory; code that uses fields
-in the extension record must always check the \fIextension\fP field and take
-some appropriate default action if it is NULL.
-.LP
-In order to permit multiple subclasses and libraries to chain extension
-records from a single \fIextension\fP field, extension records should be
-declared as a linked list, and each extension record definition should
-contain the following four fields at the beginning of the structure
-declaration:
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-struct {
- XtPointer next_extension;
- XrmQuark record_type;
- long version;
- Cardinal record_size;
-};
-.De
-.IP \fInext_extension\fP 1.25i
-Specifies the next record in the list, or NULL.
-.IP \fIrecord_type\fP 1.25i
-Specifies the particular structure declaration to which
-each extension record instance conforms.
-.IP \fIversion\fP 1.25i
-Specifies a version id symbolic constant supplied by
-the definer of the structure.
-.IP \fIrecord_size\fP 1.25i
-Specifies the total number of bytes allocated for the
-extension record.
-.LP
-.eM
-The \fIrecord_type\fP field identifies the contents of the extension record
-and is used by the definer of the record to locate its particular
-extension record in the list. The
-\fIrecord_type\fP field is normally assigned the
-result of
-.PN XrmStringToQuark
-for a registered string constant. The
-\*(xI reserve all record type strings beginning with the two
-characters ``XT'' for future standard uses. The value
-.PN \s-1NULLQUARK\s+1
-may also be used
-by the class part owner in extension records attached to its own class
-part extension field to identify the extension record unique to that
-particular class.
-.LP
-The \fIversion\fP field is an owner-defined constant that may be used to
-identify binary files that have been compiled with alternate
-definitions of the remainder of the extension record data structure. The private
-header file for a widget class should provide a symbolic constant for
-subclasses to use to initialize this field.
-The \fIrecord_size\fP field value includes the four common header fields and
-should normally be initialized with
-.PN sizeof ().
-.LP
-Any value stored in the class part extension fields of
-.PN CompositeClassPart ,
-.PN ConstraintClassPart ,
-or
-.PN ShellClassPart
-must point to an extension record conforming to this definition.
-.LP
-The \*(xI provide a utility function for widget writers to locate a
-particular class extension record in a linked list, given a widget class
-and the offset of the \fIextension\fP field in the class record.
-.LP
-To locate a class extension record, use
-.PN XtGetClassExtension .
-.IN "XtGetClassExtension" "" "@DEF@"
-.LP
-.sM
-.FD 0
-XtPointer XtGetClassExtension(\fIobject_class\fP, \fIbyte_offset\fP, \
-\fItype\fP, \fIversion\fP, \fIrecord_size\fP)
-.br
- WidgetClass \fIobject_class\fP;
-.br
- Cardinal \fIbyte_offset\fP;
-.br
- XrmQuark \fItype\fP;
-.br
- long \fIversion\fP;
-.br
- Cardinal \fIrecord_size\fP;
-.FN
-.IP \fIobject_class\fP 1i
-Specifies the object class containing the extension list to be searched.
-.IP \fIbyte_offset\fP 1i
-Specifies the offset in bytes from the base of the
-class record of the extension field to be searched.
-.IP \fItype\fP 1i
-Specifies the record_type of the class extension to be located.
-.IP \fIversion\fP 1i
-Specifies the minimum acceptable version of the class
-extension required for a match.
-.IP \fIrecord_size\fP 1i
-Specifies the minimum acceptable length of the class
-extension record required for a match, or 0.
-.LP
-.eM
-The list of extension records at the specified offset in the specified
-object class will be searched for a match on the specified type,
-a version greater than or equal to the specified version, and a record
-size greater than or equal the specified record_size if it is nonzero.
-.PN XtGetClassExtension
-returns a pointer to a matching extension record or NULL if no match
-is found. The returned extension record must not be modified or
-freed by the caller if the caller is not the extension owner.
-.bp
diff --git a/specs/CH02 b/specs/CH02
deleted file mode 100644
index 12fdfc7..0000000
--- a/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/specs/CH03 b/specs/CH03
deleted file mode 100644
index 0d6a069..0000000
--- a/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/specs/CH04 b/specs/CH04
deleted file mode 100644
index 56a170a..0000000
--- a/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<session id>\*U does not
-already appear in the \fIrestart_command\fP, it will be added by the
-initialize and set_values methods at the beginning of the command arguments;
-if the \*Q\fR-xtsessionID\fP\*U argument already appears with an incorrect
-\fRsession id\fP in the following argument, that argument
-will be replaced with the current \fRsession id\fP.
-.LP
-After this, the shell initialize and set_values procedures check the
-\fIclone_command\fP. If \fIclone_command\fP is NULL,
-\fIrestart_command\fP will be copied to \fIclone_command\fP,
-except the \*Q\fR-xtsessionID\fP\*U and following argument will not be copied.
-.LP
-Finally, the shell initialize and set_values procedures check the
-\fIprogram_path\fP. If \fIprogram_path\fP is NULL, the
-first element of \fIrestart_command\fP is copied to \fIprogram_path\fP.
-.LP
-The possible values of \fIrestart_style\fP are
-.PN SmRestartIfRunning ,
-.PN SmRestartAnyway ,
-.PN SmRestartImmediately ,
-and
-.PN SmRestartNever .
-A resource converter is registered for this resource;
-for the strings that it recognizes,
-see Section 9.6.1.
-.LP
-The resource type EnvironmentArray is a NULL-terminated array of
-pointers to strings;
-each string has the format "name=value".
-The `=' character may not appear in the name,
-and the string is terminated by a null character.
-
-.NH 2
-Session Participation
-.XS
-\fB\*(SN Session Participation\fP
-.XE
-.LP
-Applications can participate in a user's session, exchanging messages
-with the session manager as described in the \fIX Session Management
-Protocol\fP and the \fIX Session Management Library\fP.
-.LP
-When a widget of
-.PN sessionShellWidgetClass
-or a subclass is created, the widget provides support for the application
-as a session participant and continues to provide support until the
-widget is destroyed.
-
-.NH 3
-Joining a Session
-.XS
-\fB\*(SN Joining a Session\fP
-.XE
-.LP
-When a Session shell is created,
-if \fIconnection\fP is NULL,
-and if \fIjoin_session\fP is
-.PN True ,
-and if \fIargv\fP or \fIrestart_command\fP is not NULL,
-and if in POSIX environments the
-.PN \s-1SESSION_MANAGER\s+1
-environment variable is defined,
-the shell will attempt to establish a new connection with the session manager.
-.LP
-To transfer management of an existing session connection from an
-application to the shell at widget creation time, pass the existing
-session connection ID as the \fIconnection\fP resource value
-when creating the Session shell,
-and if the other creation-time conditions on session participation are met,
-the widget will maintain the connection with the session manager.
-The application must ensure that only one
-Session shell manages the connection.
-.LP
-In the Session shell set_values procedure,
-if \fIjoin_session\fP changes from
-.PN False
-to
-.PN True
-and \fIconnection\fP is NULL and when in POSIX environments the
-.PN \s-1SESSION_MANAGER\s+1
-environment variable is defined,
-the shell will attempt to open a connection to the session manager.
-If \fIconnection\fP changes from NULL to non-NULL, the
-Session shell
-will take over management of that session connection and will set
-\fIjoin_session\fP to
-.PN True .
-If \fIjoin_session\fP changes from
-.PN False
-to
-.PN True
-and \fIconnection\fP is not NULL, the
-Session shell will take over management of the session connection.
-.LP
-When a successful connection has been established, \fIconnection\fP
-contains the session connection ID for the session participant.
-When the shell begins to manage the connection, it will call
-.PN XtAppAddInput
-to register the handler which watches for protocol messages
-from the session manager.
-When the attempt to connect fails, a warning message is issued
-and \fIconnection\fP is set to NULL.
-.LP
-While the connection is being managed, if a
-.PN SaveYourself ,
-.PN SaveYourselfPhase2 ,
-.PN Interact ,
-.PN ShutdownCancelled ,
-.PN SaveComplete ,
-or
-.PN Die
-message is received from the session manager, the Session shell will
-call out to application callback procedures registered
-on the respective callback list of the Session shell and will
-send
-.PN SaveYourselfPhase2Request ,
-.PN InteractRequest ,
-.PN InteractDone ,
-.PN SaveYourselfDone ,
-and
-.PN ConnectionClosed
-messages as appropriate.
-Initially, all of the client's session properties are undefined.
-When any of the session property resource values are defined or change,
-the Session shell initialize and set_values procedures
-will update the client's session property value by a
-.PN SetProperties
-or a
-.PN DeleteProperties
-message, as appropriate.
-The session ProcessID and UserID properties are always set by the shell
-when it is possible to determine the value of these properties.
-
-.NH 3
-Saving Application State
-.XS
-\fB\*(SN Saving Application State\fP
-.XE
-.LP
-The session manager instigates an application checkpoint by sending a
-.PN SaveYourself
-request.
-Applications are responsible for saving their state in response to the
-request.
-.LP
-When the
-.PN SaveYourself
-request arrives, the procedures registered on the
-Session shell's save callback list are called.
-If the application does not register any save callback procedures on
-the save callback list, the shell will report to the session manager
-that the application failed to save its state.
-Each procedure on the save callback list receives a token
-in the \fIcall_data\fP parameter.
-.sp
-.LP
-.KS
-The checkpoint token in the \fIcall_data\fP parameter is of type
-.PN XtCheckpointToken .
-.LP
-.IN "XtCheckpointToken" "" "@DEF@"
-.IN "XtCheckpointTokenRec" "" "@DEF@"
-.sM
-.Ds 0
-.TA .5i 2i 4i
-.ta .5i 2i 4i
-typedef struct {
- int save_type;
- int interact_style;
- Boolean shutdown;
- Boolean fast;
- Boolean cancel_shutdown
- int phase;
- int interact_dialog_type; /* return */
- Boolean request_cancel; /* return */
- Boolean request_next_phase; /* return */
- Boolean save_success; /* return */
-} XtCheckpointTokenRec, *XtCheckpointToken;
-.De
-.LP
-.eM
-.KE
-The \fIsave_type\fP, \fIinteract_style\fP, \fIshutdown\fP, and \fIfast\fP
-fields of the token contain the parameters of the
-.PN SaveYourself
-message.
-The possible values of \fIsave_type\fP are
-.PN SmSaveLocal ,
-.PN SmSaveGlobal ,
-and
-.PN SmSaveBoth ;
-these indicate the type of information to be saved.
-The possible values of \fIinteract_style\fP are
-.PN SmInteractStyleNone ,
-.PN SmInteractStyleErrors ,
-and
-.PN SmInteractStyleAny ;
-these indicate whether user interaction would be permitted
-and, if so, what kind of interaction.
-If \fIshutdown\fP is
-.PN True ,
-the checkpoint is being performed in preparation for the end of the session.
-If \fIfast\fP is
-.PN True ,
-the client should perform the checkpoint as quickly as possible.
-If \fIcancel_shutdown\fP is
-.PN True ,
-a
-.PN ShutdownCancelled
-message has been received for the current save operation. (See Section 4.4.4.)
-The \fIphase\fP is used by manager clients, such as a window manager,
-to distinguish between the first and second phase of a save operation.
-The \fIphase\fP will be either 1 or 2.
-The remaining fields in the checkpoint token structure are provided for
-the application to communicate with the shell.
-.LP
-Upon entry to the first application save callback procedure, the return
-fields in the token have the following initial values:
-\fIinteract_dialog_type\fP is
-.PN SmDialogNormal ;
-\fIrequest_cancel\fP is
-.PN False ;
-\fIrequest_next_phase\fP is
-.PN False ;
-and \fIsave_success\fP is
-.PN True .
-When a token is returned with any of the four return fields containing
-a noninitial value, and when the field is applicable, subsequent tokens
-passed to the application during the current save operation
-will always contain the noninitial value.
-.LP
-The purpose of the token's \fIsave_success\fP field is to
-indicate the outcome of the entire operation to the
-session manager and ultimately, to the user.
-Returning
-.PN False
-indicates some portion of the application state
-could not be successfully saved. If any token is returned
-to the shell with \fIsave_success\fP
-.PN False ,
-tokens subsequently received
-by the application for the current save operation will show
-\fIsave_success\fP as
-.PN False .
-When the shell sends the final status of the checkpoint to the
-session manager, it will indicate failure to save application state
-if any token was returned with \fIsave_success\fP
-.PN False .
-.LP
-Session participants that manage and save the state of other clients
-should structure their save or interact callbacks to
-set \fIrequest_next_phase\fP to
-.PN True
-when phase is 1, which will cause the shell to send the
-.PN SaveYourselfPhase2Request
-when the first phase is complete. When the
-.PN SaveYourselfPhase2
-message is received, the shell will invoke the save callbacks a
-second time with \fIphase\fP equal to 2.
-Manager clients should save the state of other clients
-when the callbacks are invoked the second time and \fIphase\fP equal to 2.
-.LP
-The application may request additional tokens while a checkpoint is under way,
-and these additional tokens must be returned by an explicit call.
-.sp
-.LP
-.KS
-To request an additional token for a save callback response that has a
-deferred outcome, use
-.PN XtSessionGetToken .
-.LP
-.IN "XtSessionGetToken" "" "@DEF@"
-.sM
-.FD 0
-XtCheckpointToken XtSessionGetToken(\fIwidget\fP)
-.br
- Widget \fIwidget\fP;
-.FN
-.IP \fIwidget\fP 1i
-Specifies the Session shell widget which manages session participation.
-.LP
-.eM
-The
-.PN XtSessionGetToken
-function will return NULL if no checkpoint operation is currently under way.
-.KE
-.sp
-.LP
-.KS
-To indicate the completion of checkpoint processing including user
-interaction, the application must signal the Session shell
-by returning all tokens.
-(See Sections 4.2.2.2 and 4.2.2.4).
-To return a token, use
-.PN XtSessionReturnToken .
-.LP
-.IN "XtSessionReturnToken" "" "@DEF@"
-.sM
-.FD 0
-void XtSessionReturnToken(\fItoken\fP)
-.br
- XtCheckpointToken \fItoken\fP;
-.FN
-.IP \fItoken\fP 1i
-Specifies a token that was received as the \fIcall_data\fP by a procedure
-on the interact callback list or a token that was received by a call to
-.PN XtSessionGetToken .
-.LP
-.eM
-.KE
-.LP
-Tokens passed as \fIcall_data\fP to save callbacks are implicitly
-returned when the save callback procedure returns.
-A save callback procedure should not call
-.PN XtSessionReturnToken
-on the token passed in its \fIcall_data\fP.
-
-.NH 4
-Requesting Interaction
-.XS
-\fB\*(SN Requesting Interaction\fP
-.XE
-.LP
-When the token \fIinteract_style\fP allows user interaction,
-the application may
-interact with the user during the checkpoint, but must wait for permission
-to interact.
-Applications request permission to interact with the user during the
-checkpointing operation by registering a procedure on the Session
-shell's interact callback list. When all save callback procedures have
-returned, and each time a token that was granted by a call to
-.PN XtSessionGetToken
-is returned, the Session shell examines the interact callback list.
-If interaction is permitted and the interact callback list is not empty,
-the shell will send an
-.PN InteractRequest
-to the session manager when an interact request is not already outstanding
-for the application.
-.LP
-The type of interaction dialog that will be requested is specified by
-the \fIinteract_dialog_type\fP field in the checkpoint token.
-The possible values for \fIinteract_dialog_type\fP are
-.PN SmDialogError
-and
-.PN SmDialogNormal .
-If a token is returned with \fIinteract_dialog_type\fP containing
-.PN SmDialogError ,
-the interact request and any subsequent interact requests will be for
-an error dialog; otherwise, the request will be for a normal dialog with
-the user.
-.LP
-When a token is returned with \fIsave_success\fP
-.PN False
-or \fIinteract_dialog_type\fP
-.PN SmDialogError ,
-tokens subsequently passed to callbacks during the same active
-.PN SaveYourself
-response will reflect these changed values, indicating that
-an error condition has occurred during the checkpoint.
-.LP
-The \fIrequest_cancel\fP field is a return value for interact callbacks only.
-Upon return from a procedure on the save callback list, the value
-of the token's \fIrequest_cancel\fP field is not examined by the shell.
-This is also true of tokens received through a call to
-.PN XtSessionGetToken .
-
-.NH 4
-Interacting with the User during a Checkpoint
-.XS
-\fB\*(SN Interacting with the User during a Checkpoint\fP
-.XE
-.LP
-When the session manager grants the application's request for user interaction,
-the Session shell receives an
-.PN Interact
-message.
-The procedures registered on the interact callback list are executed,
-but not as if executing a typical callback list.
-These procedures are individually executed in
-sequence, with a checkpoint token functioning as the sequencing mechanism.
-Each step in the sequence begins by removing a procedure
-from the interact callback list
-and executing it with a token passed in the \fIcall_data\fP.
-The interact callback will typically pop up a dialog box and return.
-When the user interaction and associated application checkpointing has
-completed, the application must return the token by calling
-.PN XtSessionReturnToken .
-Returning the token completes the current step and triggers the next step
-in the sequence.
-.LP
-During interaction the client may request cancellation of a shutdown.
-When a token passed as \fIcall_data\fP to an interact procedure is returned,
-if \fIshutdown\fP is
-.PN True
-and \fIcancel_shutdown\fP is
-.PN False ,
-\fIrequest_cancel\fP indicates whether the
-application requests that the pending shutdown be cancelled.
-If \fIrequest_cancel\fP is
-.PN True ,
-the field will also be
-.PN True
-in any tokens subsequently granted during the checkpoint operation.
-When a token is returned requesting cancellation of
-the session shutdown, pending interact procedures will still be
-called by the Session shell.
-When all interact procedures have been removed from the interact callback
-list, executed, and the final interact token returned to the shell, an
-.PN InteractDone
-message is sent to the session manager, indicating whether
-a pending session shutdown is requested to be cancelled.
-
-.NH 4
-Responding to a Shutdown Cancellation
-.XS
-\fB\*(SN Responding to a Shutdown Cancellation\fP
-.XE
-.LP
-Callbacks registered on the cancel callback list are invoked when the
-Session shell processes a
-.PN ShutdownCancelled
-message from the session manager. This may occur during the
-processing of save callbacks, while waiting for interact permission,
-during user interaction, or after the save operation is complete and
-the application is expecting a
-.PN SaveComplete
-or a
-.PN Die
-message.
-The \fIcall_data\fP for these callbacks is NULL.
-.LP
-When the shell notices that a pending shutdown has been cancelled,
-the token \fIcancel_shutdown\fP field will be
-.PN True
-in tokens subsequently given to the application.
-.LP
-Receiving notice of a shutdown cancellation does not cancel the
-pending execution of save callbacks or interact callbacks.
-After the cancel callbacks execute, if \fIinteract_style\fP is not
-.PN SmInteractStyleNone
-and the interact list is not empty,
-the procedures on the interact callback list will be executed
-and passed a token with \fIinteract_style\fP
-.PN SmInteractStyleNone .
-The application should not interact with the user, and the Session shell
-will not send an
-.PN InteractDone
-message.
-
-.NH 4
-Completing a Save
-.XS
-\fB\*(SN Completing a Save\fP
-.XE
-.LP
-When there is no user interaction, the shell regards the application
-as having finished saving state when all callback procedures
-on the save callback list have returned, and any additional tokens
-passed out by
-.PN XtSessionGetToken
-have been returned by corresponding calls to
-.PN XtSessionReturnToken .
-If the save operation involved user interaction,
-the above completion conditions apply, and in addition, all requests for
-interaction have been granted or cancelled,
-and all tokens passed to interact callbacks have been returned
-through calls to
-.PN XtSessionReturnToken .
-If the save operation involved a manager client that requested the
-second phase, the above conditions apply to both the first and second
-phase of the save operation.
-.br
-.LP
-When the application has finished saving state,
-the Session shell will report the result to the session manager by
-sending the
-.PN SaveYourselfDone
-message.
-If the session is continuing, the shell will receive the
-.PN SaveComplete
-message when all applications have completed saving state.
-This message indicates that applications may again allow changes
-to their state. The shell will execute the save_complete callbacks.
-The \fIcall_data\fP for these callbacks is NULL.
-
-.NH 3
-Responding to a Shutdown
-.XS
-\fB\*(SN Responding to a Shutdown\fP
-.XE
-.LP
-Callbacks registered on the die callback list are invoked when the
-session manager sends a
-.PN Die
-message.
-The callbacks on this list should do whatever is appropriate to quit
-the application.
-Before executing procedures on the die callback list,
-the Session shell will close the connection to the session manager
-and will remove the handler that watches for protocol messages.
-The \fIcall_data\fP for these callbacks is NULL.
-
-.NH 3
-Resigning from a Session
-.XS
-\fB\*(SN Resigning from a Session\fP
-.XE
-.LP
-When the Session shell widget is destroyed, the destroy method will
-close the connection to the session manager by sending a
-.PN ConnectionClosed
-protocol message and will remove the input callback
-that was watching for session protocol messages.
-.LP
-When
-.PN XtSetValues
-is used to set \fIjoin_session\fP to
-.PN False ,
-the set_values method of the Session shell will close the
-connection to the session manager if one exists by sending a
-.PN ConnectionClosed
-message, and \fIconnection\fP will be set to NULL.
-.LP
-Applications that exit in response to user actions and that do not
-wait for phase 2 destroy to complete on
-the Session shell should set \fIjoin_session\fP to
-.PN False
-before exiting.
-.LP
-When
-.PN XtSetValues
-is used to set \fIconnection\fP to NULL,
-the Session shell will stop managing the connection, if one exists.
-However, that session connection will not be closed.
-.LP
-Applications that wish to ensure continuation of a session connection
-beyond the destruction of the shell should first retrieve the
-\fIconnection\fP resource value,
-then set the \fIconnection\fP resource to NULL,
-and then they may safely destroy the widget without losing control
-of the session connection.
-.LP
-The error callback list will be called if an unrecoverable
-communications error occurs while the shell is managing the connection.
-The shell will close the connection, set \fIconnection\fP to NULL,
-remove the input callback, and
-call the procedures registered on the error callback list.
-The \fIcall_data\fP for these callbacks is NULL.
-.bp
diff --git a/specs/CH05 b/specs/CH05
deleted file mode 100644
index 0ffac3c..0000000
--- a/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/specs/CH06 b/specs/CH06
deleted file mode 100644
index 1376d96..0000000
--- a/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/specs/CH07 b/specs/CH07
deleted file mode 100644
index d55598f..0000000
--- a/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 <implementation-defined>
-#define XtExposeCompressMaximal <implementation-defined>
-.De
-.LP
-.eM
-optionally ORed with any combination of the following flags (all with
-implementation-defined values):
-.PN XtExposeGraphicsExpose ,
-.PN XtExposeGraphicsExposeMerged ,
-.PN XtExposeNoExpose ,
-and
-.PN XtExposeNoRegion .
-
-.LP
-If the \fIcompress_exposure\fP field in the widget class structure does not
-specify
-.PN XtExposeNoCompress ,
-the event manager calls the widget's expose procedure only
-once for a series of exposure events.
-In this case, all
-.PN Expose
-or
-.PN GraphicsExpose
-events are accumulated into a region.
-When the final event is received,
-the event manager replaces the rectangle in the event with the
-bounding box for the region
-and calls the widget's expose procedure,
-passing the modified exposure event and (unless
-.PN XtExposeNoRegion
-is specified) the region.
-For more information on regions, see Section 16.5 in \fI\*(xL\fP.)
-.LP
-The values have the following interpretation:
-.sp
-.LP
-.PN XtExposeNoCompress
-.IN "XtExposeNoCompress" "" "@DEF@"
-.IP
-No exposure compression is performed; every selected event is
-individually dispatched to the expose procedure with a \fIregion\fP
-argument of NULL.
-.sp
-.LP
-.PN XtExposeCompressSeries
-.IN "XtExposeCompressSeries" "" "@DEF@"
-.IP
-Each series of exposure events is coalesced into a single event,
-which is dispatched
-when an exposure event with count equal to zero is reached.
-.sp
-.LP
-.PN XtExposeCompressMultiple
-.IN "XtExposeCompressMultiple" "" "@DEF@"
-.IP
-Consecutive series of exposure events are coalesced into a single
-event, which is dispatched
-when an exposure event with count equal to zero is reached and either
-the event queue is empty or the next event is not an exposure event
-for the same widget.
-.sp
-.LP
-.PN XtExposeCompressMaximal
-.IN "XtExposeCompressMaximal" "" "@DEF"
-.IP
-All expose series currently in the queue for the widget
-are coalesced into a single
-event without regard to intervening nonexposure events. If a
-partial series is in the end of the queue, the \*(xI will
-block until the end of the series is received.
-.sp
-.LP
-The additional flags have the following meaning:
-.sp
-.LP
-.PN XtExposeGraphicsExpose
-.IN "XtExposeGraphicsExpose" "" "@DEF@"
-.IP
-Specifies that
-.PN GraphicsExpose
-events are also to be dispatched to
-the expose procedure.
-.PN GraphicsExpose
-events are compressed, if specified, in the same manner as
-.PN Expose
-events.
-.sp
-.LP
-.PN XtExposeGraphicsExposeMerged
-.IN "XtExposeGraphicsExposeMerged" "" "@DEF@"
-.IP
-Specifies in the case of
-.PN XtExposeCompressMultiple
-and
-.PN XtExposeCompressMaximal
-that series of
-.PN GraphicsExpose
-and
-.PN Expose
-events are to be compressed together, with the final event type
-determining the type of the event passed to the expose procedure.
-If this flag is not set, then only series of the same event type
-as the event at the head of the queue are coalesced. This flag
-also implies
-.PN XtExposeGraphicsExpose .
-.sp
-.LP
-.PN XtExposeNoExpose
-.IN "XtExposeNoExpose" "" "@DEF@"
-.IP
-Specifies that
-.PN NoExpose
-events are also to be dispatched to the expose procedure.
-.PN NoExpose
-events are never coalesced with
-other exposure events or with each other.
-.sp
-.LP
-.PN XtExposeNoRegion
-.IN "XtExposeNoRegion" "" "@DEF"
-.IP
-Specifies that the final region argument passed to the expose
-procedure is NULL. The rectangle in the event will still
-contain bounding box information for the entire series of
-compressed exposure events. This option saves processing time when the
-region is not needed by the widget.
-
-.NH 2
-Widget Exposure and Visibility
-.XS
-\*(SN Widget Exposure and Visibility
-.XE
-.LP
-Every primitive widget and some composite widgets display data on the screen
-by means of direct Xlib calls.
-Widgets cannot simply write to the screen and forget what they have done.
-They must keep enough state to redisplay the window or parts
-of it if a portion is obscured and then reexposed.
-
-.NH 3
-Redisplay of a Widget: The expose Procedure
-.XS
-\*(SN Redisplay of a Widget: The expose Procedure
-.XE
-.IN "expose procedure"
-.LP
-The expose procedure pointer in a widget class is of type
-.PN XtExposeProc .
-.LP
-.IN "XtExposeProc" "" "@DEF@"
-.sM
-.FD 0
-typedef void (*XtExposeProc)(Widget, XEvent*, Region);
-.br
- Widget \fIw\fP;
-.br
- XEvent *\fIevent\fP;
-.br
- Region \fIregion\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget instance requiring redisplay.
-.IP \fIevent\fP 1i
-Specifies the exposure event giving the rectangle requiring redisplay.
-.IP \fIregion\fP 1i
-Specifies the union of all rectangles in this exposure sequence.
-.LP
-.eM
-The redisplay of a widget upon exposure is the responsibility of the
-expose procedure in the widget's class record.
-If a widget has no display semantics,
-it can specify NULL for the \fIexpose\fP field.
-Many composite widgets serve only as containers for their children
-and have no expose procedure.
-.NT
-If the \fIexpose\fP procedure is NULL,
-.PN XtRealizeWidget
-fills in a default bit gravity of
-.PN NorthWestGravity
-before it calls the widget's realize procedure.
-.NE
-.LP
-If the widget's \fIcompress_exposure\fP class field specifies
-.PN XtExposeNoCompress
-or
-.PN XtExposeNoRegion ,
-or if the event type is
-.PN NoExpose
-(see Section 7.9.3),
-\fIregion\fP is NULL. If
-.PN XtExposeNoCompress
-is not specified and the event type is not
-.PN NoExpose ,
-the event is the final event in the compressed series
-but \fIx\fP, \fIy\fP, \fIwidth\fP, and \fIheight\fP contain
-the bounding box for all the compressed events.
-The region is created and destroyed by the \*(xI, but
-the widget is permitted to modify the region contents.
-.LP
-A small simple widget (for example, Label) can ignore the bounding box
-information in the event and redisplay the entire window.
-A more complicated widget (for example, Text) can use the bounding box
-information to minimize the amount of calculation and redisplay it does.
-A very complex widget uses the region as a clip list in a GC and
-ignores the event information.
-The expose procedure is not chained and is therefore
-responsible for exposure of all superclass data
-as well as its own.
-.LP
-However,
-it often is possible to anticipate the display needs of several levels
-of subclassing.
-For example, rather than implement separate display procedures for
-the widgets Label, Pushbutton, and Toggle,
-you could write a single display routine in Label that uses display state
-fields like
-.LP
-.DS
-Boolean invert;
-Boolean highlight;
-Dimension highlight_width;
-.DE
-Label would have \fIinvert\fP and \fIhighlight\fP always
-.PN False
-and \fIhighlight_width\fP zero.
-Pushbutton would dynamically set \fIhighlight\fP and \fIhighlight_width\fP,
-but it would leave \fIinvert\fP always
-.PN False .
-Finally, Toggle would dynamically set all three.
-In this case,
-the expose procedures for Pushbutton and Toggle inherit
-their superclass's expose procedure;
-see Section 1.6.10.
-
-.NH 3
-Widget Visibility
-.XS
-\*(SN Widget Visibility
-.XE
-.LP
-Some widgets may use substantial computing resources to produce the
-data they will display.
-However, this effort is wasted if the widget is not actually visible
-on the screen, that is, if the widget is obscured by another application
-or is iconified.
-.LP
-.IN "Visibility"
-The \fIvisible\fP field in the
-core
-widget structure provides a hint to the widget that it need not compute
-display data.
-This field is guaranteed to be
-.PN True
-by the time an
-exposure
-event is processed if any part of the widget is visible,
-but is
-.PN False
-if the widget is fully obscured.
-.LP
-Widgets can use or ignore the \fIvisible\fP hint.
-If they ignore it,
-they should have \fIvisible_interest\fP in their widget class record set
-.PN False .
-In such cases,
-the \fIvisible\fP field is initialized
-.PN True
-and never changes.
-If \fIvisible_interest\fP is
-.PN True ,
-the event manager asks for
-.PN VisibilityNotify
-events for the widget and sets \fIvisible\fP to
-.PN True
-on
-.PN VisibilityUnobscured
-or
-.PN VisibilityPartiallyObscured
-.IN VisibilityNotify
-events and
-.PN False
-on
-.PN VisibilityFullyObscured
-events.
-
-.NH 2
-X Event Handlers
-.XS
-\*(SN X Event Handlers
-.XE
-.LP
-Event handlers are procedures called when specified events
-occur in a widget.
-Most widgets need not use event handlers explicitly.
-Instead, they use the \*(xI translation manager.
-Event handler procedure pointers are of the type
-.PN XtEventHandler .
-.LP
-.IN "XtEventHandler" "" "@DEF@"
-.sM
-.FD 0
-typedef void (*XtEventHandler)(Widget, XtPointer, XEvent*, Boolean*);
-.br
- Widget \fIw\fP;
-.br
- XtPointer \fIclient_data\fP;
-.br
- XEvent *\fIevent\fP;
-.br
- Boolean *\fIcontinue_to_dispatch\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget for which the event arrived.
-.IP \fIclient_data\fP 1i
-Specifies any client-specific information registered with the event handler.
-.IP \fIevent\fP 1i
-Specifies the triggering event.
-.IP \fIcontinue_to_dispatch\fP 1i
-Specifies whether the remaining event
-handlers registered for the current event
-should be called.
-.LP
-.eM
-After receiving an event and before calling any event handlers, the
-Boolean pointed to by \fIcontinue_to_dispatch\fP is initialized to
-.PN True .
-When an event handler is called, it may decide that further processing
-of the event is not desirable and may store
-.PN False
-in this Boolean, in
-which case any handlers remaining to be called for the event are
-ignored.
-.LP
-The circumstances under which the \*(xI may add event handlers
-to a widget are currently implementation-dependent. Clients must
-therefore be aware that storing
-.PN False
-into the \fIcontinue_to_dispatch\fP argument can lead to portability problems.
-
-.NH 3
-Event Handlers That Select Events
-.XS
-\*(SN Event Handlers That Select Events
-.XE
-.LP
-To register an event handler procedure with the dispatch mechanism, use
-.PN XtAddEventHandler .
-.LP
-.IN "XtAddEventHandler" "" "@DEF@"
-.sM
-.FD 0
-void XtAddEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
-\fIproc\fP, \fIclient_data\fP)
-.br
- Widget \fIw\fP;
-.br
- EventMask \fIevent_mask\fP;
-.br
- Boolean \fInonmaskable\fP;
-.br
- XtEventHandler \fIproc\fP;
-.br
- XtPointer \fIclient_data\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget for which this event handler is being registered. \*(cI
-.IP \fIevent_mask\fP 1i
-Specifies the event mask for which to call this procedure.
-.IP \fInonmaskable\fP 1i
-Specifies whether this procedure should be
-called on the nonmaskable events
-.Pn ( GraphicsExpose ,
-.PN NoExpose ,
-.PN SelectionClear ,
-.PN SelectionRequest ,
-.PN SelectionNotify ,
-.PN ClientMessage ,
-and
-.PN MappingNotify ).
-.IP \fIproc\fP 1i
-Specifies the procedure to be called.
-.IP \fIclient_data\fP 1i
-Specifies additional data to be passed to the event handler.
-.LP
-.eM
-The
-.PN XtAddEventHandler
-function registers a procedure with the dispatch mechanism that is
-to be called when an event that matches the mask occurs on the specified
-widget.
-Each widget has a single registered event handler list, which will
-contain any procedure/client_data pair exactly once regardless of
-the manner in which it is registered.
-If the procedure is already registered with the same \fIclient_data\fP
-value,
-the specified mask augments the existing mask.
-If the widget is realized,
-.PN XtAddEventHandler
-calls
-.PN XSelectInput ,
-if necessary.
-The order in which this procedure is called relative to other handlers
-registered for the same event is not defined.
-.sp
-.LP
-To remove a previously registered event handler, use
-.PN XtRemoveEventHandler .
-.LP
-.IN "XtRemoveEventHandler" "" "@DEF@"
-.sM
-.FD 0
-void XtRemoveEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
-\fIproc\fP, \fIclient_data\fP)
-.br
- Widget \fIw\fP;
-.br
- EventMask \fIevent_mask\fP;
-.br
- Boolean \fInonmaskable\fP;
-.br
- XtEventHandler \fIproc\fP;
-.br
- XtPointer \fIclient_data\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget for which this procedure is registered. \*(cI
-.IP \fIevent_mask\fP 1i
-Specifies the event mask for which to unregister this procedure.
-.IP \fInonmaskable\fP 1i
-Specifies whether this procedure should be
-removed on the nonmaskable events
-.Pn ( GraphicsExpose ,
-.PN NoExpose ,
-.PN SelectionClear ,
-.PN SelectionRequest ,
-.PN SelectionNotify ,
-.PN ClientMessage ,
-and
-.PN MappingNotify ).
-.IP \fIproc\fP 1i
-Specifies the procedure to be removed.
-.IP \fIclient_data\fP 1i
-Specifies the registered client data.
-.LP
-.eM
-The
-.PN XtRemoveEventHandler
-function unregisters an event handler registered with
-.PN XtAddEventHandler
-or
-.PN XtInsertEventHandler
-for the specified events.
-The request is ignored if \fIclient_data\fP does not match the value given
-when the handler was registered.
-If the widget is realized and no other event handler requires the event,
-.PN XtRemoveEventHandler
-calls
-.PN XSelectInput .
-If the specified procedure has not been registered
-or if it has been registered with a different value of \fIclient_data\fP,
-.PN XtRemoveEventHandler
-returns without reporting an error.
-.LP
-To stop a procedure registered with
-.PN XtAddEventHandler
-or
-.PN XtInsertEventHandler
-from receiving all selected events, call
-.PN XtRemoveEventHandler
-with an \fIevent_mask\fP of
-.PN XtAllEvents
-and \fInonmaskable\fP
-.PN True .
-The procedure will continue to receive any events
-that have been specified in calls to
-.PN XtAddRawEventHandler
-or
-.PN XtInsertRawEventHandler .
-.sp
-.LP
-To register an event handler procedure that receives events before or
-after all previously registered event handlers, use
-.PN XtInsertEventHandler .
-.LP
-.IN "XtListPosition" "" "@DEF@"
-.IN "XtInsertEventHandler" "" "@DEF@"
-.sM
-.Ds 0
-typedef enum {XtListHead, XtListTail} XtListPosition;
-.De
-.LP
-.FD 0
-void XtInsertEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
-\fIproc\fP, \fIclient_data\fP, \fIposition\fP)
-.br
- Widget \fIw\fP;
-.br
- EventMask \fIevent_mask\fP;
-.br
- Boolean \fInonmaskable\fP;
-.br
- XtEventHandler \fIproc\fP;
-.br
- XtPointer \fIclient_data\fP;
-.br
- XtListPosition \fIposition\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget for which this event handler is being registered. \*(cI
-.IP \fIevent_mask\fP 1i
-Specifies the event mask for which to call this procedure.
-.IP \fInonmaskable\fP 1i
-Specifies whether this procedure should be
-called on the nonmaskable events
-.Pn ( GraphicsExpose ,
-.PN NoExpose ,
-.PN SelectionClear ,
-.PN SelectionRequest ,
-.PN SelectionNotify ,
-.PN ClientMessage ,
-and
-.PN MappingNotify ).
-.IP \fIproc\fP 1i
-Specifies the procedure to be called.
-.IP \fIclient_data\fP 1i
-Specifies additional data to be passed to the client's event handler.
-.IP \fIposition\fP 1i
-Specifies when the event handler is to be called
-relative to other previously registered handlers.
-.LP
-.eM
-.PN XtInsertEventHandler
-is identical to
-.PN XtAddEventHandler
-with the additional \fIposition\fP argument. If \fIposition\fP is
-.PN XtListHead ,
-the event
-handler is registered so that it is called before any event
-handlers that were previously registered for the same widget. If
-\fIposition\fP is
-.PN XtListTail ,
-the event handler is registered to be called
-after any previously registered event handlers. If the procedure is
-already registered with the same \fIclient_data\fP value, the specified mask
-augments the existing mask and the procedure is repositioned in
-the list.
-
-.NH 3
-Event Handlers That Do Not Select Events
-.XS
-\*(SN Event Handlers That Do Not Select Events
-.XE
-.LP
-On occasion,
-clients need to register an event handler procedure with the
-dispatch mechanism without explicitly
-causing the X server to select for that event.
-To do this, use
-.PN XtAddRawEventHandler .
-.LP
-.IN "XtAddRawEventHandler" "" "@DEF@"
-.sM
-.FD 0
-void XtAddRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
-\fIproc\fP, \fIclient_data\fP)
-.br
- Widget \fIw\fP;
-.br
- EventMask \fIevent_mask\fP;
-.br
- Boolean \fInonmaskable\fP;
-.br
- XtEventHandler \fIproc\fP;
-.br
- XtPointer \fIclient_data\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget for which this event handler is being registered. \*(cI
-.IP \fIevent_mask\fP 1i
-Specifies the event mask for which to call this procedure.
-.IP \fInonmaskable\fP 1i
-Specifies whether this procedure should be
-called on the nonmaskable events
-.Pn ( GraphicsExpose ,
-.PN NoExpose ,
-.PN SelectionClear ,
-.PN SelectionRequest ,
-.PN SelectionNotify ,
-.PN ClientMessage ,
-and
-.PN MappingNotify ).
-.IP \fIproc\fP 1i
-Specifies the procedure to be called.
-.IP \fIclient_data\fP 1i
-Specifies additional data to be passed to the client's event handler.
-.LP
-.eM
-The
-.PN XtAddRawEventHandler
-function is similar to
-.PN XtAddEventHandler
-except that it does not affect the widget's event mask and never causes an
-.PN XSelectInput
-for its events.
-Note that the widget might already have those mask bits set
-because of other nonraw event handlers registered on it.
-If the procedure is already registered with the same \fIclient_data\fP,
-the specified mask augments the existing mask.
-The order in which this procedure is called relative to other handlers
-registered for the same event is not defined.
-.sp
-.LP
-To remove a previously registered raw event handler, use
-.PN XtRemoveRawEventHandler .
-.LP
-.IN "XtRemoveRawEventHandler" "" "@DEF@"
-.sM
-.FD 0
-void XtRemoveRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
-\fIproc\fP, \fIclient_data\fP)
-.br
- Widget \fIw\fP;
-.br
- EventMask \fIevent_mask\fP;
-.br
- Boolean \fInonmaskable\fP;
-.br
- XtEventHandler \fIproc\fP;
-.br
- XtPointer \fIclient_data\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget for which this procedure is registered. \*(cI
-.IP \fIevent_mask\fP 1i
-Specifies the event mask for which to unregister this procedure.
-.IP \fInonmaskable\fP 1i
-Specifies whether this procedure should be
-removed on the nonmaskable events
-.Pn ( GraphicsExpose ,
-.PN NoExpose ,
-.PN SelectionClear ,
-.PN SelectionRequest ,
-.PN SelectionNotify ,
-.PN ClientMessage ,
-and
-.PN MappingNotify ).
-.IP \fIproc\fP 1i
-Specifies the procedure to be registered.
-.IP \fIclient_data\fP 1i
-Specifies the registered client data.
-.LP
-.eM
-The
-.PN XtRemoveRawEventHandler
-function unregisters an event handler registered with
-.PN XtAddRawEventHandler
-or
-.PN XtInsertRawEventHandler
-for the specified events without changing
-the window event mask.
-The request is ignored if \fIclient_data\fP does not match the value given
-when the handler was registered.
-If the specified procedure has not been registered
-or if it has been registered with a different value of \fIclient_data\fP,
-.PN XtRemoveRawEventHandler
-returns without reporting an error.
-.LP
-To stop a procedure
-registered with
-.PN XtAddRawEventHandler
-or
-.PN XtInsertRawEventHandler
-from receiving all nonselected events, call
-.PN XtRemoveRawEventHandler
-with an \fIevent_mask\fP of
-.PN XtAllEvents
-and \fInonmaskable\fP
-.PN True .
-The procedure
-will continue to receive any events that have been specified in calls to
-.PN XtAddEventHandler
-or
-.PN XtInsertEventHandler .
-.sp
-.LP
-To register an event handler procedure that receives events before or
-after all previously registered event handlers without selecting for
-the events, use
-.PN XtInsertRawEventHandler .
-.LP
-.IN "XtInsertRawEventHandler" "" "@DEF@"
-.sM
-.FD 0
-void XtInsertRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
-\fIproc\fP, \fIclient_data\fP, \fIposition\fP)
-.br
- Widget \fIw\fP;
-.br
- EventMask \fIevent_mask\fP;
-.br
- Boolean \fInonmaskable\fP;
-.br
- XtEventHandler \fIproc\fP;
-.br
- XtPointer \fIclient_data\fP;
-.br
- XtListPosition \fIposition\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget for which this event handler is being registered. \*(cI
-.IP \fIevent_mask\fP 1i
-Specifies the event mask for which to call this procedure.
-.IP \fInonmaskable\fP 1i
-Specifies whether this procedure should be
-called on the nonmaskable events
-.Pn ( GraphicsExpose ,
-.PN NoExpose ,
-.PN SelectionClear ,
-.PN SelectionRequest ,
-.PN SelectionNotify ,
-.PN ClientMessage ,
-and
-.PN MappingNotify ).
-.IP \fIproc\fP 1i
-Specifies the procedure to be registered.
-.IP \fIclient_data\fP 1i
-Specifies additional data to be passed to the client's event handler.
-.IP \fIposition\fP 1i
-Specifies when the event handler is to be called
-relative to other previously registered handlers.
-.LP
-.eM
-The
-.PN XtInsertRawEventHandler
-function is similar to
-.PN XtInsertEventHandler
-except that it does not modify the widget's event
-mask and never causes an
-.PN XSelectInput
-for the specified events. If
-the procedure is already registered with the same \fIclient_data\fP
-value, the
-specified mask augments the existing mask and the procedure is
-repositioned in the list.
-
-.NH 3
-Current Event Mask
-.XS
-\*(SN Current Event Mask
-.XE
-.LP
-To retrieve the event mask for a given widget, use
-.PN XtBuildEventMask .
-.LP
-.IN "XtBuildEventMask" "" "@DEF@"
-.sM
-.FD 0
-EventMask XtBuildEventMask(\fIw\fP)
-.br
- Widget \fIw\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget. \*(cI
-.LP
-.eM
-The
-.PN XtBuildEventMask
-function returns the event mask representing the logical OR
-of all event masks for event handlers registered on the widget with
-.PN XtAddEventHandler
-and
-.PN XtInsertEventHandler
-and all event translations, including accelerators,
-installed on the widget.
-This is the same event mask stored into the
-.PN XSetWindowAttributes
-structure by
-.PN XtRealizeWidget
-and sent to the server when event handlers and translations are installed or
-removed on the realized widget.
-
-.NH 3
-Event Handlers for X11 Protocol Extensions
-.XS
-\fB\*(SN Event Handlers for X11 Protocol Extensions\fP
-.XE
-.LP
-To register an event handler procedure with the \*(xI dispatch
-mechanism according to an event type, use
-.PN XtInsertEventTypeHandler .
-.LP
-.IN "XtInsertEventTypeHandler" "" "@DEF"
-.sM
-.FD 0
-void XtInsertEventTypeHandler(\fIwidget\fP, \fIevent_type\fP, \
-\fIselect_data\fP, \fIproc\fP, \fIclient_data\fP, \fIposition\fP)
-.br
- Widget \fIwidget\fP;
-.br
- int \fIevent_type\fP;
-.br
- XtPointer \fIselect_data\fP;
-.br
- XtEventHandler \fIproc\fP;
-.br
- XtPointer \fIclient_data\fP;
-.br
- XtListPosition \fIposition\fP;
-.FN
-.IP \fIwidget\fP 1i
-Specifies the widget for which this event handler is being registered. \*(cI
-.IP \fIevent_type\fP 1i
-Specifies the event type for which to call this event handler.
-.IP \fIselect_data\fP 1i
-Specifies data used to request events of the specified type from the server,
-or NULL.
-.IP \fIproc\fP 1i
-Specifies the event handler to be called.
-.IP \fIclient_data\fP 1i
-Specifies additional data to be passed to the event handler.
-.IP \fIposition\fP 1i
-Specifies when the event handler is to be called relative to other
-previously registered handlers.
-.LP
-.eM
-.PN XtInsertEventTypeHandler
-registers a procedure with the
-dispatch mechanism that is to be called when an event that matches the
-specified \fIevent_type\fP is dispatched to the specified \fIwidget\fP.
-.LP
-If \fIevent_type\fP specifies one of the core X protocol events, then
-\fIselect_data\fP must be a pointer to a value of type
-.PN EventMask ,
-indicating
-the event mask to be used to select for the desired event. This event
-mask is included in the value returned by
-.PN XtBuildEventMask .
-If the widget is realized,
-.PN XtInsertEventTypeHandler
-calls
-.PN XSelectInput
-if necessary. Specifying NULL for \fIselect_data\fP is equivalent to
-specifying a pointer to an event mask containing 0. This is similar
-to the
-.PN XtInsertRawEventHandler
-function.
-.LP
-If \fIevent_type\fP specifies an extension event type, then the semantics of
-the data pointed to by \fIselect_data\fP are defined by the extension
-selector registered for the specified event type.
-.LP
-In either case the \*(xI are not required to copy the data
-pointed to by \fIselect_data\fP, so the caller must ensure that it remains
-valid as long as the event handler remains registered with this value
-of \fIselect_data\fP.
-.LP
-The \fIposition\fP argument allows the client to control the order of
-invocation of event handlers registered for the same event type. If
-the client does not care about the order, it should normally specify
-.PN XtListTail ,
-which registers this event handler after any previously
-registered handlers for this event type.
-.LP
-Each widget has a single registered event handler list, which will
-contain any procedure/client_data pair exactly once if it is
-registered with
-.PN XtInsertEventTypeHandler ,
-regardless of the manner
-in which it is registered and regardless of the value(s)
-of \fIselect_data\fP. If the procedure is already registered with the
-same \fIclient_data\fP value, the specified mask augments the existing
-mask and the procedure is repositioned in the list.
-.sp
-.LP
-To remove an event handler registered with
-.PN XtInsertEventTypeHandler ,
-use
-.PN XtRemoveEventTypeHandler .
-.LP
-.IN "XtRemoveEventTypeHandler" "" "@DEF"
-.sM
-.FD 0
-void XtRemoveEventTypeHandler(\fIwidget\fP, \fIevent_type\fP, \
-\fIselect_data\fP, \fIproc\fP, \fIclient_data\fP)
-.br
- Widget \fIwidget\fP;
-.br
- int \fIevent_type\fP;
-.br
- XtPointer \fIselect_data\fP;
-.br
- XtEventHandler \fIproc\fP;
-.br
- XtPointer \fIclient_data\fP;
-.FN
-.IP \fIwidget\fP 1i
-Specifies the widget for which the event handler was registered. \*(cI
-.IP \fIevent_type\fP 1i
-Specifies the event type for which the handler was registered.
-.IP \fIselect_data\fP 1i
-Specifies data used to deselect events of the specified type
-from the server, or NULL.
-.IP \fIproc\fP 1i
-Specifies the event handler to be removed.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data with which the procedure was registered.
-.LP
-.eM
-The
-.PN XtRemoveEventTypeHandler
-function unregisters an event handler
-registered with
-.PN XtInsertEventTypeHandler
-for the specified event type.
-The request is ignored if \fIclient_data\fP does not match the value given
-when the handler was registered.
-.LP
-If \fIevent_type\fP specifies one of the core X protocol events,
-\fIselect_data\fP must be a pointer to a value of type
-.PN EventMask, indicating the event
-mask to be used to deselect for the appropriate event. If the widget
-is realized,
-.PN XtRemoveEventTypeHandler
-calls
-.PN XSelectInput
-if necessary.
-Specifying NULL for \fIselect_data\fP is equivalent to specifying a pointer
-to an event mask containing 0. This is similar to the
-.PN XtRemoveRawEventHandler
-function.
-.LP
-If \fIevent_type\fP specifies an extension event type, then the semantics of
-the data pointed to by \fIselect_data\fP are defined by the extension
-selector registered for the specified event type.
-.sp
-.LP
-To register a procedure to select extension events for a widget, use
-.PN XtRegisterExtensionSelector .
-.LP
-.IN "XtRegisterExtensionSelector" "" "@DEF@"
-.sM
-.FD 0
-void XtRegisterExtensionSelector(\fIdisplay\fP, \fImin_event_type\fP, \
-\fImax_event_type\fP, \fIproc\fP,
- \fIclient_data\fP)
-.br
- Display \fI*display\fP;
-.br
- int \fImin_event_type\fP;
-.br
- int \fImax_event_type\fP;
-.br
- XtExtensionSelectProc \fIproc\fP;
-.br
- XtPointer \fIclient_data\fP;
-.FN
-.IP \fIdisplay\fP 1.5i
-Specifies the display for which the extension selector is to be registered.
-.IP \fImin_event_type\fP
-.IP \fImax_event_type\fP 1.5i
-Specifies the range of event types for the extension.
-.IP \fIproc\fP 1.5i
-Specifies the extension selector procedure.
-.IP \fIclient_data\fP 1.5i
-Specifies additional data to be passed to the extension selector.
-.LP
-.eM
-The
-.PN XtRegisterExtensionSelector
-function registers a procedure to arrange
-for the delivery of extension events to widgets.
-.LP
-If \fImin_event_type\fP and \fImax_event_type\fP match the parameters
-to a previous call to
-.PN XtRegisterExtensionSelector
-for the same \fIdisplay\fP, then \fIproc\fP and \fIclient_data\fP
-replace the previously
-registered values. If the range specified by \fImin_event_type\fP
-and \fImax_event_type\fP overlaps the range of the parameters to a
-previous call for the same display in any other way, an error results.
-.LP
-When a widget is realized,
-after the \fIcore.realize\fP method is called,
-the \*(xI check to see if any event
-handler specifies an event type within the range of a registered
-extension selector. If so, the \*(xI call each such selector.
-If an event type handler is added or removed, the \*(xI check to
-see if the event type falls within the range of a registered extension
-selector, and if it does, calls the selector. In either case the \*(xI
-pass a list of all the widget's event types that are within the
-selector's range. The corresponding select data are also passed. The
-selector is responsible for enabling the delivery of extension events
-required by the widget.
-.sp
-.LP
-An extension selector is of type
-.PN XtExtensionSelectProc .
-.LP
-.IN "XtExtensionSelectProc" "" "@DEF"
-.sM
-.FD 0
-typedef void (*XtExtensionSelectProc)(Widget, int *, XtPointer *, int, \
-XtPointer);
-.br
- Widget \fIwidget\fP;
-.br
- int *\fIevent_types\fP;
-.br
- XtPointer *\fIselect_data\fP;
-.br
- int \fIcount\fP;
-.br
- XtPointer \fIclient_data\fP;
-.FN
-.IP \fIwidget\fP 1i
-Specifies the widget that is being realized or is having
-an event handler added or removed.
-.IP \fIevent_types\fP 1i
-Specifies a list of event types that the widget has
-registered event handlers for.
-.IP \fIselect_data\fP 1i
-Specifies a list of the select_data parameters specified in
-.PN XtInsertEventTypeHandler .
-.IP \fIcount\fP 1i
-Specifies the number of entries in the \fIevent_types\fP and \fIselect_data\fP
-lists.
-.IP \fIclient_data\fP 1i
-Specifies the additional client data with which the procedure was registered.
-.LP
-.eM
-The \fIevent_types\fP and \fIselect_data\fP lists will always have the
-same number of elements, specified by \fIcount\fP.
-Each event type/select data pair represents one call to
-.PN XtInsertEventTypeHandler .
-.sp
-.LP
-To register a procedure to dispatch events of a specific type within
-.PN XtDispatchEvent ,
-use
-.PN XtSetEventDispatcher .
-.LP
-.IN "XtSetEventDispatcher" "" "@DEF@"
-.sM
-.FD 0
-XtEventDispatchProc XtSetEventDispatcher(\fIdisplay\fP, \fIevent_type\fP, \
-\fIproc\fP)
-.br
- Display *\fIdisplay\fP;
-.br
- int \fIevent_type\fP;
-.br
- XtEventDispatchProc \fIproc\fP;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the display for which the event dispatcher is to be registered.
-.IP \fIevent_type\fP 1i
-Specifies the event type for which the dispatcher should be invoked.
-.IP \fIproc\fP 1i
-Specifies the event dispatcher procedure.
-.LP
-.eM
-The
-.PN XtSetEventDispatcher
-function registers the event dispatcher procedure specified by \fIproc\fP
-for events with the type \fIevent_type\fP. The previously registered
-dispatcher (or the default dispatcher if there was no previously registered
-dispatcher) is returned. If \fIproc\fP is NULL, the default procedure is
-restored for the specified type.
-.LP
-In the future, when
-.PN XtDispatchEvent
-is called with an event type of \fIevent_type\fP, the specified \fIproc\fP
-(or the default dispatcher) is invoked to determine a widget
-to which to dispatch the event.
-.LP
-The default dispatcher handles the \*(xI modal cascade and keyboard
-focus mechanisms, handles the semantics of \fIcompress_enterleave\fP
-and \fIcompress_motion\fP, and discards all extension events.
-.sp
-.LP
-An event dispatcher procedure pointer is of type
-.PN XtEventDispatchProc .
-.LP
-.IN "XtEventDispatchProc" "" "@DEF@"
-.sM
-.FD 0
-typedef Boolean (*XtEventDispatchProc)(XEvent*)
-.br
- XEvent *\fIevent\fP;
-.FN
-.IP \fIevent\fP 1i
-Passes the event to be dispatched.
-.LP
-.eM
-The event dispatcher procedure should determine whether this event is of
-a type that should be dispatched to a widget.
-.LP
-If the event should be dispatched to a widget, the event dispatcher
-procedure should determine the appropriate widget to receive the
-event, call
-.PN XFilterEvent
-with the window of this widget, or
-.PN None
-if the event is to be discarded, and if
-.PN XFilterEvent
-returns
-.PN False ,
-dispatch the event to the widget using
-.PN XtDispatchEventToWidget .
-The procedure should return
-.PN True
-if either
-.PN XFilterEvent
-or
-.PN XtDispatchEventToWidget
-returned
-.PN True
-and
-.PN False
-otherwise.
-.LP
-If the event should not be dispatched to a widget, the event
-dispatcher procedure should attempt to dispatch the event elsewhere as
-appropriate and return
-.PN True
-if it successfully dispatched the event and
-.PN False
-otherwise.
-.sp
-.LP
-Some dispatchers for extension events may wish to forward events
-according to the Intrinsics' keyboard focus mechanism. To determine
-which widget is the end result of keyboard event forwarding, use
-.PN XtGetKeyboardFocusWidget .
-.LP
-.IN "XtGetKeyboardFocusWidget" "" "@DEF@"
-.sM
-.FD 0
-Widget XtGetKeyboardFocusWidget(\fIwidget\fP)
-.br
- Widget \fIwidget\fP;
-.FN
-.IP \fIwidget\fP 1i
-Specifies the widget to get forwarding information for.
-.LP
-.eM
-The
-.PN XtGetKeyboardFocusWidget
-function returns the widget that would be the end result of keyboard
-event forwarding for a keyboard event for the specified widget.
-.sp
-.LP
-To dispatch an event to a specified widget, use
-.PN XtDispatchEventToWidget .
-.LP
-.IN "XtDispatchEventToWidget" "" "@DEF@"
-.sM
-.FD 0
-Boolean XtDispatchEventToWidget(\fIwidget\fP, \fIevent\fP)
-.br
- Widget \fIwidget\fP;
-.br
- XEvent *\fIevent\fP;
-.FN
-.IP \fIwidget\fP 1i
-Specifies the widget to which to dispatch the event.
-.IP \fIevent\fP 1i
-Specifies a pointer to the event to be dispatched.
-.LP
-.eM
-The
-.PN XtDispatchEventToWidget
-function scans the list of registered event handlers for the
-specified widget and calls each handler that has been registered
-for the specified event type, subject to the \fIcontinue_to_dispatch\fP
-value returned by each handler.
-The \*(xI behave as if event handlers were registered at the head
-of the list for
-.PN Expose ,
-.PN NoExpose ,
-.PN GraphicsExpose ,
-and
-.PN VisibilityNotify
-events to invoke the widget's expose procedure according to the exposure
-compression rules and to update the widget's \fIvisible\fP field
-if \fIvisible_interest\fP is
-.PN True .
-These internal event handlers never set \fIcontinue_to_dispatch\fP to
-.PN False .
-.LP
-.PN XtDispatchEventToWidget
-returns
-.PN True
-if any event handler was called and
-.PN False
-otherwise.
-
-.NH 2
-Using the \*(xI in a Multi-Threaded Environment
-.XS
-\*(SN Using the \*(xI in a Multi-Threaded Environment
-.XE
-.LP
-The \*(xI may be used in environments that offer multiple threads
-of execution within the context of a single process. A multi-threaded
-application using the \*(xI must explicitly initialize the toolkit
-for mutually exclusive access by calling
-.PN XtToolkitThreadInitialize .
-
-.NH 3
-Initializing a Multi-Threaded \*(xI Application
-.XS
-\fB\*(SN Initializing a Multi-Threaded \*(xI Application\fP
-.XE
-.LP
-To test and initialize \*(xI support for mutually exclusive thread
-access, call
-.PN XtToolkitThreadInitialize .
-.LP
-.IN "XtToolkitThreadInitialize" "" "@DEF@"
-.sM
-.FD 0
-Boolean XtToolkitThreadInitialize()
-.FN
-.LP
-.eM
-.PN XtToolkitThreadInitialize
-returns \fBTrue\fP if the \*(xI support mutually exclusive thread
-access, otherwise it returns \fBFalse\fP. \fBXtToolkitThreadInitialize\fP
-must be called before
-.PN XtCreateApplicationContext ,
-.PN XtAppInitialize ,
-.PN XtOpenApplication ,
-or
-.PN XtSetLanguageProc
-is called. \fBXtToolkitThreadInitialize\fP may be called more than once;
-however, the application writer must ensure that it is not called
-simultaneously by two or more threads.
-
-.NH 3
-Locking \*(tk Data Structures
-.XS
-\fB\*(SN Locking \*(tk Data Structures\fP
-.XE
-.LP
-The \*(xI employs two levels of locking: application context and
-process. Locking an application context ensures mutually exclusive
-access by a thread to the state associated with the application context,
-including all displays and widgets associated with it. Locking a
-process ensures mutually exclusive access by a thread to \*(xI process
-global data.
-.LP
-A client may acquire a lock multiple times and the effect is cumulative.
-The client must ensure that the lock is released an equal number of times in
-order for the lock to be acquired by another thread.
-.LP
-Most application writers will have little need to use locking as the
-\*(xI performs the necessary locking internally.
-Resource converters are an exception.
-They require the application context or process to be locked
-before the application can safely call them directly, for example:
-.LP
-.KS
-.Ds
-.TA .5i 2i
-.ta .5i 2i
- ...
- XtAppLock(app_context);
- XtCvtStringToPixel(dpy, args, num_args, fromVal, toVal, closure_ret);
- XtAppUnlock(app_context);
- ...
-.De
-.KE
-.LP
-When the application relies upon
-.PN XtConvertAndStore
-or a converter to provide the storage for the results of a
-conversion, the application should acquire the process lock before
-calling out and hold the lock until the results have been copied.
-.LP
-Application writers who write their own
-utility functions, such as one which retrieves the being_destroyed field from
-a widget instance, must lock the application context before accessing
-widget internal data. For example:
-.LP
-.KS
-.Ds
-.TA .5i 2i
-.ta .5i 2i
-#include <X11/CoreP.h>
-Boolean BeingDestroyed (widget)
- Widget widget;
-{
- Boolean ret;
- XtAppLock(XtWidgetToApplicationContext(widget));
- ret = widget->core.being_destroyed;
- XtAppUnlock(XtWidgetToApplicationContext(widget));
- return ret;
-}
-.De
-.KE
-A client that wishes to atomically call two or more \*(xI functions
-must lock the application context. For example:
-.LP
-.KS
-.Ds
-.TA .5i 2i
-.ta .5i 2i
- ...
- XtAppLock(XtWidgetToApplicationContext(widget));
- XtUnmanageChild (widget1);
- XtManageChild (widget2);
- XtAppUnlock(XtWidgetToApplicationContext(widget));
- ...
-.De
-.KE
-
-.NH 4
-Locking the Application Context
-.XS
-\fB\*(SN Locking the Application Context\fP
-.XE
-.LP
-To ensure mutual exclusion of application context, display, or
-widget internal state, use
-.PN XtAppLock.
-.LP
-.IN "XtAppLock" "" "@DEF@"
-.sM
-.FD 0
-void XtAppLock(\fIapp_context\fP)
-.br
- XtAppContext \fIapp_context\fP;
-.FN
-.IP \fIapp_context\fP 1i
-Specifies the application context to lock.
-.LP
-.eM
-\fBXtAppLock\fP blocks until it is able to acquire the lock. Locking the
-application context also ensures that only the thread holding the lock
-makes Xlib calls from within Xt. An application that makes its own
-direct Xlib calls must either lock the application context around every
-call or enable thread locking in Xlib.
-.LP
-To unlock a locked application context, use
-.PN XtAppUnlock.
-.LP
-.IN "XtAppUnlock" "" "@DEF@"
-.sM
-.FD 0
-void XtAppUnlock(\fIapp_context\fP)
-.br
- XtAppContext \fIapp_context\fP;
-.FN
-.IP \fIapp_context\fP 1i
-Specifies the application context that was previously locked.
-.LP
-.eM
-
-.NH 4
-Locking the Process
-.XS
-\*(SN Locking the Process
-.XE
-.LP
-To ensure mutual exclusion of \*(tk process global data, a
-widget writer must use
-.PN XtProcessLock.
-.LP
-.IN "XtProcessLock" "" "@DEF@"
-.sM
-.FD 0
-void XtProcessLock()
-.FN
-.LP
-.eM
-\fBXtProcessLock\fP blocks until it is able to acquire the lock.
-Widget writers may use XtProcessLock to guarantee mutually exclusive
-access to widget static data.
-.LP
-To unlock a locked process, use
-.PN XtProcessUnlock .
-.LP
-.IN "XtProcessUnlock" "" "@DEF@"
-.sM
-.FD 0
-void XtProcessUnlock()
-.FN
-.LP
-.eM
-To lock both an application context and the process at the same
-time, call
-.PN XtAppLock
-first and then
-.PN XtProcessLock .
-To release both locks, call
-.PN XtProcessUnlock
-first and then
-.PN XtAppUnlock .
-The order is important to avoid deadlock.
-
-.NH 3
-Event Management in a Multi-Threaded Environment
-.XS
-\fB\*(SN Event Management in a Multi-Threaded Environment\fP
-.XE
-.LP
-In a nonthreaded environment an application writer could reasonably
-assume that it is safe to exit the application from a quit callback.
-This assumption may no longer hold true in a multi-threaded environment;
-therefore it is desirable to provide a mechanism to terminate an
-event-processing loop without necessarily terminating its thread.
-.LP
-To indicate that the event loop should terminate after the current
-event dispatch has completed, use
-.PN XtAppSetExitFlag .
-.LP
-.IN "XtAppSetExitFlag" "" "@DEF@"
-.sM
-.FD 0
-void XtAppSetExitFlag(\fIapp_context\fP)
-.br
- XtAppContext \fIapp_context\fP;
-.FN
-.IP \fIapp_context\fP 1i
-Specifies the application context.
-.LP
-.eM
-.PN XtAppMainLoop
-tests the value of the flag and will return if the flag is \fBTrue\fP.
-.LP
-Application writers who implement their own main loop may test the
-value of the exit flag with
-.PN XtAppGetExitFlag .
-.LP
-.IN "XtAppGetExitFlag" "" "@DEF@"
-.sM
-.FD 0
-Boolean XtAppGetExitFlag(\fIapp_context\fP)
-.br
- XtAppContext \fIapp_context\fP;
-.FN
-.IP \fIapp_context\fP 1i
-Specifies the application context.
-.LP
-.eM
-.PN XtAppGetExitFlag
-will normally return \fBFalse\fP, indicating that event processing
-may continue. When
-.PN XtAppGetExitFlag
-returns \fBTrue\fP, the loop must terminate and return to the caller,
-which might then destroy the application context.
-.LP
-Application writers should be aware that, if a thread is blocked in
-.PN XtAppNextEvent ,
-.PN XtAppPeekEvent ,
-or
-.PN XtAppProcessEvent
-and another thread in the same application context opens a new display,
-adds an alternate input, or a timeout, any new source(s) will not
-normally be "noticed" by the blocked thread. Any new sources are
-"noticed" the next time one of these functions is called.
-.LP
-The \*(xI manage access to events on a last-in, first-out basis. If
-multiple threads in the same application context block in
-.PN XtAppNextEvent ,
-.PN XtAppPeekEvent ,
-or
-.PN XtAppProcessEvent ,
-the last thread to call one of these functions is the first
-thread to return.
-.bp
diff --git a/specs/CH08 b/specs/CH08
deleted file mode 100644
index c4818a1..0000000
--- a/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/specs/CH09 b/specs/CH09
deleted file mode 100644
index 205ca58..0000000
--- a/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/specs/CH10 b/specs/CH10
deleted file mode 100644
index b0e9447..0000000
--- a/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 =
- "<EnterWindow>: Highlight()\\n\\
- <LeaveWindow>: Unhighlight()\\n\\
- <Btn1Down>: Set()\\n\\
- <Btn1Up>: Notify() Unset()";
-.De
-.LP
-The \fItm_table\fP field of the
-.PN CoreClassPart
-should be filled in at class initialization time with
-the string containing the class's default translations.
-If a class wants to inherit its superclass's translations,
-it can store the special value
-.PN XtInheritTranslations
-into \fItm_table\fP.
-In Core's class part initialization procedure,
-the \*(xI compile this translation table into an efficient internal form.
-Then, at widget creation time,
-this default translation table is
-combined with the XtNtranslations
-and XtNbaseTranslations resources; see Section 10.3.
-.LP
-The resource conversion mechanism automatically compiles
-string translation tables that are specified in the resource database.
-If a client uses translation tables that are not retrieved via a
-resource conversion,
-it must compile them itself using
-.PN XtParseTranslationTable .
-.LP
-The \*(xI use the compiled form of the translation table to register the
-necessary events with the event manager.
-Widgets need do nothing other than specify the action and translation tables
-for events to be processed by the translation manager.
-
-.NH 3
-Event Sequences
-.XS
-\fB\*(SN Event Sequences\fP
-.XE
-.LP
-An event sequence is a comma-separated list of X event descriptions
-that describes a specific sequence of X events to map to a set of
-program actions.
-Each X event description consists of three parts:
-The X event type, a prefix consisting of the X modifier bits, and
-an event-specific suffix.
-.LP
-Various abbreviations are supported to make translation tables easier
-to read. The events must match incoming events in left-to-right order
-to trigger the action sequence.
-
-.NH 3
-Action Sequences
-.XS
-\fB\*(SN Action Sequences\fP
-.XE
-.LP
-Action sequences specify what program or widget actions to take in response to
-incoming X events. An action sequence consists of space-separated
-action procedure call specifications.
-Each action procedure call consists of the name of an action procedure and a
-parenthesized list of zero or more comma-separated
-string parameters to pass to that procedure.
-The actions are invoked in left-to-right order as specified in the
-action sequence.
-
-.NH 3
-Multi-Click Time
-.XS
-\fB\*(SN Multi-Click Time\fP
-.XE
-.LP
-Translation table entries may specify actions that are taken when two
-or more identical events occur consecutively within a short time
-interval, called the multi-click time. The multi-click time value may
-be specified as an application resource with name ``multiClickTime'' and
-.IN "multiClickTime" "" "@DEF@"
-.IN "Resources" "multiClickTime"
-class ``MultiClickTime'' and may also be modified dynamically by the
-application. The multi-click time is unique for each Display value and
-is retrieved from the resource database by
-.PN XtDisplayInitialize .
-If no value is specified, the initial value is 200 milliseconds.
-.sp
-.LP
-To set the multi-click time dynamically, use
-.PN XtSetMultiClickTime .
-.LP
-.IN "XtSetMultiClickTime" "" "@DEF@"
-.sM
-.FD 0
-void XtSetMultiClickTime(\fIdisplay\fP, \fItime\fP)
-.br
- Display *\fIdisplay\fP;
-.br
- int \fItime\fP;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the display connection.
-.IP \fItime\fP 1i
-Specifies the multi-click time in milliseconds.
-.LP
-.eM
-.PN XtSetMultiClickTime
-sets the time interval used by the translation
-manager to determine when multiple events are interpreted as a
-repeated event. When a repeat count is specified in a translation
-entry, the interval between the timestamps in each pair of repeated
-events (e.g., between two
-.PN ButtonPress
-events) must be less than the
-multi-click time in order for the translation actions to be taken.
-.sp
-.LP
-To read the multi-click time, use
-.PN XtGetMultiClickTime .
-.LP
-.IN "XtGetMultiClickTime" "" "@DEF@"
-.sM
-.FD 0
-int XtGetMultiClickTime(\fIdisplay\fP)
-.br
- Display *\fIdisplay\fP;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the display connection.
-.LP
-.eM
-.PN XtGetMultiClickTime
-returns the time in milliseconds that the
-translation manager uses to determine if multiple events are to be
-interpreted as a repeated event for purposes of matching a translation
-entry containing a repeat count.
-
-.NH 2
-Translation Table Management
-.XS
-\fB\*(SN Translation Table Management\fP
-.XE
-.LP
-Sometimes an application needs to merge
-its own translations with a widget's translations.
-For example, a window manager provides functions to move a window.
-The window manager wishes to bind this operation to a specific
-pointer button in the title bar without the possibility of user
-override and bind it to other buttons that may be overridden by the user.
-.LP
-To accomplish this,
-the window manager should first create the title bar
-and then should merge the two translation tables into
-the title bar's translations.
-One translation table contains the translations that the window manager
-wants only if the user has not specified a translation for a particular event
-or event sequence (i.e., those that may be overridden).
-The other translation table contains the translations that the
-window manager wants regardless of what the user has specified.
-.LP
-Three \*(xI functions support this merging:
-.TS
-lw(2i) lw(3.75i).
-T{
-.PN XtParseTranslationTable
-T} T{
-Compiles a translation table.
-T}
-.sp
-T{
-.PN XtAugmentTranslations
-T} T{
-Merges a compiled translation table into a widget's
-compiled translation table, ignoring any new translations that
-conflict with existing translations.
-T}
-.sp
-T{
-.PN XtOverrideTranslations
-T} T{
-Merges a compiled translation table into a widget's
-compiled translation table, replacing any existing translations that
-conflict with new translations.
-T}
-.TE
-.sp
-.LP
-To compile a translation table, use
-.PN XtParseTranslationTable .
-.LP
-.IN "XtParseTranslationTable" "" "@DEF@"
-.sM
-.FD 0
-XtTranslations XtParseTranslationTable(\fItable\fP)
-.br
- String \fItable\fP;
-.FN
-.IP \fItable\fP 1i
-Specifies the translation table to compile.
-.LP
-.eM
-The
-.PN XtParseTranslationTable
-function compiles the translation table, provided in the format given
-in Appendix B, into an opaque internal representation
-of type
-.PN XtTranslations .
-Note that if an empty translation table is required for any purpose,
-one can be obtained by calling
-.PN XtParseTranslationTable
-and passing an empty string.
-.sp
-.LP
-To merge additional translations into an existing translation table, use
-.PN XtAugmentTranslations .
-.LP
-.IN "XtAugmentTranslations" "" "@DEF@"
-.sM
-.FD 0
-void XtAugmentTranslations(\fIw\fP, \fItranslations\fP)
-.br
- Widget \fIw\fP;
-.br
- XtTranslations \fItranslations\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget into which the new translations are to be merged. \*(cI
-.IP \fItranslations\fP 1i
-Specifies the compiled translation table to merge in.
-.LP
-.eM
-The
-.PN XtAugmentTranslations
-function merges the new translations into the existing widget
-translations, ignoring any
-.PN #replace ,
-.PN #augment ,
-or
-.PN #override
-directive that may have been specified
-in the translation string. The translation table specified by
-\fItranslations\fP is not altered by this process.
-.PN XtAugmentTranslations
-logically appends the string representation of the new translations to
-the string representation of the widget's current translations and reparses
-the result with no warning messages about duplicate left-hand sides, then
-stores the result back into the widget instance; i.e.,
-if the new translations contain an event or event sequence that
-already exists in the widget's translations,
-the new translation is ignored.
-.sp
-.LP
-To overwrite existing translations with new translations, use
-.PN XtOverrideTranslations .
-.LP
-.IN "XtOverrideTranslations" "" "@DEF@"
-.sM
-.FD 0
-void XtOverrideTranslations(\fIw\fP, \fItranslations\fP)
-.br
- Widget \fIw\fP;
-.br
- XtTranslations \fItranslations\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget into which the new translations are to be merged. \*(cI
-.IP \fItranslations\fP 1i
-Specifies the compiled translation table to merge in.
-.LP
-.eM
-The
-.PN XtOverrideTranslations
-function merges the new translations into the existing widget
-translations, ignoring any
-.PN #replace ,
-.PN #augment ,
-or
-.PN #override
-directive that may have been
-specified in the translation string. The translation table
-specified by \fItranslations\fP is not altered by this process.
-.PN XtOverrideTranslations
-logically appends the string representation of the widget's current
-translations to the string representation of the new translations and
-reparses the result with no warning messages about duplicate left-hand
-sides, then stores the result back into the widget instance; i.e.,
-if the new translations contain an event or event sequence that
-already exists in the widget's translations,
-the new translation overrides the widget's translation.
-.LP
-To replace a widget's translations completely, use
-.PN XtSetValues
-on the XtNtranslations resource and specify a compiled translation table
-as the value.
-.sp
-.LP
-To make it possible for users to easily modify translation tables in their
-resource files,
-the string-to-translation-table resource type converter
-allows the string to specify whether the table should replace,
-augment, or override any
-existing translation table in the widget.
-To specify this,
-a pound sign (#) is given as the first character of the table
-followed by one of the keywords ``replace'', ``augment'', or
-``override'' to indicate
-whether to replace, augment, or override the existing table.
-The replace or merge
-operation is performed during the
-Core
-instance initialization.
-Each merge operation produces a new
-translation resource value; if the original tables were shared by
-other widgets, they are unaffected. If no directive is
-specified, ``#replace'' is assumed.
-.LP
-At instance initialization
-the XtNtranslations resource is first fetched. Then, if it was
-not specified or did not contain ``#replace'', the
-resource database is searched for the resource XtNbaseTranslations.
-If XtNbaseTranslations is found, it is merged into the widget class
-translation table. Then the widget \fItranslations\fP field is
-merged into the result or into the class translation table if
-XtNbaseTranslations was not found. This final table is then
-stored into the widget \fItranslations\fP field. If the XtNtranslations
-resource specified ``#replace'', no merge is done.
-If neither XtNbaseTranslations or XtNtranslations are specified,
-the class translation table is copied into the widget instance.
-.sp
-.LP
-To completely remove existing translations, use
-.PN XtUninstallTranslations .
-.LP
-.IN "XtUninstallTranslations" "" "@DEF@"
-.sM
-.FD 0
-void XtUninstallTranslations(\fIw\fP)
-.br
- Widget \fIw\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget from which the translations are to be removed. \*(cI
-.LP
-.eM
-The
-.PN XtUninstallTranslations
-function causes the entire translation table for the widget to be removed.
-
-.NH 2
-Using Accelerators
-.XS
-\fB\*(SN Using Accelerators\fP
-.XE
-.LP
-It is often desirable to be able to bind events in one widget to actions in
-another.
-In particular,
-it is often useful to be able to invoke menu actions from the keyboard.
-The \*(xI provide a facility, called accelerators, that lets you
-accomplish this.
-.IN "Accelerator" "" "@DEF@"
-An accelerator table is a translation table that is bound with its
-actions in the context of a particular widget, the \fIsource\fP widget.
-The accelerator table can then be installed on one or more \fIdestination\fP widgets.
-When an event sequence in the destination widget would cause an
-accelerator action to be taken, and if the source widget is sensitive,
-the actions are executed as though triggered by the same event sequence
-in the accelerator source
-widget. The event is
-passed to the action procedure without modification. The action
-procedures used within accelerators must not assume that the source
-widget is realized nor that any fields of the event are in reference
-to the source widget's window if the widget is realized.
-.LP
-Each widget instance contains that widget's exported accelerator table
-as a resource.
-Each class of widget exports a method that takes a
-displayable string representation of the accelerators
-so that widgets can display their current accelerators.
-The representation is the accelerator table in canonical
-translation table form (see Appendix B).
-The display_accelerator procedure pointer is of type
-.PN XtStringProc .
-.LP
-.IN "display_accelerator procedure" "" "@DEF@"
-.IN "XtStringProc" "" "@DEF@"
-.sM
-.FD 0
-typedef void (*XtStringProc)(Widget, String);
-.br
- Widget \fIw\fP;
-.br
- String \fIstring\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the source widget that supplied the accelerators.
-.IP \fIstring\fP 1i
-Specifies the string representation of the accelerators for this widget.
-.LP
-.eM
-Accelerators can be specified in resource files,
-and the string representation is the same as for a translation table.
-However,
-the interpretation of the
-.PN #augment
-and
-.PN #override
-directives applies to
-what will happen when the accelerator is installed;
-that is, whether or not the accelerator translations will override the
-translations in the destination widget.
-The default is
-.PN #augment ,
-which means that the accelerator translations have lower priority
-than the destination translations.
-The
-.PN #replace
-directive is ignored for accelerator tables.
-.sp
-.LP
-To parse an accelerator table, use
-.PN XtParseAcceleratorTable .
-.LP
-.IN "XtParseAcceleratorTable" "" "@DEF@"
-.sM
-.FD 0
-XtAccelerators XtParseAcceleratorTable(\fIsource\fP)
-.br
- String \fIsource\fP;
-.FN
-.IP \fIsource\fP 1i
-Specifies the accelerator table to compile.
-.LP
-.eM
-The
-.PN XtParseAcceleratorTable
-function compiles the accelerator table into an opaque internal representation.
-The client
-should set the XtNaccelerators resource of
-each widget that is to be activated by these translations
-to the returned value.
-.sp
-.LP
-To install accelerators from a widget on another widget, use
-.PN XtInstallAccelerators .
-.LP
-.IN "XtInstallAccelerators" "" "@DEF@"
-.sM
-.FD 0
-void XtInstallAccelerators(\fIdestination\fP, \fIsource\fP)
-.br
- Widget \fIdestination\fP;
-.br
- Widget \fIsource\fP;
-.FN
-.IP \fIdestination\fP 1i
-Specifies the widget on which the accelerators are to be installed. \*(cI
-.IP \fIsource\fP 1i
-Specifies the widget from which the accelerators are to come. \*(cI
-.LP
-.eM
-The
-.PN XtInstallAccelerators
-function installs the \fIaccelerators\fP resource value from
-\fIsource\fP onto \fIdestination\fP
-by merging the source accelerators into the destination translations.
-If the source \fIdisplay_accelerator\fP field is non-NULL,
-.PN XtInstallAccelerators
-calls it with the source widget and a string representation
-of the accelerator table,
-which indicates that its accelerators have been installed
-and that it should display them appropriately.
-The string representation of the accelerator table is its
-canonical translation table representation.
-.sp
-.LP
-As a convenience for installing all accelerators from a widget and all its
-descendants onto one destination, use
-.PN XtInstallAllAccelerators .
-.LP
-.IN "XtInstallAllAccelerators" "" "@DEF@"
-.sM
-.FD 0
-void XtInstallAllAccelerators(\fIdestination\fP, \fIsource\fP)
-.br
- Widget \fIdestination\fP;
-.br
- Widget \fIsource\fP;
-.FN
-.IP \fIdestination\fP 1i
-Specifies the widget on which the accelerators are to be installed. \*(cI
-.IP \fIsource\fP 1i
-Specifies the root widget of the widget tree
-from which the accelerators are to come. \*(cI
-.LP
-.eM
-The
-.PN XtInstallAllAccelerators
-function recursively descends the widget tree rooted at \fIsource\fP
-and installs the accelerators resource value
-of each widget encountered onto \fIdestination\fP.
-A common use is to call
-.PN XtInstallAllAccelerators
-and pass the application main window as the source.
-
-.NH 2
-KeyCode-to-KeySym Conversions
-.XS
-\*(SN KeyCode-to-KeySym Conversions
-.XE
-.LP
-The translation manager provides support for automatically translating
-KeyCodes in incoming key events into KeySyms.
-KeyCode-to-KeySym translator procedure pointers are of type
-.PN XtKeyProc .
-.LP
-.IN "XtKeyProc" "" "@DEF@"
-.sM
-.FD 0
-typedef void (*XtKeyProc)(Display*, KeyCode, Modifiers, Modifiers*, \
-KeySym*);
-.br
- Display *\fIdisplay\fP;
-.br
- KeyCode \fIkeycode\fP;
-.br
- Modifiers \fImodifiers\fP;
-.br
- Modifiers *\fImodifiers_return\fP;
-.br
- KeySym *\fIkeysym_return\fP;
-.FN
-.IP \fIdisplay\fP 1.1i
-Specifies the display that the KeyCode is from.
-.IP \fIkeycode\fP 1.1i
-Specifies the KeyCode to translate.
-.IP \fImodifiers\fP 1.1i
-Specifies the modifiers to the KeyCode.
-.IP \fImodifiers_return\fP 1.1i
-Specifies a location in which to store
-a mask that indicates the subset of all
-modifiers that are examined by the key translator for the specified keycode.
-.IP \fIkeysym_return\fP 1.1i
-Specifies a location in which to store the resulting KeySym.
-.LP
-.eM
-This procedure takes a KeyCode and modifiers and produces a KeySym.
-For any given key translator function and keyboard encoding,
-\fImodifiers_return\fP will be a constant per KeyCode that indicates
-the subset of all modifiers that are examined by the key translator
-for that KeyCode.
-.LP
-The KeyCode-to-KeySym translator procedure
-must be implemented such that multiple calls with the same
-\fIdisplay\fP, \fIkeycode\fP, and \fImodifiers\fP return the same
-result until either a new case converter, an
-.PN XtCaseProc ,
-is installed or a
-.PN MappingNotify
-event is received.
-
-.sp
-.LP
-The \*(xI maintain tables internally to map KeyCodes to KeySyms
-for each open display. Translator procedures and other clients may
-share a single copy of this table to perform the same mapping.
-.LP
-To return a pointer to the KeySym-to-KeyCode mapping table for a
-particular display, use
-.PN XtGetKeysymTable .
-.LP
-.IN "XtGetKeysymTable" "" "@DEF@"
-.sM
-.FD 0
-KeySym *XtGetKeysymTable(\fIdisplay\fP, \fImin_keycode_return\fP, \
-\fIkeysyms_per_keycode_return\fP)
-.br
- Display *\fIdisplay\fP;
-.br
- KeyCode *\fImin_keycode_return\fP;
-.br
- int *\fIkeysyms_per_keycode_return\fP;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the display whose table is required.
-.IP \fImin_keycode_return\fP 1i
-Returns the minimum KeyCode valid for the display.
-.IP \fIkeysyms_per_keycode_return\fP 1i
-Returns the number of KeySyms stored for each KeyCode.
-.LP
-.eM
-.PN XtGetKeysymTable
-returns a pointer to the \*(xI' copy of the
-server's KeyCode-to-KeySym table. This table must not be modified.
-There are \fIkeysyms_per_keycode_return\fP KeySyms associated with each
-KeyCode, located in the table with indices starting at index
-.IP
- (test_keycode - min_keycode_return) * keysyms_per_keycode_return
-.LP
-for KeyCode \fItest_keycode\fP. Any entries that have no KeySyms associated
-with them contain the value
-.PN NoSymbol .
-Clients should not cache the KeySym table but should call
-.PN XtGetKeysymTable
-each time the value is
-needed, as the table may change prior to dispatching each event.
-.LP
-For more information on this table, see Section 12.7 in \fI\*(xL\fP.
-.sp
-.LP
-To register a key translator, use
-.PN XtSetKeyTranslator .
-.LP
-.IN "XtSetKeyTranslator" "" "@DEF@"
-.sM
-.FD 0
-void XtSetKeyTranslator(\fIdisplay\fP, \fIproc\fP)
-.br
- Display *\fIdisplay\fP;
-.br
- XtKeyProc \fIproc\fP;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the display from which to translate the events.
-.IP \fIproc\fP 1i
-Specifies the procedure to perform key translations.
-.LP
-.eM
-The
-.PN XtSetKeyTranslator
-function sets the specified procedure as the current key translator.
-The default translator is
-.PN XtTranslateKey ,
-an
-.PN XtKeyProc
-that uses the Shift, Lock, numlock, and group modifiers
-with the interpretations defined in \fI\*(xP\fP, Section 5.
-It is provided so that new translators can call it to get default
-KeyCode-to-KeySym translations and so that the default translator
-can be reinstalled.
-.sp
-.LP
-To invoke the currently registered KeyCode-to-KeySym translator,
-use
-.PN XtTranslateKeycode .
-.LP
-.IN "XtTranslateKeycode" "" "@DEF@"
-.sM
-.FD 0
-void XtTranslateKeycode(\fIdisplay\fP, \fIkeycode\fP, \fImodifiers\fP, \
-\fImodifiers_return\fP, \fIkeysym_return\fP)
-.br
- Display *\fIdisplay\fP;
-.br
- KeyCode \fIkeycode\fP;
-.br
- Modifiers \fImodifiers\fP;
-.br
- Modifiers *\fImodifiers_return\fP;
-.br
- KeySym *\fIkeysym_return\fP;
-.FN
-.IP \fIdisplay\fP 1.1i
-Specifies the display that the KeyCode is from.
-.IP \fIkeycode\fP 1.1i
-Specifies the KeyCode to translate.
-.IP \fImodifiers\fP 1.1i
-Specifies the modifiers to the KeyCode.
-.IP \fImodifiers_return\fP 1.1i
-Returns a mask that indicates the modifiers actually used
-to generate the KeySym.
-.IP \fIkeysym_return\fP 1.1i
-Returns the resulting KeySym.
-.LP
-.eM
-The
-.PN XtTranslateKeycode
-function passes the specified arguments
-directly to the currently registered KeyCode-to-KeySym translator.
-.sp
-.LP
-To handle capitalization of nonstandard KeySyms, the \*(xI allow
-clients to register case conversion routines.
-Case converter procedure pointers are of type
-.PN XtCaseProc .
-.LP
-.IN "XtCaseProc" "" "@DEF@"
-.sM
-.FD 0
-typedef void (*XtCaseProc)(Display*, KeySym, KeySym*, KeySym*);
-.br
- Display *\fIdisplay\fP;
-.br
- KeySym \fIkeysym\fP;
-.br
- KeySym *\fIlower_return\fP;
-.br
- KeySym *\fIupper_return\fP;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the display connection for which the conversion is required.
-.IP \fIkeysym\fP 1i
-Specifies the KeySym to convert.
-.IP \fIlower_return\fP 1i
-Specifies a location into which to store the lowercase equivalent for
-the KeySym.
-.IP \fIupper_return\fP 1i
-Specifies a location into which to store the uppercase equivalent for
-the KeySym.
-.LP
-.eM
-If there is no case distinction,
-this procedure should store the KeySym into both return values.
-.sp
-.LP
-To register a case converter, use
-.PN XtRegisterCaseConverter .
-.LP
-.IN "XtRegisterCaseConverter" "" "@DEF@"
-.sM
-.FD 0
-void XtRegisterCaseConverter(\fIdisplay\fP, \fIproc\fP, \fIstart\fP, \fIstop\fP)
-.br
- Display *\fIdisplay\fP;
-.br
- XtCaseProc \fIproc\fP;
-.br
- KeySym \fIstart\fP;
-.br
- KeySym \fIstop\fP;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the display from which the key events are to come.
-.IP \fIproc\fP 1i
-Specifies the
-.PN XtCaseProc
-to do the conversions.
-.IP \fIstart\fP 1i
-Specifies the first KeySym for which this converter is valid.
-.IP \fIstop\fP 1i
-Specifies the last KeySym for which this converter is valid.
-.LP
-.eM
-The
-.PN XtRegisterCaseConverter
-registers the specified case converter.
-The \fIstart\fP and \fIstop\fP arguments provide the inclusive range of KeySyms
-for which this converter is to be called.
-The new converter overrides any previous converters for KeySyms in that range.
-No interface exists to remove converters;
-you need to register an identity converter.
-When a new converter is registered,
-the \*(xI refresh the keyboard state if necessary.
-The default converter understands case conversion for all
-Latin KeySyms defined in \fI\*(xP\fP, Appendix A.
-.sp
-.LP
-To determine uppercase and lowercase equivalents for a KeySym, use
-.PN XtConvertCase .
-.LP
-.IN "XtConvertCase" "" "@DEF@"
-.sM
-.FD 0
-void XtConvertCase(\fIdisplay\fP, \fIkeysym\fP, \fIlower_return\fP, \
-\fIupper_return\fP)
-.br
- Display *\fIdisplay\fP;
-.br
- KeySym \fIkeysym\fP;
-.br
- KeySym *\fIlower_return\fP;
-.br
- KeySym *\fIupper_return\fP;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies the display that the KeySym came from.
-.IP \fIkeysym\fP 1i
-Specifies the KeySym to convert.
-.IP \fIlower_return\fP 1i
-Returns the lowercase equivalent of the KeySym.
-.IP \fIupper_return\fP 1i
-Returns the uppercase equivalent of the KeySym.
-.LP
-.eM
-The
-.PN XtConvertCase
-function calls the appropriate converter and returns the results.
-A user-supplied
-.PN XtKeyProc
-may need to use this function.
-
-.NH 2
-Obtaining a KeySym in an Action Procedure
-.XS
-\fB\*(SN Obtaining a KeySym in an Action Procedure\fP
-.XE
-.LP
-When an action procedure is invoked on a
-.PN KeyPress
-or
-.PN KeyRelease
-event, it often has a need to retrieve the KeySym and modifiers
-corresponding to the event that caused it to be invoked. In order to
-avoid repeating the processing that was just performed by the
-\*(xI to match the translation entry, the KeySym and modifiers
-are stored for the duration of the action procedure and are made
-available to the client.
-.LP
-To retrieve the KeySym and modifiers that matched the final event
-specification in the translation table entry, use
-.PN XtGetActionKeysym .
-.LP
-.IN "XtGetActionKeysym" "" "@DEF@"
-.sM
-.FD 0
-KeySym XtGetActionKeysym(\fIevent\fP, \fImodifiers_return\fP)
-.br
- XEvent *\fIevent\fP;
-.br
- Modifiers *\fImodifiers_return\fP;
-.FN
-.IP \fIevent\fP 1.25i
-Specifies the event pointer passed to the action procedure by the \*(xI.
-.IP \fImodifiers_return\fP 1.25i
-Returns the modifiers that caused the match, if non-NULL.
-.LP
-.eM
-If
-.PN XtGetActionKeysym
-is called after an action procedure has been
-invoked by the \*(xI and before that action procedure returns, and
-if the event pointer has the same value as the event pointer passed to
-that action routine, and if the event is a
-.PN KeyPress
-or
-.PN KeyRelease
-event, then
-.PN XtGetActionKeysym
-returns the KeySym that matched the final
-event specification in the translation table and, if \fImodifiers_return\fP
-is non-NULL, the modifier state actually used to generate this KeySym;
-otherwise, if the event is a
-.PN KeyPress
-or
-.PN KeyRelease
-event, then
-.PN XtGetActionKeysym
-calls
-.PN XtTranslateKeycode
-and returns the results;
-else it returns
-.PN NoSymbol
-and does not examine \fImodifiers_return\fP.
-.LP
-Note that if an action procedure invoked by the \*(xI
-invokes a subsequent action procedure (and so on) via
-.PN XtCallActionProc ,
-the nested action procedure may also call
-.PN XtGetActionKeysym
-to retrieve the \*(xI' KeySym and modifiers.
-
-.NH 2
-KeySym-to-KeyCode Conversions
-.XS
-\*(SN KeySym-to-KeyCode Conversions
-.XE
-.LP
-To return the list of KeyCodes that map to a particular KeySym in
-the keyboard mapping table maintained by the \*(xI, use
-.PN XtKeysymToKeycodeList .
-.LP
-.IN "XtKeysymToKeycodeList" "" "@DEF@"
-.sM
-.FD 0
-void XtKeysymToKeycodeList(\fIdisplay\fP, \fIkeysym\fP, \fIkeycodes_return\fP, \
-\fIkeycount_return\fP)
-.br
- Display *\fIdisplay\fP;
-.br
- KeySym \fIkeysym\fP;
-.br
- KeyCode **\fIkeycodes_return\fP;
-.br
- Cardinal *\fIkeycount_return\fP;
-.FN
-.IP \fIdisplay\fP 1.25i
-Specifies the display whose table is required.
-.IP \fIkeysym\fP 1.25i
-Specifies the KeySym for which to search.
-.IP \fIkeycodes_return\fP 1.25i
-Returns a list of KeyCodes that have \fIkeysym\fP
-associated with them, or NULL if \fIkeycount_return\fP is 0.
-.IP \fIkeycount_return\fP 1.25i
-Returns the number of KeyCodes in the keycode list.
-.LP
-.eM
-The
-.PN XtKeysymToKeycodeList
-procedure returns all the KeyCodes that have \fIkeysym\fP
-in their entry for the keyboard mapping table associated with \fIdisplay\fP.
-For each entry in the
-table, the first four KeySyms (groups 1 and 2) are interpreted as
-specified by \fI\*(xP\fP, Section 5. If no KeyCodes map to the
-specified KeySym, \fIkeycount_return\fP is zero and *\fIkeycodes_return\fP is NULL.
-.LP
-The caller should free the storage pointed to by \fIkeycodes_return\fP using
-.PN XtFree
-when it is no longer useful. If the caller needs to examine
-the KeyCode-to-KeySym table for a particular KeyCode, it should call
-.PN XtGetKeysymTable .
-
-.NH 2
-Registering Button and Key Grabs for Actions
-.XS
-\fB\*(SN Registering Button and Key Grabs for Actions\fP
-.XE
-.LP
-To register button and key grabs for a widget's window according to the
-event bindings in the widget's translation table, use
-.PN XtRegisterGrabAction .
-.LP
-.IN "XtRegisterGrabAction" "" "@DEF@"
-.sM
-.FD 0
-void XtRegisterGrabAction(\fIaction_proc\fP, \fIowner_events\fP, \
-\fIevent_mask\fP, \fIpointer_mode\fP, \fIkeyboard_mode\fP)
-.br
- XtActionProc \fIaction_proc\fP;
-.br
- Boolean \fIowner_events\fP;
-.br
- unsigned int \fIevent_mask\fP;
-.br
- int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
-.FN
-.IP \fIaction_proc\fP 1i
-Specifies the action procedure to search for in translation tables.
-.sp
-.IP \fIowner_events\fP
-.br
-.ns
-.IP \fIevent_mask\fP
-.br
-.ns
-.IP \fIpointer_mode\fP
-.br
-.ns
-.IP \fIkeyboard_mode\fP 1i
-Specify arguments to
-.PN XtGrabButton
-or
-.PN XtGrabKey .
-.LP
-.eM
-.PN XtRegisterGrabAction
-adds the specified \fIaction_proc\fP to a list known to
-the translation manager. When a widget is realized, or when the
-translations of a realized widget or the accelerators installed on a
-realized widget are modified, its translation table and any installed
-accelerators are scanned for action procedures on this list.
-If any are invoked on
-.PN ButtonPress
-or
-.PN KeyPress
-events as the only or final event
-in a sequence, the \*(xI will call
-.PN XtGrabButton
-or
-.PN XtGrabKey
-for the widget with every button or KeyCode which maps to the
-event detail field, passing the specified \fIowner_events\fP, \fIevent_mask\fP,
-\fIpointer_mode\fP, and \fIkeyboard_mode\fP. For
-.PN ButtonPress
-events, the modifiers
-specified in the grab are determined directly from the translation
-specification and \fIconfine_to\fP and \fIcursor\fP are specified as
-.PN None .
-For
-.PN KeyPress
-events, if the translation table entry specifies colon (:) in
-the modifier list, the modifiers are determined by calling the key
-translator procedure registered for the display and calling
-.PN XtGrabKey
-for every combination of standard modifiers which map the KeyCode to
-the specified event detail KeySym, and ORing any modifiers specified in
-the translation table entry, and \fIevent_mask\fP is ignored. If the
-translation table entry does not specify colon in the modifier list,
-the modifiers specified in the grab are those specified in the
-translation table entry only. For both
-.PN ButtonPress
-and
-.PN KeyPress
-events, don't-care modifiers are ignored unless the translation entry
-explicitly specifies ``Any'' in the \fImodifiers\fP field.
-.LP
-If the specified \fIaction_proc\fP is already registered for the calling
-process, the new values will replace the previously specified values
-for any widgets that become realized following the call, but existing
-grabs are not altered on currently realized widgets.
-.LP
-When translations or installed accelerators are modified for a
-realized widget, any previous key or button grabs registered
-as a result of the old bindings are released if they do not appear in
-the new bindings and are not explicitly grabbed by the client with
-.PN XtGrabKey
-or
-.PN XtGrabButton .
-
-.NH 2
-Invoking Actions Directly
-.XS
-\fB\*(SN Invoking Actions Directly\fP
-.XE
-.LP
-Normally action procedures are invoked by the \*(xI when an
-event or event sequence arrives for a widget. To
-invoke an action procedure directly, without generating
-(or synthesizing) events, use
-.PN XtCallActionProc .
-.LP
-.IN "XtCallActionProc" "" "@DEF@"
-.sM
-.FD 0
-void XtCallActionProc(\fIwidget\fP, \fIaction\fP, \fIevent\fP, \fIparams\fP, \
-\fInum_params\fP)
-.br
- Widget \fIwidget\fP;
-.br
- String \fIaction\fP;
-.br
- XEvent *\fIevent\fP;
-.br
- String *\fIparams\fP;
-.br
- Cardinal \fInum_params\fP;
-.FN
-.IP \fIwidget\fP 1i
-Specifies the widget in which the action is to be invoked. \*(cI
-.IP \fIaction\fP 1i
-Specifies the name of the action routine.
-.IP \fIevent\fP 1i
-Specifies the contents of the \fIevent\fP passed to the action routine.
-.IP \fIparams\fP 1i
-Specifies the contents of the \fIparams\fP passed to the action routine.
-.IP \fInum_params\fP 1i
-Specifies the number of entries in \fIparams\fP.
-.LP
-.eM
-.PN XtCallActionProc
-searches for the named action routine in the same
-manner and order as translation tables are bound, as described in
-Section 10.1.2, except that application action tables are searched, if
-necessary, as of the time of the call to
-.PN XtCallActionProc .
-If found,
-the action routine is invoked with the specified widget, event pointer,
-and parameters. It is the responsibility of the caller to ensure that
-the contents of the \fIevent\fP, \fIparams\fP, and \fInum_params\fP arguments are
-appropriate for the specified action routine and, if necessary, that
-the specified widget is realized or sensitive. If the named action
-routine cannot be found,
-.PN XtCallActionProc
-generates a warning message and returns.
-
-.NH 2
-Obtaining a Widget's Action List
-.XS
-\*(SN Obtaining a Widget's Action List
-.XE
-.LP
-Occasionally a subclass will require the pointers to one or more of
-its superclass's action procedures. This would be needed, for
-example, in order to envelop the superclass's action. To retrieve
-the list of action procedures registered in the superclass's
-\fIactions\fP field, use
-.PN XtGetActionList .
-.LP
-.IN "XtGetActionList" "" "@DEF@"
-.sM
-.FD 0
-void XtGetActionList(\fIwidget_class\fP, \fIactions_return\fP, \
-\fInum_actions_return\fP)
-.br
- WidgetClass \fIwidget_class\fP;
-.br
- XtActionList *\fIactions_return\fP;
-.br
- Cardinal *\fInum_actions_return\fP;
-.FN
-.IP \fIwidget_class\fP 1.5i
-Specifies the widget class whose actions are to be returned.
-.IP \fIactions_return\fP 1.5i
-Returns the action list.
-.IP \fInum_actions_return\fP 1.5i
-Returns the number of action procedures declared by the class.
-.LP
-.eM
-.PN XtGetActionList
-returns the action table defined by the specified
-widget class. This table does not include actions defined by the
-superclasses. If \fIwidget_class\fP is not initialized, or is not
-.PN coreWidgetClass
-or a subclass thereof, or if the class does not define any actions,
-*\fIactions_return\fP will be NULL and *\fInum_actions_return\fP
-will be zero.
-If *\fIactions_return\fP is non-NULL the client is responsible for freeing
-the table using
-.PN XtFree
-when it is no longer needed.
-.bp
diff --git a/specs/CH11 b/specs/CH11
deleted file mode 100644
index 0a15602..0000000
--- a/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/specs/CH12 b/specs/CH12
deleted file mode 100644
index 4bd67d6..0000000
--- a/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/specs/CH13 b/specs/CH13
deleted file mode 100644
index ac56c99..0000000
--- a/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/specs/Xtk.intr.front b/specs/Xtk.intr.front
deleted file mode 100644
index a31f06b..0000000
--- a/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/specs/appA b/specs/appA
deleted file mode 100644
index 52935c6..0000000
--- a/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 | <empty line>
-Comment = ``!'' {<any character except null or newline>}
-IncludeFile = ``#'' WhiteSpace ``include'' WhiteSpace FileName WhiteSpace
-FileName = <valid filename for operating system>
-ResourceSpec = WhiteSpace ResourceName WhiteSpace ``:'' WhiteSpace Value
-ResourceName = [Binding] {Component Binding} ComponentName
-Binding = ``.'' | ``*''
-WhiteSpace = {<space> | <horizontal tab>}
-Component = ``?'' | ComponentName
-ComponentName = NameChar {NameChar}
-NameChar = ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-''
-Value = {<any character except null or unescaped newline>}
-.TE
-.LP
-Elements separated by vertical bar (|) are alternatives.
-Curly braces ({\&.\&.\&.}) indicate zero or more repetitions
-of the enclosed elements.
-Square brackets ([\&.\&.\&.]) indicate that the enclosed element is optional.
-Quotes (``\&.\&.\&.'') are used around literal characters.
-.LP
-If the last character on a line is a backslash (\\),
-that line is assumed to continue on the next line.
-.LP
-To allow a Value to begin with whitespace,
-the two-character sequence ``\\\^\fIspace\fP'' (backslash followed by space)
-is recognized and replaced by a space character,
-and the two-character sequence ``\\\^\fItab\fP''
-(backslash followed by horizontal tab)
-is recognized and replaced by a horizontal tab character.
-
-To allow a Value to contain embedded newline characters,
-the two-character sequence ``\\\^n'' is recognized and replaced by a
-newline character.
-To allow a Value to be broken across multiple lines in a text file,
-the two-character sequence ``\\\^\fInewline\fP''
-(backslash followed by newline) is
-recognized and removed from the value.
-
-To allow a Value to contain arbitrary character codes,
-the four-character sequence ``\\\^\fInnn\fP'',
-where each \fIn\fP is a digit character in the range of ``0''\-``7'',
-is recognized and replaced with a single byte that contains
-the octal value specified by the sequence.
-Finally, the two-character sequence ``\\\\'' is recognized
-and replaced with a single backslash.
diff --git a/specs/appB b/specs/appB
deleted file mode 100644
index 0a0b517..0000000
--- a/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 = [ ``^'' | ``$'' | ``\\\\'' ] <ISO Latin 1 character>
-event = [modifier_list] ``<''event_type``>'' [ ``('' count[``+''] ``)'' ] {detail}
-modifier_list = ( [``!''] [``:''] {modifier} ) | ``None''
-modifier = [``~''] modifier_name
-count = (``1'' | ``2'' | ``3'' | ``4'' | ...)
-modifier_name = ``@'' <keysym> | <see ModifierNames table below>
-event_type = <see Event Types table below>
-detail = <event specific details>
-rhs = { name ``('' [params] ``)'' }
-name = namechar { namechar }
-namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' }
-params = string {``,'' string}
-string = quoted_string | unquoted_string
-quoted_string = ``"'' {<Latin 1 character> | escape_char} [``\\\\\\\\'' ] ``"''
-escape_char = ``\\\\"''
-unquoted_string = {<Latin 1 character except space, tab, ``,'', ``\\\\n'', ``)''>}
-.TE
-
-.LP
-The \fIparams\fP field is parsed into a list of
-.PN String
-values that will be passed to the named action procedure. A
-\fIquoted string\fP may contain an embedded quotation mark if the
-quotation mark is preceded by a single backslash (\\). The
-three-character sequence ``\\\\"'' is interpreted as ``single backslash
-followed by end-of-string''.
-
-.SH
-Modifier Names
-.LP
-The modifier field is used to specify standard X keyboard and button
-modifier mask bits.
-Modifiers are legal on event types
-.PN KeyPress ,
-.PN KeyRelease ,
-.PN ButtonPress ,
-.PN ButtonRelease ,
-.PN MotionNotify ,
-.PN EnterNotify ,
-.PN LeaveNotify ,
-and their abbreviations.
-An error is generated when a translation table
-that contains modifiers for any other events is parsed.
-.IP \(bu 5
-If the modifier list has no entries and is not ``None'',
-it means ``don't care'' on all modifiers.
-.IP \(bu 5
-If an exclamation point (!) is specified at the beginning
-of the modifier list,
-it means that the listed modifiers must be in the correct state
-and no other modifiers can be asserted.
-.IP \(bu 5
-If any modifiers are specified
-and an exclamation point (!) is not specified,
-it means that the listed modifiers must be in the
-correct state and ``don't care'' about any other modifiers.
-.IP \(bu 5
-If a modifier is preceded by a tilde (~),
-it means that that modifier must not be asserted.
-.IP \(bu 5
-If ``None'' is specified, it means no modifiers can be asserted.
-.IP \(bu 5
-If a colon (:) is specified at the beginning of the modifier list,
-it directs the \*(xI to apply any standard modifiers in the
-event to map the event keycode into a KeySym.
-The default standard modifiers are Shift and Lock,
-with the interpretation as defined in \fI\*(xP\fP, Section 5.
-The resulting KeySym must exactly match the specified
-KeySym, and the nonstandard modifiers in the event must match the
-modifier list.
-For example, ``:<Key>a'' is distinct from ``:<Key>A'',
-and ``:Shift<Key>A'' is distinct from ``:<Key>A''.
-.IP \(bu 5
-If both an exclamation point (!) and a colon (:) are specified at
-the beginning of the modifier list, it means that the listed
-modifiers must be in the correct state and that no other modifiers
-except the standard modifiers can be asserted. Any standard
-modifiers in the event are applied as for colon (:) above.
-.IP \(bu 5
-If a colon (:) is not specified,
-no standard modifiers are applied.
-Then, for example, ``<Key>A'' and ``<Key>a'' are equivalent.
-.LP
-In key sequences,
-a circumflex (^) is an abbreviation for the Control modifier,
-a dollar sign ($) is an abbreviation for Meta,
-and a backslash (\\) can be used to quote any
-character, in particular a double quote ("), a circumflex (^),
-a dollar sign ($), and another backslash (\\).
-Briefly:
-.LP
-.Ds 0
-.TA 2.5i
-.ta 2.5i
-No modifiers: None <event> detail
-Any modifiers: <event> detail
-Only these modifiers: ! mod1 mod2 <event> detail
-These modifiers and any others: mod1 mod2 <event> detail
-.De
-.LP
-The use of ``None'' for a modifier list is identical to the use
-of an exclamation point with no modifers.
-.LP
-.TS H
-lw(1i) lw(1i) lw(3i).
-_
-.sp 6p
-Modifier Abbreviation Meaning
-.sp 6p
-_
-.sp 6p
-.R
-.TH
-Ctrl c Control modifier bit
-Shift s Shift modifier bit
-Lock l Lock modifier bit
-Meta m Meta key modifier
-Hyper h Hyper key modifier
-Super su Super key modifier
-Alt a Alt key modifier
-Mod1 Mod1 modifier bit
-Mod2 Mod2 modifier bit
-Mod3 Mod3 modifier bit
-Mod4 Mod4 modifier bit
-Mod5 Mod5 modifier bit
-Button1 Button1 modifier bit
-Button2 Button2 modifier bit
-Button3 Button3 modifier bit
-Button4 Button4 modifier bit
-Button5 Button5 modifier bit
-None No modifiers
-Any Any modifier combination
-.sp 6p
-_
-.TE
-.LP
-.IN "key modifier"
-A key modifier is any modifier bit one of whose corresponding KeyCodes
-contains the corresponding left or right KeySym.
-For example,
-``m'' or ``Meta'' means any modifier bit mapping to a KeyCode
-whose KeySym list contains XK_Meta_L or XK_Meta_R.
-Note that this interpretation is for each display,
-not global or even for each application context.
-The Control, Shift, and Lock modifier names refer
-explicitly to the corresponding modifier bits;
-there is no additional interpretation of KeySyms for these modifiers.
-.LP
-Because it is possible to associate arbitrary KeySyms with modifiers, the set of
-key modifiers is extensible. The ``@'' <keysym> syntax means any
-modifier bit whose corresponding KeyCode contains the specified KeySym name.
-.LP
-A modifier_list/KeySym combination in a translation matches a
-modifiers/KeyCode combination in an event in the following ways:
-.IP 1. 5
-If a colon (:) is used, the \*(xI call the display's
-.PN XtKeyProc
-with the KeyCode and modifiers.
-To match, (\fImodifiers\fP & ~\fImodifiers_return\fP) must equal \fImodifier_list\fP, and
-\fIkeysym_return\fP must equal the given KeySym.
-.IP 2. 5
-If (:) is not used, the \*(xI mask off all don't-care bits from the
-modifiers.
-This value must be equal to \fImodifier_list\fP.
-Then, for each possible combination of
-don't-care modifiers in the modifier list, the \*(xI call the display's
-.PN XtKeyProc
-with the KeyCode and that combination ORed with the cared-about modifier bits
-from the event.
-\fIKeysym_return\fP must match the KeySym in the translation.
-.SH
-Event Types
-.LP
-The event-type field describes XEvent types.
-In addition to the standard
-Xlib symbolic event type names, the following event type synonyms
-are defined:
-.TS H
-lw(1.5i) lw(3i).
-_
-.sp 6p
-Type Meaning
-.sp 6p
-_
-.sp 6p
-.TH
-Key T{
-.PN KeyPress
-T}
-KeyDown T{
-.PN KeyPress
-T}
-KeyUp T{
-.PN KeyRelease
-T}
-BtnDown T{
-.PN ButtonPress
-T}
-BtnUp T{
-.PN ButtonRelease
-T}
-Motion T{
-.PN MotionNotify
-T}
-PtrMoved T{
-.PN MotionNotify
-T}
-MouseMoved T{
-.PN MotionNotify
-T}
-Enter T{
-.PN EnterNotify
-T}
-EnterWindow T{
-.PN EnterNotify
-T}
-Leave T{
-.PN LeaveNotify
-T}
-LeaveWindow T{
-.PN LeaveNotify
-T}
-FocusIn T{
-.PN FocusIn
-T}
-FocusOut T{
-.PN FocusOut
-T}
-Keymap T{
-.PN KeymapNotify
-T}
-Expose T{
-.PN Expose
-T}
-GrExp T{
-.PN GraphicsExpose
-T}
-NoExp T{
-.PN NoExpose
-T}
-Visible T{
-.PN VisibilityNotify
-T}
-Create T{
-.PN CreateNotify
-T}
-Destroy T{
-.PN DestroyNotify
-T}
-Unmap T{
-.PN UnmapNotify
-T}
-Map T{
-.PN MapNotify
-T}
-MapReq T{
-.PN MapRequest
-T}
-Reparent T{
-.PN ReparentNotify
-T}
-Configure T{
-.PN ConfigureNotify
-T}
-ConfigureReq T{
-.PN ConfigureRequest
-T}
-Grav T{
-.PN GravityNotify
-T}
-ResReq T{
-.PN ResizeRequest
-T}
-Circ T{
-.PN CirculateNotify
-T}
-CircReq T{
-.PN CirculateRequest
-T}
-Prop T{
-.PN PropertyNotify
-T}
-SelClr T{
-.PN SelectionClear
-T}
-SelReq T{
-.PN SelectionRequest
-T}
-Select T{
-.PN SelectionNotify
-T}
-Clrmap T{
-.PN ColormapNotify
-T}
-Message T{
-.PN ClientMessage
-T}
-Mapping T{
-.PN MappingNotify
-T}
-.sp 6p
-_
-.TE
-The supported abbreviations are:
-.TS H
-lw(1.5i) lw(1.25i) lw(1.75i).
-_
-.sp 6p
-Abbreviation Event Type Including
-.sp 6p
-_
-.sp 6p
-.TH
-.R
-Ctrl T{
-.PN KeyPress
-T} with Control modifier
-Meta T{
-.PN KeyPress
-T} with Meta modifier
-Shift T{
-.PN KeyPress
-T} with Shift modifier
-Btn1Down T{
-.PN ButtonPress
-T} with Button1 detail
-Btn1Up T{
-.PN ButtonRelease
-T} with Button1 detail
-Btn2Down T{
-.PN ButtonPress
-T} with Button2 detail
-Btn2Up T{
-.PN ButtonRelease
-T} with Button2 detail
-Btn3Down T{
-.PN ButtonPress
-T} with Button3 detail
-Btn3Up T{
-.PN ButtonRelease
-T} with Button3 detail
-Btn4Down T{
-.PN ButtonPress
-T} with Button4 detail
-Btn4Up T{
-.PN ButtonRelease
-T} with Button4 detail
-Btn5Down T{
-.PN ButtonPress
-T} with Button5 detail
-Btn5Up T{
-.PN ButtonRelease
-T} with Button5 detail
-BtnMotion T{
-.PN MotionNotify
-T} with any button modifier
-Btn1Motion T{
-.PN MotionNotify
-T} with Button1 modifier
-Btn2Motion T{
-.PN MotionNotify
-T} with Button2 modifier
-Btn3Motion T{
-.PN MotionNotify
-T} with Button3 modifier
-Btn4Motion T{
-.PN MotionNotify
-T} with Button4 modifier
-Btn5Motion T{
-.PN MotionNotify
-T} with Button5 modifier
-.sp 6p
-_
-.TE
-.sp
-.LP
-The detail field is event-specific and normally corresponds to the
-detail field of the corresponding event as described
-by \fI\*(xP\fP, Section 11. The detail field is supported
-for the following event types:
-.LP
-.TS H
-l l .
-_
-.sp 6p
-Event Event Field
-.sp 6p
-_
-.TH
-.sp 6p
-KeyPress KeySym from event \fIdetail\fP (keycode)
-KeyRelease KeySym from event \fIdetail\fP (keycode)
-ButtonPress button from event \fIdetail\fP
-ButtonRelease button from event \fIdetail\fP
-MotionNotify event \fIdetail\fP
-EnterNotify event \fImode\fP
-LeaveNotify event \fImode\fP
-FocusIn event \fImode\fP
-FocusOut event \fImode\fP
-PropertyNotify \fIatom\fP
-SelectionClear \fIselection\fP
-SelectionRequest \fIselection\fP
-SelectionNotify \fIselection\fP
-ClientMessage \fItype\fP
-MappingNotify \fIrequest\fP
-.sp 6p
-_
-.TE
-.LP
-If the event type is
-.PN KeyPress
-or
-.PN KeyRelease ,
-the detail field
-specifies a KeySym name in standard format which is matched against
-the event as described above, for example, <Key>A.
-.LP
-For the
-.PN PropertyNotify ,
-.PN SelectionClear ,
-.PN SelectionRequest ,
-.PN SelectionNotify ,
-and
-.PN ClientMessage
-events the detail field is specified
-as an atom name; for example, <Message>WM_PROTOCOLS. For the
-.PN MotionNotify ,
-.PN EnterNotify ,
-.PN LeaveNotify ,
-.PN FocusIn ,
-.PN FocusOut ,
-and
-.PN MappingNotify
-events, either the symbolic constants as defined by
-\fI\*(xP\fP, Section 11,
-or the numeric values may be specified.
-.LP
-If no detail field is specified, then any value in the event detail is
-accepted as a match.
-.LP
-A KeySym can be specified as any of the standard KeySym names,
-a hexadecimal number prefixed with ``0x'' or ``0X'',
-an octal number prefixed with ``0'', or a decimal number.
-A KeySym expressed as a single digit is interpreted as the
-corresponding Latin 1 KeySym, for example, ``0'' is the KeySym XK_0.
-Other single character KeySyms are treated as literal constants from Latin 1,
-for example, ``!'' is treated as 0x21.
-Standard KeySym names are as defined in
-.Pn < X11/keysymdef.h >
-with the ``XK_'' prefix removed.
-.LP
-.SH
-Canonical Representation
-.LP
-Every translation table has a unique, canonical text representation. This
-representation is passed to a widget's
-.PN display_accelerator
-procedure to describe the accelerators installed on that widget.
-The canonical representation of a translation table is (see also
-``Syntax'')
-.TS
-l l .
-translationTable = { production }
-production = lhs ``:'' rhs ``\\\\n''
-lhs = event { ``,'' event }
-event = [modifier_list] ``<''event_type``>'' [ ``('' count[``+''] ``)'' ] {detail}
-modifier_list = [``!''] [``:''] {modifier}
-modifier = [``~''] modifier_name
-count = (``1'' | ``2'' | ``3'' | ``4'' | ...)
-modifier_name = ``@'' <keysym> | <see canonical modifier names below>
-event_type = <see canonical event types below>
-detail = <event-specific details>
-rhs = { name ``('' [params] ``)'' }
-name = namechar { namechar }
-namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' }
-params = string {``,'' string}
-string = quoted_string
-quoted_string = ``"'' {<Latin 1 character> | escape_char} [``\\\\\\\\'' ] ``"''
-escape_char = ``\\\\"''
-.TE
-.LP
-The canonical modifier names are
-.LP
-.Ds
-.TA 1i 2.5i
-.ta 1i 2.5i
-Ctrl Mod1 Button1
-Shift Mod2 Button2
-Lock Mod3 Button3
- Mod4 Button4
- Mod5 Button5
-.De
-.LP
-The canonical event types are
-.IP
-.TS
-l l.
-T{
-.PN KeyPress
-T} T{
-.PN KeyRelease
-T}
-T{
-.PN ButtonPress
-T} T{
-.PN ButtonRelease
-T}
-T{
-.PN MotionNotify
-T} T{
-.PN EnterNotify
-T}
-T{
-.PN LeaveNotify
-T} T{
-.PN FocusIn
-T}
-T{
-.PN FocusOut
-T} T{
-.PN KeymapNotify
-T}
-T{
-.PN Expose
-T} T{
-.PN GraphicsExpose,
-T}
-T{
-.PN NoExpose
-T} T{
-.PN VisibilityNotify
-T}
-T{
-.PN CreateNotify
-T} T{
-.PN DestroyNotify
-T}
-T{
-.PN UnmapNotify
-T} T{
-.PN MapNotify
-T}
-T{
-.PN MapRequest
-T} T{
-.PN ReparentNotify
-T}
-T{
-.PN ConfigureNotify
-T} T{
-.PN ConfigureRequest
-T}
-T{
-.PN GravityNotify
-T} T{
-.PN ResizeRequest
-T}
-T{
-.PN CirculateNotify
-T} T{
-.PN CirculateRequest
-T}
-T{
-.PN PropertyNotify
-T} T{
-.PN SelectionClear
-T}
-T{
-.PN SelectionRequest
-T} T{
-.PN SelectionNotify
-T}
-T{
-.PN ColormapNotify
-T} T{
-.PN ClientMessage
-T}
-.TE
-.LP
-
-.SH
-Examples
-.LP
-.IP \(bu 5
-Always put more specific events in the table before more general ones:
-.LP
-.Ds
-Shift <Btn1Down> : twas()\\n\\
-<Btn1Down> : brillig()
-.De
-.LP
-.IP \(bu 5
-For double-click on Button1 Up with Shift, use this specification:
-.IP
-.Ds
-Shift<Btn1Up>(2) : and()
-.DE
-.IP
-This is equivalent to the following line with appropriate timers set
-between events:
-.IP
-.Ds
-Shift<Btn1Down>,Shift<Btn1Up>,Shift<Btn1Down>,Shift<Btn1Up> : and()
-.De
-.IP \(bu 5
-For double-click on Button1 Down with Shift, use this specification:
-.IP
-.Ds
-Shift<Btn1Down>(2) : the()
-.De
-.IP
-This is equivalent to the following line with appropriate timers set
-between events:
-.IP
-.Ds
-Shift<Btn1Down>,Shift<Btn1Up>,Shift<Btn1Down> : the()
-.De
-.IP \(bu 5
-Mouse motion is always discarded when it occurs between events in a table
-where no motion event is specified:
-.IP
-.Ds
-<Btn1Down>,<Btn1Up> : slithy()
-.De
-.IP
-This is taken, even if the pointer moves a bit between the down and
-up events.
-Similarly, any motion event specified in a translation matches any number
-of motion events.
-If the motion event causes an action procedure to be invoked,
-the procedure is invoked after each motion event.
-.IP \(bu 5
-If an event sequence consists of a sequence of events that is also a
-noninitial subsequence of another translation,
-it is not taken if it occurs in the context of the longer sequence.
-This occurs mostly in sequences like the following:
-.IP
-.Ds
-<Btn1Down>,<Btn1Up> : toves()\\n\\
-<Btn1Up> : did()
-.De
-.IP
-The second translation is taken only if the button release is not
-preceded by a button press or if there are intervening events between the
-press and the release.
-Be particularly aware of this when using the repeat notation, above,
-with buttons and keys,
-because their expansion includes additional events;
-and when specifying motion events, because they are implicitly included
-between any two other events.
-In particular,
-pointer motion and double-click translations cannot coexist in the same
-translation table.
-.IP \(bu 5
-For single click on Button1 Up with Shift and Meta, use this specification:
-.IP
-.Ds
-Shift Meta <Btn1Down>, Shift Meta<Btn1Up>: gyre()
-.De
-.IP \(bu 5
-For multiple clicks greater or equal to a minimum number,
-a plus sign (+) may be appended to the final (rightmost)
-count in an event sequence. The actions will be invoked
-on the \fIcount\fP-th click and each subsequent one arriving
-within the multi-click time interval. For example:
-.IP
-.Ds
-Shift <Btn1Up>(2+) : and()
-.De
-.IP \(bu 5
-To indicate
-.PN EnterNotify
-with any modifiers, use this specification:
-.IP
-.Ds
-<Enter> : gimble()
-.De
-.IP \(bu 5
-To indicate
-.PN EnterNotify
-with no modifiers, use this specification:
-.IP
-.Ds
-None <Enter> : in()
-.De
-.IP \(bu 5
-To indicate
-.PN EnterNotify
-with Button1 Down and Button2 Up and ``don't care'' about
-the other modifiers, use this specification:
-.IP
-.Ds
-Button1 ~Button2 <Enter> : the()
-.De
-.IP \(bu 5
-To indicate
-.PN EnterNotify
-with Button1 down and Button2 down exclusively, use this specification:
-.IP
-.Ds
-! Button1 Button2 <Enter> : wabe()
-.De
-.IP
-You do not need to use a tilde (~) with an exclamation point (!).
diff --git a/specs/appC b/specs/appC
deleted file mode 100644
index cadabd9..0000000
--- a/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/specs/appD b/specs/appD
deleted file mode 100644
index 3f29098..0000000
--- a/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/specs/appE b/specs/appE
deleted file mode 100644
index 5598258..0000000
--- a/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/specs/appF b/specs/appF
deleted file mode 100644
index 6b2ccdc..0000000
--- a/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/specs/intr.idxmac.t b/specs/intr.idxmac.t
deleted file mode 100644
index 9a3572d..0000000
--- a/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/specs/postproc b/specs/postproc
deleted file mode 100644
index 588b1de..0000000
--- a/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/specs/strings.mit b/specs/strings.mit
deleted file mode 100644
index 87cc710..0000000
--- a/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