\section{muimaster.library}

\subsubsection*{PURPOSE}
muimaster.library contains functions for creating and diposing
objects, for requester handling and for controlling custom
classes. Additionally, several of the standard MUI classes are
built into muimaster.library. For you as a programmer, there
is no difference between using a builtin class or an external
class coming as ''sys:classes/<foobar>.mui''. The MUI object
generation call takes care of this situation and loads
external classes automatically when they are needed.


\subsection[MUI\_AllocAslRequest]{MUI\_AllocAslRequest}

\subsubsection*{FUNCTION}
Provide an interface to asl.library. Using this ensures
your application will benefit from future expansions
to MUI's window and iconification handling.

\subsubsection*{SEE ALSO}
asl.library/AllocAslRequest


\subsection[MUI\_AslRequest]{MUI\_AslRequest}

\subsubsection*{FUNCTION}
Provide an interface to asl.library. Using this ensures
your application will benefit from future expansions
to MUI's window and iconification handling.

\subsubsection*{SEE ALSO}
asl.library/AslRequest


\subsection[MUI\_CreateCustomClass]{MUI\_CreateCustomClass -- create a public/private custom class.}

\subsubsection*{SYNOPSIS}
\begin{tabbing}
MUI\_CreateCustomClass (\=base, \=supername, \=supermcc, \=datasize, \=dispfunc)\\
\>A0    \>A1        \>A2        \>D0        \>A3
\end{tabbing}

struct MUI\_CustomClass $\ast$ MUI\_CreateCustomClass(
struct Library $\ast$, char $\ast$, int, APTR );

   \subsubsection*{FUNCTION}
This function creates a public or private MUI custom class.
Public custom classes are shared libraries and can be found
in ''libs:mui/<foobar>.mcc''. Private classes simply consist
of a dispatcher and are built into applications.

MUI\_CreateCustomClass() returns a pointer to a struct
MUI\_CustomClass which in turn contains a pointer to a
struct IClass. For private classes, this struct IClass
pointer needs to be fed to a intuition.library/NewObject()
call to create new objects.

MUI creates the dispatcher hook for you, you may {\bf not}
use the IClass->cl\_Dispatcher.h\_Data field! If you need
custom data for your dispatcher, use the cl\_UserData
of the IClass structure or the mcc\_UserData of the
MUI\_CustomClass structure.

For public classes, MUI makes sure that a6 contains
a pointer to your library base when your dispatcher
is called. For private classes, you will need to keep
track of A4 of similiar things your compiler may
need yourself.

\subsubsection*{INPUTS}
\begin{description}
\item[base] =      if you create a public class, you have to call
MUI\_CreateCustomClass() from your libraries
init function. In this case, place your library
base pointer here. For private classes, you must
supply NULL.

\item[supername] = super class of your class. This can either
be a builtin MUI class (''xyz.mui'') or a external
custom class (''xyz.mcc'').

\item[supermcc] =  if (and only if) the super class is a private
custom class and hence has no name, you are allowed
to pass a NULL supername and a pointer to the
MUI\_CustomClass structure of the super class here.

\item[datasize] =  size of your classes data structure.

\item[dispfunc] =  your classes dispatcher function (no hook!).
The dispatcher will be called with a struct IClass
in a0, with your object in a2 and the message in a1.
\end{description}

\subsubsection*{RESULT}
A pointer to a struct MUI\_CustomClass or NULL to indicate
an error.

\subsubsection*{SEE ALSO}
MUI\_DeleteCustomClass()


\subsection[MUI\_DeleteCustomClass]{MUI\_DeleteCustomClass -- delete a public/private custom class.}

\subsubsection*{SYNOPSIS}
\begin{tabbing}
MUI\_DeleteCustomClass ( \=mcc )\\
\>A0
\end{tabbing}

BOOL MUI\_DeleteCustomClass(struct MUI\_CustomClass $\ast$);

   \subsubsection*{FUNCTION}
Delete a public or private custom class. Note that you
must not delete classes with outstanding objects or sub
classes.

\subsubsection*{INPUTS}
\begin{description}
\item[mcc] = pointer obtained from MUI\_CreateCustomClass().
\end{description}
   
