REF XPT_TYPECHECK Adrian Howard, Aug 90 Revised: J. Meyer, Jan 91 Revised: Adrian Howard, Jul 92 COPYRIGHT University of Sussex 1993. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< TYPE CHECKING ROUTINES >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< FOR X DATA STRUCTURES >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< This REF file details the library LIB * XPT_TYPECHECK which provides type recognition and/or checking procedures for most of the datatypes used in the Poplog X Interface. CONTENTS - (Use g to access required sections) 1 Recognition vs Type Checking 2 General XptDescriptor Type-Checking 3 Autoloadable Type-Checking Procedures 4 LIB XPT_TYPECHECK 4.1 "Weak" Type-Checking Procedures 4.2 Type-Checking Of Lists Structures 4.3 Type-Checking Of Procedures 4.4 Type-Checking Integer Types 4.5 Others ------------------------------- 1 Recognition vs Type Checking ------------------------------- The recognition procedures return false when supplied with an item which is not of the correct type. Type checking procedures * mishap with an appropriate error message if the supplied item is not of the correct type. Both kinds of procedures will return the item itself if it is the correct type. -------------------------------------- 2 General XptDescriptor Type-Checking -------------------------------------- The following autoloadable procedures are used for testing the * XptDataType of XptDescriptor structures. For details of the "weak" type-checking of XptDescriptors, see REF * XptDescriptor. XptIsType(item, type) -> item [procedure] XptIsLiveType(item, type) -> item [procedure] Returns item if it is an external pointer class object with an * XptDataType field of type, otherwise returns false. The * XptIsLiveType procedure additionally checks that the object is live (ie. it has a non-null external pointer field), and will return false if item is not live. XptTypeCheck(item, type) -> item [procedure] This procedure will return item if it has an * XptDataType of type, otherwise the procedure will produce a 'type NEEDED' mishap. XptLiveTypeCheck(item, type) -> item [procedure] This procedure will return the Poplog object item if it has an * XptDataType of type type and the item is "live" (ie, its external pointer is not null.) If this is not the case the procedure will produce a 'LIVE type NEEDED' mishap. ---------------------------------------- 3 Autoloadable Type-Checking Procedures ---------------------------------------- The following autoloadable type-checking procedures are available: XptCheckWidget(item) -> item [procedure] Checks that item is a live * XptWidget (ie. an XptDescriptor with a non-null pointer and an * XptDataType of * XDT_WIDGET.) Will mishap with the message '(LIVE) Widget NEEDED' if item is not am XptWidget, otherwise item is returned. XptCheckWindowedWidget(item) -> item [procedure] As for * XptCheckWidget, but will * mishap unless item is also a subclass of the Core widget class (compare with * XtIsWidget.) XptCheckWidgetClass(item) -> item [procedure] Checks that item is a live * XptWidgetClass (ie. an XptDescriptor with a non-null pointer and an * XptDataType of * XDT_WIDGETCLASS.) Will mishap with the message '(LIVE) WidgetClass NEEDED' if item is not am XptWidgetClass, otherwise item is returned. XptCheckString(item) -> item [procedure] This procedure will return the Poplog object item if it is a Pop-11 string, otherwise the procedure will mishap with a 'STRING NEEDED' message. XptCheckShort(item) -> item [procedure] XptCheckUnsignedShort(item) -> item [procedure] Returns item if it as Poplog integer which is within the range of a (signed or unsigned) machine short integer, which is usually 16 bits in length. If it is not an integer in the correct range the procedure will mishap. XptCheckInt(item) -> item [procedure] XptCheckUnsignedInt(item) -> item [procedure] Returns item if it as Poplog integer which is within the range of a (signed or unsigned) int, which is usually 32 bits in length. If it is not an integer in the correct range the procedure will mishap with an 'INTEGER NEEDED' message. XptCheckUnsignedIntegral(item) -> item [procedure] Returns the Poplog object item if it is an unsigned long integer as used by the X Toolkit, otherwise they will mishap with a 'UNSIGNED LONG INTEGER NEEDED' message. In all current implementations an unsigned long is the same as an unsigned int, ie 32 bits in length. -------------------- 4 LIB XPT_TYPECHECK -------------------- The following type-checking procedures are provided by the library LIB * XPT_TYPECHECK: 4.1 "Weak" Type-Checking Procedures ------------------------------------ XptCheckActionHookId(item) -> item [procedure] XptCheckActionList(item) -> item [procedure] XptCheckAppContext(item) -> item [procedure] XptCheckAppContextPtr(item) -> item [procedure] XptCheckArgList(item) -> item [procedure] XptCheckCacheRefList(item) -> item [procedure] XptCheckCacheRefPtr(item) -> item [procedure] XptCheckCallbackList(item) -> item [procedure] XptCheckCardinalPtr(item) -> item [procedure] XptCheckConvertArgList(item) -> item [procedure] XptCheckDisplayPtr(item) -> item [procedure] XptCheckGCValuesPtr(item) -> item [procedure] XptCheckInputId(item) -> item [procedure] XptCheckIntervalId(item) -> item [procedure] XptCheckOptionDescList(item) -> item [procedure] XptCheckPositionPointer(item) -> item [procedure] XptCheckResourceList(item) -> item [procedure] XptCheckResourceListPtr(item) -> item [procedure] XptCheckScreenPtr(item) -> item [procedure] XptCheckStringList(item) -> item [procedure] XptCheckSubstitution(item) -> item [procedure] XptCheckTimePtr(item) -> item [procedure] XptCheckTranslations(item) -> item [procedure] XptCheckValuePtr(item) -> item [procedure] XptCheckVarArgsList(item) -> item [procedure] XptCheckWidgetList(item) -> item [procedure] XptCheckWindow(item) -> item [procedure] XptCheckWorkProcId(item) -> item [procedure] XptCheckXEventPtr(item) -> item [procedure] XptCheckXrmDatabase(item) -> item [procedure] The above routines act like * XptTypeCheck but for specific XptDataTypes. Each procedure XptChecktype will return the Poplog object item if it has an * XptDataType of "type". Otherwise the procedure will produce a * mishap. See REF * XPT_CONSTANTS for details of possible XptDataTypes. XptCheckValidValuePtr(item) -> item [constant] Just like * XptCheckValuePtr this procedure checks that item is a live * XptXrmValuePtr structure (ie. an XptDescriptor with a non-null pointer and an * XptDataType of * XDT_VALUEPTR.) Additionally XptCheckValidValuePtr checks that the * XptXVAddr field of the XptXrmValuePtr is also a valid. If item is not an XotXrmValuePtr, or its XptXVAddr field is not valid, then a * mishap occurs. 4.2 Type-Checking Of Lists Structures -------------------------------------- XptCheckArgListAndCardinal(list or vector) -> (arglist, len) [procedure] XptCheckArgListAndCardinal(arglist, len) -> (arglist, len) [procedure] This procedure expects Xt argument list data either as a Pop-11 list or vector, or as an * XptArgList shadowclass plus its integer length. In the former case the argument is processed using * XptArgList (see REF * XT_LIBS) and the resultant * XptArgList and length returned. In the latter the arguments supplied are checked and returned. If type-checking fails, a * mishap occurs. Compare with * CHECKARGLIST. CHECKARGLIST [macro] A macro for calling * XptCheckArgListAndCardinal as a * dlocal expression to handle * XptArgList call forms. Equivalent to: dlocal 0 % if dlocal_context == 1 then XptCheckArgListAndCardinal() endif, %; XptCheckVarargs(n) [procedure] This procedure mishap unless the top n items on the user stack form a variable length argument list (as taken by procedures like * XtVaAppInitialize, see REF * XT_APPINIT). XptCheckNTStringList(item) -> item [procedure] Returns item if it is a null-terminated * XptStringList structure, will * mishap otherwise. XptCheckNTCallbackList(item) -> item [procedure] Returns item if it is a null-terminated * XptCallbackList structure, will * mishap otherwise. XptCheckNTCacheRefList(item) -> item [procedure] Returns item if it is a null-terminated * XptCacheRefList structure, will * mishap otherwise. XptCheckResourceListAndLength(item, length) [procedure] -> (item, length) Returns item and length if item is an * XptResourceList structure of length length or less. length must be positive integer. The procedure will * mishap under all other conditions. XptCheckActionListAndLength(item, length) [procedure] -> (item, length) Returns item and length if item is an * XptActionList structure of length length or less. length must be positive integer. The procedure will * mishap under all other conditions. XptCheckStringListAndLength(item, length) [procedure] -> (item, length) Returns item and length if item is an * XptStringList structure of length length or less. length must be positive integer. The procedure will * mishap under all other conditions. XptCheckOptionDescListAndLength(item, length) [procedure] -> (item, length) Returns item and length if item is an * XptOptionDescList structure of length length or less. length must be positive integer. The procedure will * mishap under all other conditions. XptCheckWidgetListAndLength(item, length) [procedure] -> (item, length) Returns item and length if item is an * XptWidgetList structure of length length or less. length must be positive integer. The procedure will * mishap under all other conditions. XptCheckConvertArgListAndLength(item, length) [procedure] -> (item, length) Returns item and length if item is an * XptConvertArgList structure of length length or less. length must be positive integer. The procedure will * mishap in under other conditions. XptCheckValueListAndLength(item, length) [procedure] -> (item, length) Returns item and length if item is an * XptXrmValueList structure of length length or less. length must be positive integer. The procedure will * mishap in under other conditions. 4.3 Type-Checking Of Procedures -------------------------------- XptCheckProcedure(item) -> item [procedure] This procedure will return the Poplog object item if it is a Pop-11 procedure or external procedure, otherwise the procedure will mishap. XptCheckFilePredicate(item) -> item [procedure] This procedure will the return the Poplog object item if it is a procedure, external procedure or the value false, otherwise it will * mishap with the message 'FALSE OR PROCEDURE NEEDED'. 4.4 Type-Checking Integer Types -------------------------------- XptCheckGrabKind(item) -> item [procedure] This procedure will return the Poplog object item if it is a GrabKind. A GrabKind specifies the way input can be accepted by certain widgets and is an integer value between 0 and 2. If item is not a GrabKind then the procedure will mishap with a 'GrabKind NEEDED' message. XptCheckListPosition(item) -> item [procedure] This procedure will return the Poplog object item if it is a ListPosition. A ListPosition is used to specify when an event handler is called with respect to previously registered event handlers (see * XtInsertEventHandler & * XtInsertRawEventHandler). Its value is one of the constants XtListHead or XtListTail (see REF * XT_CONSTANTS.) XptCheckModifiers(item) -> item [procedure] XptCheckCardinal(item) -> item [procedure] XptCheckPosition(item) -> item [procedure] XptCheckGCMask(item) -> item [procedure] XptCheckCacheType(item) -> item [procedure] All the above procedure will return the Poplog object item if it is a unsigned integer, otherwise they will mishap with a 'UNSIGNED INTEGER NEEDED' message. In the current implementation an unsigned integer is 32 bits in length. XptCheckCursor(item) -> item [procedure] XptCheckGC(item) -> item [procedure] XptCheckTime(item) -> item [procedure] XptCheckInputMask(item) -> item [procedure] XptCheckEventMask(item) -> item [procedure] All the above procedures will return the Poplog object item if it is an unsigned long integer as used by the X Toolkit, otherwise they will mishap with a 'UNSIGNED LONG INTEGER NEEDED' message. In the current implementation an unsigned long is the same as an unsigned int, ie. 32 bits in length. XptCheckKeyCode(item) -> item [procedure] This procedure will the Poplog object item if it is a KeyCode. A KeyCode represents a character input to X and is represented by an integer between 0 and 255. If item is not a KeyCode the procedure will mishap with a 'KeyCode NEEDED' message. 4.5 Others ----------- XptCheckDevice(item) -> item [procedure] This procedure will return the Poplog object item if it is a device (ie, isdevice(item)==true). If item is not a device then the procedure will mishap with a 'DEVICE NEEDED' message. --- C.x/x/pop/ref/xpt_typecheck --- Copyright University of Sussex 1993. All rights reserved.