%---------------- Functions ------------ \chapter{muimaster.library/--background--} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf PURPOSE] \begin{flushleft} \begin{verbatim} 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. \end{verbatim} \end{flushleft} \end{deflist} \subsection{muimaster.library/MUI\_AllocAslRequest} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf NAME] MUI\_AllocAslRequest \item[\bf FUNCTION] Provide an interface to asl.library. Using this ensures your application will benefit from future expansions to MUI's window and iconification handling. \item[\bf SEE ALSO] asl.library/AllocAslRequest \end{deflist} \subsection{muimaster.library/MUI\_AslRequest} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf NAME] MUI\_AslRequest \item[\bf FUNCTION] Provide an interface to asl.library. Using this ensures your application will benefit from future expansions to MUI's window and iconification handling. \item[\bf SEE ALSO] asl.library/AslRequest \end{deflist} \subsection{muimaster.library/MUI\_DisposeObject} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf NAME] \begin{description} \item[MUI\_DisposeObject] -- Delete a MUI object. \end{description} \item[\bf SYNOPSIS] \begin{flushleft} \begin{verbatim} MUI_DisposeObject( object ) A0 VOID MUI_DisposeObject( APTR ); \end{verbatim} \end{flushleft} \item[\bf   FUNCTION] \begin{flushleft} \begin{verbatim} 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. \end{verbatim} \end{flushleft} \item[\bf 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. \item[\bf RESULT] None. \item[\bf SEE ALSO] MUI\_NewObjectA(), SetAttrs(), GetAttr(). \end{deflist} \subsection{muimaster.library/MUI\_Error} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf NAME] \begin{description} \item[MUI\_Error] -- Return extra information from the MUI system. \end{description} \item[\bf SYNOPSIS] \begin{flushleft} \begin{verbatim} LONG MUI_Error(VOID); \end{verbatim} \end{flushleft} \item[\bf   FUNCTION] \begin{flushleft} \begin{verbatim} Obsolete. Better use SetIoErr()/IoErr(). \end{verbatim} \end{flushleft} \item[\bf SEE ALSO] MUI\_SetError() \end{deflist} \subsection{muimaster.library/MUI\_FreeAslRequest} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf NAME] MUI\_FreeAslRequest \item[\bf FUNCTION] Provide an interface to asl.library. Using this ensures your application will benefit from future expansions to MUI's window and iconification handling. \item[\bf SEE ALSO] asl.library/FreeAslRequest \end{deflist} \subsection{muimaster.library/MUI\_FreeClass} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf NAME] \begin{description} \item[MUI\_FreeClass] -- Free class. \end{description} \item[\bf SYNOPSIS] \begin{flushleft} \begin{verbatim} MUI_FreeClass( classptr ) A0 VOID MUI_FreeClass(struct IClass *classptr); \end{verbatim} \end{flushleft} \item[\bf   FUNCTION] \begin{flushleft} \begin{verbatim} This function is obsolete since MUI V8. Use MUI_DeleteCustomClass() instead. \end{verbatim} \end{flushleft} \item[\bf SEE ALSO] MUI\_CreateCustomClass(), MUI\_DeleteCustomClass() \end{deflist} \subsection{muimaster.library/MUI\_GetClass} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf NAME] \begin{description} \item[MUI\_GetClass] -- Get a pointer to a MUI class. \end{description} \item[\bf SYNOPSIS] \begin{flushleft} \begin{verbatim} class = MUI_GetClass( classid ) D0 A0 struct IClass * MUI_GetClass(char *classid); \end{verbatim} \end{flushleft} \item[\bf   FUNCTION] \begin{flushleft} \begin{verbatim} This function is obsolete since MUI V8. Use MUI_CreateCustomClass instead. \end{verbatim} \end{flushleft} \item[\bf SEE ALSO] MUI\_CreateCustomClass(), MUI\_DeleteCustomClass() \end{deflist} \subsection{muimaster.library/MUI\_MakeObjectA} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf NAME] \begin{description} \item[MUI\_MakeObjectA] -- create an object from the builtin object collection. \item[MUI\_MakeObject] -- Varargs stub for MUI\_MakeObjectA \end{description} \item[\bf SYNOPSIS] \begin{flushleft} \begin{verbatim} object = MUI_MakeObjectA( objtype, params ) D0 D0 A0 Object * MUI_MakeObjectA(ULONG type, ULONG *params); Object * MUI_MakeObject(ULONG type, ...); \end{verbatim} \end{flushleft} \item[\bf   FUNCTION] \begin{flushleft} \begin{verbatim} 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. \end{verbatim} \end{flushleft} \item[\bf SEE ALSO] MUI\_CreateCustomClass(), MUI\_DeleteCustomClass() \end{deflist} \subsection{muimaster.library/MUI\_NewObjectA} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf NAME] \begin{description} \item[MUI\_NewObjectA] -- Create an object from a class. \item[MUI\_NewObject] -- Varargs stub for MUI\_NewObjectA(). \end{description} \item[\bf SYNOPSIS] \begin{flushleft} \begin{verbatim} object = MUI_NewObjectA( class, tags ) D0 A0 A1 APTR MUI_NewObjectA( char *, struct TagItem * ); object = MUI_NewObject( classID, Tag1, ... ) APTR MUI_NewObject( classID, ULONG, ... ); \end{verbatim} \end{flushleft} \item[\bf   FUNCTION] \begin{flushleft} \begin{verbatim} 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. \end{verbatim} \end{flushleft} \item[\bf 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. \item[\bf 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(). \item[\bf BUGS] \item[\bf SEE ALSO] MUI\_DisposeObject(), MUI\_Error(), SetAttrs(), GetAttr(). \end{deflist} \subsection{muimaster.library/MUI\_ObtainPen} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf NAME] \begin{description} \item[MUI\_ObtainPen] -- Obtain a drawing pen. \end{description} \item[\bf SYNOPSIS] \begin{flushleft} \begin{verbatim} MUI_ObtainPen ( mri , spec , flags ) A0 A1 D0 LONG MUI_ObtainPen ( struct MUI_RenderInfo *mri, struct MUI_PenSpec *spec, ULONG flags ); \end{verbatim} \end{flushleft} \item[\bf FUNCTION] 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(). \item[\bf NOTE] This function will work under 2.x but will generally perform better under 3.x and above. \item[\bf EXAMPLE] \begin{flushleft} \begin{verbatim} See demo program Class2.c \end{verbatim} \end{flushleft} \item[\bf SEE ALSO] MUI\_ReleasePen(), Poppen.mui \end{deflist} \subsection{muimaster.library/MUI\_RejectIDCMP} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf NAME] \begin{description} \item[MUI\_RejectIDCMP] -- Reject previously requested input events. \end{description} \item[\bf SYNOPSIS] \begin{flushleft} \begin{verbatim} MUI_RejectIDCMP( obj, flags ) A0 D0 VOID MUI_RejectIDCMP( Object *obj, ULONG flags ); \end{verbatim} \end{flushleft} \item[\bf   FUNCTION] \begin{flushleft} \begin{verbatim} 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. \end{verbatim} \end{flushleft} \item[\bf INPUTS] \begin{description} \item[obj ] - pointer to yourself as an object. \item[flags] - one or more IDCMP\_XXXX flags. \end{description} \item[\bf EXAMPLE] \begin{flushleft} \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} \end{flushleft} \item[\bf SEE ALSO] MUI\_RequestIDMCP() \end{deflist} \subsection{muimaster.library/MUI\_ReleasePen} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf NAME] \begin{description} \item[MUI\_ObtainPen] -- Obtain a drawing pen. \end{description} \item[\bf SYNOPSIS] \begin{flushleft} \begin{verbatim} MUI_ReleasePen ( mri , pen ) A0 D0 LONG MUI_ReleasePen ( struct MUI_RenderInfo *mri, ULONG pen ); \end{verbatim} \end{flushleft} \item[\bf FUNCTION] Release a pen obtained with MUI\_ObtainPen(). Usually placed in the Cleanup method of custom classes. \item[\bf NOTE] Do *not* use the MUIPEN() maros when releasing pens! \item[\bf EXAMPLE] \begin{flushleft} \begin{verbatim} See demo program Class2.c \end{verbatim} \end{flushleft} \item[\bf SEE ALSO] MUI\_ObtainPen(), Poppen.mui \end{deflist} \subsection{muimaster.library/MUI\_RequestIDCMP} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf NAME] \begin{description} \item[MUI\_RequestIDCMP] -- Request input events for your custom class. \end{description} \item[\bf SYNOPSIS] \begin{flushleft} \begin{verbatim} MUI_RequestIDCMP( obj, flags ) A0 D0 VOID MUI_RequestIDCMP( Object *obj, ULONG flags ); \end{verbatim} \end{flushleft} \item[\bf   FUNCTION] \begin{flushleft} \begin{verbatim} 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. \end{verbatim} \end{flushleft} \item[\bf INPUTS] \begin{description} \item[obj ] - pointer to yourself as an object. \item[flags] - one or more IDCMP\_XXXX flags. \end{description} \item[\bf EXAMPLE] \begin{flushleft} \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} \end{flushleft} \item[\bf SEE ALSO] MUI\_RejectIDMCP() \end{deflist} \subsection{muimaster.library/MUI\_SetError} \rule{\textwidth}{1mm} \vspace{0.5cm} \begin{deflist}{MMMMMMMM} \item[\bf NAME] \begin{description} \item[MUI\_SetError] -- Set an error value. \end{description} \item[\bf SYNOPSIS] \begin{flushleft} \begin{verbatim} VOID MUI_SetError(LONG); \end{verbatim} \end{flushleft} \item[\bf   FUNCTION] \begin{flushleft} \begin{verbatim} Obsolete. Better use SetIoErr()/IoErr(). \end{verbatim} \end{flushleft} \item[\bf SEE ALSO] MUI\_Error() \end{deflist} %---------------- End of File ----------