\subsubsection*{RESULT}
TRUE if all went well, FALSE if some objects or
sub classes were still hanging around. Nothing
will be freed in this case.

\subsubsection*{SEE ALSO}
MUI\_CreateCustomClass()


\subsection[MUI\_DisposeObject]{MUI\_DisposeObject -- Delete a MUI object.}

\subsubsection*{SYNOPSIS}
\begin{tabbing}
MUI\_DisposeObject( \=object )\\
\>A0
\end{tabbing}
   
VOID MUI\_DisposeObject( APTR );

   \subsubsection*{FUNCTION}
Deletes a MUI object and all of it's auxiliary data.
These objects are all created by MUI\_NewObject(). Objects
of certain classes ''own'' other objects, which will also
be deleted when the object is passed to MUI\_DisposeObject().
Read the per-class documentation carefully to be aware
of these instances.

\subsubsection*{INPUTS}
\begin{description}
\item[object] = abstract pointer to a MUI object returned by
MUI\_NewObject(). The pointer may be NULL, in which case
this function has no effect.
\end{description}

\subsubsection*{RESULT}
None.

\subsubsection*{SEE ALSO}
MUI\_NewObject(), SetAttrs(), GetAttr().


\subsection[MUI\_Error]{MUI\_Error -- Return extra information from the MUI system.}

\subsubsection*{SYNOPSIS}
LONG MUI\_Error(VOID);

   \subsubsection*{FUNCTION}
Some MUI functions will set an error if they fail for
some reason. The error functions is task sensitive,
only the task that caused the error will receive it
from this function.

\subsubsection*{RESULT}
Currently, the following error values are defined:

\begin{center} \begin{tabular}{lcl}
MUIE\_OK                  &-& no error, everything allright.\\
MUIE\_OutOfMemory         &-& went out of memory.\\
MUIE\_OutOfGfxMemory      &-& went out of graphics memory.\\
MUIE\_InvalidWindowObject &-& NULL window specified.\\
MUIE\_MissingLibrary      &-& can't open a needed library.\\
MUIE\_NoARexx             &-& unable to create arexx port.\\
MUIE\_SingleTask          &-& application is already running.\\
\end{tabular} \end{center}
   
\subsubsection*{SEE ALSO}
MUI\_SetError()


\subsection[MUI\_FreeAslRequest]{MUI\_FreeAslRequest}

\subsubsection*{FUNCTION}
Provide an interface to asl.library. Using this ensures
your application will benefit from future expansions
to MUI's window and iconification handling.

\subsubsection*{SEE ALSO}
asl.library/FreeAslRequest


\subsection[MUI\_FreeClass]{MUI\_FreeClass -- Free class.}

\subsubsection*{SYNOPSIS}
\begin{tabbing}
MUI\_FreeClass( \=classptr )\\
\>A0
\end{tabbing}
   
VOID MUI\_FreeClass(struct IClass $\ast$classptr);

   \subsubsection*{FUNCTION}
This function is obsolete since MUI V8.
Use MUI\_DeleteCustomClass() instead.

\subsubsection*{SEE ALSO}
MUI\_CreateCustomClass(), MUI\_DeleteCustomClass()


\subsection[MUI\_GetClass]{MUI\_GetClass -- Get a pointer to a MUI class.}

\subsubsection*{SYNOPSIS}
\begin{tabbing}
class = MUI\_GetClass( \=classid )\\
D0                    \>A0
\end{tabbing}

struct IClass $\ast$ MUI\_GetClass(char $\ast$classid);

   \subsubsection*{FUNCTION}
This function is obsolete since MUI V8.
Use MUI\_CreateCustomClass instead.

\subsubsection*{SEE ALSO}
MUI\_CreateCustomClass(), MUI\_DeleteCustomClass()


\subsection[MUI\_MakeObjectA]{MUI\_MakeObjectA -- create an object from the builtin object collection.}
MUI\_MakeObject -- Varargs stub for MUI\_MakeObjectA

\subsubsection*{SYNOPSIS}
\begin{tabbing}
object = MUI\_MakeObjectA( \=objtype, \=params )\\
D0                        \>D0       \>A0
\end{tabbing}

