From 5f8448ef6b85a9ff72c5af4cec99183c8bb60dc6 Mon Sep 17 00:00:00 2001 From: marha Date: Tue, 10 Apr 2012 14:58:33 +0200 Subject: Updated following packages: bigreqsproto-1.1.2 fontsproto-2.1.2 recordproto-1.14.2 scrnsaverproto-1.2.2 xcmiscproto-1.2.2 libXt-1.1.3 xhost-1.0.5 kbproto-1.0.6 libXrender-0.9.7 libxkbfile-1.0.8 freetype-2.4.9 libXaw-1.0.10 libXpm-3.5.10 xproto-7.0.23 --- libXt/specs/CH13.xml | 770 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 770 insertions(+) create mode 100644 libXt/specs/CH13.xml (limited to 'libXt/specs/CH13.xml') diff --git a/libXt/specs/CH13.xml b/libXt/specs/CH13.xml new file mode 100644 index 000000000..0216b3434 --- /dev/null +++ b/libXt/specs/CH13.xml @@ -0,0 +1,770 @@ + +Evolution of the Intrinsics + + +The interfaces described by this specification have undergone several +sets of revisions in the course of adoption as an X Consortium +standard specification. Having now been adopted by the Consortium as +a standard part of the X Window System, it is expected that this and +future revisions will retain +backward compatibility in the sense that fully conforming +implementations of these specifications may be produced that provide +source compatibility with widgets and applications written to +previous Consortium standard revisions. + + + +The Intrinsics do not place any special requirement on widget +programmers to retain source or binary compatibility for their widgets +as they evolve, but several conventions have been established to +assist those developers who want to provide such compatibility. + + + +In particular, widget programmers may wish to conform to the convention +described in when defining class extension records. + + +Determining Specification Revision Level + +Widget and application developers who wish to maintain a common source +pool that will build properly with implementations of the Intrinsics +at different revision levels of these specifications but that take +advantage of newer features added in later revisions may use the +symbolic macro +XtSpecificationRelease. + + +#define XtSpecificationRelease 6 + + +As the symbol +XtSpecificationRelease +was new to Release 4, widgets and +applications desiring to build against earlier implementations should +test for the presence of this symbol and assume only Release 3 +interfaces if the definition is not present. + + + + +Release 3 to Release 4 Compatibility + +At the data structure level, Release 4 retains binary compatibility +with Release 3 (the first X Consortium standard release) for all data +structures except +WMShellPart, +TopLevelShellPart, +and +TransientShellPart. +Release 4 changed the argument type to most procedures that now take +arguments of type +XtPointer +and structure members that are now of type +XtPointer +in order to avoid potential ANSI C conformance problems. It is +expected that most implementations will be binary compatible with the +previous definition. + + + +Two fields in +CoreClassPart +were changed from +Boolean +to +XtEnum +to allow implementations additional freedom in specifying the +representations of each. This change should require no source +modification. + + +Additional Arguments + +Arguments were added to the procedure definitions for +, +, +and + +to provide more information and to +allow event handlers to abort further dispatching of the current event +(caution is advised!). The added arguments to + +and + +make the initialize_hook and set_values_hook methods +obsolete, but the hooks have been retained for those widgets that used +them in Release 3. + + + + +set_values_almost Procedures + +The use of the arguments by a set_values_almost procedure was poorly +described in Release 3 and was inconsistent with other conventions. + + + +The current specification for the manner in which a set_values_almost +procedure returns information to the Intrinsics is not compatible with +the Release 3 specification, and all widget implementations should +verify that any set_values_almost procedures conform to the current +interface. + + + +No known implementation of the Intrinsics correctly implemented the +Release 3 interface, so it is expected that the impact of this +specification change is small. + + + + +Query Geometry + +A composite widget layout routine that calls + +is now expected to store the complete new geometry in the intended structure; +previously the specification said ``store the changes it intends to +make''. Only by storing the complete geometry does the child have +any way to know what other parts of the geometry may still be +flexible. Existing widgets should not be affected by this, except +to take advantage of the new information. + + + + +unrealizeCallback Callback List + +In order to provide a mechanism for widgets to be notified when they +become unrealized through a call to +, +the callback +list name ``unrealizeCallback'' has been defined by the Intrinsics. A +widget class that requires notification on unrealize may declare a +callback list resource by this name. No class is required to declare +this resource, but any class that did so in a prior revision may find +it necessary to modify the resource name if it does not wish to use the new +semantics. + + + + +Subclasses of WMShell + +The formal adoption of the Inter-Client Communication Conventions Manual. as +an X Consortium standard has meant the addition of four fields to +WMShellPart +and one field to +TopLevelShellPart. +In deference to some +widget libraries that had developed their own additional conventions +to provide binary compatibility, these five new fields were added at +the end of the respective data structures. + + + +To provide more convenience for TransientShells, a field was added +to the previously empty +TransientShellPart. +On some architectures the size of the part structure will not +have changed as a result of this. + + + +Any widget implementation whose class is a subclass of +TopLevelShell +or +TransientShell +must at minimum be +recompiled with the new data structure declarations. Because +WMShellPart +no longer contains a contiguous +XSizeHints +data structure, +a subclass that expected to do a single structure assignment of an +XSizeHints +structure to the size_hints field of +WMShellPart +must be revised, though the old fields remain at the same positions within +WMShellPart. + + + + +Resource Type Converters + +A new interface declaration for resource type converters was defined +to provide more information to converters, to support conversion +cache cleanup with resource reference counting, and to allow +additional procedures to be declared to free resources. The old +interfaces remain (in the compatibility section), and a new set of +procedures was defined that work only with the new type converter +interface. + + + +In the now obsolete old type converter interface, converters are +reminded that they must return the size of the converted value as well +as its address. The example indicated this, but the description of + +was incomplete. + + + + +KeySym Case Conversion Procedure + +The specification for the + +function type has been changed +to match the Release 3 implementation, which included necessary +additional information required by the function (a pointer to the +display connection), and corrects the argument type of the source +KeySym parameter. No known implementation of the Intrinsics +implemented the previously documented interface. + + + + +Nonwidget Objects + +Formal support for nonwidget objects is new to Release 4. A +prototype implementation was latent in at least one Release 3 +implementation of the Intrinsics, but the specification has changed +somewhat. The most significant change is the requirement for a +composite widget to declare the +CompositeClassExtension +record with the accepts_objects field set to +True +in order to permit a client to create a nonwidget child. + + + +The addition of this extension field ensures that composite widgets +written under Release 3 will not encounter unexpected errors if an +application attempts to create a nonwidget child. In Release 4 there +is no requirement that all composite widgets implement the extra +functionality required to manage windowless children, so the +accepts_objects field allows a composite widget to declare that it +is not prepared to do so. + + + + + +Release 4 to Release 5 Compatibility + +At the data structure level, Release 5 retains complete binary +compatibility with Release 4. The specification of the +ObjectPart, +RectObjPart, +CorePart, +CompositePart, +ShellPart, +WMShellPart, +TopLevelShellPart, +and +ApplicationShellPart +instance records was made less strict to permit implementations to +add internal fields to these structures. Any implementation that +chooses to do so would, of course, force a recompilation. +The Xlib specification for +XrmValue +and +XrmOptionDescRec +was updated to use a new type, +XPointer, +for the addr and value fields, respectively, to avoid +ANSI C conformance problems. The definition of +XPointer +is binary compatible with the previous implementation. + + +baseTranslations Resource + +A new pseudo-resource, XtNbaseTranslations, was defined to permit +application developers to specify translation tables in application +defaults files while still giving end users the ability to augment +or override individual event sequences. This change will affect +only those applications that wish to take advantage of the new +functionality or those widgets that may have previously defined +a resource named ``baseTranslations''. + + + +Applications wishing to take advantage of the new functionality +would change their application defaults file, e.g., from + + app.widget.translations: value +to + app.widget.baseTranslations: value + +If it is important to the application to preserve complete +compatibility of the defaults file between different versions +of the application running under Release 4 and Release 5, +the full translations can be replicated in both the ``translations'' +and the ``baseTranslations'' resource. + + + + +Resource File Search Path + +The current specification allows implementations greater flexibility +in defining the directory structure used to hold the application class +and per-user application defaults files. Previous specifications +required the substitution strings to appear in the default path in a +certain order, preventing sites from collecting all the files for +a specific application together in one directory. The Release 5 +specification allows the default path to specify the substitution +strings in any order within a single path entry. Users will need to +pay close attention to the documentation for the specific +implementation to know where to find these files and how to specify +their own +XFILESEARCHPATH +and +XUSERFILESEARCHPATH +values when overriding the system defaults. + + + + +Customization Resource + + +supports a new substitution string, %C, for specifying separate +application class resource files according to arbitrary user-specified +categories. The primary motivation for this addition was separate +monochrome and color application class defaults files. The +substitution value is obtained by querying the current resource +database for the application resource name ``customization'', class +``Customization''. Any application that previously used this +resource name and class will need to be aware of the possibly +conflicting semantics. + + + + +Per-Screen Resource Database + +To allow a user to specify separate preferences for each screen of a +display, a per-screen resource specification string has been added and +multiple resource databases are created; one for each screen. This +will affect any application that modified the (formerly unique) +resource database associated with the display subsequent to the Intrinsics +database initialization. Such applications will need to be aware +of the particular screen on which each shell widget is to be created. + + + +Although the wording of the specification changed substantially in the +description of the process by which the resource database(s) is +initialized, the net effect is the same as in prior releases with the +exception of the added per-screen resource specification and the new +customization substitution string in +. + + + + +Internationalization of Applications + +Internationalization as defined by ANSI is a technology that +allows support of an application in a single locale. In +adding support for internationalization to the Intrinsics +the restrictions of this model have been followed. +In particular, the new Intrinsics interfaces are designed not to +preclude an application from using other alternatives. +For this reason, no Intrinsics routine makes a call to establish the +locale. However, a convenience routine to establish the +locale at initialize time has been provided, in the form +of a default procedure that must be explicitly installed +if the application desires ANSI C locale behavior. + + + +As many objects in X, particularly resource databases, now inherit +the global locale when they are created, applications wishing to use +the ANSI C locale model should use the new function +XtSetLanguageProc +to do so. + + + +The internationalization additions also define event filters +as a part of the Xlib Input Method specifications. The +Intrinsics enable the use of event filters through additions to +. +Applications that may not be dispatching all events through + +should be reviewed in the context of this new input method mechanism. + + + +In order to permit internationalization of error messages, the name +and path of the error database file are now allowed to be +implementation-dependent. +No adequate standard mechanism has yet been suggested to +allow the Intrinsics to locate the database from localization information +supplied by the client. + + + +The previous specification for the syntax of the language string +specified by +xnlLanguage +has been dropped to avoid potential conflicts with other standards. +The language string syntax is now implementation-defined. +The example syntax cited is consistent with the previous +specification. + + + + +Permanently Allocated Strings + +In order to permit additional memory savings, an Xlib interface was +added to allow the resource manager to avoid copying certain string +constants. The Intrinsics specification was updated to explicitly require +the Object class_name, resource_name, resource_class, +resource_type, default_type in resource tables, Core actions +string field, and Constraint resource_name, resource_class, +resource_type, and default_type resource fields to be +permanently allocated. This explicit requirement is expected to +affect only applications that may create and destroy classes +on the fly. + + + + +Arguments to Existing Functions + +The args argument to +, +, +, +, +and + +were changed from +Cardinal* +to int* to conform to pre-existing convention and avoid otherwise +annoying typecasting in ANSI C environments. + + + + + +Release 5 to Release 6 Compatibility + +At the data structure level, Release 6 retains binary compatibility +with Release 5 for all data structures except +WMShellPart. +Three resources were added to the specification. +The known implementations had unused space in the data structure, +therefore on some architectures and implementations, +the size of the part structure will not have changed as a result of this. + + +Widget Internals + +Two new widget methods for instance allocation and deallocation were added +to the Object class. These new methods +allow widgets to be treated as C++ objects in the C++ environment +when an appropriate allocation method is specified or inherited +by the widget class. + + + +The textual descriptions of the processes of widget creation and +widget destruction have been edited to provide clarification to widget +writers. Widgets writers may have reason to rely on the specific order of +the stages of widget creation and destruction; with that motivation, +the specification now more exactly describes the process. + + + +As a convenience, an interface to locate a widget class extension +record on a linked list, +, +has been added. + + + +A new option to allow bundled changes to the managed set of a Composite +widget is introduced in the Composite class extension record. +Widgets that define a change_managed procedure that can accommodate +additions and deletions to the managed set of children in a single +invocation should set allows_change_managed_set to True in the +extension record. + + + +The wording of the process followed by + +has changed slightly to better handle changes to the managed set +during phase 2 destroy processing. + + + +A new exposure event compression flag, +XtExposeNoRegion, +was added. Many widgets specify exposure compression, but either +ignore the actual damage region passed to the core expose procedure or +use only the cumulative bounding box data available in the event. +Widgets with expose procedures that do not make use of exact +exposure region information can indicate that the Intrinsics need not +compute the region. + + + + +General Application Development + + +is a new convenience procedure to initialize the toolkit, create an +application context, open an X display connection, and create the +root of the widget instance tree. It is identical to the interface +it replaces, +, +in all respects except that it takes an additional argument specifying +the widget class of the root shell to create. +This interface is now the recommended one so that clients may easily +become session participants. +The old convenience procedures appear in the compatibility section. + + + +The toolkit initialization function + +may be called multiple times without penalty. + + + +In order to optimize changes in geometry to a set of geometry-managed +children, a new interface, +, +has been added. + + + + +Communication with Window and Session Managers + +The revision of the Inter-Client Communication Conventions Manual. as an X Consortium standard has resulted +in the addition of three fields to the specification of +WMShellPart. +These are urgency, client_leader, and window_role. + + + +The adoption of the X Session Management Protocol as an X Consortium +standard has resulted in the addition of a new shell widget, +SessionShell, +and an accompanying subclass verification interface, +XtIsSessionShell. +This widget provides support for communication between an application +and a session manager, as well as a window manager. +In order to preserve compatibility with existing subclasses of +ApplicationShell, +the +ApplicationShell +was subclassed to create the new widget class. +The session protocol requires a modal response to certain checkpointing +operations by participating applications. The +SessionShell +structures +the application's notification of and responses to messages from the session +manager by use of various callback lists and by use of the new interfaces + +and +. +There is also a new command line argument, -xtsessionID, which facilitates +the session manager in restarting applications based on the Intrinsics. + + + +The resource name and class strings defined by the Intrinsics shell +widgets in +<X11/Shell.h> +are now listed in Appendix E. The addition of a new symbol +for the +WMShell +wait_for_wm resource was made to bring the external symbol +and the string it represents into agreement. The actual resource name +string in +WMShell +has not changed. +The resource representation type of the XtNwinGravity resource of the +WMShell +was changed to XtRGravity in order to register a type +converter so that window gravity resource values could be specified by name. + + + + +Geometry Management + +A clarification to the specification was made to indicate that geometry +requests may include current values along with the requested changes. + + + + +Event Management + +In Release 6, support is provided for registering selectors +and event handlers for events generated by X protocol extensions +and for dispatching those events to the appropriate widget. +The new event handler registration interfaces are + +and +. +Since the mechanism to indicate selection of extension events is specific +to the extension being used, the Intrinsics introduces +, +which allows the application to select for the events of interest. +In order to change the dispatching algorithm to accommodate extension events +as well as core X protocol events, +the Intrinsics event dispatcher may now be replaced or enveloped +by the application with +. +The dispatcher may wish to call + +to determine the widget with the current Intrinsics keyboard focus. +A dispatcher, after determining the destination widget, may use + +to cause the event to be dispatched to the event handlers registered +by a specific widget. + + + +To permit the dispatching of events +for nonwidget drawables, such as pixmaps that are not associated +with a widget's window, + +and + +have been added to the library. A related update was made to +the description of +. + + + +The library is now thread-safe, allowing one thread at a time to +enter the library and protecting global data as necessary from concurrent use. +Threaded toolkit applications are supported by the +new interfaces +, +, +, +, +and +. +Widget writers may also use + +and +. + + + +Safe handling of POSIX signals and other asynchronous notifications +is now provided by use of +, +, +and +. + + + +The application can receive notification of an impending block +in the Intrinsics event manager by registering interest through + +and +. + + + + +returns the most recent event passed to + +for a specified display. + + + + +Resource Management + +Resource converters are registered by the Intrinsics for window gravity +and for three new resource types associated with session participation: +RestartStyle, CommandArgArray and DirectoryString. + + + +The file search path syntax has been extended to make it easier to +include the default search path, which controls resource +database construction, by using the new substitution string, %D. + + + + +Translation Management + +The default key translator now recognizes the NumLock modifier. +If NumLock is on and the second keysym is a keypad keysym +(a standard keysym named with a ``KP'' prefix or a +vendor-specific keysym in the hexadecimal range 0x11000000 to 0x1100FFFF), +then the default key translator will +use the first keysym if Shift and/or ShiftLock is on and will +use the second keysym if neither is on. Otherwise, it will +ignore NumLock and apply the normal protocol semantics. + + + + +Selections + +The targets of selection requests may be parameterized, as described +by the revised Inter-Client Communication Conventions Manual.. +When such requests are made, + +is used by the requestor to specify the target parameters and + +is used by the selection owner to retrieve the parameters. +When a parameterized target is specified in the context of a bundled +request for multiple targets, +, +, +and + +are used to envelop the assembly of the request. +When the parameters themselves are the names of properties, +the Intrinsics provides support for the economical use of property atom names; +see + +and +. + + + + +External Agent Hooks + +External agent hooks were added for the benefit of applications +that instrument other applications for purposes of accessibility, +testing, and customization. The external agent and the application +communicate by a shared protocol which is transparent to the application. +The hook callbacks permit the external agent to register interest +in groups or classes of toolkit activity and to be notified of the +type and details of the activity as it occurs. The new interfaces +related to this effort are +, +which returns the hook registration widget, and +, +which returns a list of the X displays associated with an application context. + + + + -- cgit v1.2.3