BST_System/BeastLibrary
BeastLibrary/BST_AddClass
BeastLibrary/BST_ApplyTagChanges
BeastLibrary/BST_CloneTagItems
BeastLibrary/BST_FillAttrTagList
BeastLibrary/BST_FindTagItem
BeastLibrary/BST_FreeClass
BeastLibrary/BST_FreeTagItems
BeastLibrary/BST_MakeClass
BeastLibrary/BST_MakeSubClass
BeastLibrary/BST_NextTagItem
BeastLibrary/BST_RemoveClass
BeastLibrary/CLSS_AddMethod
BeastLibrary/CLSS_DisposeMethod
BeastLibrary/CLSS_FindMethod
BeastLibrary/OBJ_CreateConnection
BeastLibrary/OBJ_DestroyObject
BeastLibrary/OBJ_DisposeObject
BeastLibrary/OBJ_DoMethod
BeastLibrary/OBJ_FromInput
BeastLibrary/OBJ_MethodToChildren
BeastLibrary/OBJ_MethodToParent
BeastLibrary/OBJ_NewObject
BeastLibrary/OBJ_RemoveConnection
BeastLibrary/OBJ_ToOutput
BeastLibrary/mth_AllocMem_BeastLibrary
BeastLibrary/mth_ForEach_BeastLibrary
BeastLibrary/mth_FreeMem_BeastLibrary
BeastLibrary/mth_LockMem_BeastLibrary
BeastLibrary/mth_UnlockMem_BeastLibrary

          BeastLibrary -- Library for BEAST. (V1 Bravo)

          Maverick Software Development

          The BEAST engine.

                The method names are defined as follows;
                mth_[method name]_[class name]

                The following tokens are used to explain the methods.

                af[..] = Attribute flags;
                        R    = Required, must be supplied.
                        P    = When not available, the method will try retrieve it from it's parents.
                        S(n) = This tag is used/filled in by a superclass (n) of this class.
                        E    = When supplied the object will act more efficient.
                        D(n) = Default value when it's not supplied and it cannot be retrieved
                               from something else.
                        A    = Always supplied by the method.
                        F    = This tag is filled in by the method.
                        I    = BTF_Ignore flag is set when processed.
                        T(n) = Extra information about the typeof the tag.

          Jacco van Weert

          23-Apr-95

          27-Mar-96:    First release, V1 Alpha.
          16-Apr-96:    BST_FillAttrTagList, V1 Bravo.
                        OBM_ALLOCMEM, OBM_FREEMEM, OBM_LOCKMEM, OBM_UNLOCKMEM
                        OBM_FOREACH Methods V1 Bravo.
                        Library version 2.

          BST_AddClass -- Add a Beast class to the class list. (V1 Alpha)

          AddClass( Class )
                    A0
          void BST_AddClass( struct BST_Class * );

          Add the Beast class to the Beast system.

          Class - Pointer to the class.

          BST_RemoveClass, BST_MakeClass

          BST_ApplyTagChanges -- (V1 Alpha)

          BST_ApplyTagChanges( list, changeList )
                               A0    A1

          <Same as in the utility.library>

          This routine is subject to change

          BST_CloneTagItems -- (V1 Alpha)

          clone = BST_CloneTagItems( original )
          D0                         A0

          <Same as in the utility.library>

          This routine is subject to change

          BST_FillAttrTagList -- (V1 Bravo)

          Result = BST_FillAttrTagList( TagList, SupportedTags, Object, MethodFlags )
          D0                            A0       A1             A2,     D3

          This function can be used in assembler programs to process a TagList.
          The 'functions' are called with;
                D4 = Number of this filled item
                A0 = Pointer to { TAG, xxxx_data }
                A2 = Pointer to the object
                A3 = Pointer to the start of the TagList
                A5 = Pointer to the Instance

          TagList        - Pointer to the to be processed TagList
          SupportedTags  - Pointer to a Table with all the supported tags
                           ends with TAG_DONE.

                           Example:
                                dc.l    BTA_Size,  addr_GetSize
                                dc.l    BTA_Title, addr_GetTitle
                                dc.l    TAG_DONE
          Object         - Pointer to the object from which the instance is used.
          MethodFlags    - The MethodFlags, these are chanced when there is a
                           BTA_NumberOf tag, and it is neccesary.

          Result - New MethodFlags

          BST_FindTagItem -- (V1 Alpha)

          Result = BST_FindTagItem( tagValue, tagList )
          D0,A0                     D0        A0
          struct TagItem *BST_FindTagItem( ULONG, struct TagItem * );

          Same functionallity as the utility.library equivalent, added are
          special handling functions for the BEAST tags.

          BST_FreeClass -- Free a Beast class. (V1 Alpha)

          BST_FreeClass( Class )
                         A0
          void BST_FreeClass( struct BST_Class );

          Free the Beast class from the memory. Also deallocate all class related
          stuff. Such as the methods lists.

          Class - Pointer to the class.

          Before this routine BST_RemoveClass must be called.

          No check if the Class is still in use.

          BST_RemoveClass, BST_MakeClass

          BST_FreeTagItems -- (V1 Alpha)

          BST_FreeTagItems( taglist )
                            A0

          <Same as in the utility.library>

          This routine is subject to change

          BST_MakeClass -- Make a Beast class. (V1 Alpha)

          Result = BST_MakeClass( ClassID, InstanceSize )
          D0                      A0       D0
          struct BST_Class *BST_MakeClass( char *, ULONG );

          Defines a new public class, BST_AddClass must be called to add
          the class to the BEAST system.

          ClassID      - Class ID, pointer to the public-name.
                         Please choose this name carefully, otherwise a
                         conflict may occur.
                         Beast classes always are starting with a 'B'.
                         BST_,  BVS_, BFS_, ..etc..

          InstanceSize - The Instance size in bytes.

          Result - The created class

          BST_FreeClass, BST_AddClass

          BST_MakeSubClass -- Make a Beast subclass. (V1 Alpha)

          Result = BST_MakeSubClass( ClassID, InstanceSize, SuperClass )
          D0                         A0       D0            A1

          The same function as BST_MakeClass, only now this class is a subclass
          of 'SuperClass'. This superclass _must_ be added to the system, because
          at least 1 object is created of this class.

          ClassID      - Class ID, pointer to public-name.
          InstanceSize - The private class datasize in bytes.
          SuperClass   - The name of the SuperClass.

          Result - The created sub class

          BST_FreeClass, BST_AddClass, BST_MakeClass

          BST_NextTagItem -- (V1 Alpha)

          Result = BST_NextTagItem( tagList )
          D0,A0                     A0
          struct TagItem *BST_NextTagItem( struct TagItem * );

          Similar function as the one in the utility.library, only this
          takes care about some BEAST tags.

          Result - Pointer to the new position.
                   =NULL when end of TagList

          BST_RemoveClass -- Remove a Beast class from the class list. (V1 Alpha)

          BST_RemoveClass( Class )
                           A0
          void BST_RemoveClass( struct BST_Class * );

          Unlink the Beast class from the list.

          Class - Pointer to the class.

          BST_AddClass, BST_FreeClass

          CLSS_AddMethod -- Add a Method to a class. (V1 Alpha)

          Result = CLSS_AddMethod( Class, MethodStart, Method_ID )
          D0                       A0     A1           D0
          struct BST_Class CLSS_AddMethod( struct BST_Class *, ULONG *, BST_Method );

          Add a method to a class, every method may have several method-routines.
          The Beast system has a large number of pre-defined method ID's.
          There are a number of free slots for local methods. Please consider
          very carefully when using local methods ID. Those are not supported
          among other classes. Also _NEVER_ use method delegation (MTHF_DOPARENTS,
          MTHF_DOCHILDREN..etc..) when using local methods. In the BEAST OO system
          objects are _never_ sure who parents or children are, even if you add them
          yourself.
          Free slots for local method ID's:
                OBM_local0      =       0x00000040 - 0x0000007F
                OBM_local1      =       0x00000100 - 0x000007FF
                OBM_local2      =       0x00004000 - 0x00004FFF
                OBM_local3      =       0x00100000 - 0x001FFFFF

          The method ID's with the lowest number have the highest priority. In
          V1 Alpha the priority is not yet implemented, but it will be in the future.

          Class       - Pointer to the class.
          MethodStart - The start of the method routine.
          Method_ID   - The Method_ID number.

          Result - =NULL when Error.
                   <>NULL Class.

          CLSS_DisposeMethod

          CLSS_DisposeMethod -- Dispose a Method from a class. (V1 Alpha)

          CLSS_DisposeMethod( Class, MethodStart, Method_ID )
                              A0     A1           D0
          void CLSS_DisposeMethod( struct BST_Class *, ULONG *, BST_Method );

          Remove the method from the class.

          Class       - Pointer to the class.
          MethodStart - Start of the method routine.
          Method_ID   - Method ID number

          CLSS_AddMethod

          CLSS_FindMethod -- Find a Method in a class. (V1 Alpha)

          Result = CLSS_FindMethod( Class, Method_ID )
          D0,A0                     A0     D0
          struct class_MethodList *CLSS_FindMethod( struct BST_Class *, BST_Method );

          Search for a certain method ID.

          Class     - Pointer to the class.
          Method_ID - Method ID number.

          Result - Pointer to found CLSS_MethodList or NULL when the method
                   is not found.

          OBJ_CreateConnection -- Create a connection between two methods. (V1 Alpha)

          Result = OBJ_CreateConnection( FromObject, ToObject, FromMethod, ToMethod )
          D0                             A0          A1        D0          D1
          struct obj_OutputLink *OBJ_CreateConnection( struct BST_Object *, struct BST_Object *, BST_Method, BST_Method );

          Create a connection between two objects. Every Method can be connected to any
          other method. Connections between objects running at the same task will be
          a direct connection. When connecting to object of different task the routine
          will insert an intermediair (not implemented in V1 Alpha). The same when connecting
          between two objects at two different computer systems.
          A connection can have multiple inputs and outputs. But a things must be take into
          consideration. When a 'FromMethod' is connected to several other methods the
          TagList (which is the data) is shared among the connected objects, which means
          that if the first object changes something in the TagList, the others will also
          see it.

          FromObject - Pointer to the 'From' object.
          ToObject   - Pointer to the 'To' object
          FromMethod - The Method ID number of the FromObject.
          ToMethod   - The Method ID number of the ToObject.

          Result - 0 = An error has occured. Also when FromObject or ToObject
                       is zero. Otherwise, pointer to the obj_OutputLink.

          A double linked connection is created, an OIL_Connection
          and an OOL_Connection structure.

          OBJ_RemoveConnection

          OBJ_DestroyObject -- Destroy an object. (V1 Alpha)

          OBJ_DestroyObject( Object, MethodFlags )
                             A0      D3
          struct BST_Object *OBJ_DestroyObject( struct BST_Object *, BST_MethodFlags );

          This function combines a OBM_DISPOSE method with a OBJ_DisposeObject
          call.

          Object      - Pointer to the object to be destroyed.
          MethodFlags - MTHF_DOCHILDREN will be added by the function!!

          OBJ_DoMethod, OBJ_DisposeObject

          OBJ_DisposeObject -- Dispose an object. (V1 Alpha)

          OBJ_DisposeObject( Object )
                             A0
          void OBJ_DisposeObject( struct BST_Object * );

          Dispose this object AND all it's children.

          Object - The object to be disposed. May be NULL.

          This object AND the children objects are disposed.

          This function will NOT perform an OBM_DISPOSE method.

          OBJ_NewObject, OBJ_DestroyObject

          OBJ_DoMethod -- Perform a method on a object. (V1 Alpha)

          Result = OBJ_DoMethod( Object, Method_ID, TagList, MethodFlags )
                                 A0      D0         A1       D3
          BST_MethodFlags OBJ_DoMethod( struct BST_Object *, BST_Method, struct TagItem *, BST_MethodFlags );

          Trigger a method on a certain object.

          Object      - Pointer to the object (may NULL).
          Method_ID   - Method ID number.
          TagList     - Pointer to the TagList used by the Method routine.
          MethodFlags - Special method flags;
                                See the Beast:Docs/Beast_OO/Methods.doc

          Result = The new method flags

                        Method call with the following registers set;
                                D2 = Method_ID
                                D3 = MethodFlags
                                A2 = Object
                                A3 = TagList

          As a result the method must deliver the new MethodFlags in d0.
          Besides the discussed MethodFlags (INPUTS) there are some more;
                See the Beast:Docs/Beast_OO/Methods.doc

          OBJ_MethodToParent, OBJ_MethodToChildren

          OBJ_FromInput -- Trigger methods connections to an input. (V1 Alpha)

          OBJ_FromInput( Object, InputMethod, MethodFlags, TagList )
                         A0,     D0           D3           A1
          BST_MethodFlags OBJ_FromInput( struct BST_Object *, BST_Method, BST_MethodFlags, struct TagItem * );

          Request input from the method 'InputMethod', this will trigger ( if
          connected ) a method at the object connected to the 'InputMethod'.

          Object       - Pointer to the object.
          InputMethod  - The input method number.
          MethodFlags  - The Method flags, see OBJ_DoMethod.
          TagList      - The TagList put to the input/output-methods of the
                         connection.

          OBJ_ToOutput, OBJ_CreateConnection

          OBJ_MethodToChildren -- Delegate the method to the children. (V1 Alpha)

          Result = OBJ_MethodToChildren( Object, Method_ID, TagList, MethodFlags )
                                         A0      D0         A1       D3

          See DoMethod for full description. 
          This function pass the method to the children. This is used in a method
          definition when the MTHF_PASSTOCHILD flag is set.

          Object      - Pointer to the object (may NULL).
          Method_ID   - Method ID number.
          TagList     - Pointer to the TagList used by the Method routine.
          MethodFlags - Special method flags;

          Result = The new method flags

          Method call with the following registers set;

                D2 = Method_ID
                D3 = MethodFlags
                A2 = Object
                A3 = TagList

          As a result the method must deliver the new MethodFlags in d0.

          OBJ_DoMethod

          OBJ_MethodToParent -- Delegate the method to the parent. (V1 Alpha)

          Result = OBJ_MethodToParent( Object, Method_ID, TagList, MethodFlags )
                                       A0      D0         A1       D3
          BST_MethodFlags OBJ_MethodToParent( struct BST_Object *, BST_Method, struct TagItem *, BST_MethodFlags );

          See DoMethod for full description. 
          This function pass the method to the parent. In this way the method won't
          be triggered at the caller object. Remember to set the MTHF_DOPARENTS flags
          the method should be delegated to other parents as well.

          Object      - Pointer to the object (may NULL).
          Method_ID   - Method ID number.
          TagList     - Pointer to the TagList used by the Method routine.
          MethodFlags - Special method flags;

          Result = The new method flags

          Method call with the following registers set;

                D2 = Method_ID
                D3 = MethodFlags
                A2 = Object
                A3 = TagList

          As a result the method must deliver the new MethodFlags in d0.

          OBJ_DoMethod

          OBJ_NewObject -- Create a new object. (V1 Alpha)

          Result = OBJ_NewObject( Class, Class_ID, Parent )
          D0                      A0     A1        D0
          struct BST_Object *OBJ_NewObject( struct BST_Class *, char *, struct BST_Object * );

          Create a new object. The object is added 'under' the Parent. In version
          V1 Alpha multiple parents are not supported. If the Parent is null the
          object is added under the Beast root, or when the Beast FileSystem is
          available it's added under the UserClass.
          The object instance is allocated with MEMF_CLEAR, so the instance is cleared.

          Class    - Pointer to an already known class (private class)
                     NULL if not used. (normally NULL).
          Class_ID - Pointer to the name of the public class.
          Parent   - Pointer to the parent object or NULL.

          Result - Pointer to created object. NULL if the object could
                   not be added.

          OBJ_DisposeObject

          OBJ_RemoveConnection -- (V1 Alpha)

          OBJ_RemoveConnection( OxL_Connection )
                                A1
          void OBJ_RemoveConnection( struct obj_OutputLink * );

          Remove a created OIL_Connection or OOL_Connection.

          OxL_Connection - Pointer to an OIL/OOL_Connection.

          The OIL_Connection and OOL_Connection structures are destroyed.

          OBJ_CreateConnection

          OBJ_ToOutput -- Trigger methods connections to an output. (V1 Alpha)

          Result = OBJ_ToOutput( Object, TagList, OutputMethod, MethodFlags )
                                 A0      A1       D0            D3
          BST_MethodFlags OBJ_ToOutput( struct BST_Object *, struct TagItem *, BST_Method, BST_MethodFlags );

          'Output' the TagList (A1) to the connected input, the used output
          is the OutputMethod (D0). The object is triggered which is connected
          to 'Object' at MethodID 'OutputMethod'.

          Object       - Pointer to the object.
          TagList      - The TagList put to the input/output-method of the
                         connection.
          OutputMethod - The output method ID.
          MethodFlags  - The Method flags, see OBJ_DoMethod.

          Result = The new methodflags.

          OBJ_FromInput, OBJ_CreateConnection, OBJ_DoMethod

          mth_AllocMem - Allocate a memory block. (V1 Bravo)

          Use this function to allocate a memory block.

          TagList -
                BTA_MemSize     - af[D(0)]
                        The size of the to be allocated memory in bytes.

                BTA_MemFlags    - af[D(MEMF_PUBLIC)]
                        The memory flags of the memory.
                        The same as the one used by the exec.library AllocMem.
                        Extra flags;
                                MEMF_MOVEABLE_DISK
                                        The memory block may be swapped to
                                        slow memory (e.g. disk) when it's
                                        not locked.
                                MEMF_MOVEABLE_MEMORY
                                        The memory block may move around the
                                        systems memory when it's not locked.
                                MEMF_DISCARABLE
                                        The memory may be discard when it is
                                        not locked. So the whole memory will
                                        be released!.
                        These extra flags will be used by the BST_MemoryClass
                        and other memory handling classes.

                BTA_MemHandle   - af[RF]
                        On return this tag will hold the pointer to the
                        MemoryHandle. This is _not_ the pointer to the memory
                        block. One must OBM_LOCKMEM the handle to obtain the
                        actual pointer to the memory block.

          mth_FreeMem_BeastLibrary

          mth_ForEach - (V1 Bravo)

          Trigger the 'BTA_Method' of 'BTA_MainObject' for each of the
          'BTA_Object1's children objects. The supplied TagList is also
          send to the 'BTA_Method'. Every time 'BTA_Object2' is filled in
          with the current object. Only(!) the children of BTA_Object1 are
          processed, not the childrens children.
          If the OBM_FOREACH must work recursive throughout the whole
          children tree, the 'BTA_Method' must do an OBM_FOREACH method again
          and must replace BTA_Object1 with the value of BTA_Object2.
          The BST_SearchClass has an example how to do this.

          TagList -
                BTA_MainObject  - af[R]
                  Method 'BTA_Method' is this object is always triggered for
                  object. Mostly this is the object from which the OBM_FOREACH
                  method is triggered.
                BTA_Method      - af[R]
                  This method is triggered on 'BTA_MainObject'.
                BTA_Object1     - af[R]
                  The start point of the OBM_FOREACH method. The children
                  objects of _this_ object are processed.
                BTA_Object2     - af[FR]
                  The tag is always filled with the current child object.
                  With this tag the called method can find out which object
                  the OBM_FOREACH has processed.

          mth_GetEach_BeastLibrary

          mth_FreeMem - Free a memory block. (V1 Bravo)

          Use this function to free a memory block, allocate by the
          OBM_ALLOCMEM method.

          TagList -
                BTA_MemSize     - af[R]
                        The size of the memory in bytes.

                BTA_MemHandle   - af[R]
                        The memory handle

          mth_AllocMem_BeastLibrary, mth_LockMem_BeastLibrary,
          mth_UnlockMem_BeastLibrary

          mth_LockMem - Lock a memory handle. (V1 Bravo)

          Use this method to obtain the pointer to the memory.

          TagList -
                BTA_MemHandle   - af[R]
                        The MemoryHandle supplied by the OBM_ALLOCMEM method.
                BTA_MemBlock    - af[F]
                        When the method is finished this tag will hold the
                        pointer to the physical memory.

          mth_UnlockMem_BeastLibrary, mth_AllocMem_BeastLibrary,
          mth_FreeMem_BeastLibrary

          mth_UnlockMem - Unlock a memory handle. (V1 Bravo)

          Use this method to 'given' back your memory. After this method has
          been called you MAY NOT use the memory. You must lock it first again.

          TagList -
                BTA_MemHandle   - af[R]
                        The MemoryHandle supplied by the OBM_ALLOCMEM method.

          mth_LockMem_BeastLibrary, mth_AllocMem_BeastLibrary,
          mth_FreeMem_BeastLibrary