Object Handling
===============

   Since MUI uses BOOPSI as object oriented programming system, objects
could simply be created using intuition.library/NewObject().  However,
`muimaster.library' also features a generation function called

     Object * MUI_NewObjectA(STRPTR class, struct TagItem *taglist);

with the varargs stub
     Object * MUI_NewObject(STRPTR class, Tag tag1, ..., TAG_DONE);

   That's the function you should use when creating objects of public
MUI classes. The parameter `class' specifies the name of the object's
class (e.g. `MUIC_Window', `MUIC_Slider', ...).  If the needed class
isn't already in memory, it is automatically loaded from disk.

   With `taglist', you specify initial create time attributes for your
object. Every attribute from the objects true class or from one of its
super classes is valid here, as long as it's marked with the letter `I'
in the accompanying autodocs documentation.

   To create a string object with a string-kind frame, a maximum length
of 80 and the initial contents "foobar", you would have to use the
following command:

     MyString = MUI_NewObject(MUIC_String,
                    MUIA_Frame          , MUIV_Frame_String,
                    MUIA_String_Contents, "foobar",
                    MUIA_String_MaxLen  , 80,
                    TAG_DONE);

   Once your object is ready, you can start talking to it by setting or
getting one of its attributes or by sending it methods. The standard
BOOPSI functions `SetAttrs()', `GetAttr()' and `DoMethod()' are used
for these purposes:

        char *contents;
        SetAttrs(MyString,MUIA_String_Contents,"look",TAG_DONE);
        GetAttr(MUIA_String_Contents,MyString,&contents);
        printf("Always %s on the bright side of life.",contents);
     
        DoMethod(mylist,MUIM_List_Remove,42); /* remove entry nr 42 */

   As already mentioned above, all attributes and methods are completely
documented in the autodocs coming with this distribution. These
autodocs follow the usual format, you can parse them with one of the
various tools to create some hypertext online help for your favourite
editor.

   When you're done with an object, you should delete it with a call to

     VOID MUI_DisposeObject(Object *obj);

from `muimaster.library'. After doing so, the object pointer is invalid
and must no longer be used.

   When deleting objects, the parent-child connections mentioned above
play an important role. If you dispose an object with children, not
only the object itself but also all of its children (and their
children, and the children of their children ...) get deleted. Since in
a usual MUI application, the application object is the father of every
window, the window is the father of it's contents and every group is
the father of its sub objects, a single dispose of the application
object will free the entire application.

   Note well: you may *not* delete objects that are currently children
of other objects. Thus, if you have a complete application tree, the
only thing you can delete is the application object itself as this one
has no father. You can, however, add and remove children dynamically.
More information on that topic follows later in this document.