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 <ENTER> 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}]) =>
** <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_<name> 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 <ENTER> 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
<Prefix WidgetClass ClassName>
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 =>
<Xt WidgetClass ApplicationShellWidget>
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.