REF XPT_RESOURCE Jonathan Meyer, Mar 1990 Revised John Gibson, Sep 1992 COPYRIGHT University of Sussex 1992. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< X TOOLKIT RESOURCE >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< ACCESS LIBRARY >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< This file describes some high-level utilities for dealing with X Toolkit widget resources from Poplog. See REF * XT_LIBS for details of other libraries found in the Poplog X Toolkit interface. Also see REF * XT_RESOURCE for information about toolkit resource manipulation procedures. CONTENTS - (Use g to access required sections) 1 Resource Names 2 Basic Resource Access 3 Resource Information Database 4 Resource Setting/Retrieving 5 Old XptValue ----------------- 1 Resource Names ----------------- In the Poplog X Toolkit interface, resource names that in C are called XtN are constructed using the * XtN macro: XtC word [macro] XtN word [macro] XtR word [macro] These macros read a single word item from proglist and convert it into a fixed address string. The string is cached so future uses of the macro with the same word will always use the same string. For example: XtN width => ** width (XtN width) == (XtN width) => ** See HELP * XtN for more details. ------------------------ 2 Basic Resource Access ------------------------ The XptVal syntax construct generates efficient in-line code for getting or setting multiple resources for a widget: XptVal [syntax] This construct has the form XptVal attributes widget ( resource1, ..., resourceN ) It may be used either in ordinary evaluate mode (to get resource values), or in update mode (to set them). In evaluate mode, N resource values are returned on the stack; in update mode, N are taken off. attributes This part is optional, and is the same as the attributes part of an exacc or defexacc statement (see REF * DEFSTRUCT), except that the "@" attribute (address mode) is not allowed. If "fast" is specified, then widget is not checked to a be live widget. widget This supplies the widget whose resources are being accessed or updated, and may be either a single identifier name, or any Pop-11 expression in parentheses. resource Each resource specifies a resource name string, an optional type-spec, and some optional flags that are used when updating, i.e. resource-name type-spec update-flags where type-spec defaults to :int if omitted. (If present, update-flags are ignored when accessing values.) The resource name string is usually got using the XtN macro described above, e.g. if widget is an identifier containing a widget, then XptVal widget(XtN x :XptPosition, XtN y :XptPosition) -> (x, y); would access its "x" and "y" resources, and (x, y) -> XptVal widget(XtN x :XptPosition, XtN y :XptPosition); would update them. Note that resource-name is by default read as a compile-time string; if you wish to use a variable string (i.e. one supplied at run-time), you can specify it as an arbitrary Pop-11 expression inside "%" signs, e.g. XptVal widget(%name1% :int, %name2% :int) -> (val1, val2); would use the values of the identifiers name1 and name2 as the resource names. type-spec The full type-spec syntax and the basic typenames are described in REF * DEFSTRUCT. A number of common types corresponding to X Toolkit types or Poplog specific ones, all with names :Xpt-, are defined in the include files INCLUDE * XPT_CORETYPES INCLUDE * XPT_XTYPES (see REF * XPT_CORETYPES, * XPT_XTYPES), which you can include or loadinclude in your program. Note that the type-spec part of each resource is fixed at compile-time, and cannot be run-time-variable. update-flags For updating, flags can be specified for each resource to control (1) automatic resource conversion, and (2) optional setting of values: Automatic Resource Conversion ----------------------------- By default, values assigned to resources must conform with the typespecs given for them, e.g. ':int' will expect an integer. However, to enable things like e.g. fonts and colours to be specified by strings (which are converted automatically by the X Toolkit), you can supply the flag at the end of a resource. For example, val -> XptVal widget(XtN font :XptFont ); will test whether the given val is a string and if so, bypass the normal check for :XptFont (and pass the string as an XtVaTypedArg, i.e. making the Toolkit do automatic conversion). Currently, two possible TYPEs are allowed: "string" and "integer". They can be specified separately, or together in the form which will pass either a string or a (big)integer as an XtVaTypedArg. Optional Values --------------- To enable an update XptVal statement to selectively set some values but not others, the flag can be used on any resource. When present, if the item given for the resource is equal (==) to value, then that resource will not be set. value may be an identifier name (meaning that identifier's value) or an integer; alternatively, the =value part may be omitted, which is the same as =false. E.g. val1, val2 -> XptVal widget(XtN foo , XtN baz); will always set XtN baz, but will only set XtN foo if val1 is not false. (If you use both TYPE and OPT flags on a resource, the OPT value is always tested for first, regardless of the order in which the flags are specified.) Further examples XptVal shell_widget(XtN title :XptString)=> ** my window 'test' -> XptVal shell_widget(XtN title :XptString); XptVal button_widget(XtN parent :XptWidget) => ** XptVal[fast] quitButton(XtN width :XptDimension) => ** 124 -------------------------------- 3 Resource Information Database -------------------------------- This important facility in the Poplog X Toolkit interface is a method for determining what resources any widget has available to it, and how those resources are represented. The procedure XptResourceInfo is used to build and examine a database of information about resources available to widgets, their representation types and their sizes. Entries in this database can also be specified manually using XptSpecifyResourceInfo. This autoloadable procedure is small, and can be loaded without loading all of the XptResourceInfo library. It is intended for use in widgetset libraries that wish to inform Poplog about any additional/incorrect widget resource definitions for a given widget class. The resource information database is used by XptPopValue to perform type-checking, coercion and conversion of widget resources. XptResourceInfo(widgetclass, res_name) -> info_or_false [procedure] XptResourceInfo(widget, res_name) -> info_or_false [procedure] Returns information about a resource for widget. This information is maintained in a set of property tables that are built from information stored in the widget class. res_name should be a string constant as returned by the XtN macro (words and ordinary pop strings are converted into XtN strings, but this is less efficient). If information is found, info will be a vector of the form {representation size} where representation is the X Toolkit representation type of the resource as a Poplog word and size is the size in bits of resources of this type. If no information is found about the resource, false is returned. For example: XptResourceInfo(widget, XtN width) => ** {Dimension 16} XptResourceInfo(widget, XtN dummy) => ** false If the widget's parent is a constraint widget, then the constraint resources will also be examined - info will in that case be a resource which is either a widget resource or a constraint resource. XptResourceInfo keeps a one-entry cache of the last widget seen, so repeated calls with the same widget will result in a single property access. The first time a widget's class is encountered, the toolkit functions XtGetResourceList and XtGetConstraintResourceList are called to get the resources listed in the class structure. These are then cached in Pop-11 properties. Future accesses involve two property table accesses, and so will be relatively efficient. The info structures are shared as much as possible. So each {representation size} element is constructed once and kept in a table. Future appearances of the same element will be the element stored in the table. Since there are relatively few representations in the toolkit, this is effective. XptSpecifyResourceInfo(widgetclass, list); [procedure] Overrides/adds additional resource info to the widget resource information database that is used by XptResourceInfo. This is desirable in cases where widgetclass has incorrect or missing information stored in the resource list that is returned by XtGetResourceList or XtGetConstraintResourceList. For example, any "subpart" resources for a widget do not appear in the list returned by XtGetResourceList. list is a two element list, of the form: [widget_resources constraint_resources] where widget_resources and constraint_resources are either a list or false. If they are a list, the list should contain elements of the form [res_name representation] or [res_name {representation size}] where res_name and representation are words, and size is an integer. If specified without an associated size, representation must be one of the following standard types: Bitmap Boolean Font Int Pixel Pixmap Pointer Short String Widget WidgetClass For example: XptSpecifyResourceInfo(FormWidget, [ [ ;;; widget resources [width {Position 32}] [height {Dimension 16}] ] [ ;;; constraint resources [yRefWidget Widget] ] ]); NOTE: This library can be loaded without loading XptResourceInfo, so it is possible to quite cheaply specify widget resource types in widgetset libraries if necessary. XptListResourceInfo(widget) -> list [procedure] XptListResourceInfo(widgetclass) -> list [procedure] This procedure is useful for examining the currently known resources and their types/sizes for any given widget or widgetclass. list is a two element list, of the form: [widget_resources constraint_resources] where widget_resources and constraint_resources are either a list or false. If they are a list, they will contain elements of the form: [res_name {representation size}] where res_name is a fixed address null terminated string as returned by the xtn macro, representation is a Poplog word, and size is an integer. If XptListResourceInfo is given a widget, constraint_resources will be any constraint resources of the parent of the widget. For a widgetclass, the constraint resources will be those of the class itself. ------------------------------ 4 Resource Setting/Retrieving ------------------------------ The high level procedure XptPopValue is a convenient way of setting and retrieving widget resources. It uses a lookup table in conjunction with XptResourceInfo to determine the how to set/get a resource. The entries in this lookup table can be defined by widgetset libraries, so it is possible to easily specify how XptPopValue should deal with new resource types. XptPopValue makes use of the X Toolkit varargs interface. This means that it is reasonable cheap in terms of the amount of datastructure it needs to build (it doesn't need to build XptArgList structures for example). In the best case, XptPopValue will perform two property table accesses for each resource that it retrieves (3 for each set). One property access to find the resource information in XptResourceInfo and one (or two during a set) to convert this into typespec/size coercion data. In the worst case more than half a dozen property table accesses may be performed as XptPopValue tries converting its name arguments into XtN strings, checks to see that it has the resource information for the given widget, etc. XptSpecifyPopValueTypes(list) [procedure] This small autoloadable procedure is used to tell XptPopValue how to deal with the various representation types of widget resources. It is also used to instruct XptPopValue which Poplog datakeys should be specified as X toolkit typed args using XtVaTypedArg. list should contain entries in one of four forms: 1. For specifying key typing information, use: [Poplog_key {representation size_or_false}] This informs XptPopValue that, when a value with a datakey of Poplog_key is assigned to a resource, it should be specified as a vararg typed arg, with representation type representation (a Poplog word), and of the indicated size (in bits). for a size of false, datasize is used to determine the values size. By default, the following types are defined: [^string_key [String ^false]] [^integer_key [Int 32]] Note that if representation is found to be the same as the one in the information returned by XptResourceInfo, (eg you are assigning a string to a resource which is of representation type XtRString), then XptPopValue will not specify the resource as typed. 2. For automating X Toolkit representation handling, use: [representation :typespec] This tells XptPopValue that when a resource with a toolkit representation type representation (a Poplog word) is accessed or updated, the given typespec should be used to perform that access or update. typespec should be any valid input to p_typespec. Initially, all the basic toolkit representation types are defined: Atom Bitmap Bool Boolean Callback CallProc Cardinal Color Colormap Cursor Dimension Display Enum File Float Font FontStruct Function Geometry Int LongBoolean Object Pixel Pixmap Pointer Position Screen Short String StringArray StringTable UnsignedChar TranslationTable Visual Widget WidgetClass WidgetList Window 3. Type coercion information can also be based on data size: [integer :typespec] If XptPopValue cannot find information on how to deal with a specific toolkit representation, it will as a second resort use the resource info's size field to get a typespec suitable for accessing/updating the resource. Initial size types are: [32 :int] [16 :short] [8 :byte] 4. To unset any typing information, use: [ ^false] where is a key, integer or word as described above. XptPopValue(widget, res1, ..., resN) -> (val1, ..., valN) [procedure] (val1, ..., valN) -> XptPopValue(widget, res1, ..., resN) XptPopValue is used to access or update multiple widget resources, performing type checking and any type conversion needed. For example, if shell is a shell widget, you can do the following: ;;; access mode XptPopValue(shell, XtN width, XtN height, XtN title) => ** 100 200 'hello' ;;; update mode 100,'goodbye' -> XptPopValue(shell, XtN width, XtN title); ;;; strings are converted, so you can do: 'red' -> XptPopValue(shell, XtN foreground); XptPopValue uses the information defined using XptSetPopValueTypes, as well as data supplied from XptResourceInfo to perform three things: 1. Type-checking access to widget resources. Accessing a non-existent resource using XptPopValue will generate a mishap. Additionally, assigning non-valid values to a resource will also generate a mishap. XptPopValueError can be used to make XptPopValue generate warnings instead of mishaps if desired. 2. Data coercion between Poplog and external representation. When you update a Boolean resource, you do so using a Poplog BOOL (ie. true or false). Similarly, accessing a Boolean resource will return a Poplog boolean. You just use the Poplog form of the data; XptPopValue performs automatic coercion. In cases where XptPopValue cannot determine the type and coercion of a resource, a default type of XptPointer is used. 3. Automatic resource conversion where needed. In updater mode, XptPopValue can be instructed to 'type' certain Poplog keys (by default, Poplog integers and strings are typed in this way). The X Toolkit detects such typing and attempts to convert between the type of the data and the representation type for the resource. This allows you to assign (otherwise invalid) strings to resources such as colours, fonts etc. XptPopValueError [procedure variable] Called by XptPopValue when it cannot find information about a resource, representation type etc. By default, this variable is assigned the value mishap, but it can be changed to warning or equivalent if desired. --------------- 5 Old XptValue --------------- XptValue is an old procedure for accessing or updating a single resource that predated the introduction of XptVal; it is less efficient than the in-line code generated by the latter. It remains in this file for the sole reason that it can do one thing XptVal cannot: deal with a run-time-variable type-spec. However, since this is almost never necessary, it is unlikely you will ever need to use XptValue. XptValue(widget, name, type) -> value [procedure] value -> XptValue(widget, name, type) fast_XptValue(widget, name, type) -> value [procedure] value -> fast_XptValue(widget, name, type) Sets or retrieves the value of a widget resource. The (fast_) XptValue procedure is a convenience routine that makes use of XtSetValues and XtGetValues to retrieve or update the value of a single resource. widget must be a live X Toolkit widget. name must be a string specifying a resource of the widget. Use of the * XtN string cache to specify the resource name will improve efficiency. The type argument is optional, but if present should be either a word or a type-spec as returned by the * TYPESPEC macro. If the type argument is omitted, XptValue will assume the type is "int". Use words to specify the basic Poplog types such as "short", "uint", "byte", "exptr" etc. Full typespecs are necessary when the resource is an Xpt datatype such as a widget or a translation table, or when further operations are needed to convert the value to/from C and Poplog representations (eg strings). --- C.x/x/pop/ref/xpt_resource --- Copyright University of Sussex 1992. All rights reserved.