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

MUI_AllocAslRequest

MUI_AllocAslRequest

DESCRIPTION

	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

MUI_AslRequest

MUI_AslRequest

DESCRIPTION

	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

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

DESCRIPTION

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

delete a public/private custom class.

SYNOPSIS

	MUI_DeleteCustomClass ( mcc )
	                        A0

	BOOL MUI_DeleteCustomClass(struct MUI_CustomClass *);

DESCRIPTION

	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_DisposeObject

Delete a MUI object.

SYNOPSIS

	MUI_DisposeObject( object )
	                   A0

	VOID MUI_DisposeObject( APTR );

DESCRIPTION

	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_Error

Return extra information from the MUI system.

SYNOPSIS

	LONG MUI_Error(VOID);

DESCRIPTION

	Obsolete. Better use SetIoErr()/IoErr

SEE ALSO

MUI_FreeAslRequest

MUI_FreeAslRequest

DESCRIPTION

	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

MUI_FreeClass

Free class.

SYNOPSIS

	MUI_FreeClass( classptr )
	               A0

	VOID MUI_FreeClass(struct IClass *classptr);

DESCRIPTION

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

SEE ALSO

MUI_GetClass

Get a pointer to a MUI class.

SYNOPSIS

	class = MUI_GetClass( classid )
	D0                    A0

	struct IClass * MUI_GetClass(char *classid);

DESCRIPTION

	This function is obsolete since MUI V8.
	Use MUI_CreateCustomClass instead

SEE ALSO

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, ...);

DESCRIPTION

	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_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, ... );

DESCRIPTION

	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

SEE ALSO

MUI_ObtainPen

Obtain a drawing pen.

SYNOPSIS

	MUI_ObtainPen ( mri , spec , flags )
	                A0    A1     D0

	LONG MUI_ObtainPen
	(
		struct MUI_RenderInfo *mri,
		struct MUI_PenSpec *spec,
		ULONG flags
	);

DESCRIPTION

	Whenever your application needs custom drawing pens, you should allow
	your user to adjust them with a Poppen class. The result from this
	Poppen class is a struct MUI_PenSpec which you can save somewhere in
	your preferences and use together with MUI_ObtainPen(),
	MUI_ReleasePen() and the MUIPEN() macro to transform the spec into a
	pen number useful for SetAPen

EXAMPLE

	See demo program Class2.c

NOTE

	This function will work under 2.x but will generally perform better
	under 3.x and above.

SEE ALSO

MUI_GetRGBColor

Get RGB triplet from pen specification.

SYNOPSIS

	MUI_GetRGBColor ( mri , spec , rgb )

	LONG MUI_GetRGBColor
	(
		struct MUI_RenderInfo *mri,
		struct MUI_PenSpec *spec,
		ULONG *rgb
	);

DESCRIPTION

	Get 32-bit RGB triplet from pen specification

RESULT

	TRUE if succeeded, FALSE if an error occurred

SEE ALSO

  • Poppen.mui

MUI_Redraw

Redraw yourself.

SYNOPSIS

	MUI_Redraw( obj, flag )
	            A0   D0

	VOID MUI_Redraw( Object *obj, ULONG flag );

DESCRIPTION

	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.

	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

INPUTS

	obj  - pointer to yourself.
	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