\noindent Object $\ast$ MUI\_MakeObjectA(ULONG type, ULONG $\ast$params);\\
Object $\ast$ MUI\_MakeObject(ULONG type, ...);

   \subsubsection*{FUNCTION}
Prior to muimaster.library V8, MUI was distributed with several macros
to help creating often used objects. This practice was easy, but using
lots of these macros often resulted in big programs. Now, muimaster
library contains an object library with several often used objects
already built in.

MUI\_MakeObject() takes the type of the object as first parameter and
a list of additional (type specific) parameters. Note that these
additional values are {\bf not} a taglist!

See the header file mui.h for documentation on object types and the
required parameters.

\subsubsection*{SEE ALSO}
MUI\_CreateCustomClass(), MUI\_DeleteCustomClass()


\subsection[MUI\_NewObjectA]{MUI\_NewObjectA -- Create an object from a class.}
MUI\_NewObject -- Varargs stub for MUI\_NewObjectA().

\subsubsection*{SYNOPSIS}
\begin{tabbing}
object = MUI\_NewObjectA( \=class, \=tags )\\
D0                       \>A0     \>A1
\end{tabbing}

APTR MUI\_NewObjectA( char $\ast$, struct TagItem $\ast$ );

object = MUI\_NewObject( classID, Tag1, ... )

APTR MUI\_NewObject( classID, ULONG, ... );

   \subsubsection*{FUNCTION}
This is the general method of creating objects from MUI classes.
You specify a class by its ID string. If the class is not
already in memory or built into muimaster.library, it will be
loaded using OpenLibrary(''mui/\%s'',0).

You further specify initial ''create-time'' attributes for the
object via a TagItem list, and they are applied to the resulting
generic data object that is returned. The attributes, their meanings,
attributes applied only at create-time, and required attributes
are all defined and documented on a class-by-class basis.

\subsubsection*{INPUTS}
\begin{description}
\item[classID] = the name/ID string of a MUI class, e.g. ''Image.mui''.
Class names are case sensitive!

\item[tagList] = pointer to array of TagItems containing attribute/value
pairs to be applied to the object being created.
\end{description}

\subsubsection*{RESULT}
A MUI object, which may be used in different contexts such
as an application, window or gadget, and may be manipulated
by generic functions. You eventually free the object using
MUI\_DisposeObject().
NULL indicates failure, more information on the error can be
obtained with MUI\_Error().

\subsubsection*{SEE ALSO}
MUI\_DisposeObject(), MUI\_Error(), SetAttrs(), GetAttr().


\subsection[MUI\_Redraw]{MUI\_Redraw -- Redraw yourself.}

\subsubsection*{SYNOPSIS}
\begin{tabbing}
MUI\_Redraw( \=obj, \=flag )\\
\>A0   \>D0
\end{tabbing}

VOID MUI\_Redraw( Object $\ast$obj, ULONG flag );

\subsubsection*{FUNCTION}
With MUI\_Redraw(), an object tells itself to refresh, e.g. when
some internal attributes were changed. Calling MUI\_Redraw() is
only legal within a custom class dispatcher, using this function
within an applications main part is invalid!

Most objects graphical representation in a window depends on some
attributes. A fuel gauge for example would depend on its
MUIA\_Gauge\_Current attribute, an animation object would
depend on MUIA\_Animation\_CurrentFrame.

Whenever someone changes such an attribute with a SetAttrs() call,
the corresponding object receives an OM\_SET method with the new
value. Usually, it could just render itself with some
graphics.library calls. However, if the object is placed
in a virtual group or if some other clipping or coordinate
translation is required, this simple rendering will lead
into problems.

That's why MUI offers the MUI\_Redraw() function call. Instead
of drawing directly during OM\_SET, you should simply call
MUI\_Redraw(). MUI calculates all necessary coordinates
and clip regions (in case of virtual groups) and then sends
a MUIM\_Draw method to your object.

To emphasize this point again: The only time your object is
allowed to render something is when you receive a MUIM\_Draw
method. Drawing during other methods is illegal.

