muimaster.library/--background-- muimaster.library/--background--

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 "mui:libs/mui/.mui". The MUI object
generation call takes care of this situation and loads
external classes automatically when they are needed.

GO TO CONTENTS

muimaster.library/MUI_AllocAslRequest muimaster.library/MUI_AllocAslRequest

MUI_AllocAslRequest

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

SEE ALSO
asl.library/AllocAslRequest

GO TO CONTENTS

muimaster.library/MUI_AslRequest

MUI_AslRequest

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

SEE ALSO
asl.library/AslRequest

GO TO CONTENTS

muimaster.library/MUI_CreateCustomClass MUI_CreateCustomClass

MUI_CreateCustomClass -- create a public/private custom class.

SYNOPSIS
MUI_CreateCustomClass (base, supername, supermcc, datasize, dispfunc)
A0 A1 A2 D0 A3

struct MUI_CustomClass * MUI_CreateCustomClass(
struct Library *, char *, int, APTR );

This function creates a public or private MUI custom class.
Public custom classes are shared libraries and can be found
in "libs:mui/.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 *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 or similiar things the compiler may need yourself.

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

supername = super class of your class. This can either
be a builtin MUI class ("xyz.mui") or a external
custom class ("xyz.mcc").

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.

datasize = size of your classes data structure.

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.

RESULT
A pointer to a struct MUI_CustomClass or NULL to indicate
an error.

SEE ALSO
MUI_DeleteCustomClass()

GO TO CONTENTS

muimaster.library/MUI_DeleteCustomClass MUI_DeleteCustomClass

MUI_DeleteCustomClass -- delete a public/private custom class.

SYNOPSIS
MUI_DeleteCustomClass ( mcc )
A0

BOOL MUI_DeleteCustomClass(struct MUI_CustomClass *);

Delete a public or private custom class. Note that you
must not delete classes with outstanding objects or sub
classes.

INPUTS
mcc = pointer obtained from MUI_CreateCustomClass().

RESULT
TRUE if all went well, FALSE if some objects or
sub classes were still hanging around. Nothing
will be freed in this case.

SEE ALSO
MUI_CreateCustomClass()

GO TO CONTENTS

muimaster.library/MUI_DisposeObject muimaster.library/MUI_DisposeObject

MUI_DisposeObject -- Delete a MUI object.

SYNOPSIS
MUI_DisposeObject( object )
A0

VOID MUI_DisposeObject( APTR );

Deletes a MUI object and all of it's auxiliary data.
These objects are all created by MUI_NewObject() or 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.

INPUTS
object = abstract pointer to a MUI object returned by
MUI_NewObject(). The pointer may be NULL, in which case
this function has no effect.

RESULT
None.

SEE ALSO
MUI_NewObjectA()
SetAttrs()
GetAttr().
GetAttr().

GO TO CONTENTS

muimaster.library/MUI_Error muimaster.library/MUI_Error

MUI_Error -- Return extra information from the MUI system.

SYNOPSIS
LONG MUI_Error(VOID);

Obsolete. Better use SetIoErr()/IoErr().

SEE ALSO
MUI_SetError()

GO TO CONTENTS

muimaster.library/MUI_FreeAslRequest muimaster.library/MUI_FreeAslRequest

MUI_FreeAslRequest

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

SEE ALSO
asl.library/FreeAslRequest

GO TO CONTENTS

muimaster.library/MUI_FreeClass muimaster.library/MUI_FreeClass

MUI_FreeClass -- Free class.

SYNOPSIS
MUI_FreeClass( classptr )
A0

VOID MUI_FreeClass(struct IClass *classptr);

This function is obsolete since MUI V8.
Use MUI_DeleteCustomClass() instead.

SEE ALSO
MUI_CreateCustomClass()
MUI_DeleteCustomClass()
MUI_DeleteCustomClass()

GO TO CONTENTS

muimaster.library/MUI_GetClass muimaster.library/MUI_GetClass

MUI_GetClass -- Get a pointer to a MUI class.

SYNOPSIS
class = MUI_GetClass( classid )
D0 A0

struct IClass * MUI_GetClass(char *classid);

This function is obsolete since MUI V8.
Use MUI_CreateCustomClass instead.

SEE ALSO
MUI_CreateCustomClass()
MUI_DeleteCustomClass()
MUI_DeleteCustomClass()