EXAMPLE

	/* 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

SEE ALSO

MUI_ReleasePen

Release a drawing pen.

SYNOPSIS

	MUI_ReleasePen ( mri , pen )
	                 A0    D0

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

DESCRIPTION

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

EXAMPLE

	See demo program Class2.c

NOTE

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

SEE ALSO

MUI_RequestA

Pop up a MUI requester.

SYNOPSIS

	MUI_RequestA(app,win,flags,title,gadgets,format,params)
	             D0   D1  D2    A0     A1      A2     A3

	LONG MUI_RequestA ( APTR app, APTR win, LONGBITS flags,
	     char *title, char *gadgets, char *format, APTR params );

	LONG MUI_Request ( APTR app, APTR win, LONGBITS flags,
	     char *title, char *gadgets, char *format, ...);

DESCRIPTION

	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

INPUTS

	app     - The application object. If you leave this
	          NULL, MUI_RequestA() will fall back to a
	          standard system requester.

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

	flags   - For future expansion, must be 0 for now.

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

	gadgets - Pointer to a string containing the possible answers.
	          The format looks like "_Save|_Use|_Test|_Cancel".
	          If you precede an entry with a '*', 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.

	format  - A printf-style formatting string.

	params  - Pointer to an array of ULONG containing the parameter
	          values for format

RESULT

	0, 1, ..., N = Successive id values, for the gadgets
	you specify for the requester.  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

SEE ALSO

MUI_RequestObjectA

Pop up an extended MUI requester.

SYNOPSIS

	MUI_RequestObjectA(app,win,flags,title,gadgets,object, format,params)
	                   D0   D1  D2    A0     A1      A2     A3    A4

	LONG MUI_RequestObjectA ( APTR app, APTR win, LONGBITS flags,
	     char *title, char *gadgets, Boopsiojbect *object, char *format, APTR params );

	LONG MUI_RequestObjectA ( APTR app, APTR win, LONGBITS flags,
	     char *title, char *gadgets, Boopsiojbect *object, char *format, ...);

DESCRIPTION

	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

INPUTS

	app     - The application object. If you leave this
	          NULL, MUI_RequestA() will fall back to a
	          standard system requester.

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

	flags   - For future expansion, must be 0 for now.

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

	gadgets - Pointer to a string containing the possible answers.
	          The format looks like "_Save|_Use|_Test|_Cancel".
	          If you precede an entry with a '*', 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.

	object  - A MUI area object (could be a group) to display as
	          part of the requester.
	          CAUTION: call DoMethod(object, OM_RETAIN) before calling
	          MUI_RequestObjectA if you need the object to remain valid
	          after closing the requester.

	format  - A printf-style formatting string.

	params  - Pointer to an array of ULONG containing the parameter
	          values for format

RESULT

	0, 1, ..., N = Successive id values, for the gadgets
	you specify for the requester.  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

EXAMPLE

	#include <proto/muimaster.h>
	#include <clib/alib_protos.h>
	#include <stdio.h>
	int main(void)
	{
		Object *string = StringObject, MUIA_Frame, MUIV_Frame_String, End;
		DoMethod(string, OM_RETAIN); // make sure the object remains valid
		ULONG rc = MUI_RequestObjectA(NULL, NULL, 0, "My Requester", "OK|Cancel", string,
			"Enter your name below", NULL);
		if (rc == 1)
		{
			const char *name = NULL;
			get(string, MUIA_String_Contents, &name);
			printf("Entered name: %s\n", name);
		}
		// same as DoMethod(string, OM_RELEASE) - both calls decrease use count by 1
		MUI_DisposeObject(string);
		return 0

SEE ALSO

MUI_RejectIDCMP

Reject previously requested input events.

SYNOPSIS

	MUI_RejectIDCMP( obj, flags )
	                  A0   D0

	VOID MUI_RejectIDCMP( Object *obj, ULONG flags );

DESCRIPTION

	OBSOLETE! Please use event handlers for your classes
	input needs

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

OLD AND OBSOLETE DOCUMENTATION

	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.

SEE ALSO

MUI_RequestIDCMP

Request input events for your custom class.

SYNOPSIS

	MUI_RequestIDCMP( obj, flags )
	                  A0   D0

	VOID MUI_RequestIDCMP( Object *obj, ULONG flags );

DESCRIPTION

	OBSOLETE! Please use event handlers for your classes
	input needs

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

OLD AND OBSOLETE DOCUMENTATION

	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.

SEE ALSO

MUI_SetError

Set an error value.

SYNOPSIS

	VOID MUI_SetError(LONG);

DESCRIPTION

	Obsolete. Better use SetIoErr()/IoErr

SEE ALSO