\subsubsection*{NOTE}
As long as no special cases (e.g. virtual groups) are
present, MUI\_Redraw is very quick and calls your MUIM\_Draw
method immediately. No coordinate translations or clip
regions need to be calculated.

\subsubsection*{INPUTS}
\begin{description}
\item[obj]  - pointer to yourself.
\item[flag] - MADF\_DRAWOBJECT or MADF\_DRAWUPDATE.
The flag given here affects the objects flags when
MUI calls the MUIM\_Draw method. There are several
caveats when implementing MUIM\_DRAW, see the
developer documentation for details.
\end{description}

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}

/* Note: This example was broken up to version 2.1 of muimaster.doc */

LONG mSet(struct IClass *cl,Object *obj,sruct opSet *msg)
{
   struct Data *data = INST_DATA(cl,obj);
   struct TagItem *tags,*tag;

   for (tags=msg->ops_AttrList;tag=NextTagItem(&tags);)
   {
      switch (tag->ti_Tag)
      {
         case MYATTR_PEN_1:
            data->pen1 = tag->ti_Data;       /* set the new value  */
            data->mark = 1;                  /* set internal marker*/
            MUI_Redraw(obj,MADF_DRAWUPDATE); /* update ourselves   */
            break;

         case MYATTR_PEN_1:
            data->pen2 = tag->ti_Data;       /* set the new value  */
            data->mark = 2;                  /* set internal marker*/
            MUI_Redraw(obj,MADF_DRAWUPDATE); /* update ourselves   */
            break;
      }
   }

   return(DoSuperMethodA(cl,obj,msg));
}

LONG mDraw(struct IClass *cl,Object *obj,struct MUIP_Draw *msg)
{
   struct Data *data = INST_DATA(cl,obj);

   // ** Note: You *must* call the super method prior to do
   // ** anything else, otherwise msg->flags will not be set
   // ** properly !!!

   DoSuperMethodA(cl,obj,msg); // ALWAYS REQUIRED!

   if (msg->flags & MADF_DRAWUPDATE)
   {
      /* called as a result of our MUI_Redraw() during
         MUIM_Set method. Depending on our internal
         marker, we render different things. */

      switch (data->mark)
      {
         case 1: RenderChangesFromPen1(cl,obj); break;
         case 2: RenderChangesFromPen2(cl,obj); break;
      }
   }
   else if (msg->flags & MADF_DRAWOBJECT)
   {
      /* complete redraw, maybe the window was just opened. */
      DrawObjectCompletely(cl,obj);
   }

   /* if MADF_DRAWOBJECT wasn't set, MUI just wanted to update
      the frame or some other part of our object. In this case
      we just do nothing. */

    return(0);
}

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
area.mui/MUIM\_Draw


\subsection[MUI\_RequestA]{MUI\_RequestA  -- Pop up a MUI requester.}

\subsubsection*{SYNOPSIS}
\begin{tabbing}
MUI\_RequestA(\=app,\=win,\=flags,\=title,\=gadgets,\=format,\=params)\\
\>D0   \>D1  \>D2    \>A0     \>A1      \>A2     \>A3
\end{tabbing}

LONG MUI\_RequestA ( APTR app, APTR win, LONGBITS flags,
char $\ast$title, char $\ast$gadgets, char $\ast$format, APTR params );

LONG MUI\_Request ( APTR app, APTR win, LONGBITS flags,
char $\ast$title, char $\ast$gadgets, char $\ast$format, ...);

   \subsubsection*{FUNCTION}
Pop up a MUI requester. Using a MUI requester instead
of a standard system requester offers you the possibility
to include text containing all the text engine format codes.

\subsubsection*{INPUTS}
\begin{description}
\item[app]     - The application object. If you leave this
NULL, MUI\_RequestA() will fall back to a
standard system requester.

\item[win]     - Pointer to a window of the application. If
this is used, the requester will appear centered
relative to this window.

\item[flags]   - For future expansion, must be 0 for now.

\item[title]   - Title for the requester window. Defaults to the
name of the application when NULL (and app!=NULL).

