diff options
Diffstat (limited to 'specs')
| -rw-r--r-- | specs/CH01 | 140 | ||||
| -rw-r--r-- | specs/CH02 | 192 | ||||
| -rw-r--r-- | specs/CH03 | 62 | ||||
| -rw-r--r-- | specs/CH04 | 154 | ||||
| -rw-r--r-- | specs/CH05 | 56 | ||||
| -rw-r--r-- | specs/CH06 | 86 | ||||
| -rw-r--r-- | specs/CH07 | 280 | ||||
| -rw-r--r-- | specs/CH08 | 24 | ||||
| -rw-r--r-- | specs/CH09 | 104 | ||||
| -rw-r--r-- | specs/CH10 | 74 | ||||
| -rw-r--r-- | specs/CH11 | 272 | ||||
| -rw-r--r-- | specs/CH12 | 20 | ||||
| -rw-r--r-- | specs/CH13 | 88 | ||||
| -rw-r--r-- | specs/Xtk.intr.front | 28 | ||||
| -rw-r--r-- | specs/appA | 14 | ||||
| -rw-r--r-- | specs/appB | 66 | ||||
| -rw-r--r-- | specs/appC | 74 | ||||
| -rw-r--r-- | specs/appD | 14 | ||||
| -rw-r--r-- | specs/appE | 16 | ||||
| -rw-r--r-- | specs/appF | 36 |
20 files changed, 900 insertions, 900 deletions
@@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -67,7 +67,7 @@ Intrinsics \fB\*(SN Intrinsics\fP .XE .LP -The \*(xI provide the base mechanism necessary to build +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 @@ -145,7 +145,7 @@ 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, +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. @@ -222,7 +222,7 @@ A data structure which contains instance-specific values. 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, +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, @@ -236,15 +236,15 @@ Core Widgets .XE .LP .IN "Core" "" "@DEF@" -The -Core +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 +which is defined by the .PN CoreClassPart -and -.PN CorePart +and +.PN CorePart structures. .NH 4 @@ -545,7 +545,7 @@ logical AND of parent's \fIsensitive\fP and T} accelerators NULL T{ -border_pixel +border_pixel T} T{ .PN XtDefaultForeground T} @@ -608,14 +608,14 @@ Composite Widgets .XE .LP .IN "Composite" "" "@DEF@" -The Composite -widget class is a subclass of the -Core +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 +and .PN CompositePart structures. @@ -625,8 +625,8 @@ CompositeClassPart Structure \*(SN CompositeClassPart Structure .XE .LP -In addition to the -Core +In addition to the +Core class fields, widgets of the Composite class have the following class fields. .LP @@ -670,7 +670,7 @@ typedef struct { .De .LP .eM -Composite +Composite classes have the Composite class fields immediately following the Core class fields. .LP @@ -765,7 +765,7 @@ typedef struct { .De .LP .eM -Composite +Composite widgets have the Composite instance fields immediately following the Core instance fields. .LP @@ -828,8 +828,8 @@ CompositePart Default Values .XE .LP The default values for the Composite fields, -which are filled in from the -Composite +which are filled in from the +Composite resource list and by the Composite initialize procedure, are @@ -871,8 +871,8 @@ Constraint Widgets .XE .LP .IN "Constraint" "" "@DEF@" -The Constraint -widget class is a subclass of the +The Constraint +widget class is a subclass of the Composite widget class (see Section 3.6). Constraint widgets maintain additional state @@ -893,7 +893,7 @@ ConstraintClassPart Structure In addition to the Core and -Composite +Composite class fields, widgets of the Constraint class have the following class fields. @@ -938,7 +938,7 @@ typedef struct { .De .LP .eM -Constraint +Constraint classes have the Constraint class fields immediately following the Composite class fields. .LP @@ -1033,7 +1033,7 @@ typedef struct { .De .LP .eM -Constraint +Constraint widgets have the Constraint instance fields immediately following the Composite instance fields. .LP @@ -1184,17 +1184,17 @@ Widget Classing .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, +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 +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 +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 @@ -1212,7 +1212,7 @@ superclass, you should consider whether you have chosen the most appropriate superclass. .LP -To make good use of subclassing, +To make good use of subclassing, widget declarations and naming conventions are highly stylized. A widget consists of three files: .IP \(bu 5 @@ -1253,12 +1253,12 @@ 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 +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 +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'' @@ -1385,9 +1385,9 @@ 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 +the public .h file for the +Constraint +widget class is .PN Constraint.h . .NH 3 @@ -1521,9 +1521,9 @@ 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 +the private .h file for the +Constraint +widget class is .PN ConstrainP.h . .NH 3 @@ -1540,9 +1540,9 @@ 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, +Data constants (for example, \fIresources\fP and \fInum_resources\fP, \fIactions\fP and \fInum_actions\fP, \fIvisible_interest\fP, -\fIcompress_motion\fP, +\fIcompress_motion\fP, \fIcompress_exposure\fP, and \fIversion\fP). .IP \(bu 5 Widget operations (for example, \fIinitialize\fP, \fIrealize\fP, \fIdestroy\fP, @@ -1586,7 +1586,7 @@ 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 +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. @@ -1600,11 +1600,11 @@ 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, +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 +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. @@ -1780,8 +1780,8 @@ Specifies the widget class for which to test. \*(oC .eM The .PN XtIsSubclass -function returns -.PN True +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 @@ -1879,12 +1879,12 @@ 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 +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 +DEBUG defined; otherwise, it is defined as the empty string and generates no code. .NH 3 @@ -1903,7 +1903,7 @@ 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 +superclass value (called downward superclass chaining) or before accessing its corresponding superclass value (called upward superclass chaining). The self-contained fields are .sp @@ -1962,7 +1962,7 @@ the invocation of an operation first accesses the field from the Object, RectObj, and -Core +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 @@ -2004,9 +2004,9 @@ class down to the subclass: .sp .LP With upward superclass chaining, -the invocation of an operation first accesses the field from the widget +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 +and so on up the class chain to the Core, RectObj, and @@ -2092,16 +2092,16 @@ 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 +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 +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, @@ -2113,16 +2113,16 @@ 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 +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 +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, @@ -2170,7 +2170,7 @@ If the specified widget class is already initialized, .PN XtInitializeWidgetClass returns immediately. .LP -If the class initialization procedure registers type converters, +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 @@ -2314,7 +2314,7 @@ 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 +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" @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -72,48 +72,48 @@ other clients. .LP Composite widgets, that is, members of the class .PN compositeWidgetClass , -are containers for an arbitrary, +are containers for an arbitrary, but widget implementation-defined, collection of children, -which may be instantiated by the composite widget itself, +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) +Composite widgets also contain methods for managing the geometry (layout) of any child widget. Under unusual circumstances, -a composite widget may have zero children, +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 +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 +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. +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 +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 +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 +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 +Shell widget that -.PN XtAppCreateShell +.PN XtAppCreateShell returns has a \fIparent\fP pointer of NULL. .LP To facilitate downward traversal of the widget tree, @@ -136,8 +136,8 @@ Initializing the \*(tk .LP Before an application can call any \*(xI function other than -.PN XtSetLanguageProc -and +.PN XtSetLanguageProc +and .PN XtToolkitThreadInitialize , it must initialize the \*(xI by using .IP \(bu 5 @@ -164,20 +164,20 @@ prior to calling .PN XtDisplayInitialize , .PN XtOpenDisplay , .PN XtOpenApplication , -or +or .PN XtAppInitialize . .LP -Multiple instances of \*(tk applications may be implemented +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 +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, +To accommodate both requirements, the \*(xI define application contexts, each of which provides the information needed to distinguish one application instance from another. @@ -330,10 +330,10 @@ 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, +function to parse the command line, and performs other per-display initialization. -After -.PN XrmParseCommand +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 @@ -362,14 +362,14 @@ display before returning. .KS .LP To open a display, initialize it, and then -add it to an application context, use +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, +\fIapplication_name\fP, \fIapplication_class\fP, .br \fIoptions\fP, \fInum_options\fP, \fIargc\fP, \fIargv\fP) .br @@ -414,14 +414,14 @@ Specifies the list of command line parameters. The .PN XtOpenDisplay function calls -.PN XOpenDisplay +.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, +On POSIX-based systems, this is the value of the .PN \s-1DISPLAY\s+1 environment variable. @@ -478,11 +478,11 @@ If called from within an event dispatch (for example, a callback procedure), does not close the display until the dispatch is complete. Note that applications need only call .PN XtCloseDisplay -if they are to continue executing after closing the display; +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 +See Section 7.12 for information regarding the use of .PN XtCloseDisplay in multiple threads. @@ -947,7 +947,7 @@ function first parses the command line for the following options: Specifies the display name for .PN XOpenDisplay . .IP \-name 1i -Sets the resource name prefix, +Sets the resource name prefix, which overrides the application name passed to .PN XtOpenDisplay . .IP \-xnllanguage 1i @@ -957,7 +957,7 @@ and for finding application class resource files. .PN XtDisplayInitialize has a table of standard command line options that are passed to .PN XrmParseCommand -for adding resources to the resource database, +for adding resources to the resource database, and it takes as a parameter additional application-specific resource abbreviations. .IN "XrmOptionDescRec" "" "@DEF@" @@ -1103,13 +1103,13 @@ The widgets create X windows, which then are mapped. .EQ delim $$ .EN -To start the first phase, +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 +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. @@ -1130,7 +1130,7 @@ 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, +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. @@ -1147,8 +1147,8 @@ 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 +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 @@ -1498,7 +1498,7 @@ and initializes the \fIconstraints\fP field. 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. +\fIpopup_list\fP, and \fInum_popups\fP. .IP \(bu 5 Initializes the resource fields (for example, \fIbackground_pixel\fP) by using the @@ -1514,7 +1514,7 @@ 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 +Calls the initialize procedures for the widget starting at the Object initialize procedure on down to the widget's initialize procedure. .IP \(bu 5 @@ -1579,7 +1579,7 @@ Creating an Application Shell Instance An application can have multiple top-level widgets, each of which specifies a unique widget tree that can potentially be on different screens or displays. -An application uses +An application uses .PN XtAppCreateShell to create independent widget trees. .LP @@ -1666,17 +1666,17 @@ XtNargc resources. .LP To create multiple top-level shells within a single (logical) -application, +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 +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. +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, +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 @@ -1687,7 +1687,7 @@ xmail.read.geometry:... (the read window) xmail.compose.geometry:... (the compose window) .De .LP -The second method, +The second method, which is best if there is no main window, leads to resource specifications like the following: .LP @@ -1830,10 +1830,10 @@ with \fIdisplay_string\fP NULL and 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 +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 +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 @@ -1989,24 +1989,24 @@ if requested and an error occurred; otherwise, unchanged. .LP .eM At widget allocation time, if an extension record with \fIrecord_type\fP -equal to +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 +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 +and .PN XtInheritDeallocate are assumed. If no .PN XtAllocateProc is found, the \*(xI will allocate memory for the widget. .LP -An +An .PN XtAllocateProc must perform the following: .IP \(bu 5 @@ -2086,10 +2086,10 @@ 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 +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 +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. @@ -2099,7 +2099,7 @@ It is not necessary to allocate space for or to copy callback lists. .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 +the widget should compute an appropriate width and height based on its other resources. .NT A widget may directly assign only @@ -2200,7 +2200,7 @@ 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, +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, @@ -2281,7 +2281,7 @@ Specifies the widget. \*(cI .LP If the widget is already realized, .PN XtRealizeWidget -simply returns. +simply returns. Otherwise it performs the following: .IP \(bu 5 Binds all action names in the widget's @@ -2293,13 +2293,13 @@ 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 +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 +not a subclass of .PN compositeWidgetClass , .PN XtRealizeWidget returns; otherwise it continues and performs the following: @@ -2310,16 +2310,16 @@ 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 +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 , +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 , +\fImapped_when_managed\fP is +.PN True , .PN XtRealizeWidget maps the widget window. .LP @@ -2373,8 +2373,8 @@ Specifies the widget. \*(oI .eM The .PN XtIsRealized -function returns -.PN True +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 @@ -2439,7 +2439,7 @@ 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 +and whether \fIvisible_interest\fP is .PN True . .IP \(bu 5 The \fIbit_gravity\fP is set to @@ -2452,7 +2452,7 @@ These or any other fields in attributes and the corresponding bits in 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 +structure with all the appropriate fields from non-Core superclasses. .LP @@ -2460,7 +2460,7 @@ superclasses. A widget class can inherit its realize procedure from its superclass during class initialization. The realize procedure defined for -.PN coreWidgetClass +.PN coreWidgetClass calls .PN XtCreateWindow with the passed \fIvalue_mask\fP and \fIattributes\fP @@ -2569,14 +2569,14 @@ Obtaining Window Information from a Widget \fB\*(SN Obtaining Window Information from a Widget\fP .XE .LP -The +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 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@" @@ -2730,7 +2730,7 @@ 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 +.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 @@ -2818,7 +2818,7 @@ 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 +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. @@ -2855,13 +2855,13 @@ In phase 1, .PN XtDestroyWidget performs the following: .IP \(bu 5 -If the \fIbeing_destroyed\fP field of the widget is +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 +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 @@ -2884,19 +2884,19 @@ In phase 2, 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 +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 +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 +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 +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 @@ -2920,7 +2920,7 @@ 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 +If the widget class object class part contains an .PN ObjectClassExtension record with the record_type .PN \s-1NULLQUARK\s+1 @@ -2950,7 +2950,7 @@ The destroy callback procedures use the mechanism described in Chapter 8. The destroy callback list is identified by the resource name XtNdestroyCallback. .LP -For example, the following adds an application-supplied destroy callback +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" @@ -3002,7 +3002,7 @@ 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 +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, @@ -3043,7 +3043,7 @@ on timers created with Calling .PN XtDestroyWidget for each child if the widget has children -and is not a subclass of +and is not a subclass of .PN compositeWidgetClass . .LP During destroy phase 2 for each widget, the \*(xI remove the widget @@ -3111,11 +3111,11 @@ 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 +equal to .PN \s-1NULLQUARK\s+1 , -then +then .PN XtInheritAllocate -and +and .PN XtInheritDeallocate are assumed. The responsibilities of the deallocate procedure are to deallocate the @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -56,7 +56,7 @@ Chapter 3 \(em Composite Widgets and Their Children .XE .IN "Composite widgets" -Composite widgets (widgets whose class is a subclass of +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. @@ -104,7 +104,7 @@ and .PN XtChangeManagedSet , which notify the parent to recalculate the physical layout of its children by calling the parent's change_managed procedure. -The +The .PN XtCreateManagedWidget convenience function calls .PN XtCreateWidget @@ -116,10 +116,10 @@ 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 +if their \fImap_when_managed\fP field is .PN False . -The default is -.PN True +The default is +.PN True and is changed by using .PN XtSetMappedWhenManaged . .LP @@ -337,7 +337,7 @@ The 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 +if the parent's class is not a subclass of .PN compositeWidgetClass . .IP \(bu 5 Returns immediately if the common parent is being destroyed; @@ -356,7 +356,7 @@ Calls .PN XtRealizeWidget on each previously unmanaged child that is unrealized. .IP \- 5 -Maps each previously unmanaged child that has \fImap_when_managed\fP +Maps each previously unmanaged child that has \fImap_when_managed\fP .PN True . .RE .LP @@ -364,7 +364,7 @@ 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 +.PN True and should ignore all other children. Note that some composite widgets, especially fixed boxes, call .PN XtManageChild @@ -374,13 +374,13 @@ 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 +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 +its children, it calls .PN XtResizeWidget , which first updates the \fIwidth\fP, \fIheight\fP, and \fIborder_width\fP @@ -516,10 +516,10 @@ function performs the following: 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 +or if the parent is not a subclass of .PN compositeWidgetClass . .IP \(bu 5 -For each unique child on the list, +For each unique child on the list, .PN XtUnmanageChildren ignores the child if it is unmanaged; otherwise it performs the following: .RS @@ -648,7 +648,7 @@ Specifies the list of widget children to finally add to the managed set. Specifies the number of entries in the \fImanage_children\fP list. .LP .eM -The +The .PN XtChangeManagedSet function performs the following: .IP \(bu 5 @@ -695,11 +695,11 @@ it is unmapped. 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 +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 +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 @@ -815,7 +815,7 @@ 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 +or by setting the \fImap_when_managed\fP field to .PN False . .sp .LP @@ -835,17 +835,17 @@ void XtSetMappedWhenManaged(\fIw\fP, \fImap_when_managed\fP) 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 +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 +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 +and if \fImap_when_managed\fP is .PN False , it unmaps the window. .PN XtSetMappedWhenManaged @@ -901,13 +901,13 @@ Constrained Composite Widgets \*(SN Constrained Composite Widgets .XE .LP -The Constraint +The Constraint widget class is a subclass of .PN compositeWidgetClass . The name is derived from the fact that constraint widgets -may manage the geometry +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 +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 @@ -921,13 +921,13 @@ Accordingly, constraint resources may be included in the argument list or resource file just like any other resource for the child. .LP -Constraint +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, +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. @@ -936,7 +936,7 @@ If a child's parent does not belong to a subclass of then the child's \fIconstraints\fP field is NULL. .LP Subclasses of -Constraint +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 @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -121,16 +121,16 @@ Shell Widget Definitions \*(SN Shell Widget Definitions .XE .LP -Widgets negotiate their size and position with their parent widget, +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. +Widgets at the top of the hierarchy do not have parent widgets. Instead, they must deal with the outside world. -To provide for this, +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 +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. @@ -211,7 +211,7 @@ OverrrideShell, TransientShell, TopLevelShell, ApplicationShell, -and +and SessionShell are intended for public use. @@ -958,10 +958,10 @@ ShellPart Default Values .XE .LP The default values for fields common to all classes of public shells -(filled in by the +(filled in by the +Shell +resource lists and the Shell -resource lists and the -Shell initialize procedures) are: .TS lw(1.75i) lw(3i). @@ -983,19 +983,19 @@ allow_shell_resize T{ T} client_specified (internal) save_under T{ -.PN True +.PN True for -OverrideShell +OverrideShell and TransientShell, -.PN False +.PN False otherwise T} override_redirect T{ -.PN True +.PN True for OverrideShell, -.PN False +.PN False otherwise T} popup_callback NULL @@ -1052,8 +1052,8 @@ and .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 , +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. @@ -1109,10 +1109,10 @@ wait_for_wm T{ .PN True T} transient T{ -.PN True +.PN True for TransientShell, -.PN False +.PN False otherwise T} urgency T{ @@ -1169,11 +1169,11 @@ 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 +.PN False (later events may reset this value). -When \fIwait_for_wm\fP is +When \fIwait_for_wm\fP is .PN False , -the shell does not wait for a response, but relies on asynchronous +the shell does not wait for a response, but relies on asynchronous notification. If \fItransient\fP is .PN True , @@ -1184,7 +1184,7 @@ 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 +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 @@ -1197,7 +1197,7 @@ 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 +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 @@ -1420,7 +1420,7 @@ 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, +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 @@ -1445,7 +1445,7 @@ 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. +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 @@ -1455,12 +1455,12 @@ if the \*Q\fR-xtsessionID\fP\*U argument already appears with an incorrect 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, +\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 +\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 @@ -1469,7 +1469,7 @@ The possible values of \fIrestart_style\fP are .PN SmRestartImmediately , and .PN SmRestartNever . -A resource converter is registered for this resource; +A resource converter is registered for this resource; for the strings that it recognizes, see Section 9.6.1. .LP @@ -1501,12 +1501,12 @@ Joining a Session \fB\*(SN Joining a Session\fP .XE .LP -When a Session shell is created, +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 +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. @@ -1521,13 +1521,13 @@ 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 +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, +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 @@ -1550,7 +1550,7 @@ 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 +While the connection is being managed, if a .PN SaveYourself , .PN SaveYourselfPhase2 , .PN Interact , @@ -1561,7 +1561,7 @@ or 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 +send .PN SaveYourselfPhase2Request , .PN InteractRequest , .PN InteractDone , @@ -1572,7 +1572,7 @@ 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 +will update the client's session property value by a .PN SetProperties or a .PN DeleteProperties @@ -1588,7 +1588,7 @@ Saving Application State .LP The session manager instigates an application checkpoint by sending a .PN SaveYourself -request. +request. Applications are responsible for saving their state in response to the request. .LP @@ -1636,7 +1636,7 @@ message. The possible values of \fIsave_type\fP are .PN SmSaveLocal , .PN SmSaveGlobal , -and +and .PN SmSaveBoth ; these indicate the type of information to be saved. The possible values of \fIinteract_style\fP are @@ -1652,9 +1652,9 @@ 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 +If \fIcancel_shutdown\fP is .PN True , -a +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, @@ -1665,7 +1665,7 @@ 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 +\fIinteract_dialog_type\fP is .PN SmDialogNormal ; \fIrequest_cancel\fP is .PN False ; @@ -1678,32 +1678,32 @@ 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 +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 +Returning .PN False -indicates some portion of the application state +indicates some portion of the application state could not be successfully saved. If any token is returned -to the shell with \fIsave_success\fP +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 +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 +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 +set \fIrequest_next_phase\fP to .PN True -when phase is 1, which will cause the shell to send the +when phase is 1, which will cause the shell to send the .PN SaveYourselfPhase2Request -when the first phase is complete. When the -.PN SaveYourselfPhase2 +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 @@ -1729,14 +1729,14 @@ XtCheckpointToken XtSessionGetToken(\fIwidget\fP) Specifies the Session shell widget which manages session participation. .LP .eM -The +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 +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). @@ -1760,8 +1760,8 @@ on the interact callback list or a token that was received by a call to .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 +A save callback procedure should not call +.PN XtSessionReturnToken on the token passed in its \fIcall_data\fP. .NH 4 @@ -1777,7 +1777,7 @@ 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 +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, @@ -1796,7 +1796,7 @@ 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. +the user. .LP When a token is returned with \fIsave_success\fP .PN False @@ -1810,7 +1810,7 @@ an error condition has occurred during the checkpoint. 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 +This is also true of tokens received through a call to .PN XtSessionGetToken . .NH 4 @@ -1839,11 +1839,11 @@ 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 +if \fIshutdown\fP is .PN True and \fIcancel_shutdown\fP is .PN False , -\fIrequest_cancel\fP indicates whether the +\fIrequest_cancel\fP indicates whether the application requests that the pending shutdown be cancelled. If \fIrequest_cancel\fP is .PN True , @@ -1879,20 +1879,20 @@ 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 +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 +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 +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 +will not send an .PN InteractDone message. @@ -1957,7 +1957,7 @@ Resigning from a Session .LP When the Session shell widget is destroyed, the destroy method will close the connection to the session manager by sending a -.PN ConnectionClosed +.PN ConnectionClosed protocol message and will remove the input callback that was watching for session protocol messages. .LP @@ -1967,7 +1967,7 @@ 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 +.PN ConnectionClosed message, and \fIconnection\fP will be set to NULL. .LP Applications that exit in response to user actions and that do not @@ -1977,22 +1977,22 @@ the Session shell should set \fIjoin_session\fP to before exiting. .LP When -.PN XtSetValues +.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 +beyond the destruction of the shell should first retrieve the \fIconnection\fP resource value, -then set the \fIconnection\fP resource to NULL, +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 +remove the input callback, and call the procedures registered on the error callback list. The \fIcall_data\fP for these callbacks is NULL. .bp @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -59,11 +59,11 @@ 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 +.\"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 +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; @@ -76,8 +76,8 @@ 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 +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 @@ -223,7 +223,7 @@ all remaining resources for the widget not specified in A spring-loaded pop-up invoked from a translation table via .PN XtMenuPopup must already exist -at the time that the translation is invoked, +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. @@ -277,7 +277,7 @@ either statically or dynamically. At startup, an application can create the child of the pop-up shell, which is appropriate for pop-up children composed of a fixed set -of widgets. +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, @@ -390,16 +390,16 @@ Calls 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 +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 +Sets the shell \fIpopped_up\fP field to .PN True , -the shell \fIspring_loaded\fP field to +the shell \fIspring_loaded\fP field to .PN False , and the shell \fIgrab_kind\fP field from \fIgrab_kind\fP. .IP \(bu 5 @@ -418,7 +418,7 @@ XtAddGrab(\fIpopup_shell\fP, (\fIgrab_kind\fP == XtGrabExclusive), False) .De .IP \(bu 5 Calls -.PN XtRealizeWidget +.PN XtRealizeWidget with \fIpopup_shell\fP specified. .IP \(bu 5 Calls @@ -540,7 +540,7 @@ specify and .PN XtGrabExclusive , respectively. -Each function then sets the widget that executed the callback list +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. @@ -627,13 +627,13 @@ Unmapping a Pop-Up Widget Pop-ups can be popped down through several mechanisms: .IP \(bu 5 A call to -.PN XtPopdown +.PN XtPopdown .IP \(bu 5 The supplied callback procedure -.PN XtCallbackPopdown +.PN XtCallbackPopdown .IP \(bu 5 The standard translation action -.PN XtMenuPopdown +.PN XtMenuPopdown .sp .LP To unmap a pop-up from within an application, use @@ -678,7 +678,7 @@ it calls .PN XtRemoveGrab . .\".PN XtRemoveGrab(popup_shell) .IP \(bu 5 -Sets \fIpopup_shell\fP's \fIpopped_up\fP field to +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, @@ -686,7 +686,7 @@ 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 +To pop down a pop-up from a callback list, you may use the callback .PN XtCallbackPopdown . .LP .IN "XtCallbackPopdown" "" "@DEF@" @@ -734,7 +734,7 @@ in one of the pop-up callback convenience procedures. .PN XtCallbackPopdown calls .PN XtPopdown -with the specified \fIshell_widget\fP +with the specified \fIshell_widget\fP and then calls .PN XtSetSensitive to resensitize \fIenable_widget\fP. @@ -771,13 +771,13 @@ 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 +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, +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 @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -53,7 +53,7 @@ .nr H5 0 .LP .XS -Chapter 6 \(em Geometry Management +Chapter 6 \(em Geometry Management .XE .LP .IN "geometry_manager procedure" @@ -67,7 +67,7 @@ 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 +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 @@ -97,11 +97,11 @@ 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 +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 +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. @@ -121,8 +121,8 @@ It can simultaneously move and resize a child with a single call to .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 +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. @@ -213,11 +213,11 @@ it makes the changes and returns .PN XtGeometryYes . .IP \(bu 5 If the parent's class is not a subclass of -.PN compositeWidgetClass +.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 +If the widget's \fIbeing_destroyed\fP field is .PN True , it returns .PN XtGeometryNo . @@ -227,7 +227,7 @@ If the widget \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, and all equal to the requested values, it returns .PN XtGeometryYes ; -otherwise, it calls the parent's geometry_manager procedure +otherwise, it calls the parent's geometry_manager procedure with the given parameters. .IP \(bu 5 If the parent's geometry manager returns @@ -237,9 +237,9 @@ and if is not set in \fIrequest->request_mode\fP and if the widget is realized, .PN XtMakeGeometryRequest -calls the +calls the .PN XConfigureWindow -Xlib function to reconfigure the widget's window (set its size, location, +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 @@ -247,7 +247,7 @@ If the geometry manager returns the change has been approved and actually has been done. In this case, .PN XtMakeGeometryRequest -does no configuring and returns +does no configuring and returns .PN XtGeometryYes . .PN XtMakeGeometryRequest never returns @@ -360,8 +360,8 @@ 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 +like the +.PN XConfigureWindow Xlib function, uses \fIrequest_mode\fP to determine which fields in the .PN XtWidgetGeometry structure the caller wants to specify. @@ -443,7 +443,7 @@ Resize Requests .XE .LP To make a simple resize request from a widget, you can use -.PN XtMakeResizeRequest +.PN XtMakeResizeRequest as an alternative to .PN XtMakeGeometryRequest . .LP @@ -495,7 +495,7 @@ the widget should immediately call again and request that the compromise width and height be applied. If the widget is not interested in .PN XtGeometryAlmost -replies, +replies, it can pass NULL for \fIwidth_return\fP and \fIheight_return\fP. .NH 2 @@ -508,17 +508,17 @@ 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 +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 +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 +To accomplish this, the geometry manager uses .PN XtCWQueryOnly in the intermediate request. .LP @@ -538,17 +538,17 @@ 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 +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 +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 +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; +is guaranteed only for the next call to the same widget; therefore, a cache of size 1 is sufficient. .NH 2 @@ -591,9 +591,9 @@ 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 +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 @@ -610,7 +610,7 @@ it using .PN XtConfigureWidget or .PN XtResizeWidget -as part of its layout process, unless +as part of its layout process, unless .PN XtCWQueryOnly is specified. If it does this, @@ -699,7 +699,7 @@ 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 +the geometry manager frequently rearranges the position of other managed children by calling .PN XtMoveWidget . However, a few geometry managers may sometimes change the @@ -794,7 +794,7 @@ Specify the new widget size. The .PN XtResizeWidget function returns immediately if the specified geometry fields -are the same as the old values. +are the same as the old values. Otherwise, .PN XtResizeWidget writes the new \fIwidth\fP, \fIheight\fP, and \fIborder_width\fP values into @@ -853,7 +853,7 @@ 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 +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. @@ -881,10 +881,10 @@ Specifies the widget. \*(cI .eM The .PN XtResizeWindow -function calls the +function calls the .PN XConfigureWindow Xlib function to make the window of the specified widget match its width, -height, and border 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. @@ -905,7 +905,7 @@ 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 +to obtain the preferred geometry and, as they see fit, can use or ignore any portion of the response. .sp .LP @@ -1050,7 +1050,7 @@ 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 +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 @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -103,7 +103,7 @@ Adding and Deleting Additional Event Sources .XE .LP While most applications are driven only by X events, -some applications need to incorporate other sources of input +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. @@ -157,7 +157,7 @@ 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 +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. @@ -271,7 +271,7 @@ Specifies an argument passed to the specified procedure when it is called. .LP .eM The -.PN XtAppAddBlockHook +.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. @@ -307,8 +307,8 @@ Specifies the identifier returned from the corresponding call to .PN XtAppAddBlockHook . .LP .eM -The -.PN XtRemoveBlockHook +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. @@ -418,9 +418,9 @@ Adding and Removing Signal Callbacks \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 +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 @@ -430,7 +430,7 @@ call 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 +to notify the \*(xI that a signal has occured. To register a signal callback use .PN XtAppAddSignal . .LP @@ -469,7 +469,7 @@ typedef void (*XtSignalCallbackProc)(XtPointer, XtSignalId*); 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 +Passes the id returned from the corresponding .PN XtAppAddSignal call. .LP @@ -494,7 +494,7 @@ call. On a POSIX-based system, .PN XtNoticeSignal is the only \*(xI function that can safely be called from a signal handler. -If +If .PN XtNoticeSignal is invoked multiple times before the \*(xI are able to invoke the registered callback, the callback is only called once. @@ -505,7 +505,7 @@ and is set to .PN True by .PN XtNoticeSignal . -When +When .PN XtAppNextEvent or .PN XtAppProcessEvent @@ -517,11 +517,11 @@ 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 +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 @@ -586,8 +586,8 @@ user events may be delivered to one of several modal widgets in the cascade. Display-related events should be delivered outside the modal cascade so that exposure events and the like keep the application's display up-to-date. Any event that occurs within the cascade is delivered as usual. -The user events delivered to the most recent spring-loaded shell -in the cascade when they occur outside the cascade are called remap events +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 , @@ -610,11 +610,11 @@ this, typically by ignoring any unmatched events. .LP .PN XtPopup -uses the +uses the .PN XtAddGrab and .PN XtRemoveGrab -functions to constrain user events to a modal cascade +functions to constrain user events to a modal cascade and subsequently to remove a grab when the modal widget is popped down. .sp @@ -636,7 +636,7 @@ void XtAddGrab(\fIw\fP, \fIexclusive\fP, \fIspring_loaded\fP) .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 +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 @@ -646,9 +646,9 @@ a pointer button. The .PN XtAddGrab function appends the widget to the modal cascade -and checks that \fIexclusive\fP is -.PN True -if \fIspring_loaded\fP is +and checks that \fIexclusive\fP is +.PN True +if \fIspring_loaded\fP is .PN True . If this condition is not met, .PN XtAddGrab @@ -657,7 +657,7 @@ generates a warning message. 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, +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 @@ -669,10 +669,10 @@ 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 +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 +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 @@ -680,7 +680,7 @@ 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 +subset of the cascade registered with \fIspring_loaded\fP .PN True , if any such widget exists. If the event @@ -707,7 +707,7 @@ Specifies the widget to remove from the modal cascade. .eM The .PN XtRemoveGrab -function removes widgets from the modal cascade starting +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. @@ -1164,11 +1164,11 @@ void XtSetKeyboardFocus(\fIsubtree\fP\, \fIdescendant\fP) Widget \fIsubtree\fP, \fIdescendant\fP; .FN .IP \fIsubtree\fP 1i -Specifies the subtree of the hierarchy for which the keyboard focus is +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 +keyboard events are logically directed, or .PN None . It is not an error to specify .PN None @@ -1349,7 +1349,7 @@ returns .NH 3 Events for Drawables That Are Not a Widget's Window -.XS +.XS \fB\*(SN Events for Drawables That Are Not a Widget's Window\fP .XE .LP @@ -1358,7 +1358,7 @@ associated with widgets in its widget tree. Examples include handling .PN GraphicsExpose and .PN NoExpose -events on Pixmaps, and handling +events on Pixmaps, and handling .PN PropertyNotify events on the root window. .LP @@ -1419,10 +1419,10 @@ Specifies the drawable to unregister. .LP .eM .PN XtUnregisterDrawable -removes an association created with -.PN XtRegisterDrawable . +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 +the results of calling .PN XtUnregisterDrawable are undefined. @@ -1467,11 +1467,11 @@ value returned is a bit mask that is the OR of .PN XtIMXEvent , .PN XtIMTimer , .PN XtIMAlternateInput , -and -.PN XtIMSignal +and +.PN XtIMSignal (see .PN XtAppProcessEvent ). -If there are no events pending, +If there are no events pending, .PN XtAppPending flushes the output buffers of each Display in the application context and returns zero. @@ -1519,9 +1519,9 @@ returns .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, +available, .PN XtAppPeekEvent -will return +will return .PN True without returning an event. .FE @@ -1615,7 +1615,7 @@ 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, +input sources by calling any appropriate input callbacks, signal source by calling any appropriate signal callbacks, and X events by calling @@ -1686,7 +1686,7 @@ Otherwise, sends the event to the event handler functions that have been previously registered with the dispatch routine. .PN XtDispatchEvent -returns +returns .PN True if .PN XFilterEvent @@ -1740,8 +1740,8 @@ Specifies the application context that identifies the application. 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 +.PN XtAppNextEvent +and then dispatches the event to the appropriate registered procedure by calling .PN XtDispatchEvent . This constitutes the main loop of \*(tk applications. @@ -1757,7 +1757,7 @@ 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 +and .PN XtAppUnlock . .LP Applications can provide their own version of this loop, @@ -1794,7 +1794,7 @@ or 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 +\fIancestor_sensitive\fP field also is .PN False . A widget can but does not need to distinguish these two cases visually. .NT @@ -1875,10 +1875,10 @@ 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 +maintains the invariant that, if the parent has either \fIsensitive\fP +or \fIancestor_sensitive\fP .PN False , -then all children have \fIancestor_sensitive\fP +then all children have \fIancestor_sensitive\fP .PN False . .sp .LP @@ -1899,18 +1899,18 @@ Specifies the object. \*(oI .eM The .PN XtIsSensitive -function returns -.PN True -or -.PN False +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 +both \fIsensitive\fP and \fIancestor_sensitive\fP are .PN True , .PN XtIsSensitive -returns +returns .PN True ; -otherwise, it returns +otherwise, it returns .PN False . .NH 2 @@ -1920,7 +1920,7 @@ Adding Background Work Procedures .XE .LP The \*(xI have some limited support for background processing. -Because most applications spend most of their time waiting for input, +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 @@ -1948,7 +1948,7 @@ 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. +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 @@ -1983,12 +1983,12 @@ 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, +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 +To remove a work procedure, either return +.PN True from the procedure when it is called or use .PN XtRemoveWorkProc outside of the procedure. @@ -2046,9 +2046,9 @@ 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 +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 +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 @@ -2109,7 +2109,7 @@ 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 +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.) @@ -2265,7 +2265,7 @@ before it calls the widget's realize procedure. .LP If the widget's \fIcompress_exposure\fP class field specifies .PN XtExposeNoCompress -or +or .PN XtExposeNoRegion , or if the event type is .PN NoExpose @@ -2303,11 +2303,11 @@ Boolean invert; Boolean highlight; Dimension highlight_width; .DE -Label would have \fIinvert\fP and \fIhighlight\fP always +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 +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, @@ -2324,7 +2324,7 @@ Widget Visibility Some widgets may use substantial computing resources to produce the data they will display. However, this effort is wasted if the widget is not actually visible -on the screen, that is, if the widget is obscured by another application +on the screen, that is, if the widget is obscured by another application or is iconified. .LP .IN "Visibility" @@ -2338,18 +2338,18 @@ by the time an exposure event is processed if any part of the widget is visible, but is -.PN False +.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 +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 +the \fIvisible\fP field is initialized +.PN True and never changes. -If \fIvisible_interest\fP is +If \fIvisible_interest\fP is .PN True , the event manager asks for .PN VisibilityNotify @@ -2450,7 +2450,7 @@ 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 +Specifies whether this procedure should be called on the nonmaskable events .Pn ( GraphicsExpose , .PN NoExpose , @@ -2510,7 +2510,7 @@ 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 +Specifies whether this procedure should be removed on the nonmaskable events .Pn ( GraphicsExpose , .PN NoExpose , @@ -2539,7 +2539,7 @@ 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 +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. @@ -2552,7 +2552,7 @@ from receiving all selected events, call .PN XtRemoveEventHandler with an \fIevent_mask\fP of .PN XtAllEvents -and \fInonmaskable\fP +and \fInonmaskable\fP .PN True . The procedure will continue to receive any events that have been specified in calls to @@ -2593,7 +2593,7 @@ 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 +Specifies whether this procedure should be called on the nonmaskable events .Pn ( GraphicsExpose , .PN NoExpose , @@ -2662,7 +2662,7 @@ 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 +Specifies whether this procedure should be called on the nonmaskable events .Pn ( GraphicsExpose , .PN NoExpose , @@ -2681,7 +2681,7 @@ Specifies additional data to be passed to the client's event handler. The .PN XtAddRawEventHandler function is similar to -.PN XtAddEventHandler +.PN XtAddEventHandler except that it does not affect the widget's event mask and never causes an .PN XSelectInput for its events. @@ -2717,7 +2717,7 @@ 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 +Specifies whether this procedure should be removed on the nonmaskable events .Pn ( GraphicsExpose , .PN NoExpose , @@ -2743,7 +2743,7 @@ 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 +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. @@ -2794,7 +2794,7 @@ 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 +Specifies whether this procedure should be called on the nonmaskable events .Pn ( GraphicsExpose , .PN NoExpose , @@ -2855,7 +2855,7 @@ and .PN XtInsertEventHandler and all event translations, including accelerators, installed on the widget. -This is the same event mask stored into the +This is the same event mask stored into the .PN XSetWindowAttributes structure by .PN XtRealizeWidget @@ -2869,7 +2869,7 @@ Event Handlers for X11 Protocol Extensions .XE .LP To register an event handler procedure with the \*(xI dispatch -mechanism according to an event type, use +mechanism according to an event type, use .PN XtInsertEventTypeHandler . .LP .IN "XtInsertEventTypeHandler" "" "@DEF" @@ -2909,24 +2909,24 @@ previously registered handlers. .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. +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 +\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 +mask is included in the value returned by .PN XtBuildEventMask . If the widget is realized, -.PN XtInsertEventTypeHandler -calls +.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 +to the .PN XtInsertRawEventHandler -function. +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 @@ -2946,7 +2946,7 @@ 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 +registered with .PN XtInsertEventTypeHandler , regardless of the manner in which it is registered and regardless of the value(s) @@ -2955,7 +2955,7 @@ 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 +To remove an event handler registered with .PN XtInsertEventTypeHandler , use .PN XtRemoveEventTypeHandler . @@ -2981,7 +2981,7 @@ 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 +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. @@ -2999,10 +2999,10 @@ 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 +\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, +is realized, .PN XtRemoveEventTypeHandler calls .PN XSelectInput @@ -3050,7 +3050,7 @@ Specifies additional data to be passed to the extension selector. .eM The .PN XtRegisterExtensionSelector -function registers a procedure to arrange +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 @@ -3062,7 +3062,7 @@ 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, +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 @@ -3112,7 +3112,7 @@ 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. +same number of elements, specified by \fIcount\fP. Each event type/select data pair represents one call to .PN XtInsertEventTypeHandler . .sp @@ -3142,7 +3142,7 @@ Specifies the event type for which the dispatcher should be invoked. Specifies the event dispatcher procedure. .LP .eM -The +The .PN XtSetEventDispatcher function registers the event dispatcher procedure specified by \fIproc\fP for events with the type \fIevent_type\fP. The previously registered @@ -3154,7 +3154,7 @@ 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. +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 @@ -3176,11 +3176,11 @@ 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. +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 +event, call .PN XFilterEvent with the window of this widget, or .PN None @@ -3228,7 +3228,7 @@ Specifies the widget to get forwarding information for. .LP .eM The -.PN XtGetKeyboardFocusWidget +.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 @@ -3251,7 +3251,7 @@ Specifies the widget to which to dispatch the event. Specifies a pointer to the event to be dispatched. .LP .eM -The +The .PN XtDispatchEventToWidget function scans the list of registered event handlers for the specified widget and calls each handler that has been registered @@ -3285,8 +3285,8 @@ 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 +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 . @@ -3308,7 +3308,7 @@ Boolean XtToolkitThreadInitialize() .LP .eM .PN XtToolkitThreadInitialize -returns \fBTrue\fP if the \*(xI support mutually exclusive thread +returns \fBTrue\fP if the \*(xI support mutually exclusive thread access, otherwise it returns \fBFalse\fP. \fBXtToolkitThreadInitialize\fP must be called before .PN XtCreateApplicationContext , @@ -3317,7 +3317,7 @@ must be called before or .PN XtSetLanguageProc is called. \fBXtToolkitThreadInitialize\fP may be called more than once; -however, the application writer must ensure that it is not called +however, the application writer must ensure that it is not called simultaneously by two or more threads. .NH 3 @@ -3382,7 +3382,7 @@ Boolean BeingDestroyed (widget) } .De .KE -A client that wishes to atomically call two or more \*(xI functions +A client that wishes to atomically call two or more \*(xI functions must lock the application context. For example: .LP .KS @@ -3404,7 +3404,7 @@ Locking the Application Context \fB\*(SN Locking the Application Context\fP .XE .LP -To ensure mutual exclusion of application context, display, or +To ensure mutual exclusion of application context, display, or widget internal state, use .PN XtAppLock. .LP @@ -3419,10 +3419,10 @@ void XtAppLock(\fIapp_context\fP) 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 +\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 +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 @@ -3458,7 +3458,7 @@ void XtProcessLock() .LP .eM \fBXtProcessLock\fP blocks until it is able to acquire the lock. -Widget writers may use XtProcessLock to guarantee mutually exclusive +Widget writers may use XtProcessLock to guarantee mutually exclusive access to widget static data. .LP To unlock a locked process, use @@ -3471,7 +3471,7 @@ void XtProcessUnlock() .FN .LP .eM -To lock both an application context and the process at the same +To lock both an application context and the process at the same time, call .PN XtAppLock first and then @@ -3489,12 +3489,12 @@ Event Management in a Multi-Threaded Environment .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; +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 +To indicate that the event loop should terminate after the current event dispatch has completed, use .PN XtAppSetExitFlag . .LP @@ -3512,7 +3512,7 @@ Specifies the application context. .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 +Application writers who implement their own main loop may test the value of the exit flag with .PN XtAppGetExitFlag . .LP @@ -3534,21 +3534,21 @@ may continue. When 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 +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 +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 +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 XtAppNextEvent , +.PN XtAppPeekEvent , +or .PN XtAppProcessEvent , the last thread to call one of these functions is the first thread to return. @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -107,7 +107,7 @@ it passes the new position of the thumb. .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, +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. @@ -115,7 +115,7 @@ 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 +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 @@ -173,15 +173,15 @@ Identifying Callback Lists \fB\*(SN Identifying Callback Lists\fP .XE .LP -Whenever a widget contains a callback list for use by clients, +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 +All the callback manipulation functions described in this chapter except .PN XtCallCallbackList -check +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, @@ -437,7 +437,7 @@ Specifies the callback list to be checked. .eM The .PN XtHasCallbacks -function first checks to see if the widget has a callback list identified +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 @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -70,7 +70,7 @@ 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 +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 @@ -133,7 +133,7 @@ The \fIresource_name\fP field contains the name used by clients to access the fi 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 +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 @@ -153,7 +153,7 @@ 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 +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. @@ -185,7 +185,7 @@ change all pixels to ivory or darkblue: .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 +Thus, changing all fonts simply requires only a single line in the default resource file: .LP .Ds 5 @@ -384,7 +384,7 @@ 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 +The \fIresource_offset\fP field is the offset in bytes of the field within the widget. You should use the .PN XtOffsetOf @@ -398,10 +398,10 @@ 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 +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, +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. @@ -415,14 +415,14 @@ 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 +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 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 . @@ -458,7 +458,7 @@ Specifies the resource value descriptor to return. .eM The .PN XtResourceDefaultProc -procedure should fill in the \fIvalue->addr\fP field with a pointer +procedure should fill in the \fIvalue->addr\fP field with a pointer to the resource value in its correct representation type. .sp .LP @@ -492,7 +492,7 @@ 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 +returns a merged resource list that includes the resources for all superclasses. The list returned by .PN XtGetResourceList @@ -574,9 +574,9 @@ static XtResource resources[] = { .De .LP The complete resource name for a field of a widget instance is the -concatenation of the application shell name (from +concatenation of the application shell name (from .PN XtAppCreateShell ), -the instance names of all the widget's parents up to the +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. @@ -584,7 +584,7 @@ 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 +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. @@ -660,7 +660,7 @@ Superclass-to-Subclass Chaining of Resource Lists .IN "Inheritance" .IN "Superclass Chaining" .IN "Chaining" -The +The .PN XtCreateWidget function gets resources as a superclass-to-subclass chained operation. That is, the resources specified in the @@ -676,7 +676,7 @@ 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 +Core class contains a resource entry for \fIbackground_pixel\fP. Consequently, the implementation of Label need not also have a resource entry @@ -686,8 +686,8 @@ 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 +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. @@ -899,7 +899,7 @@ If \fIargs\fP is NULL, 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 members of a structure and pass the address of the structure as the \fIbase\fP argument. .LP .PN XtGetApplicationResources @@ -981,14 +981,14 @@ Predefined Resource Converters \*(SN Predefined Resource Converters .XE .LP -The \*(xI define all the representations used in the +The \*(xI define all the representations used in the Object, RectObj, -Core, -Composite, -Constraint, -and -Shell +Core, +Composite, +Constraint, +and +Shell widget classes. The \*(xI register the following resource converters that accept input values of representation type @@ -1136,7 +1136,7 @@ and .PN XtDefaultBackground . .IN "XtDefaultBackground" "" "@DEF@" .IN "XtDefaultForeground" "" "@DEF@" -They evaluate to the black and white pixel values of the widget's screen, +They evaluate to the black and white pixel values of the widget's screen, respectively. .IN "Resources" "reverseVideo" If the application resource reverseVideo is @@ -1225,8 +1225,8 @@ as defined in \fI\*(xL\fP: .PN CenterGravity , .PN EastGravity , .PN SouthWestGravity , -.PN SouthGravity , -.PN SouthEastGravity , +.PN SouthGravity , +.PN SouthEastGravity , and .PN StaticGravity . Alphabetic case is not significant in the conversion. @@ -1243,7 +1243,7 @@ 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 +The String-to-RestartStyle conversion accepts the values .PN RestartIfRunning , .PN RestartAnyway , .PN RestartImmediately , @@ -1422,7 +1422,7 @@ 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. +includes the NULL-terminating byte. .LP A resource converter procedure pointer is of type .PN XtTypeConverter . @@ -1592,7 +1592,7 @@ static Boolean CvtStringToPixel(dpy, args, num_args, fromVal, toVal, converter_d } - status = XAllocNamedColor(DisplayOfScreen(screen), colormap, (char*)fromVal->addr, + status = XAllocNamedColor(DisplayOfScreen(screen), colormap, (char*)fromVal->addr, &screenColor, &exactColor); if (status == 0) { @@ -1779,7 +1779,7 @@ upon the same source value and conversion arguments. .LP .PN XtCacheByDisplay .IN "XtCacheByDisplay" "" "@DEF@" -.IP +.IP Specifies that the results of a previous conversion should be used as for .PN XtCacheAll @@ -1807,7 +1807,7 @@ converted value will be removed from the conversion cache. .LP To register a type converter for all application contexts in a -process, use +process, use .PN XtSetTypeConverter , and to register a type converter in a single application context, use .PN XtAppSetTypeConverter . @@ -2021,7 +2021,7 @@ 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 +The following example illustrates how to register the CvtStringToPixel routine given earlier: .LP .Ds @@ -2181,7 +2181,7 @@ 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. +enters the result in the cache. .PN XtCallConverter then returns what the converter returned. .LP @@ -2495,11 +2495,11 @@ 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, +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, +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 . @@ -2730,13 +2730,13 @@ Specifies the number of entries in the argument list. .eM The .PN XtSetValues -function starts with the resources specified for the +function starts with the resources specified for the Object class fields and proceeds down the subclass chain to the object. At each stage, it replaces the \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 +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, @@ -2793,7 +2793,7 @@ which determines what should be done. then repeats this process, deciding once more whether the geometry manager should be called. .LP -Finally, if any of the set_values procedures returned +Finally, if any of the set_values procedures returned .PN True , and the widget is realized, .PN XtSetValues @@ -2937,7 +2937,7 @@ never necessary to examine the contents of \fIargs\fP. 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 +the set_values procedure to return .PN True ; the X server will eventually generate an .PN Expose @@ -2946,7 +2946,7 @@ After calling all the set_values procedures, .PN XtSetValues forces a redisplay by calling .PN XClearArea -if any of the set_values procedures returned +if any of the set_values procedures returned .PN True . Therefore, a set_values procedure should not try to do its own redisplaying. .LP @@ -3007,8 +3007,8 @@ manager with .LP .eM Most classes inherit the set_values_almost procedure from their superclass by -specifying -.PN XtInheritSetValuesAlmost +specifying +.PN XtInheritSetValuesAlmost in the class initialization. The set_values_almost procedure in @@ -3035,7 +3035,7 @@ 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 +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. @@ -3128,7 +3128,7 @@ a widget instance using varargs lists, use .LP .IN "XtVaSetSubvalues" "" "@DEF@" .sM -.FD 0 +.FD 0 void XtVaSetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, ...) .br XtPointer \fIbase\fP; @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -44,7 +44,7 @@ .ce 3 \s+1\fBChapter 10\fP\s-1 -\s+1\fBTranslation Management\s-1 +\s+1\fBTranslation Management\s-1 .sp 2 .nr H1 10 .nr H2 0 @@ -53,7 +53,7 @@ .nr H5 0 .LP .XS -Chapter 10 \(em Translation Management +Chapter 10 \(em Translation Management .XE Except under unusual circumstances, widgets do not hardwire the mapping of user events into widget behavior @@ -63,7 +63,7 @@ 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 +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: @@ -75,7 +75,7 @@ to the corresponding procedure implemented by the widget class. A translation table, which is in the widget class structure, specifies the mapping of event sequences to procedure name strings. .LP -You can override the translation table in the class structure +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 @@ -231,7 +231,7 @@ Specifies the action table to register. Specifies the number of entries in this action table. .LP .eM -If more than one action is registered with the same name, +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. @@ -452,10 +452,10 @@ Event Sequences \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: +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 @@ -523,7 +523,7 @@ 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. +multi-click time in order for the translation actions to be taken. .sp .LP To read the multi-click time, use @@ -706,13 +706,13 @@ as the value. .sp .LP To make it possible for users to easily modify translation tables in their -resource files, +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. +existing translation table in the widget. To specify this, -a pound sign (#) is given as the first character of the table +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. @@ -767,7 +767,7 @@ 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 +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 @@ -809,7 +809,7 @@ Specifies the source widget that supplied the accelerators. Specifies the string representation of the accelerators for this widget. .LP .eM -Accelerators can be specified in resource files, +Accelerators can be specified in resource files, and the string representation is the same as for a translation table. However, the interpretation of the @@ -875,11 +875,11 @@ The 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, +If the source \fIdisplay_accelerator\fP field is non-NULL, .PN XtInstallAccelerators -calls it with the source widget and a string representation +calls it with the source widget and a string representation of the accelerator table, -which indicates that its accelerators have been installed +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. @@ -907,7 +907,7 @@ from which the accelerators are to come. \*(cI .eM The .PN XtInstallAllAccelerators -function recursively descends the widget tree rooted at \fIsource\fP +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 @@ -1040,14 +1040,14 @@ Specifies the procedure to perform key translations. The .PN XtSetKeyTranslator function sets the specified procedure as the current key translator. -The default translator is +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 +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 @@ -1078,7 +1078,7 @@ 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 +Returns a mask that indicates the modifiers actually used to generate the KeySym. .IP \fIkeysym_return\fP 1.1i Returns the resulting KeySym. @@ -1086,7 +1086,7 @@ Returns the resulting KeySym. .eM The .PN XtTranslateKeycode -function passes the specified arguments +function passes the specified arguments directly to the currently registered KeyCode-to-KeySym translator. .sp .LP @@ -1120,7 +1120,7 @@ Specifies a location into which to store the uppercase equivalent for the KeySym. .LP .eM -If there is no case distinction, +If there is no case distinction, this procedure should store the KeySym into both return values. .sp .LP @@ -1143,8 +1143,8 @@ void XtRegisterCaseConverter(\fIdisplay\fP, \fIproc\fP, \fIstart\fP, \fIstop\fP) .IP \fIdisplay\fP 1i Specifies the display from which the key events are to come. .IP \fIproc\fP 1i -Specifies the -.PN XtCaseProc +Specifies the +.PN XtCaseProc to do the conversions. .IP \fIstart\fP 1i Specifies the first KeySym for which this converter is valid. @@ -1155,10 +1155,10 @@ Specifies the last KeySym for which this converter is valid. The .PN XtRegisterCaseConverter registers the specified case converter. -The \fIstart\fP and \fIstop\fP arguments provide the inclusive range of KeySyms +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; +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. @@ -1197,7 +1197,7 @@ The .PN XtConvertCase function calls the appropriate converter and returns the results. A user-supplied -.PN XtKeyProc +.PN XtKeyProc may need to use this function. .NH 2 @@ -1359,7 +1359,7 @@ Specifies the action procedure to search for in translation tables. .IP \fIkeyboard_mode\fP 1i Specify arguments to .PN XtGrabButton -or +or .PN XtGrabKey . .LP .eM @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -176,7 +176,7 @@ Managing Memory Usage .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 +These functions are completely compatible with their standard C language runtime counterparts .PN malloc , .PN calloc , @@ -222,7 +222,7 @@ Specifies the number of bytes desired. .eM The .PN XtMalloc -function returns a pointer to a block of storage of at least +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 @@ -250,7 +250,7 @@ Specifies the size of each array element in bytes. .eM The .PN XtCalloc -function allocates space for the specified number of array elements +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 @@ -389,7 +389,7 @@ is a convenience macro that calls .PN XtMalloc with the following arguments specified: .LP -.Ds +.Ds .TA .5i .ta .5i (strcpy(XtMalloc((unsigned)strlen(str) + 1), str)) @@ -515,7 +515,7 @@ The .PN XtGetGC function returns a shareable, read-only GC. The parameters to this function are the same as those for -.PN XCreateGC +.PN XCreateGC except that an Object is passed instead of a Display. .PN XtGetGC is equivalent to @@ -562,7 +562,7 @@ Managing Selections \*(SN Managing Selections .XE .LP -Arbitrary widgets in multiple applications can communicate +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 @@ -582,7 +582,7 @@ 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 +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. @@ -628,9 +628,9 @@ Specifies the application context. The .PN XtAppGetSelectionTimeout function returns the current selection timeout value in milliseconds. -The selection timeout is the time within which the two communicating +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 +The initial timeout value is set by the selectionTimeout .IN "selectionTimeout" application resource as retrieved by @@ -693,26 +693,26 @@ Specifies the widget that currently owns this selection. Specifies the atom naming the selection requested (for example, .PN XA_PRIMARY -or +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 +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 +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 +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 +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, +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. @@ -720,15 +720,15 @@ when it is done with it. 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 +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 +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 +It returns +.PN True if the owner successfully converted the selection to the target type or .PN False otherwise. @@ -738,7 +738,7 @@ the values of the return arguments are undefined. Each .PN XtConvertSelectionProc should respond to target value -.PN TARGETS +.PN TARGETS by returning a value containing the list of the targets into which it is prepared to convert the selection. @@ -826,7 +826,7 @@ Specifies the atom naming the selection. .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 +Note that this procedure does not ask the widget to relinquish the selection ownership; it is merely informative. .sp .LP @@ -911,13 +911,13 @@ 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 +.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 +The requesting client owns this storage and is responsible for freeing it by calling .PN XtFree when it is done with it. @@ -981,20 +981,20 @@ when it is called. 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 +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 +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 +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. @@ -1040,7 +1040,7 @@ that are passed to the callback procedure when it is called for that target. 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 +the value .PN CurrentTime is not acceptable. .LP @@ -1048,7 +1048,7 @@ is not acceptable. The .PN XtGetSelectionValues function is similar to multiple calls to -.PN XtGetSelectionValue +.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 @@ -1094,17 +1094,17 @@ 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 +.PN CurrentTime is not acceptable. .IP \fIconvert_proc\fP 1i -Specifies the procedure to be called whenever a client requests the +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 +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 +Specifies the procedure called after the requestor has received the selection value, or NULL if the owner is not interested in being called back. @@ -1114,17 +1114,17 @@ 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 +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 +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 +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 +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 @@ -1142,7 +1142,7 @@ 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 +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 @@ -1173,17 +1173,17 @@ 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 +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 +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 +However, its done procedure is called if a conversion that started before the call to .PN XtDisownSelection finishes after the call to @@ -1208,12 +1208,12 @@ 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. +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. +requestor, which is asking for the first segment. .NH 4 Incremental Transfer Procedures @@ -1708,16 +1708,16 @@ 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 +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 +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 +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 @@ -1736,10 +1736,10 @@ and .PN XtGetSelectionValueIncremental with corresponding individual calls to .PN XtSetSelectionParameters , -and enclose these all within +and enclose these all within .PN XtCreateSelectionRequest and -.PN XtSendSelectionRequest. +.PN XtSendSelectionRequest. .PN XtGetSelectionValues and .PN XtGetSelectionValuesIncremental @@ -1747,7 +1747,7 @@ 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 +the selection owner calls .PN XtGetSelectionParameters . .LP .IN "XtGetSelectionParameters" "" "@DEF@" @@ -1796,7 +1796,7 @@ in the elements of \fIvalue\fP is stored. .PN XtGetSelectionParameters may be called only from within an .PN XtConvertSelectionProc -or from within the first call to an +or from within the first call to an .PN XtConvertSelectionIncrProc with a new request_id. .LP @@ -1811,7 +1811,7 @@ 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 +a single request using a \s-1MULTIPLE\s+1 target, use .PN XtCreateSelectionRequest and .PN XtSendSelectionRequest . @@ -1831,18 +1831,18 @@ Specifies the widget making the request. \*(cI Specifies the particular selection desired. .LP .eM -When +When .PN XtCreateSelectionRequest -is called, subsequent calls to +is called, subsequent calls to .PN XtGetSelectionValue , .PN XtGetSelectionValueIncremental , .PN XtGetSelectionValues , and .PN XtGetSelectionValuesIncremental , -with the requestor and selection as specified to +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 +multiple targets. The request is made by calling .PN XtSendSelectionRequest . .LP .IN "XtSendSelectionRequest" "" "@DEF@" @@ -1862,15 +1862,15 @@ Specifies the widget making the request. \*(cI Specifies the particular selection desired. .IP \fItime\fP 1i Specifies the timestamp that indicates when the selection request was -initiated. The value +initiated. The value .PN CurrentTime is not acceptable. .LP .eM -When +When .PN XtSendSelectionRequest is called with a value of \fIrequestor\fP and \fIselection\fP matching -a previous call to +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. @@ -1958,7 +1958,7 @@ Specifies the widget making a selection request. .eM .PN XtReservePropertyAtom returns an atom that may be used as a property name during selection -requests involving the specified widget. +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 @@ -2157,7 +2157,7 @@ Return the root-relative x and y coordinates. While .PN XtTranslateCoords is similar to the Xlib -.PN XTranslateCoordinates +.PN XTranslateCoordinates function, it does not generate a server request because all the required information already is in the widget's data structures. @@ -2206,7 +2206,7 @@ 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: +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 @@ -2253,7 +2253,7 @@ 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 +For a complete listing of all errors and warnings that can be generated by the \*(xI, see Appendix D. .sp .LP @@ -2279,10 +2279,10 @@ String*, Cardinal*); Cardinal *\fInum_params\fP; .FN .IP \fIname\fP 1i -Specifies the name to be concatenated with the specified type to form +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 +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. @@ -2294,12 +2294,12 @@ Specifies a pointer to a list of parameters to be substituted in the message. Specifies the number of entries in \fIparams\fP. .LP .eM -The specified name can be a general kind of error, -like ``invalidParameters'' or ``invalidWindow'', +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 +Standard +.PN printf notation is used to substitute the parameters into the message. .sp .LP @@ -2330,7 +2330,7 @@ Specifies the application context. .br .ns .IP \fItype\fP 1i -Specify the name and type concatenated to form the resource name +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. @@ -2765,8 +2765,8 @@ Specifies a potential filename. .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 True +if this string specifies a file that is appropriate for the intended use and .PN False otherwise. .sp @@ -2888,7 +2888,7 @@ are determined from the value of the language string retrieved by for the specified display. To set the language for all applications specify ``*xnlLanguage: \fIlang\fP'' in the -resource database. +resource database. .IN "xnlLanguage" The format and content of the language string are implementation-defined. One suggested syntax is to compose @@ -3037,11 +3037,11 @@ Specifies the desired display. 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. +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: @@ -3126,7 +3126,7 @@ The XtNcreateHook callback list is called from: .PN XtAppCreateShell , and their corresponding varargs versions. .LP -The \fIcall_data\fP parameter in a createHook callback may be +The \fIcall_data\fP parameter in a createHook callback may be cast to type .PN XtCreateHookData . .LP @@ -3147,7 +3147,7 @@ typedef struct { 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 +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: @@ -3165,7 +3165,7 @@ The XtNchangeHook callback list is called from: .IP .PN XtAddCallback , .PN XtRemoveCallback , -.PN XtAddCallbacks, +.PN XtAddCallbacks, .PN XtRemoveCallbacks , .PN XtRemoveAllCallbacks .IP @@ -3213,7 +3213,7 @@ or \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 +\fIevent_data\fP may be cast to type .PN XtChangeHookSetValuesData . .IN "XtChangeHookSetValuesData" "" "@DEF@" .LP @@ -3232,7 +3232,7 @@ typedef struct { .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 +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 @@ -3242,7 +3242,7 @@ or \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 +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 @@ -3261,20 +3261,20 @@ 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 +.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 +.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 +.PN XtHrealizeWidget and \fIwidget\fP is the widget being realized. The callbacks are called after the widget has been realized. .LP @@ -3290,7 +3290,7 @@ When the changeHook callbacks are called as a result of a call to \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 +\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 @@ -3299,7 +3299,7 @@ When the changeHook callbacks are called as a result of a call to 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 +\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 @@ -3309,7 +3309,7 @@ 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 +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 @@ -3317,8 +3317,8 @@ When the changeHook callbacks are called as a result of a call to 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 +\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 @@ -3334,7 +3334,7 @@ When the changeHook callbacks are called as a result of a call to 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 +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 @@ -3342,7 +3342,7 @@ When the changeHook callbacks are called as a result of a call to 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 +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 @@ -3350,33 +3350,33 @@ When the changeHook callbacks are called as a result of a call to 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 +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 +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 +\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 +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 @@ -3397,8 +3397,8 @@ 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 +\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 @@ -3407,7 +3407,7 @@ When the changeHook callbacks are called as a result of a call to the \fItype\fP is set to .PN XtHpopupSpringLoaded and \fIwidget\fP is the widget being popped up. -The callbacks are called +The callbacks are called before returning from \fBXtPopupSpringLoaded\fP. .LP When the changeHook callbacks are called as a result of a call to @@ -3415,7 +3415,7 @@ When the changeHook callbacks are called as a result of a call to the \fItype\fP is set to .PN XtHpopdown and \fIwidget\fP is the widget being popped down. -The callbacks are called +The callbacks are called before returning from \fBXtPopdown\fP. .LP A widget set that exports interfaces that change application state @@ -3447,7 +3447,7 @@ typedef struct { String type; Widget widget; XtGeometryMask changeMask; - XWindowChanges changes; + XWindowChanges changes; } XtConfigureHookDataRec, *XtConfigureHookData; .De .eM @@ -3456,11 +3456,11 @@ typedef struct { .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 +\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 +The XtNgeometryHook callback list is called from .PN XtMakeGeometryRequest and .PN XtMakeResizeRequest @@ -3486,16 +3486,16 @@ typedef struct { .eM .sp .LP -When the geometryHook callbacks are called prior to geometry negotiation, +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 +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, +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. @@ -3560,7 +3560,7 @@ 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 +list of open displays that belong to an application context. To free the list of displays, use .PN XtFree . .bp @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -171,7 +171,7 @@ typedef struct _ObjectClassPart { .eM The extension record defined for .PN ObjectClassPart -with a \fIrecord_type\fP equal to +with a \fIrecord_type\fP equal to .PN \s-1NULLQUARK\s+1 is .PN ObjectClassExtensionRec . @@ -419,7 +419,7 @@ if class of argument is not a subclass of Core) .IP .PN XtWidgetToApplicationContext -.IP +.IP .PN XtDestroyWidget .IP .PN XtParent , @@ -495,7 +495,7 @@ will otherwise generate an error message on an attempt to create a nonwidget child. .LP Of the classes defined by the \*(xI, -ApplicationShell +ApplicationShell and SessionShell accept nonwidget children, and the class of any nonwidget child @@ -807,7 +807,7 @@ discussion, \fIrectobj\fP refers only to objects whose class is RectObj or a subclass of RectObj, but not Core or a subclass of -Core. +Core. .LP Composite widget classes that wish to accept rectobj children must set @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -108,7 +108,7 @@ Release 3 to Release 4 Compatibility At the data structure level, Release 4 retains binary compatibility with Release 3 (the first X Consortium standard release) for all data structures except -.PN WMShellPart, +.PN WMShellPart, .PN TopLevelShellPart , and .PN TransientShellPart . @@ -217,7 +217,7 @@ and one field to 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. +the end of the respective data structures. .LP To provide more convenience for TransientShells, a field was added to the previously empty @@ -517,9 +517,9 @@ Release 5 to Release 6 Compatibility .XE .LP At the data structure level, Release 6 retains binary compatibility -with Release 5 for all data structures except +with Release 5 for all data structures except .PN WMShellPart . -Three resources were added to the specification. +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. @@ -531,19 +531,19 @@ Widget Internals .XE .LP Two new widget methods for instance allocation and deallocation were added -to the Object class. These new methods +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 +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 +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, +record on a linked list, .PN XtGetClassExtension , has been added. .LP @@ -578,7 +578,7 @@ General Application Development is a new convenience procedure to initialize the toolkit, create an application context, open an X display connection, and create the root of the widget instance tree. It is identical to the interface -it replaces, +it replaces, .PN XtAppInitialize , in all respects except that it takes an additional argument specifying the widget class of the root shell to create. @@ -607,16 +607,16 @@ in the addition of three fields to the specification of 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, +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 +In order to preserve compatibility with existing subclasses of .PN ApplicationShell , -the -.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 @@ -625,25 +625,25 @@ 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 +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 > +widgets in +.Pn < X11/Shell.h > are now listed in Appendix E. The addition of a new symbol -for the +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 +string in .PN WMShell has not changed. -The resource representation type of the XtNwinGravity resource of the +The resource representation type of the XtNwinGravity resource of the .PN WMShell -was changed to XtRGravity in order to register a type +was changed to XtRGravity in order to register a type converter so that window gravity resource values could be specified by name. .NH 3 @@ -669,7 +669,7 @@ The new event handler registration interfaces are and .PN XtRemoveEventTypeHandler . Since the mechanism to indicate selection of extension events is specific -to the extension being used, the \*(xI introduces +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 @@ -677,7 +677,7 @@ 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 +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 @@ -687,9 +687,9 @@ 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, +with a widget's window, .PN XtRegisterDrawable -and +and .PN XtUnregisterDrawable have been added to the library. A related update was made to the description of @@ -697,21 +697,21 @@ the description of .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 +Threaded toolkit applications are supported by the new interfaces .PN XtToolkitThreadInitialize , .PN XtAppLock , .PN XtAppUnlock , .PN XtAppSetExitFlag , -and +and .PN XtAppGetExitFlag . -Widget writers may also use +Widget writers may also use .PN XtProcessLock -and +and .PN XtProcessUnlock . .LP Safe handling of POSIX signals and other asynchronous notifications -is now provided by use of +is now provided by use of .PN XtAppAddSignal , .PN XtNoticeSignal , and @@ -720,7 +720,7 @@ and The application can receive notification of an impending block in the \*(xI event manager by registering interest through .PN XtAppAddBlockHook -and +and .PN XtRemoveBlockHook . .LP .PN XtLastEventProcessed @@ -753,7 +753,7 @@ 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 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. @@ -771,17 +771,17 @@ 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, +request for multiple targets, .PN XtCreateSelectionRequest , .PN XtCancelSelectionRequest , -and -.PN XtSendSelectionRequest +and +.PN XtSendSelectionRequest are used to envelop the assembly of the request. -When the parameters themselves are the names of properties, +When the parameters themselves are the names of properties, the \*(xI provides support for the economical use of property atom names; -see +see .PN XtReservePropertyAtom -and +and .PN XtReleasePropertyAtom . .NH 3 @@ -799,7 +799,7 @@ 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 +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 index 353467f..a31f06b 100644 --- a/specs/Xtk.intr.front +++ b/specs/Xtk.intr.front @@ -105,8 +105,8 @@ Acknowledgments .sp 2 .na .LP -The design of the X11 Intrinsics was done primarily -by Joel McCormack of Digital WSL. +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: @@ -122,8 +122,8 @@ 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 +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: @@ -136,7 +136,7 @@ Charles Haynes (Digital WSL) Frank Hall (HP) .De .LP -The design and implementation of the X10 toolkit's sample widgets were +The design and implementation of the X10 toolkit's sample widgets were by the above, as well as by: .LP .Ds @@ -148,9 +148,9 @@ Kathleen Langone (Digital UEG) 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 +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 +and to John Ousterhout of Berkeley for extensively reviewing early drafts of it. .LP Finally, a special thanks to Mike Chow, @@ -234,7 +234,7 @@ July 1991 .LP The Release 6 Intrinsics is a result of the collaborative efforts of participants in the X Consortium's \fBintrinsics\fP -working group. +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. @@ -280,20 +280,20 @@ About This Manual .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 +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 +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 +(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 +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 @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -55,7 +55,7 @@ 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. +for convenience only. .LP The format of a resource specification is .TS @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -109,27 +109,27 @@ Modifier Names .LP The modifier field is used to specify standard X keyboard and button modifier mask bits. -Modifiers are legal on event types +Modifiers are legal on event types .PN KeyPress , -.PN KeyRelease , +.PN KeyRelease , .PN ButtonPress , .PN ButtonRelease , .PN MotionNotify , .PN EnterNotify , .PN LeaveNotify , and their abbreviations. -An error is generated when a translation table +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 +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 +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. @@ -142,12 +142,12 @@ If ``None'' is specified, it means no modifiers can be asserted. If a colon (:) is specified at the beginning of the modifier list, it directs the \*(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, +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'', +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 @@ -162,9 +162,9 @@ 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, +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 (^), +character, in particular a double quote ("), a circumflex (^), a dollar sign ($), and another backslash (\\). Briefly: .LP @@ -216,13 +216,13 @@ _ .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 +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, +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; +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 @@ -232,19 +232,19 @@ modifier bit whose corresponding KeyCode contains the specified KeySym name. A modifier_list/KeySym combination in a translation matches a modifiers/KeyCode combination in an event in the following ways: .IP 1. 5 -If a colon (:) is used, the \*(xI call the display's -.PN XtKeyProc +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 +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 +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 +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 @@ -517,14 +517,14 @@ or the numeric values may be specified. If no detail field is specified, then any value in the event detail is accepted as a match. .LP -A KeySym can be specified as any of the standard KeySym names, -a hexadecimal number prefixed with ``0x'' or ``0X'', +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 +Standard KeySym names are as defined in .Pn < X11/keysymdef.h > with the ``XK_'' prefix removed. .LP @@ -675,7 +675,7 @@ For double-click on Button1 Up with Shift, use this specification: Shift<Btn1Up>(2) : and() .DE .IP -This is equivalent to the following line with appropriate timers set +This is equivalent to the following line with appropriate timers set between events: .IP .Ds @@ -747,7 +747,7 @@ within the multi-click time interval. For example: Shift <Btn1Up>(2+) : and() .De .IP \(bu 5 -To indicate +To indicate .PN EnterNotify with any modifiers, use this specification: .IP @@ -755,7 +755,7 @@ with any modifiers, use this specification: <Enter> : gimble() .De .IP \(bu 5 -To indicate +To indicate .PN EnterNotify with no modifiers, use this specification: .IP @@ -763,8 +763,8 @@ with no modifiers, use this specification: None <Enter> : in() .De .IP \(bu 5 -To indicate -.PN EnterNotify +To indicate +.PN EnterNotify with Button1 Down and Button2 Up and ``don't care'' about the other modifiers, use this specification: .IP @@ -772,7 +772,7 @@ the other modifiers, use this specification: Button1 ~Button2 <Enter> : the() .De .IP \(bu 5 -To indicate +To indicate .PN EnterNotify with Button1 down and Button2 down exclusively, use this specification: .IP @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -105,9 +105,9 @@ themselves. .sp .LP .PN XtAppInitialize -and -.PN XtVaAppInitialize -have been replaced by +and +.PN XtVaAppInitialize +have been replaced by .PN XtOpenApplication and .PN XtVaOpenApplication . @@ -288,7 +288,7 @@ This parameter is ignored; therefore, you can specify NULL. 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 +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. @@ -342,10 +342,10 @@ void XtNextEvent(\fIevent_return\fP) 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 +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 . @@ -364,7 +364,7 @@ Specifies the type of input to process. .LP .eM .PN XtProcessEvent -processes one X event, timeout, or alternate input source +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 . @@ -382,19 +382,19 @@ Boolean XtPeekEvent(\fIevent_return\fP) Returns the event information to the specified event structure. .LP .eM -If there is an event in the queue for the default application context, +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, +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. +fills in the event and returns a nonzero value. Otherwise, the input is for an alternate input source, and .PN XtPeekEvent -returns zero. +returns zero. This routine has been replaced by .PN XtAppPeekEvent . .PN XtInitialize @@ -408,10 +408,10 @@ Boolean XtPending() .LP .eM .PN XtPending -returns a nonzero value if there are +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, +If there are no events pending, it flushes the output buffer and returns a zero value. It has been replaced by .PN XtAppPending . @@ -433,7 +433,7 @@ XtInputId XtAddInput(\fIsource\fP, \fIcondition\fP, \fIproc\fP, \ XtPointer \fIclient_data\fP; .FN .IP \fIsource\fP 1i -Specifies the source file descriptor on a POSIX-based system +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 @@ -444,16 +444,16 @@ Specifies the procedure called when input is available. Specifies the parameter to be passed to \fIproc\fP when input is available. .LP .eM -The +The .PN XtAddInput -function registers in the default application context a new -source of events, +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 +(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, +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 . @@ -479,14 +479,14 @@ Specifies the procedure to be called when time expires. Specifies the parameter to be passed to \fIproc\fP when it is called. .LP .eM -The +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 +This routine has been replaced by .PN XtAppAddTimeOut . .PN XtInitialize must be called before using this routine. @@ -530,8 +530,8 @@ Widget XtCreateApplicationShell(\fIname\fP, \fIwidget_class\fP, \fIargs\fP, \ 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 +This will usually be +.PN topLevelShellWidgetClass or a subclass thereof. .IP \fIargs\fP 1i Specifies the argument list to override any other resource specifications. @@ -593,13 +593,13 @@ 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 +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 +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 @@ -782,7 +782,7 @@ Returns the converted value. .eM The .PN XtConvert -function looks up the type converter registered to convert \fIfrom_type\fP +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 @@ -862,7 +862,7 @@ Specifies the action table to register. Specifies the number of entries in \fIactions\fP. .LP .eM -If more than one action is registered with the same name, +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. @@ -908,7 +908,7 @@ unsigned long XtGetSelectionTimeout() .FN .LP .eM -The selection timeout is the time within which the two communicating +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. @@ -962,7 +962,7 @@ void XtGetErrorDatabaseText(\fIname\fP, \fItype\fP, \fIclass\fP, \ .br .ns .IP \fItype\fP 1i -Specify the name and type that are concatenated to form the resource name +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. @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -57,7 +57,7 @@ All \*(xI errors and warnings have class The following two tables summarize the common errors and warnings that can be generated by the \*(xI. Additional implementation-dependent messages are permitted. -.SH +.SH Error Messages .LP .ps 9 @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -52,7 +52,7 @@ \fBAppendix E \(em Defined Strings\fP .XE .LP -The +The .PN StringDefs.h header file contains definitions for the following resource name, class, and representation type symbolic constants. @@ -441,7 +441,7 @@ _ .TE .sp 6p .LP -The +The .PN Shell.h header file contains definitions for the following resource name, class, and representation type symbolic constants. @@ -1,7 +1,7 @@ .\" $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 @@ -9,10 +9,10 @@ .\" 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. @@ -20,15 +20,15 @@ .\" 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 @@ -53,31 +53,31 @@ .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 +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 +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 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, +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 +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 +initialized, two atoms are interned with the strings \fICustom Init\fP and -\fICustom Data\fP. Both +\fICustom Data\fP. Both .PN _XtCreatePopupShell and .PN _XtAppCreateShell @@ -109,7 +109,7 @@ The resource value When setting the application's resource, the event handler calls functions to walk the application's widget tree, determining which widgets are affected by the resource string, and then applying the value -with +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. |