REF XTOOLKIT R.Evans Mar 1991 Revised: Adrian Howard Jul 1992 COPYRIGHT University of Sussex 1990. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< THE X TOOLKIT INTERFACE >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< This REF file discusses the overall organisation of the X toolkit interface and provides pointers to documentation of more specific points. See REF * X for a more general overview of all Poplog's X-related facilities. CONTENTS - (Use g to access required sections) 1 Introduction 2 The Poplog X Toolkit Interface 3 Naming Conventions 3.1 X Toolkit Procedures 3.2 X Toolkit Constants 3.3 Poplog Extensions To The Toolkit 3.4 Other Externally-Defined Libraries 3.5 Data Conversion Procedures 3.6 Type Specifications 3.7 Library And Documentation Filenames 3.8 Documentation Cross-references 3.9 Conventions For Other packages 4 Loading X Toolkit Routines 5 Calling X Toolkit Routines 6 Creating Argument Data Structures 7 Callbacks 8 Event Handling 9 X Toolkit Default Initialisation 10 Garbage Collector Feedback 11 Version identification 12 Further Documentation 13 Known Bugs and Problems --------------- 1 Introduction --------------- The X Toolkit is a high level 'object oriented' interface to the X facilities written in C and provided as part of the X standard. The Poplog X Toolkit interface provides support for application programmers to use the X Toolkit facilities in a convenient and interactive fashion. For full details of the X Toolkit itself, the programmer should consult the "X Toolkit Intrinsics Programming Manual" and the "X Toolkit Intrinsics Reference Manual", available from several sources. Documentation for the Poplog X Toolkit interface should be read in conjunction with this material. Note: at the present time there is no explicit support for widget class programming (the creation of new widget classes) within Poplog. --------------------------------- 2 The Poplog X Toolkit Interface --------------------------------- The Poplog X Toolkit consists of a number of distinct components: # A set of near-transparent bindings (Pop-11 procedures) for routines in the C X Toolkit library needed for applications programming. These are near-transparent in that they do almost no argument checking or processing at all (and they carry the prefix 'fast_' to emphasise this --- see 'Naming Conventions' below). Thus they offer a very faithful interface to the C Toolkit. # Facilities for the automatic management of core X Toolkit data structures. These are discussed in REF * XptDescriptor. They allow Toolkit use to take advantage of Poplog's automatic memory management facilities, particularly valuable during interactive development and large dynamic applications. # Support libraries providing argument type-checking and easy creation of argument data structures These also contribute to the convenient interactive development environment, including the provision of run-time type-checking not readily available in the C Toolkit. # Additional facilities (beyond the Toolkit's XtMainLoop) for synchronous and asynchronous event handling. These facilities allow Poplog to support one or more X applications while retaining its traditional interactive model if desired. So X applications can be run while simultaneously editing in Ved, or running other more conventional Poplog programs. # Higher level support and application packages: A range of additional support libraries and packages is provided and more will become available shortly. See REF * XT_LIBS for more information. --------------------- 3 Naming Conventions --------------------- The C X Toolkit uses a wide range of conventions for the names of the various symbols it defines. In mapping these 'name-spaces' into Pop-11, the C names have been preserved wherever possible, and the conventions extended in hopefully reasonable ways. In some cases, the danger of name clashes, or explosion of run-time symbols have meant that slight variations have been necessary. However the aim throughout has been to provide predictable names once the underlying rules are known. In this section, those underlying rules are described. 3.1 X Toolkit Procedures ------------------------- The names of procedures directly imported from the C Toolkit retain their C Toolkit names. This name refers to the most user-friendly variant of the procedure, that is, the one that does type-checking, argument coercions etc.. The form of the procedure that does no checking (and only limited coercions - see below) is the C Toolkit name prefixed with 'fast_'. These two forms are present for all the supported Toolkit procedures. A third form which is available for certain procedures only is the underlying 'external' procedure record (not a Pop-11 procedure at all), and this will have the C name prefixed with 'raw_'. This form generally only exists for procedures which might be passed as arguments to other procedures (eg raw_XtCallbackExclusive). Thus for example, the C procedure 'XtCreateWidget' might have the following forms in Poplog: XtCreateWidget --- type checking, user-friendly version fast_XtCreateWidget --- non-checking, non-coercing version raw_XtCreateWidget --- external record version (although in fact the raw form is not provided in this case). 3.2 X Toolkit Constants ------------------------ A number of X Toolkit constants are defined in various Poplog header files and libraries. In general, these constants are imported literally (eg XtIMInput, XtIMTimeOut). However there is one important exception to this rule. The set of constants used by the resource management facilities, and prefixed 'XtN', 'XtC' and 'XtR', are not defined directly, but should instead be referenced using the macros XtN, XtC and XtR described in REF * XT_LIBS. (Thus instead of the constant 'XtNstring', one should write 'XtN string'). 3.3 Poplog Extensions To The Toolkit ------------------------------------- A number of procedures provide convenient functionality beyond that provided by the Toolkit itself. These Poplog extensions include both extensions to the 'core' interface (such as XptAppTryEvents see below), and higher level support libraries. To distinguish these from the Toolkit procedures, and avoid the risk of name clash, these routines are prefixed with 'Xpt' instead of 'Xt'. otherwise they follow the same conventions as Toolkit procedures: compound word names have the first letter of each word capitalised. In addition the Poplog-internal convention of 'fast_' and 'raw_' forms also applies. 3.4 Other Externally-Defined Libraries --------------------------------------- Some of the other substantial externally-defined libraries adopt essentially the same pattern as above. They define their own prefix in place of 'Xt' to use as the basis of their names. Thus the Poplog widget set interface uses 'Xpw', and the OpenLook widget set interface uses 'Xol'. 3.5 Data Conversion Procedures ------------------------------- Several sets of procedures are provided for various manipulations on data structures, and these also have (reasonably) uniform naming schemes. The first set consists of procedures for 'importing' data structures created by the Toolkit routines (that is, turning 'bare' pointers to the external data into properly managed Poplog records). These are prefixed 'XptImport' followed by the data-type name (thus XptImportWidget, XptImportDisplay etc..). The second consists of procedures for 'coercing' data from a friendly Poplog form to a less friendly, but still essentially Poplog form. These are prefixed 'XptCoerce' followed by the thing to be coerced (thus XptCoerceString). The third small set is a set of 'implicit access' procedures for accessing externally data fields. These are prefixed 'XptExacc' (thus XptExaccPopObj). All these sets are described more fully in REF * XPT_COERCE). Another small set of procedures is used for 'coercing' Pop-11 procedures and arguments into various Xt procedure forms (callbacks for example). All these have the preface 'XptExport' (thus XptExportCallback). See individual Xt libraries for more details (REF * XT_CALLBACK for example). 3.6 Type Specifications ------------------------ Various of the Toolkit libraries introduce type specifications for external data types. These are generally the C names prefixed with 'Xpt' (thus XptString, XptArgList). A special case is where the C name starts with 'Xt', in which cases the 'Xt is dropped (so XptPointer rather than XptXtPointer). 3.7 Library And Documentation Filenames ---------------------------------------- Filenames fall into two categories: those which are intentionally the name of some identifier in the system (typically autoloadable library names), and those which are not. For the former, the identifier name has been used verbatim (respecting case differences) for the file name, thus LIB * XptGeometrySpec defines the procedure XptGeometrySpec. For the latter, the all lower-case convention preferred for Poplog filenames has been retained. The names generally have two parts separated by an underscore. The first corresponds to the prefix convention described above (Xt, Xpt, Xol etc..) while the second is arbitrary. Thus the core Toolkit libraries are LIB * xt_widget, LIB * xt_action etc. while Poplog extension libraries are LIB * xpt_coretypes, LIB * xpt_generaltypes. 3.8 Documentation Cross-references ----------------------------------- The addition of X-related facilities to Poplog have increased the need for mixed-case library and documentation filenames. This is somewhat at odds with the existing convention for filename references, which have used all-uppercase (for prominence in the text) to refer to all-lowercase actual filenames. To retain compatibility, text references in all-uppercase refer to all-lowercase files, but mixed-case references should be taken as verbatim. This strategy does not cope with all-uppercase filenames, and for this reason such filenames have been (and should be by users) avoided. 3.9 Conventions For Other packages ----------------------------------- Higher level self contained packages generally go their own way regarding naming conventions, often not referring to their X-related nature at all (eg LIB * RC_GRAPHIC). Needless to say, some degree of internal standardisation within any sizeable package is highly desirable. ----------------------------- 4 Loading X Toolkit Routines ----------------------------- The routines comprising the basic Toolkit interface are contained in a set of libraries which have to be explicitly loaded. These are listed and discussed in more detail in REF * XT_LIBS and their own individual ref files. So generally before you can do any Toolkit programming you have to load up some of these libraries. All the libraries have two versions: one which loads the 'fast' versions of the procedures, and another which defines the checking versions in terms of the fast ones. Generally, for doing development work, you will probably want the checking versions, and so can ignore the fast versions completely. If you are producing a cut-down optimised application, you may wish to load the fast libraries alone and use those. Note: actually the above picture is slightly inaccurate. As discussed in REF * XT_LIBS, some of the fast routines are actually in the system core. ----------------------------- 5 Calling X Toolkit Routines ----------------------------- Once loaded the X Toolkit routines are ordinary Pop-11 procedure like any other. However the arguments they expect and the results they return fall into three broad classes 1) Data structures created by the Toolkit routines themselves, and viewed by Poplog largely as opaque handles with no internal structure. These include widgets, widget classes, application contexts, displays, etc. 2) Data types which have a very direct Poplog analogue which one would want to use (even if the Poplog and external representations are not identical). These comprise numbers (integer and decimals), booleans, strings and callback procedures. 3) Data structures intended to be created by the user. These include ArgLists, CallbackLists etc. There are two aspects of argument passing which need to be considered for these three classes of data: coercion and type checking. Coercion is the process of mapping whatever is supplied as the argument for the Pop-11 procedure call onto what is seen by the external (C) procedure call. Type checking is the process of deciding whether the the argument to the Pop-11 procedure is valid or not. Looking at coercion first, all Poplog calls to external procedures do the following coercions (see REF * EXTERNAL for full details): # Poplog (big)integers -> machine integers # Poplog boolean -> Toolkit boolean (XtTrue/XtFalse) # Poplog decimals -> machine floats # Poplog ddecimals -> machine doubles # Poplog external-class data -> value of external_ptr field # Other Poplog data -> address of structure In addition, fast and checking Toolkit routines carry out the following coercions: # Poplog string -> null-terminated string # Poplog callback procedure+arg -> external callback+arg These coercions only occur on actual arguments, not on fields within data structures passed as arguments, for which the user must take responsibility (to help with this, the coercion procedures used are available to users -- see REF * XPT_COERCE). Together, these two sets of coercions deal with the class 2 arguments above, so users can freely pass numbers, booleans, string and Pop-11 procedures (in callback contexts) to the Toolkit procedures. Class 1 and class 3 arguments are subject to the first set of coercions but not the second. (As we shall see, generally both classes are represented by external-class data structures, which get coerced to their external_ptr field.) Turning to type-checking (which only applies to the checking versions of the routines), we see that checking of class 2 structures is straightforward, since they have proper Poplog types. For class 1 arguments, the system uses the 'weak type' checking mechanism described in REF * XptDescriptor. In essence, it checks that a class 1 argument is external class, with an external_ptr_props field with valid type-checking data in it (eg the word "Widget" for a widget). This is simple, but flexible, and robust enough where weak types are manipulated only by well-written library code. And since class 1 data are intrinsically opaque pointers to external data, it imposes almost no significant restriction on the actual Poplog representation used. Class 3 arguments are more problematic. The Toolkit interface could provide full and specific support for the range of data structures allowed (eg new recordclasses for each one), giving them a status somewhat more like class 2's. Instead, however, a more flexible approach is adopted. The same weak type checking mechanism is used to check class 3's as for class 1's. This restricts class 3's to be external-class structures (so a Poplog vector of Poplog strings which might be perfectly well-structured and acceptable to the fast routines cannot be made acceptable to the checking ones), but this is not a huge restriction in practice, as discussed in REF * XptDescriptor. It also allows the same degree of flexibility about the precise details of data structure creation. In summary, then, the fast procedures will coerce numbers, booleans, strings and procedures, but leave anything else unchanged (allowing 'quick and dirty' structure creation if desired). The checking routines use weak type checking on all arguments except the above named, which are checked by Poplog key as usual. ------------------------------------ 6 Creating Argument Data Structures ------------------------------------ As discussed above, the Toolkit's weak type checking allows a range of possible data structures to be passed as arguments to Toolkit procedures. It provides support for doing this generally in one particular way. That is, for each structure type, there will be one supported mechanism for creating instances of it. Class 1 structures are generally returned as results from Toolkit routines so creation is not really an issue: the object returned will be an XptDescriptor for the underlying external object, and that is the supported representation for it. In cases where one wants to explicitly create an XptDescriptor (for example, where one has a 'raw' external pointer), the 'XptImport' procedures discussed in REF * XPT_COERCE can be used to create one. Class 3 structures have to be created by the user and passed out to the Toolkit routines. The Toolkit libraries use the shadowclass mechanism (see REF * SHADOWCLASS) to achieve this. That is, for each data-type required by a Toolkit routine, the (checking) version of the appropriate library will define a shadowclass for that type. Shadowclasses are like recordclasses except that they create external-class records containing the data fields. This allows them to support a wider range of typespecs than recordclasses, and in addition makes them suitable for direct use as arguments to Toolkit routines. ------------ 7 Callbacks ------------ As discussed above, Poplog will attempt to automatically coerce Pop-11 procedures used as callback arguments into externally callable forms. Callback is being used here in a general sense: we include all cases where a procedure can be passed as an argument to another to be called at some future time (this currently includes: callbacks, input callbacks, timeout callbacks, ActionHooks, action procedures). For detailed information on callbacks see REF * XT_CALLBACK. ----------------- 8 Event Handling ----------------- The X Toolkit applications are event-driven. That is, most of the work done by an application occurs in event handling routines which are called when the user causes certain events to occur (for example, pressing a mouse button.) Poplog supports two ways of dealing with X Toolkit events. Applications may invoke XtAppMainLoop, which repeatedly waits for the next event and then processes it. If invoked from within Poplog, XtAppMainLoop will take control and never return, so from that point only X applications will operate. This is not generally recommended except for completed applications. Instead, the procedure XptAsyncAppContext can be used to make Poplog process Toolkit events asynchronously, for up to 32 different application contexts simultaneously. Asynchronous processing is enabled by default on XptDefaultAppContext (see below). Although it makes no functional difference, it is useful to know that when asynchronous processing is enabled for one or more application contexts, the servicing of events by Poplog is achieved differently depending on whether the system is in a wait state or is executing program code. There are three kinds of wait state: waiting for input from a slow device like a terminal (e.g. while in Ved), waiting for a child process to die (with syswait), and simply hibernating (e.g. with syshiberate or syssleep). During these states, Poplog is actually waiting with the Toolkit routine XtAppProcessEvent, and so Xt events will generally be dealt with immediately. When more than one application context is enabled for asynchronous processing, the one waited on is always the last for which any event occurred; a Toolkit timer is then used to poll for pending events on the others. When Poplog is not in a wait state, i.e. is actually executing program code, an adaptive low-level timer mechanism is used to poll for events on all asynchronous application contexts, using the Toolkit routine XtAppPending. In this mode, an event on an application context causes a trap procedure to be run inside whatever else the system is doing (at least, as soon as it can be); the normal action of this procedure is then to process any events available (usually by calling XptAppTryEvents). Needless to say, the response to events will depend on what the system is currently doing: in particular, they will not be dealt with during garbage collections. The adaptive timer varies the polling rate according to the frequency at which events are happening, giving a fast response to short-term bursts of events while maintaining a minimal long-term polling overhead. ----------------------------------- 9 X Toolkit Default Initialisation ----------------------------------- The X Toolkit interface provides a procedure for establishing a default connection to the default server, assign command-line arguments if given, and creating an application context around it. This saves individual libraries from having to worry about such things - they can just look for the default display and create widgets on it. For details see * XptDefaultSetup and REF * XT_INIT. ------------------------------ 10 Garbage Collector Feedback ------------------------------ The X Toolkit interface include a facility to permit garbage collector feedback, that is, some visual indication that a garbage collection is taking place. This facility uses the system variable XptGarbageWidget and is activated by setting this variable to be a widget. The feedback facility operates by invoking a Toolkit 'action procedure' called 'XptGarbageFeedback' on the widget supplied as the garbage widget. Before garbage collection starts, this action is called with a single argument, namely the string describing the reason for the callback, as displayed in a GC trace output immediately after 'GC-' (ie one of 'auto' 'user' 'fopn' 'save' etc.). When garbage collection is complete, the action is called again, this time with no arguments. All application contexts created or imported by Poplog have a default value for the 'XptGarbageFeedback' action attached to them. This default action sets the supplied widget insensitive when the garbage collection starts, and sensitive when it finishes. This allows quite a range of widgets to be sensibly used as the garbage feedback widget simply by assigning them to XptGarbageWidget. However this default action can be overridden, either by defining a different value for the action in some widget class definition or by adding a new definition for the action to the appropriate application context using XtAppAddActions etc.. Note, however that since the action is called when there is no Poplog heap space left, it must be a C procedure not a Poplog one. USING A POPLOG PROCEDURE FOR THIS ACTION WILL CAUSE UNPREDICTABLE RESULTS - MOST LIKELY CRASHING THE POPLOG SYSTEM. A user-defined action procedure should use the 'num_params' argument to detect whether the garbage collection is starting or finishing, and is free to use the reason string if it wishes to vary the feedback for different kinds of garbage collection. The action procedure must take responsibility for flushing the output queue and processing any server responses in order that the feedback becomes visible, since Poplog will not otherwise service X requests until the garbage collection has finished. XptGarbageWidget [variable] This variable contains the widget which is to be used to provide garbage collector feedback. If its value is not a valid widget descriptor, no garbage collector feedback occurs. Its default value is false. XptGarbageFeedback [Xt action] This is the name of the action invoked by the garbage collector to allow for garbage collection feedback. It is invoked on XptGarbageWidget with a single 'reason' argument when the garbage collection starts, and with no arguments when it finishes. The default value, attached to all Poplog application contexts, sets the widget insensitive for the duration of the garbage collection. -------------------------- 11 Version identification -------------------------- Version identification in the X Toolkit is a little confused. An early convention used the symbol XtVersion to define the release level of the Toolkit in use. Since release 4, the symbol XtSpecificationRelease is the recommended way of defining the release level. Poplog provides both symbols, although the former may be withdrawn in subsequent releases. Note: the values are compiled into Poplog and not determined dynamically from the local X installation. Poplog is currently incapable of rigorously checking that it is running in an fully compatible environment to the one it was linked in. XtSpecificationRelease [constant] The release level of the X Toolkit (currently 4) XtVersion [constant] The X Toolkit version (currently 11004) ------------------------- 12 Further Documentation ------------------------- REF * X An Overview of Poplog X facilities REF * XptDescriptor Details of data structure management REF * XT_LIBS Libraries and associated support REF * SHADOWCLASS Using shadowclasses for data structure creation TEACH * Xpw Introduction to the Poplog widget set TEACH * OPENLOOK Introduction to the OpenLook widget set TEACH * MOTIF Introduction to the Motif widget set TEACH * ATHENA Introduction to the Athena widget set TEACH * RC_GRAPHIC Tutorial introduction to RC_GRAPHIC TEACH * RC_GRAPHPLOT Tutorial to graph plotting package --------------------------- 13 Known Bugs and Problems --------------------------- Here we summarise a few known problems: 1) Making saved images after the Toolkit has even been merely initialised does not work. 2) The system can get into bad error loops - eg infinite XIO errors if the X connection gets shut unexpectedly. A single CTRL \ will give you a setpop from which work can be saved - unclear how safe it is to go on working in the same processes though. 3) A number of facilities that really ought to be present aren't, e.g error handlers, WorkProcs ... . --- C.x/x/pop/ref/xtoolkit --- Copyright University of Sussex 1991. All rights reserved.