REF XT_LIBS R.Evans, Feb 1991 Jonathan Meyer, Mar 1991 COPYRIGHT University of Sussex 1993. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< X TOOLKIT INTERFACE >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< SUPPORT LIBRARIES >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< This file provides an overview and reference material for the libraries which support the Poplog X Toolkit interface. See REF * XTOOLKIT for details of the interface itself, REF *X for references to other X facilities in Poplog. CONTENTS - (Use g to access required sections) 1 Introduction 1.1 General Purpose Utility Libraries 1.2 Data structure support 1.3 Type specifications 2 The Xt libraries 3 Autoloadable libraries 4 Macros For Loading Procedures and Widgetclasses 5 Miscellaneous Poplog Libraries 8.1 LIB XPT_ATOMCACHE 8.2 LIB XPT_CURSORPLANE 8.3 LIB XPT_CLIENTCALLBACK 8.4 LIB XPT_TYPETEST 8.4 LIB XPT_TYPECHECK 6 Widget Set Interfaces 6.1 Other Widget Set Libraries 7 Widget Tree Manipulation 8 Other Data structure support libraries 9 Resource access facilities 10 Include Files 10.1 INCLUDE XT_CONSTANTS 10.2 INCLUDE XPT_CONSTANTS 10.3 XLIB include files 11 PROPSHEET 12 RC_GRAPHIC libraries --------------- 1 Introduction --------------- This file provides and overview of the libraries which support the X Toolkit interface. These libraries fall loosely into three classes: (i) libraries which are part of the basic low level interface which happen not to be implemented in the system core (ii) general purpose higher level support utilities (iii) libraries which are self-contained packages (and generally documented in full elsewhere). IMPORTANT NOTE: most of the libraries and documentation cross-references in this file will only be easily accessible after you have loaded LIB * POPXLIB (e.g. by doing uses popxlib; ,see REF * X). If you are reading this file on-line, you have probably already loaded LIB * POPXLIB, but you should bear in mind that you will need to ensure it has been loaded before loading these libraries. (If you do not, you will probably get a 'MISHAP - library not found' message.) 1.1 General Purpose Utility Libraries -------------------------------------- In addition to the base interface libraries, a range of general purpose support facilities are provided for "filling out" the Poplog X Toolkit interface, making the interface easier to use from Poplog. Some of these libraries are simply for data structure support - they provide type checking and a few simple field-access procedures as well as * SHADOWCLASS definitions for all X Toolkit datatypes. Other libraries go well beyond the facilities provided in the basic X Toolkit interface, and are supplied to make programming using the X Toolkit simpler and easier. 1.2 Data structure support --------------------------- Include files containing typespecs for most X Toolkit and related data are in the Poplog X include directory. The low level and data structure support libraries all make use of exacc with these include files, and shadowclass to provide support for managing X toolkit and related data. For more information about how to access data using typespecs and shadowclasses, see REF * SHADOWCLASS and REF * DEFSTRUCT. 1.3 Type specifications ------------------------ A description of the type specifications used by the Xlib and X Toolkit routines is given in REF * XPT_XTYPES, REF * XPT_GENERALTYPES and REF * XPT_CORETYPES. ------------------- 2 The Xt libraries ------------------- The basic X Toolkit interface can be considered as being provided by the following set of libraries: Library name Purpose ------------ ------- LIB * XT_ACTION Management of action tables LIB * XT_APPCON Handling application contexts LIB * XT_APPINIT Initialisation of X Toolkit applications LIB * XT_CALLBACK Management of callbacks LIB * XT_COMPOSITE Managing the children of composite widgets LIB * XT_CONVERTER Managing resource conversion tables LIB * XT_DISPLAY Handling display objects LIB * XT_EVENT event management routines LIB * XT_GRAB X Toolkit keyboard and pointer grabs LIB * XT_INIT X Toolkit initialisation routines LIB * XT_KEYBOARD Intrinsics Keyboard Handling LIB * XT_POPUP Management of pop-up widgets LIB * XT_R2COMPAT X11R2 compatibility procedures LIB * XT_RESOURCE Management of widget resources LIB * XT_TRANS Management of event translation tables LIB * XT_UTIL General X Toolkit utilities LIB * XT_WIDGET Widget handling routines LIB * XT_WIDGETCLASS Widget class handling routines LIB * XT_WIDGETINFO Routines for accessing widget information These libraries actually come in two forms: the libraries cited above provided type checking and data-structure support for the interface routines, but they all have 'fast' versions which do no checking. These libraries are obtained by prefixing 'fast_' to the library name (eg LIB * FAST_XT_ACTION). Each library pair is documented in its own REF file, with the name given above. Thus LIB * XT_ACTION and LIB * FAST_XT_ACTION are both documented in REF * XT_ACTION. In practice, some of this support is provided in the core Poplog system itself. For such modules, the 'fast' version of the library is in fact a dummy file, containing no code (note that the checking version does contain code: none of the type checking code is in the core system). LIB * FAST_XT_ACTION is an example of such a dummy library. However, the distribution of code between core and libraries is not yet fully stable and may change in future releases. To protect itself from this, USER CODE SHOULD LOAD THE LIBRARIES DEFINING MODULES IT USES, EVEN IF THEY ARE DUMMY LIBRARIES - in future releases they may not be. Note: it is not necessary to explicitly load both fast and slow version of a library: the slow versions automatically load the fast ones. ------------------------- 3 Autoloadable libraries ------------------------- The central higher-level (autoloadable) toolkit related facilities are as follows: XptArgList(list) -> (arglist, len) [procedure] This routines is a convenience procedure used to convert between Pop-11 list structures and X Toolkit "ArgList" structures, which are name-value pairs used to specify resources and their values in various X Toolkit routines. For details of the XptArgList type also see the reference for the XptArgList shadowclass typespec under LIB * XPT_GENERALTYPES (below). list should contain a list of vectors, where each vector is of the form {NAME VALUE}, in which NAME is a word or null terminated string and VALUE is a single piece of Poplog data). If NAME is a word the string cache used by the * XtN macro will be used to convert the word into a fixed address null-terminated string. NOTE: the values specified are not passed through X resource converters. For example, when specifying colours pixel numbers should be supplied as arguments, not colour names. If you wish to use resource converters see * XptVaArgList and the Va Xt procedures. XptArgList will accept single XptArgPtr structures as returned by consXptArgPtr instead of 2 element vectors. Alternatively, list can itself by an XptArgList structure, in which case the XptArgList structure and its length are left on the stack. For example, the following constructs an ArgList referring to a resource name 'width' and a value of 10: XptArgList([{width 10}]) => ** 1 Note that the length of the constructed ArgList is also left on the stack. All toolkit routines that take ArgLists also require a length argument. Note also that the above call to XptArgList could be replaced by a call to consXptArgList: consXptArgList( #| consXptArgPtr(XtN width, 10) |#), 1 Or more efficiently still, the non-constructive form of consXptArgList could be used (see REF * SHADOWCLASS): nc_consXptArgList(#| XtN width, 10, |# div 2), 1 In general, XptArgList is useful but does generate additional data structures which are never reused. See the description of XptSetArg below for an example of how to build an reuse a single XptArgList structure. XptVaArgList(list) -> (arg_1, ..., arg_n, n) [procedure] The 'Va' procedure XptVaArgList works in a similar way to XptArgList, but is used with the corresponding 'Va' vararg procedures in the X Toolkit (eg XtVaCreateManagedWidget). Vararg versions of the X Toolkit procedures differ from their non-vararg counterparts in two important ways: 1) They don't require "ArgList" structures to be built, since all the arguments are passed "exploded" on the call stack. This can significantly reduce the amount of additional ArgList structures which are often generated and garbaged when the non-varargs toolkit procedures are used. 2) As well as specifying name-value pairs, the vararg procedures allow you to specify typed arguments using name-type-value-size tuples. If a typed argument is used, the toolkit will automatically call resource converters if needed to convert between the specified type and the desired type for any widget resource. For XptVaArgList, list is a list of 2 element vectors of the form {NAME VALUE} (as with XptArgList), or it can be a 3 or 4 element vector, of the form {NAME TYPE VALUE} or {NAME TYPE VALUE SIZE}. In the former case the SIZE is automatically determined as the datalength of VALUE. TYPE should be a word or a null terminated string, and should be one of the recognised resource representation types as registered with the toolkit( for example String, Color, Font, Dimension etc). If TYPE is a word, the * XtN string cache is used to convert it into a fixed address null terminated string. As well as vectors, list can also contain XptArgPtr structures (as returned by consXptArgPtr), and nested lists. Any XptArgPtr structures will be exploded onto the stack. Nested lists are recursively descended, and each element in the nested list is exploded onto the stack. As a convenience, XptVaArgList will automatically specify any {NAME VALUE} vector for which the VALUE field is a string as a typed argument, where the resource representation type is String and the size field is the length of the string. This is almost always the desired behaviour. In cases where this is not the desired behaviour the name-value can be specified using an XptArgPtr structure as returned by consXptArgPtr. The consequence of this is that the vararg interface lets you easily specify resources using strings instead of X structures. For example to specify a widget's width as 100 and is foreground as the colour 'red', use: XptVaArgList([{width 100}{foreground 'red'}]) => ** width Note that the number of items placed on the stack is returned. Note also that each argument is simply exploded onto the stack. XptSetArgv(list) -> argv -> argc [procedure] This procedure converts an argument list (eg popunderx) into the argv/argc format required by fast_XtDisplayInitialize etc. list is a list of strings (any non-list being treated as []). argv is a vector containing the strings (null-terminated if necessary) and a final NULL, argc is a one element intvec containing the number of strings. IMPORTANT NOTE: the NULL in argv is a real NULL, like those returned by external_NULL, and the same restriction applies: argv should be used only as a direct argument to an external procedure, and not retained in a variable etc - if the garbage collector encounters it it will break. Hence this routine should be used at the last possible moment before the external call, and no references to argv retained. fast_XptSetUnprocessedArgs(argc, argv) [procedure] This procedure takes a list of command line arguments in the format required by fast_XtDisplayInitialize etc and sets the variable XptUnprocessedArgs with the command line arguments in argv. No checks are made for argc and argv being of the correct type. XptUnprocessedArgs [variable] This variable is set by various toolkit procedures (XtDisplayInitialize, XtOpenDisplay etc) to contain a list of any unprocessed command line arguments. Also see fast_XptSetUnprocessedArgs. XptCallbackList(list) -> cblist [procedure] This procedure converts a Pop-11 list into an X Toolkit callback list structure. list should contain 2 element vectors of the form {PROC CLIENT_DATA}, where PROC is a Pop-11 procedure and CLIENT_DATA is any Poplog object. XptCallbackList is used to make static callback structures that can be passed in an ArgList to one of the toolkit widget creation procedures. This allows you to specify a widgets callbacks in a single toolkit procedure call. The following code illustrates how XptCallbackList is used: constant foo = XptCallbackList([{^my_cb_proc ^my_cb_data}]); XtCreateManagedWidget('example', ExampleClass, example_parent, XptArgList([{selectCallback ^foo}]) ) -> widget; Note that it is your responsibility to keep a reference on the callback list structure. If you do not do this the callback procedure and client data may become garbage collected. XptSetArg(name, arglist, index) -> val [procedure] val -> XptSetArg(name, arglist, index) This procedure is used to set a specified element of the arglist to the given VALUE. If name is non-false, the name field is also updated. XptSetArg is used in situations where a single static XptArgList structure is built and then elements of the structure are modified. This is much more memory efficient than building new XptArgList structures every time (as XptArgList does). XptSetArg is designed with Pop-11 closures in mind (for more information, see HELP * CLOSURES). It is easy to make a closure of XptSetArg which sets/retrieves a single element of an arglist. The following examples illustrate the use of XptSetArg: ;;; make a new blank arglist structure constant arglist = initXptArgList(10); ;;; set some args. 100 -> XptSetArg(XtN width, arglist,1); 200 -> XptSetArg(XtN height, arglist,2); ... ;;; XptSetArg is useful for making closures which change a ;;; single arglist value: lconstant width_arg = XptSetArg(%false,arglist,1%); 200 -> width_arg(); ;;; pass arglist to toolkit procedure: fast_XtSetValues(widget, arglist, shadow_length(arglist)); XptParseGeometry(string) -> (x, y, width, height) [procedure] (x, y, width, height) -> XptParseGeometry() -> string Parses or creates a standard X geometry string of the form widthxheight+x+y Given a geometry string, the base procedure returns the individual components as integers or false. width and height are always positive, whereas x and y may be negative; false is returned for any component not present in string. string itself may also be false: in this case, false is returned for all results. The updater takes an integer or false for each component, and returns the equivalent geometry string. Any combination of integers or false will create a valid geometry string (except that x cannot be false if y is not -- a mishap occurs in this case.) If all four arguments are false, false is returned. XptGeometrySpec(list) -> string [procedure] Similar to the updater of XptParseGeometry, except that the arguments are specified as either a 2-element list [width height] or 4-element list [width height x y] XptEvenlySizeWidgets(widget1, ..., widgetN, N, size_spec) [procedure] Sets the width and/or height of a collection of widgets to the specified value according to size_spec. size_spec should be a two element full vector, of the form {width_spec height_spec} where the first element specifies the width of the widgets and the second specifies the height. The following values are legal values for width_spec or height_spec: false don't change the dimension max set dimension to the largest of widgets min set dimension to the smallest of widgets an integer set the size to the specified integer pixels For example, to set all of the widgets to be 10x10 pixels, use a size_spec of: {10 10} To set all of the widgets to be the same width, where that width is the width of the widest widget, but without changing the height, use: {max ^false} XptCenterWidgetOn(widget, reference_widget) [procedure] XptCenterWidgetOn(widget, x, y) [procedure] XptCenterWidgetOn(widget, "screen") [procedure] This convenience procedure is used mainly to position pop-up windows over their parents, or in the middle of the screen. It places the center of widget over a reference point, which can be specified in one of three ways: # By passing a reference_widget; the reference point is the center of the reference_widget. # Passing the reference point as an integer x, y screen coordinate. # Passing the word "screen"; the reference point is the center of the screen. The widget is positioned so that its center is over the reference point by changing the XtN x and XtN y resources of the widget's SHELL parent (or the widget itself, if it is a shell widget). Thus the position of the widget within the shell does not change - only the position of the widget on the screen changes. XptMaxWidgetVisibility(widget) [procedure] This convenience procedure can be used to ensure that pop-ups can be seen on the screen. It moves widget to maximise the amount of widget that is visible on the screen. It uses a top-left "gravity" when calculating the coordinates of the widget - ie. if the widget is larger than the screen, it will be moved to ensure that its top left corner is visible. The widget is positioned by changing the XtN x and XtN y resources of the widget's SHELL parent (or the widget itself, if it is a shell widget). Thus the position of the widget within the shell does not change, although the position of the widget on the screen does. Note that XptMaxWidgetVisibility also adds some extra padding space between the widget and the edge of the screen - this is to allow for any window manager border that may surround the window. XptWidgetCoords(widget) -> (x, y, width, height) [procedure] x, y, width, height -> XptWidgetCoords(widget) Getting and setting a widgets size and position is a commonly performed toolkit application operation. XptWidgetCoords performs this operation, using the toolkit procedures XtGetValues and XtVaSetValues to retrieve and set the x, y, width and height resources of widget. x, y, width and height should be integers. In update mode, XptWidgetCoords ignores any of the x, y, width or height arguments that are false. This allows you pass false for eg. the width and height arguments and integers for the x and y arguments to only specify the x and y coordinates for the window. XptWidgetCoords does nothing particularly special -- it simply uses XptVal. XptWMShellCoords(widget) -> (x, y, width, height) [procedure] x, y, width, height -> XptWMShellCoords(widget) This utility function takes a widget and returns or sets the x, y, width and height pixel coordinates of the innermost shell widget ancestor of widget (or widget itself if it is a shell widget). x and y specify the top left hand corner of the window. If the window has any window manager decorations around it, the coordinates of the topmost left hand corner of the decorations are returned or set. Similarly, width and height specify the total width/height of the window including window manager decorations. This procedure is useful when you wish to position a new window exactly over an old window and need to take into account any window manager decorations. In update mode, XptWMShellCoords ignores any of the x, y, width or height arguments that are false. This allows you pass false for e.g. the width and height arguments and integers for the x and y arguments to only specify the x and y coordinates for the window. When updating an unrealised shell widget, the given (non-false) values are used to replace the corresponding parts of any XtN geometry string the shell may have, i.e. they are merged with an existing string, or a new one is created. This ensures that when the shell is realised, the given values are actually used by the window manager. XptGetFontProperty(fontstruct, name) -> int_or_false [procedure] XptGetFontProperty(fontstruct, name, to_name) -> string_or_int_or_false XptGetFontProperty(fontstruct, name, displayptr) -> int_or_false XptGetFontProperty(fontstruct, name, to_name, displayptr) -> string_or_int_or_false Takes an X FontStruct, and looks for the standard font property identified by name (using XGetFontProperty). name should either be an unsigned integer or a string/word. If name is a string/word then LIB * XPT_ATOMCACHE is used to convert it to an integer atom (mishaping if the atom doesn't exist). If name is an integer, it should be in the range XA_MIN_SPACE - XA_CAP_HEIGHT, or be XA_FONT. (See the file INCLUDE * X_ATOMS.PH for a definition of these and other standard X11 Atoms.) If the optional boolean third argument to_name is supplied and true, XptGetFontProperty will call XptGetAtomName on the integer result of the XGetFontProperty call and return the resulting string. This is useful when the font property specified by name is of type ATOM and you wish to know that string associated with the atom rather than the atom itself. By default, conversions between names and integer atoms assume the display XptDefaultDisplay, but the optional third or fourth argument displayptr may be supplied to override this. If the property specified by name doesn't exist, XptGetFontProperty returns false. Note that, whilst many fonts will support the standard font properties, it is not a requirement that they do so. Examples If widget is an instance of the Poplog XpwGraphic Widget class, you can do: include x_atoms; ;;; defines standard XA_ atoms ;;; get the widget's FontStruct vars font = XptVal graphic(XtN font:exptr); ;;; Y offset in pixels to the underline start position XptGetFontProperty(font, XA_UNDERLINE_POSITION) => ** 7 ;;; Copyright Owner for font XptGetFontProperty(font, XA_COPYRIGHT, true) => ** 'Public domain font. Share and enjoy' ;;; Full name of the font as string XptGetFontProperty(font, XA_FONT, true) => ** -Misc-Fixed-Medium-R-Normal--13-120-75-75-C-80-ISO8859-1 ;;; Note: you could get the name of the font as an ATOM too- XptGetFontProperty(font, XA_FONT) => ** 94 XptConvertUnit(num,from,to,axis,screen) -> num2 [procedure] This procedure converts between standard units and X screen pixels. It takes into account the resolution of the screen. See HELP * XptConvertUnit for more details. XptNewWindow(name, size, args, class, shellargs) -> widget [procedure] XptNewWindow(name, size, args, class) -> widget This routine creates a new "top level application shell" widget, and then creates an instance of a single widget class within that shell. The shell is realised and the new widget is returned. This is useful for creating simple stand alone windows. name is a string that is used as the title of the widget's window and icon. size is a 2 or 4 element vector or list (see XptGeometrySpec above). class is the class to use as the child of the application shell widget. args is a list of args (as taken by XptArgList) that is used to create an instance of class within the application shell. The optional shellargs argument is a similar list, used to create the application shell widget. XptDestroyWindow(widget) [procedure] Companion procedure to XptNewWindow. Takes a widget and destroys it's shell. This will cause all the children of the shell (including widget) to be destroyed as well. XptShellDeleteResponse(widget) -> widentproc [procedure] widentproc -> XptShellDeleteResponse(widget) A high level autoloadable procedure for setting the response of a Shell widget to the 'WM_DELETE_WINDOW' window manager protocol message, which is sent by a window manager to a client when the shell widget should be removed from the workspace. widget must be realized before setting a delete response. Setting a delete response overrides any previous widget handling for the WM_DELETE_WINDOW for widget. widentproc should be a procedure, or a word/ident which evaluates to a procedure. The procedure is passed widget as its only argument. ie. the form for widentproc is: delete_response(widget) The delete response procedure should decide whether to accept the request to delete the window, and call for example XtPopdown or XtDestroyWidget to close the window. Useful procedures to use as a simple delete response procedures are: erase Assigning erase as the delete response for a window causes WM_DELETE_WINDOW messages to be ignored. XtPopdown Causes the window to be popped down when a WM_DELETE_WINDOW message arrives (useful for popup shells). XtDestroyWidget The widget will be destroyed when a WM_DELETE_WINDOW message is received. XtUnmapWidget The widget will be unmapped when a WM_DELETE_WINDOW is received. XtUnmanageChild This delete response is useful as a way to pop down Motif dialog boxes. Note that, if widget is not a shell widget, XptShellOfObject is used to find the nearest ancester shell of widget, and the delete response for that widget is returned/updated instead. However, when the delete response is invoked, WIDENT is always called with the widget that you specified to XptShellDeleteResponse. This allows you to direct the delete response handling for a shell widget to one of its children. Note that widentproc will be false for widgets which have not had a delete response specified. You can also specify a widentproc of false as the delete action for a widget to cancel handling of WM_DELETE_WINDOW messages for that widget. If there is no specified delete response for widget, the reaction of the widget to WM_DELETE_WINDOW is unspecified. The delete response procedure is called via XptCallbackHandler with a TYPE argument of "delete_window". You can therefore trace delete response actions by doing: [delete_window] -> XptTraceCallback; The following example will make the delete response for an XVed window be to print something. NB. After doing this, you will not be able to use the window manager to close the current XVed window (use q instead): npr -> XptShellDeleteResponse(wvedwindow); XptResizeResponse(widget) -> widentproc [procedure] widentproc -> XptResizeResponse(widget) Assigns an action to be called when widget is resized. widentproc is a word, ident or procedure. If it is a word or ident then valof/idval is used to obtain the underlying procedure. The procedure should takes one argument, widget, and return no results. The procedure can perform any actions necessary to update the contents of the widget, but should not itself cause the widget to resize since this may cause a race condition. -------------------------------------------------- 4 Macros For Loading Procedures and Widgetclasses -------------------------------------------------- The following are all macros which provide special interfaces to the exload syntax form (see REF * EXTERNAL). Multiple uses or mixtures of them can be batched within exload_batch ... endexload_batch brackets. XptLoadProcedures [macro] This macro is used by all of the Poplog X Toolkit libraries that perform external loads to obtain 'raw' Toolkit and Xlib procedures to be applied with exacc. The macro constructs and executes an exload command (see REF * EXTERNAL), and takes similar (though simplified) arguments to exload. The following example will load several Xlib and Xt procedures and store them in global identifers: XptLoadProcedures 'myprocs' XtFree, XClearArea, XSetInputFocus, XtSetSensitive; As with exload, you can also declare typespecs automatically for any of the identifiers, e.g. XptLoadProcedures 'myprocs' XtFree(ptr), XClearArea(dpy,w,x,y,width,height,exposures), XSetInputFocus(dpy,focus,revert_to,time), XtSetSensitive(w,sensitive) ; The full syntax for this macro is: XptLoadProcedures mark-item { [input-file-list] } { (attribute-list) } { declarator } funcname { function-typespec } , { funcname ... } ; where things inside { ... } are optional. If input-file-list is omitted, the autoloadable variable XLINK_EXLIBS is used instead. declarator can be one of constant, vars, lconstant, lvars, or dlvars, and defaults to whatever define would default to. (Note however, that because of the restrictions described in The = Form is a Runtime Action in REF * EXTERNAL, XptLoadProcedures cannot actually assign the identifiers until 'run-time'; there is thus little point in using constant/lconstant, since these will be coerced by exload to vars/lvars when creating a saved image etc.) One or more funcname can be specified. Each funcname should be the name of an external procedure. If no prefix attribute is present in attribute-list, the external procedure is loaded and stored in a identifier called raw_funcname (so the external procedure XtFree would be stored in the Poplog identifier raw_XtFree). If prefix (or no prefix) is present in attribute-list, that is used instead of raw_. Procedures are imported using XptImportProcedure. More accurately, funcname FooBaz is converted into the following identifier-spec for exload: raw_FooBaz = #XptImportProcedure <- FooBaz, XptPopLoadProcedures [macro] This macro is similar in form to XptLoadProcedures above, but instead of loading raw external procedures it puts Pop wrappers around them, so they can be called as ordinary Poplog procedures. Unlike XptLoadProcedures, the function-typespec is NOT optional, and must be present for each funcname: this information is used to create an apply procedure which calls the external function, taking the correct number of arguments off the stack, and returning the specified return type. (* XptPopImportProcedure is used for this.) Also unlike XptLoadProcedures, no default prefix is added to funcname to get the Pop identifier name. Thus XptPopLoadProcedures 'myprocs' XDefaultScreen(dpy) :int ; will create the Pop identifier XDefaultScreen; however, you can specify a prefix in attribute-list. Also, this form allows the exload syntax funcname function-typespec <- external-name, to specify an external name different from the Pop identifier name. As with XptLoadProcedures, declarator can be constant, vars, lconstant, lvars, or dlvars, and defaults to whatever define would default to. However, the remarks concerning constant/lconstant in XptLoadProcedures above DO NOT apply to XptPopLoadProcedures, since this form is able to assign the Pop procedures to the identifiers immediately at compile-time. All identifiers are made procedure-type. XptLoadWidgetClass [macro] This macro loads widgetclass records into identifiers, and is used by all of the Poplog widgetclass libraries. Its syntax is XptLoadWidgetClass mark-item { [input-file-list] } { (attribute-list) } { declarator } widgetclass-name { <- external-name }, { widgetclass-name ... } ; where things inside { ... } are optional. No default prefix is added to widgetclass-name to get the Pop identifier name. Thus XptPopLoadProcedures 'wclass' xtApplicationShellWidget <- applicationShellWidgetClass ; creates the Pop identifier xtApplicationShellWidget. The Poplog standard for widgetclass identifier names is exemplified by xtApplicationShellWidget, i.e. a widget set prefix beginning with lowercase "x", followed by the class name but omitting the 'Class' suffix. Unless you specify a separate <- external-name clause, the external name of the widgetclass is thus assumed to be widgetclass-nameClass The widgetclass records created will print as where Prefix is all lowercase letters at the beginning of widgetclass-name with the first letter capitalised, and ClassName is the rest. E.g. xtApplicationShellWidget => As with XptLoadProcedures and XptPopLoadProcedures above, declarator can be constant, vars, lconstant, lvars, or dlvars, and defaults to whatever define would default to. Like XptPopLoadProcedures, the remarks concerning constant/lconstant in XptLoadProcedures above DO NOT apply to XptLoadWidgetClass, since this form is able to assign its widgetclass records into the identifiers immediately at compile-time. (However, the widgetclass record pointers are not filled in until 'run-time'. Printing a record loaded when Poplog has been invoked with %nort will produce <(NULL)WidgetClass FooBazWidget> showing that the pointer has not yet been filled in.) --------------------------------- 5 Miscellaneous Poplog Libraries --------------------------------- 8.1 LIB XPT_ATOMCACHE ---------------------- This simple library extends the functionality of XInternAtom and XGetAtomName to include client-side caching of the results. Its two procedures XptInternAtom and XptGetAtomName also take and return atom names as Poplog words. See REF * XPT_ATOMCACHE for more. 8.2 LIB XPT_CURSORPLANE ------------------------ A library for throwing a cursor plane up over a widget - defining the cursor used in that widget and its children. REF * XPT_CURSORPLANE describes this facility, and also discusses how to change the cursor for widgets when your application is busy or when Poplog is performing a garbage collection. 8.3 LIB XPT_CLIENTCALLBACK --------------------------- A library providing a modular way of extending the notion of callback lists to include arbitrarily named callback lists for widgets. The client application can create and manage these callback lists using a programming interface similar to standard X toolkit callbacks.. 8.4 LIB XPT_TYPETEST --------------------- The library LIB * XPT_TYPETEST provides procedures for testing that data belongs to certain XptDataTypes. This library is used by the LIB * XPT_TYPECHECK library to recognise XptDataTypes and mishap for incorrect XptDataTypes. See REF * XPT_TYPECHECK for details of both sets of procedures. The following procedures are provided to test for data of specific XptDataTypes: XptIsType - does an object belong to a type XptIsLiveType - XptIsType and external pointer is non-NULL. 8.4 LIB XPT_TYPECHECK ---------------------- Provide type checking procedures for X Toolkit types (for details see REF * XPT_TYPECHECK). ------------------------ 6 Widget Set Interfaces ------------------------ Predefined C widget classes can be externally loaded like any other external data. However, Poplog provides direct support for the following widget sets: Name Prefix Description ---- ------ ----------- Toolkit Xt The basic widgets provided by the X Toolkit Intrinsics are in this set. Athena Xaw The 'project Athena' sample widget set, as provided with the MIT distribution of X Windows (see HELP * ATHENA). OpenLook Xol The 'OLIT' widget set, as provided with Sun's OpenWindows system (see HELP * OPENLOOK). Motif Xm The Motif widgetset from the Open Software Foundation (see HELP * MOTIF). Poplog Xpw The 'Poplog' widget set, provided with Poplog (see HELP * Xpw). Except for Toolkit, each of these sets has a corresponding sub-directory of the main Poplog X library directory, and a library file in the latter which adds that sub-directory to popuseslist (making the widgetset files available via uses). The library files are named by the widgetset prefix, viz: # LIB * Xaw # LIB * Xol # LIB * Xm # LIB * Xpw So for example, uses Xpw; would add the Poplog widgetset sub-directory to popuseslist. Within each sub-directory, each widget class in the set has a corresponding .p file that loads that class into a constant identifier. The name of both the file and the identifier is the class name prefixed by the widgetset prefix with a lowercase "x". E.g. # xawGripWidget # xolButtonGadget # xmScrollBarWidget # xpwScrollTextWidget etc. Thus uses Xpw, xpwScrollTextWidget; would load the Poplog ScrollText widget. The Toolkit widget classes are similarily named (e.g. xtApplicationShellWidget), but these identifiers are directly autoloadable from the main X autoloadable directory. Each widgetset directory also contains a file called prefixAllWidgets which loads all the widget classes in the set, e.g. uses Xol, XolAllWidgets; will load all the OpenLook widgetclasses. Similarily, uses XtAllWidgets; would load all the Toolkit widgets. Include files for the different widget sets are situated in the main X include directory (e.g. INCLUDE * XmConstants, * XolConstants, etc). Further interfaces will be provided in future releases. Note that the presence of the library does not indicate the presence of the underlying widget set. The latter takes the form of a C archive library which must be provided independently for these facilities to work. The only widget sets guaranteed to be present with Poplog are Xt and Xpw. As already mentioned, the Toolkit widget identifiers are autoloadable. These are: xtApplicationShellWidget -> widgetclass [constant] xtCompositeWidget -> widgetclass [constant] xtConstraintWidget -> widgetclass [constant] xtCoreWidget -> widgetclass [constant] xtObject -> widgetclass [constant] xtOverrideShellWidget -> widgetclass [constant] xtRectObj -> widgetclass [constant] xtShellWidget -> widgetclass [constant] xtTopLevelShellWidget -> widgetclass [constant] xtTransientShellWidget -> widgetclass [constant] xtVendorShellWidget -> widgetclass [constant] xtWidget -> widgetclass [constant] xtWmShellWidget -> widgetclass [constant] These autoloadable constants contain widgetclass structures (as produced by * XptLoadWidgetClass) for all the basic X Toolkit widgets. (Note that xtWidget is the same as xtCoreWidget.) XtAllWidgets [library] This library loads all the Toolkit widgetclass identifiers above. 6.1 Other Widget Set Libraries ------------------------------- OpenLook, Motif and Athena widget set support is provided. The following libraries contain example code that you might find useful: LIB * XolDemos see TEACH * XolDemos LIB * XolTutorial see TEACH * OPENLOOK LIB * XmDemos see TEACH * XmDemos LIB * XmTutorial see TEACH * MOTIF LIB * XawTutorial see TEACH * ATHENA --------------------------- 7 Widget Tree Manipulation --------------------------- The following procedures (not provided by the C X Toolkit) are useful for manipulating widget trees: XptChildren(widget) -> list [procedure] Returns all of the direct descendents of a composite widget widget, in the order that they appear in the XptWidgetList held in the XtN children resource. If widget is not a composite widget, the procedure will return nil. XptAncestors(widget) -> list [procedure] Returns a list containing widget, and all the parents of widget up to the nearest ancestor which is a subclass of Shell. The list is ordered with the topmost (Shell) ancestor first. XptWidgetTree(widget) -> list [procedure] Takes a widget and returns a tree of lists or widgets, mirroring the widget tree downwards from the given widget. XptShellOfObject(widget) -> shell_widget [procedure] Returns widget, or the nearest ancestor of widget which is a subclass of Shell. ----------------------------------------- 8 Other Data structure support libraries ----------------------------------------- The following libraries are used to provide additional data structure support via shadowclasses and typespecs: XptGCValuesPtr [shadowclass typespec] LIB * XptGCValuesPtr provides a specification for a shadowclass for accessing and building XGCValues structures. ----------------------------- 9 Resource access facilities ----------------------------- As well as the basic X Toolkit procedures for accessing and updating resources (XtSetValues and XtGetValues), Poplog includes more friendly utilities for accessing widget resources. REF * XPT_RESOURCE describes these utilities. The main procedures are: XtN simple macro for building resource names XptVal efficient access/update of multiple resources XptResourceInfo resource database for widget resources XptPopValue high level access/update of multiple resources ----------------- 10 Include Files ----------------- The X Toolkit interface includes a number of header files defining commonly used constants etc. associated with the interface. These should be included into user programs using include or loadinclude (see HELP * INCLUDE). The constants are all defined using iconstant (see REF * SYNTAX), and so are lexically scoped when included, but globally scoped if the file is COMPILED directly (i.e. if loadincluded). Note: some of these files are included by many of the other library files documented in this file. This means that compilation of a large application may cause these files to be read many times, each time declaring the same constants (in different lexical scopes) with the same values. However, the files contain a test for global compilation. If a file is loaded globally (ie compiled rather than included) then subsequent attempts to include it will not repeat the definitions. Thus applications may decrease load time by explicitly compiling (NOT including) these files before loading other libraries. The syntax word loadinclude, defined in LIB * INCLUDE, may be used exactly like include to cause compilation rather than inclusion of an include file. 10.1 INCLUDE XT_CONSTANTS -------------------------- INCLUDE * XT_CONSTANTS defines Poplog versions of various X Toolkit constants. See REF * XT_CONSTANTS for full details. 10.2 INCLUDE XPT_CONSTANTS --------------------------- INCLUDE * XPT_CONSTANTS defines additional constants used by the Poplog extensions to the Toolkit interface. See REF * XPT_CONSTANTS for full details. 10.3 XLIB include files ------------------------ The Poplog X Toolkit interface has include files containing constant declarations and typespecs for many of the XLIB structures. These typespecs make full use of the XptDescriptor mechanism, and so integrate well with the Poplog X Toolkit. These include files can also be used independently of the Poplog Xlib interface, and may therefore save on overheads. They simplify the task of accessing XLIB data structures. The following include files define typespecs and constants needed to use many of the Xlib structures: Include file Xlib typespecs ------------ -------------- INCLUDE * XPT_XEVENT See REF * XPT_XEVENT INCLUDE * XPT_XCOLOR XColor INCLUDE * XPT_XFONTSTRUCT XFontProp, XCharStruct, XFontStruct INCLUDE * XPT_XGCVALUES XGC, XGCValues INCLUDE * XPT_XIMAGE XImage INCLUDE * XPT_XSCREEN XScreen INCLUDE * XPT_XWINDOW XWindowAttributes, XSetWindowAttributes The following Xlib include files are also available: INCLUDE * X_ATOMS - defines constants for all of the the standard X Server atoms (atoms are integers), eg. XA_NAME, XA_WM_NAME, XA_WINDOW, XA_STRING etc. The constant XA_LAST_PREDEFINED defines the largest Atom value for builtin X server atoms. INCLUDE * X_KEYSYMS - defines constants for all of the standard X KeySym numbers (integers), eg. XK_BackSpace, XK_A, etc. Also defines the macros IsKeypadKey, IsCursorKey, IsPFKey, IsFunctionKey, IsMiscFunctionKey, and IsModifierKey, which are used to test what type of key the KeySym corresponds to. ------------- 11 PROPSHEET ------------- LIB * PROPSHEET is a high level tool for building OpenLook and Motif dialog boxes and property sheets. See TEACH * PROPSHEET for a tutorial and examples. ------------------------ 12 RC_GRAPHIC libraries ------------------------ RC_GRAPHIC is a collection of libraries which provide 'relative coordinate' graphics operations on a simple graphics tablet on the screen (using the XpwGraphic widget -see REF * XpwGraphic). Full details are given in HELP * RC_GRAPHIC. A tutorial discussion can be found in TEACH * RC_GRAPHIC. The principal libraries are as follows: LIB * RC_GRAPHIC Defines the basic interface and graphical procedures, including turtle graphics, i.e. drawing procedures relative to a current state represented as the location and heading of a "turtle" moving on the screen. LIB * RC_ROTATE_XY This extension to RC_GRAPHIC provides procedures for rotating the coordinate frame. LIB * RC_MOUSE This extension to RC_GRAPHIC provides procedures for using the mouse in the graphics window to draw pictures or for other purposes. LIB * RC_DRAWGRAPH A procedure for drawing a graph of a given function. This makes use of LIB RC_GRAPHIC LIB * RC_GRAPHPLOT, * RC_GRAPHPLOT2 These files extend the graph drawing facilities by providing a wider range of options. See TEACH * RC_GRAPHPLOT, HELP * RC_GRAPHPLOT. LIB * RC_SET_SCALE A procedure for specifying the user co-ordinates in terms of inches, centimetres or frame height or width. LIB * RC_CONTEXT A mechanism that makes it possible to switch between different windows by saving and restoring the variables associated with each window. --- C.x/x/pop/ref/xt_libs --- Copyright University of Sussex 1993. All rights reserved.