home *** CD-ROM | disk | FTP | other *** search
/ ETO Development Tools 2 / ETO Development Tools 2.iso / Tools - Objects / MacApp / MacApp CD Release / MacApp 2.0.1 (Many Libraries) / Interfaces / CIncludes / UObject.h < prev    next >
Encoding:
C/C++ Source or Header  |  1990-10-25  |  13.9 KB  |  287 lines  |  [TEXT/MPS ]
  1. /*[a-,body+,h-,o=100,r+,rec+,t=4,u+,#+,j=20/57/1$,n-]*/
  2. /* UObject.p */
  3. /* Copyright © 1984-1990  Apple Computer, Inc.  All rights reserved. */
  4. #ifndef  __UObject__
  5. #define __UObject__  0
  6. #endif
  7. #if  ! __UObject__
  8. #define __UObject__  1
  9.  
  10.         /* • Auto-Include the requirements for this unit's interface. */
  11. #ifndef  __UMacAppUtilities__
  12. #include "UMacAppUtilities.h"
  13. #endif
  14. #ifndef  __MEMORY__
  15. #include "Memory.h"
  16. #endif
  17.  
  18. const short kFailNone            = 1;
  19. const short kFailAbstract        = 2;
  20. const short kFailCoercion        = 3;
  21. const short kFailMethNotFound    = 4;
  22.  
  23. const unsigned char kInvalidObj[]          = "\p*Not an object*";
  24.    /* return value from LookupObjName if not an
  25.                                                          object*/
  26. const short kNilClass            = 0;
  27.    /* Value for superclass of the root object */
  28.  
  29. typedef unsigned short ObjClassID;                        /* Object Class identifier. The first two
  30.                                                          bytes of each object contain the class of
  31.                                                          the object as an ObjClassID. */
  32. typedef ObjClassID *ObjClassIDPtr;                        /* Preferred */
  33. typedef ObjClassIDPtr *ObjClassIDHandle;                /* Preferred */
  34. typedef ObjClassIDPtr PObjClassID;                        /* Left in for compatibility (2.0) */
  35. typedef ObjClassIDHandle HObjClassID;                    /* Left in for compatibility (2.0) */
  36.  
  37. /*--------------------------------------------------------------------------------------
  38.    ------------*/
  39.             /* Definition of the system's root object */
  40.  
  41.  
  42. class TObject : public PascalObject {
  43.   public:
  44.     virtual pascal TObject *Clone(void);
  45.  
  46.         /* Makes a duplicate copy of SELF. The default calls SELF.ShallowClone, which makes a
  47.                 literal copy of instance variables but does not attempt to clone owned objects. A
  48.                 subclass which owns other objects should override this to clone the owned objects
  49.                 and data structures as well. */
  50.  
  51.     virtual pascal void Fields(pascal void (*DoToField)(StringPtr fieldName, Ptr fieldAddr, short 
  52.        fieldType, void *DoToField_StaticLink), void *DoToField_StaticLink);
  53.                 /* Calls DoToField once for each instance variable in SELF. fieldName is a string
  54.                 representing the name of the variable. fieldAddr is the address of that variable.
  55.                 fieldType is one of the types defined in UMacAppUtilities. It is legal to use a
  56.                 local variable to hold data and pass the address of that variable to DoToField as
  57.                 if it were part of the object's instance variables. By convention, the first call
  58.                 to DoToField should have the class name as the fieldName, NIL as the fieldAddr, and
  59.                 bClass as the fieldType. Each subclass should override this method, particularly
  60.                 with qDebug on, dump its own information, then call INHERITED. */
  61.  
  62.     virtual pascal void DynamicFields(pascal void (*DoToField)(StringPtr fieldName, Ptr fieldAddr, 
  63.        short fieldType, void *DoToField_StaticLink), void *DoToField_StaticLink);
  64.                 /* Used by the Inspector and the Debugger to display the contents of this class's
  65.                 dynamic area. Defaults to nothing.  Override if your object uses the dynamic area
  66.                 See TList for an example. */
  67.  
  68.     virtual pascal void ForAllSubClassesDo(pascal void (*DoToSubClass)(ObjClassID theClass, void *
  69.        DoToSubClass_StaticLink), void *DoToSubClass_StaticLink);
  70.  
  71.         /* Calls DoToSubClass for each subclass of SELF. The order of traversal is arbitrary;
  72.                 see EachSubClass global procedure. */
  73.  
  74.     virtual pascal void ForAllSuperClassesDo(pascal void (*DoToSubClass)(ObjClassID theClass, void *
  75.        DoToSubClass_StaticLink), void *DoToSubClass_StaticLink);
  76.  
  77.        /* Calls DoToSubClass for each superclass of SELF. The order of traversal is the order
  78.                 of ancestry starting from the class of SELF; see EachSuperClass global procedure. */
  79.  
  80.     virtual pascal void Free(void);
  81.                 /* Called to dispose of an object. Gives object a chance to cleanup after itself.
  82.                 Default simply calls SELF.ShallowFree, which makes no attempt to free instance
  83.                 variables. Should be overridden by any class which allocates space or owns other
  84.                 objects in its instance variables.. Be sure to call INHERITED! */
  85.  
  86.     virtual pascal ObjClassID GetClass(void);
  87.                 /* Returns the class ID of SELF. */
  88.  
  89.     virtual pascal void GetClassName(StringPtr clName);
  90.                 /* Returns the class name of SELF. */
  91.  
  92.     virtual pascal Size GetClassSize(void);
  93.                 /* Returns the basic instantiation size. i.e. the size in bytes of a newly created
  94.                 object of this class */
  95.  
  96.     virtual pascal Ptr GetDynamicPtr(void);
  97.                 /* Our objects have a dynamic area available. In 2.0 it is at the end of the object
  98.                 handle but it may not always be so.  Returns a direct heap pointer to the start
  99.                 of the dynamic area.  Use with caution as this pointer can be invalidated if the
  100.                 heap compacts. */
  101.  
  102.     virtual pascal Size GetDynamicSize(void);
  103.                 /* Our objects can have a dynamic area that can be allocated with a SetDynamicSize
  104.                 call.  Returns the size of the dynamic area in bytes. Preferred. */
  105.  
  106.     virtual pascal Size GetInstanceSize(void);
  107.                 /* Our objects have a dynamic area after all the fixed fields. Returns the current
  108.                 size in bytes of this instance accounting for the dynamic area.
  109.                 Left in for compatibility (2.0)  */
  110.  
  111.     virtual pascal ObjClassID GetSuperClass(void);
  112.                 /* Returns immediate superclass of class. Returns kNilClass for TObject. If we ever
  113.                 get MI this will have to be an enumerator. */
  114.  
  115.     virtual pascal void GetInspectorName(StringPtr inspectorName);
  116.                 /* Returns additional information useful to the inspector. For instance (ha ha!) a
  117.                 TDocument could give its title. */
  118.  
  119.     virtual pascal void Initialize(void);
  120.                 /* Call this to put a newly created object into a known state. Subclasses should
  121.                 override it and call INHERITED. Typically used to put the object into a state where
  122.                 it can be safely FREED. Defaults to nothing. */
  123.  
  124.     virtual pascal void Inspect(void);
  125.                 /* Called from the debugger. Displays the fields of the object in the writeln window
  126.                 by calling the object's Fields method, passing InspectField as the DoToField
  127.                 routine. You can override this if you want to display any additional information in
  128.                 the writeln window when an object is inspected with the MacApp debugger. NOTE: this
  129.                 is not currently called from the "Inspector".*/
  130.  
  131.     virtual pascal void IObject(void);
  132.                 /* The ancestral initializer. Should be called in the I<ClassName> chain. i.e. IView
  133.                 -> IEvtHandler -> IOBJECT */
  134.  
  135.     virtual pascal Boolean IsMemberClass(ObjClassID testClass);
  136.                 /* True if I am a MEMBER of the testClass. i.e. the same class OR a subclass. */
  137.  
  138.     virtual pascal Boolean IsSameClass(ObjClassID testClass);
  139.                 /* True if I belong to the immediate class. */
  140.  
  141.     virtual pascal Boolean Lock(Boolean lockIt);
  142.                 /* Locks down or unlocks an object AND its dynamic area if any. Returns old state.
  143.                 Since objects can float around in memory some occasions may arise where they need
  144.                 to be locked down (The Inspect method is an example: since addresses of instance
  145.                 variables are being passed, the object had better not move during the Inspect!) 
  146.                 Typically the old state is saved in a local and re-applied when ascending the
  147.                 call chain. Don't forget to re-apply the old state from failure handlers.
  148.                 _PLEASE_ use this sparingly and don't just go locking stuff down willy-nilly just
  149.                 because you might be afraid of handles. */
  150.  
  151.     virtual pascal void SetDynamicSize(Size newSize);
  152.                 /* Set this instance's Dynamic Area size in bytes.  The dynamic area starts out
  153.                 unallocated. Signals Failure on memory error.  The size applies only to the size
  154.                 of the Dynamic Area. Preferred. */
  155.  
  156.     virtual pascal void SetInstanceSize(Size newSize);
  157.                 /* Set this instance's size in bytes. Thus changing the size of the dynamic area.
  158.                 Fails on attempts to set a size smaller than instantiation size and on memory
  159.                 error.   Left in for compatibility (2.0) */
  160.  
  161.     virtual pascal TObject *ShallowClone(void);
  162.  
  163.         /* Lowest level method for copying an object; should not be overridden except in very
  164.                 unusual cases. Simply calls HandToHand to copy the object data. */
  165.  
  166.     virtual pascal void ShallowFree(void);
  167.  
  168.         /* Lowest level method for freeing an object; should not be overridden except in very
  169.                 unusual cases. Simply calls Dispose (the Pascal builtin) to free the object. */
  170.  
  171. };
  172.  
  173. typedef TObject **TObjectPtr;                            /* Preferred */
  174. typedef TObjectPtr *TObjectHandle;                        /* Preferred */
  175. typedef TObjectPtr PTObject;                            /* Left in for compatibility (2.0) */
  176. typedef TObjectHandle HTObject;                            /* Left in for compatibility (2.0) */
  177.  
  178. /*--------------------------------------------------------------------------------------
  179.    ------------*/
  180.             /* Utility routines to support objects */
  181.  
  182. extern pascal Boolean AddNewObjectsToInspector(Boolean add);
  183.         /* Set to true (default) to automatically add all newly created objects to the inspector.
  184.         Function returns old setting. */
  185.  
  186. extern pascal Boolean AllocateObjectsFromPerm(Boolean allocateFromPerm);
  187.         /* Set to TRUE to make object allocation calls use Permanent memory (the default).
  188.         Set to false to make object allocation calls use temporary memory (if they cannot be
  189.         allowed to fail).  Returns old state */
  190.  
  191. extern pascal Boolean DisciplineMethodCalls(Boolean discipline);
  192.         /* Set to true to discipline all method calls that go through the dispatcher. Function r
  193.            eturns
  194.         old setting. */
  195.  
  196. extern pascal void EachClassDo(pascal void (*DoToClass)(ObjClassID theClass, void *
  197.    DoToClass_StaticLink), void *DoToClass_StaticLink);
  198.         /* Calls DoToClass for each class in the application */
  199.  
  200. extern pascal void EachSubClassDo(ObjClassID testClass, pascal void (*DoToClass)(ObjClassID theClass
  201.    , void *DoToClass_StaticLink), void *DoToClass_StaticLink);
  202.         /* Calls DoToClass for subclass of the test class. Uses EachClassDo, so the order of ite
  203.            ration
  204.         is not based on the class hierarchy but on the sequence of class IDs in the class table,
  205.  
  206.         Sorry… */
  207.  
  208. extern pascal void EachSuperClassDo(ObjClassID testClass, pascal void (*DoToClass)(ObjClassID 
  209.    theClass, void *DoToClass_StaticLink), void *DoToClass_StaticLink);
  210.         /* Calls DoToClass for superclass of the test class. Order of iteration is in order of
  211.         ancestry. */
  212.  
  213. extern pascal void FailNonObject(void *obj);
  214.         /* called by dispatcher to discipline an object. Invokes failure if parameter is not IsO
  215.            bject
  216.         */
  217.  
  218. extern pascal void FreeIfObject(TObject *obj);
  219.         /* IF obj <> NIL THEN obj.Free; useful for freeing an object that might sometimes be NIL. */
  220.  
  221. extern pascal void FreeObject(TObject *obj);
  222.         /* Synonym for FreeIfObject. Left in for compatibility (2.0) */
  223.  
  224. extern pascal Size GetClassSizeFromID(ObjClassID classID);
  225.         /* Given an object id, return the class's instantiation size. */
  226.  
  227. extern pascal void GetClassNameFromID(ObjClassID classID, StringPtr clName);
  228.         /* Given an object id, return the object's name. ??? add error checking ??? */
  229.  
  230. extern pascal ObjClassID GetClassIDFromName(StringPtr clName);
  231.         /* Given an object name, return its id. */
  232.  
  233. extern pascal ObjClassID GetClassID(TObject *obj);
  234.         /* Given an object, return the object's ClassID. */
  235.  
  236. extern pascal ObjClassID GetSuperClassID(ObjClassID objID);
  237.         /* returns immediate superclass of class. Returns kNilClass for TObject. If we ever get MI
  238.         this will have to be an enumerator. */
  239.  
  240. extern pascal void IDUobject(void);
  241.         /* Writeln UObject compile date */
  242.  
  243. extern pascal void InitUObject(void);
  244.         /* Essential one time initialization for this unit */
  245.  
  246. extern pascal void InspectObject(TObject *obj);
  247.         /* Called by debugger to inspect an object. NOTE: not currently called by the "inspector" */
  248.  
  249. extern pascal Boolean IsObject(void *obj);
  250.         /* Debugging check. Returns true if obj references a real object, false if obj is NIL or a
  251.         non-object reference. This is not an absloutely sure-fire test of objectness, but does
  252.         validate the following: (1) is it a handle? (2) is the handle non-purgeable? (3) is the
  253.         class ID valid? (4) is the handle size at least as large as the class size? */
  254.  
  255. extern pascal Boolean IsClassIDMemberClass(ObjClassID testClass, ObjClassID superClass);
  256.         /* tests the testClass for MEMBERship in the superclass */
  257.  
  258. extern pascal Boolean IsMemberClassID(TObject *obj, ObjClassID objID);
  259.        /* Returns true if obj references the class or a subclass of the class represented by ob
  260.           jID. */
  261.  
  262. extern pascal void OBJFail(short error);
  263.         /* Entered due (presumably) to some object failing a test for objectness. There are two 
  264.            codes
  265.         which result in a special message: kFailCoercion, which means that an object could not be
  266.         coerced to a class due to not being a subclass of that class; and kFailMethNotFound, which
  267.         means a method was called for a class, but that method is not defined for the class. Other
  268.         codes are allowed but are not given special treatment. In qDebug mode a ProgramBreak
  269.         preceeds the Failure. */
  270.  
  271. extern pascal TObject *NewObjectByClassId(ObjClassID classID);
  272.         /* Creates an object of the given class id */
  273.  
  274. extern pascal TObject *NewObjectByClassName(StringPtr className);
  275.         /* Creates an object of the given class name */
  276.  
  277. extern pascal Boolean VerboseIsObject(void *obj);
  278.         /* Debugging check. Indicate whether the parameter appears to really be an object and emit
  279.         diagnostics if it is not */
  280.  
  281. extern pascal void WrLblField(StringPtr fieldName, Ptr fieldAddr, short fieldType);
  282.         /* Writes the given field in the writeln window in the form: WRITE(fieldName, '=',
  283.  
  284.         valueAsString).*/
  285. #endif
  286.  
  287.