TABLE OF CONTENTS


    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

BST_System/BeastLibrary

NAME
          BeastLibrary -- Library for BEAST. (V1 Bravo)

COPYRIGHT
          Maverick Software Development

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


AUTHOR
          Jacco van Weert

CREATION DATE
          23-Apr-95

MODIFICATION HISTORY
          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.

NOTES



BeastLibrary/BST_AddClass

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

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

FUNCTION
          Add the Beast class to the Beast system.

INPUTS
          Class - Pointer to the class.

SEE ALSO
          BST_RemoveClass, BST_MakeClass


BeastLibrary/BST_ApplyTagChanges

NAME
          BST_ApplyTagChanges -- (V1 Alpha)

SYNOPSIS
          BST_ApplyTagChanges( list, changeList )
                               A0    A1

FUNCTION
          <Same as in the utility.library>

NOTES
          This routine is subject to change


BeastLibrary/BST_CloneTagItems

NAME
          BST_CloneTagItems -- (V1 Alpha)

SYNOPSIS
          clone = BST_CloneTagItems( original )
          D0                         A0

FUNCTION
          <Same as in the utility.library>

NOTES
          This routine is subject to change


BeastLibrary/BST_FillAttrTagList

NAME
          BST_FillAttrTagList -- (V1 Bravo)

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

FUNCTION
          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

INPUTS
          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
          Result - New MethodFlags

SEE ALSO



BeastLibrary/BST_FindTagItem

NAME
          BST_FindTagItem -- (V1 Alpha)

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

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


BeastLibrary/BST_FreeClass

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

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

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

INPUTS
          Class - Pointer to the class.

NOTES
          Before this routine BST_RemoveClass must be called.

BUGS
          No check if the Class is still in use.

SEE ALSO
          BST_RemoveClass, BST_MakeClass


BeastLibrary/BST_FreeTagItems

NAME
          BST_FreeTagItems -- (V1 Alpha)

SYNOPSIS
          BST_FreeTagItems( taglist )
                            A0

FUNCTION
          <Same as in the utility.library>

NOTES
          This routine is subject to change


BeastLibrary/BST_MakeClass

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

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

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

INPUTS
          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
          Result - The created class

SEE ALSO
          BST_FreeClass, BST_AddClass


BeastLibrary/BST_MakeSubClass

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

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

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

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

RESULT
          Result - The created sub class

SEE ALSO
          BST_FreeClass, BST_AddClass, BST_MakeClass


BeastLibrary/BST_NextTagItem

NAME
          BST_NextTagItem -- (V1 Alpha)

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

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

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


BeastLibrary/BST_RemoveClass

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

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

FUNCTION
          Unlink the Beast class from the list.

INPUTS
          Class - Pointer to the class.

SEE ALSO
          BST_AddClass, BST_FreeClass


BeastLibrary/CLSS_AddMethod

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

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

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

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

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

SEE ALSO
          CLSS_DisposeMethod


BeastLibrary/CLSS_DisposeMethod

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

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

FUNCTION
          Remove the method from the class.

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

SEE ALSO
          CLSS_AddMethod


BeastLibrary/CLSS_FindMethod

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

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

FUNCTION
          Search for a certain method ID.

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

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


BeastLibrary/OBJ_CreateConnection

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

SYNOPSIS
          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 );

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

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

SEE ALSO
          OBJ_RemoveConnection


BeastLibrary/OBJ_DestroyObject

NAME
          OBJ_DestroyObject -- Destroy an object. (V1 Alpha)

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

FUNCTION
          This function combines a OBM_DISPOSE method with a OBJ_DisposeObject
          call.

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

SEE ALSO
          OBJ_DoMethod, OBJ_DisposeObject


BeastLibrary/OBJ_DisposeObject

NAME
          OBJ_DisposeObject -- Dispose an object. (V1 Alpha)

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

FUNCTION
          Dispose this object AND all it's children.

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

RESULT
          This object AND the children objects are disposed.

NOTES
          This function will NOT perform an OBM_DISPOSE method.

SEE ALSO
          OBJ_NewObject, OBJ_DestroyObject


BeastLibrary/OBJ_DoMethod

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

SYNOPSIS
          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 );

FUNCTION
          Trigger a method on a certain object.

INPUTS
          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
          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

SEE ALSO
          OBJ_MethodToParent, OBJ_MethodToChildren


BeastLibrary/OBJ_FromInput

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

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

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

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

SEE ALSO
          OBJ_ToOutput, OBJ_CreateConnection


BeastLibrary/OBJ_MethodToChildren

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

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

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

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

NOTES

SEE ALSO
          OBJ_DoMethod


BeastLibrary/OBJ_MethodToParent

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

SYNOPSIS
          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 );

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

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

SEE ALSO
          OBJ_DoMethod


BeastLibrary/OBJ_NewObject

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

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

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

INPUTS
          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
          Result - Pointer to created object. NULL if the object could
                   not be added.

SEE ALSO
          OBJ_DisposeObject


BeastLibrary/OBJ_RemoveConnection

NAME
          OBJ_RemoveConnection -- (V1 Alpha)

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

FUNCTION
          Remove a created OIL_Connection or OOL_Connection.

INPUTS
          OxL_Connection - Pointer to an OIL/OOL_Connection.

RESULT
          The OIL_Connection and OOL_Connection structures are destroyed.

SEE ALSO
          OBJ_CreateConnection


BeastLibrary/OBJ_ToOutput

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

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

FUNCTION
          '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'.

INPUTS
          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
          Result = The new methodflags.

SEE ALSO
          OBJ_FromInput, OBJ_CreateConnection, OBJ_DoMethod


BeastLibrary/mth_AllocMem_BeastLibrary

NAME
          mth_AllocMem - Allocate a memory block. (V1 Bravo)

FUNCTION
          Use this function to allocate a memory block.

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

SEE ALSO
          mth_FreeMem_BeastLibrary


BeastLibrary/mth_ForEach_BeastLibrary

NAME
          mth_ForEach - (V1 Bravo)

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

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

SEE ALSO
          mth_GetEach_BeastLibrary



BeastLibrary/mth_FreeMem_BeastLibrary

NAME
          mth_FreeMem - Free a memory block. (V1 Bravo)

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

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

                BTA_MemHandle   - af[R]
                        The memory handle

SEE ALSO
          mth_AllocMem_BeastLibrary, mth_LockMem_BeastLibrary,
          mth_UnlockMem_BeastLibrary



BeastLibrary/mth_LockMem_BeastLibrary

NAME
          mth_LockMem - Lock a memory handle. (V1 Bravo)

FUNCTION
          Use this method to obtain the pointer to the memory.

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

SEE ALSO
          mth_UnlockMem_BeastLibrary, mth_AllocMem_BeastLibrary,
          mth_FreeMem_BeastLibrary


BeastLibrary/mth_UnlockMem_BeastLibrary

NAME
          mth_UnlockMem - Unlock a memory handle. (V1 Bravo)

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

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

SEE ALSO
          mth_LockMem_BeastLibrary, mth_AllocMem_BeastLibrary,
          mth_FreeMem_BeastLibrary