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 <ENTER> 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.