\item[gadgets] - Pointer to a string containing the possible answers.
The format looks like ''\_Save|\_Use|\_Test|\_Cancel''.
If you precede an entry with a '$\ast$', this answer will
become the active object. Pressing <Return> will
terminate the requester with this response. A '\_'
character indicates the keyboard shortcut for this
response.

\item[format]  - A printf-style formatting string.

\item[params]  - Pointer to an array of ULONG containing the parameter
values for format.
\end{description}

\subsubsection*{RESULT}
0, 1, ..., N = Successive id values, for the gadgets
you specify for the requester.  {\bf NOTE:} The numbering
from left to right is actually: 1, 2, ..., N, 0.
In case of a problem (e.g. out of memory), the
function returns FALSE.

\subsubsection*{SEE ALSO}
MUIA\_Text\_Contents


\subsection[MUI\_RejectIDCMP]{MUI\_RejectIDCMP -- Reject previously requested input events.}

\subsubsection*{SYNOPSIS}
\begin{tabbing}
MUI\_RejectIDCMP( \=obj, \=flags )\\
\>A0   \>D0
\end{tabbing}

VOID MUI\_RejectIDCMP( Object $\ast$obj, ULONG flags );

   \subsubsection*{FUNCTION}
Reject previously requested input events. You should
ensure that you reject all input events you requested
for an object before it gets disposed. Rejecting
flags that you never requested has no effect.

Critical flags such as IDCMP\_MOUSEMOVE and IDCMP\_INTUITICKS
should be rejected as soon as possible. See MUI\_RequestIDCMP()
for details.

\subsubsection*{INPUTS}
\begin{description}
\item[obj]   - pointer to yourself as an object.
\item[flags] - one or more IDCMP\_XXXX flags.
\end{description}

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
LONG CleanupMethod(struct IClass *cl, Object *obj, Msg msg)
{
   MUI_RejectIDCMP( obj, IDCMP_MOUSEBUTTONS|IDCMP_RAWKEY );
   return(DoSuperMethodA(cl,obj,msg));
}

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUI\_RequestIDMCP()


\subsection[MUI\_RequestIDCMP]{MUI\_RequestIDCMP -- Request input events for your custom class.}

\subsubsection*{SYNOPSIS}
\begin{tabbing}
MUI\_RequestIDCMP( \=obj, \=flags )\\
\>A0   \>D0
\end{tabbing}

VOID MUI\_RequestIDCMP( Object $\ast$obj, ULONG flags );

   \subsubsection*{FUNCTION}
If your custom class needs to do some input handling, you must
explicitly request the events you want to receive. You can
request (and reject) events at any time.

Whenever an input event you requested arrives at your parent
windows message port, your object will receive a
MUIM\_HandleInput method.

\subsubsection*{NOTE}
Time consuming IDCMP flags such as IDCMP\_INTUITICKS and
IDCMP\_MOUSEMOVE should be handled with care. Too many
objects receiving them will degrade performance With
the following paragraph in mind, this isn't really
a problem:

You should try to request critical events only when you
really need them and reject them with MUI\_RejectIDCMP()
as soon as possible. Usually, mouse controlled objects
only need MOUSEMOVES and INTUITICKS when a button
is pressed. You should request these flags only
on demand, i.e. after receiving a mouse down event
and reject them immediately after the button has been
released.

\subsubsection*{INPUTS}
\begin{description}
\item[obj]   - pointer to yourself as an object.
\item[flags] - one or more IDCMP\_XXXX flags.
\end{description}

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
LONG SetupMethod(struct IClass *cl, Object *obj, Msg msg)
{
   if (!DoSuperMethodA(cl,obj,msg))
      return(FALSE);

   /* do some setup here... */
   ...;

   /* i need mousebutton events and keyboard */
   MUI_RequestIDCMP( obj, IDCMP_MOUSEBUTTONS|IDCMP_RAWKEY );

   return(TRUE);
}

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUI\_RejectIDMCP()


\subsection[MUI\_SetError]{MUI\_SetError -- Set an error value.}

\subsubsection*{SYNOPSIS}
VOID MUI\_SetError(LONG);

   \subsubsection*{FUNCTION}
Setup a MUI error. MUI\_Error() will return this value when
asked.

\subsubsection*{SEE ALSO}
MUI\_Error()