GO TO CONTENTS

muimaster.library/MUI_MakeObjectA muimaster.library/MUI_MakeObjectA

MUI_MakeObjectA -- create an object from the builtin object collection.
MUI_MakeObject -- Varargs stub for MUI_MakeObjectA

SYNOPSIS
object = MUI_MakeObjectA( objtype, params )
D0 D0 A0

Object * MUI_MakeObjectA(ULONG type, ULONG *params);

Object * MUI_MakeObject(ULONG type, ...);

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 *not* a taglist!

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

SEE ALSO
MUI_CreateCustomClass()
MUI_DeleteCustomClass()
MUI_DeleteCustomClass()

GO TO CONTENTS

muimaster.library/MUI_NewObjectA muimaster.library/MUI_NewObjectA

MUI_NewObjectA -- Create an object from a class.
MUI_NewObject -- Varargs stub for MUI_NewObjectA().

SYNOPSIS
object = MUI_NewObjectA( class, tags )
D0 A0 A1

APTR MUI_NewObjectA( char *, struct TagItem * );

object = MUI_NewObject( classID, Tag1, ... )

APTR MUI_NewObject( classID, ULONG, ... );

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.

INPUTS
classID = the name/ID string of a MUI class, e.g. "Image.mui".
Class names are case sensitive!

tagList = pointer to array of TagItems containing attribute/value
pairs to be applied to the object being created.

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().

BUGS

SEE ALSO
MUI_DisposeObject()
MUI_Error()
SetAttrs()
GetAttr().
GetAttr().

GO TO CONTENTS

muimaster.library/MUI_ReleasePen muimaster.library/MUI_ReleasePen

MUI_ReleasePen -- Release a drawing pen.

SYNOPSIS
MUI_ReleasePen ( mri , pen )
A0 D0

LONG MUI_ReleasePen
(
struct MUI_RenderInfo *mri,
ULONG pen
);

Release a pen obtained with MUI_ObtainPen(). Usually placed
in the Cleanup method of custom classes.

NOTE
Do *not* use the MUIPEN() maros when releasing pens!

EXAMPLE
See demo program Class2.c

SEE ALSO
MUI_ObtainPen()
Poppen.mui
Poppen.mui
Poppen.mui
MUI_RequestA muimaster.library/MUI_RequestA
MUI_RequestA muimaster.library/MUI_RequestA
MUI_RequestA -- Pop up a MUI requester.
Pop up a MUI requester.
SYNOPSIS
win
flags
title
gadgets
format
params)
A3
A3
lags
R params );
R params );
ags
);
);
Pop up a MUI requester. Using a MUI requester instead
ibility
mat codes.
mat codes.
INPUTS
s
If
centered
centered
centered
to the
p!=NULL).
p!=NULL).
le answers.
Cancel".
answer will
n> will
e. A '_'
for this
for this
for this
for this
for this
e parameter
e parameter
e parameter
RESULT
SEE ALSO

GO TO CONTENTS

muimaster.library/MUI_RejectIDCMP muimaster.library/MUI_RejectIDCMP

MUI_RejectIDCMP -- Reject previously requested input events.

SYNOPSIS
MUI_RejectIDCMP( obj, flags )
A0 D0

VOID MUI_RejectIDCMP( Object *obj, ULONG flags );

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.

INPUTS
obj - pointer to yourself as an object.
flags - one or more IDCMP_XXXX flags.

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

SEE ALSO
MUI_RequestIDMCP()

GO TO CONTENTS

muimaster.library/MUI_RequestIDCMP muimaster.library/MUI_RequestIDCMP

MUI_RequestIDCMP -- Request input events for your custom class.

SYNOPSIS
MUI_RequestIDCMP( obj, flags )
A0 D0

VOID MUI_RequestIDCMP( Object *obj, ULONG flags );

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.

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.

INPUTS
obj - pointer to yourself as an object.
flags - one or more IDCMP_XXXX flags.

EXAMPLE
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);
}

SEE ALSO
MUI_RejectIDMCP()

GO TO CONTENTS

muimaster.library/MUI_SetError muimaster.library/MUI_SetError

MUI_SetError -- Set an error value.

SYNOPSIS
VOID MUI_SetError(LONG);

Obsolete. Better use SetIoErr()/IoErr().

SEE ALSO
MUI_Error()