Fresh Fish 5

home *** CD-ROM | disk | FTP | other *** search

/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / dev / mui-2.1.lha / MUI-2.1 / Developer / Autodocs / MUImaster.doc < prev

Wrap

Text File | 1994-07-04 | 18.7 KB | 637 lines

TABLE OF CONTENTS muimaster.library/--background-- muimaster.library/MUI_AllocAslRequest muimaster.library/MUI_AslRequest muimaster.library/MUI_CreateCustomClass muimaster.library/MUI_DeleteCustomClass muimaster.library/MUI_DisposeObject muimaster.library/MUI_Error muimaster.library/MUI_FreeAslRequest muimaster.library/MUI_FreeClass muimaster.library/MUI_GetClass muimaster.library/MUI_MakeObjectA muimaster.library/MUI_NewObjectA muimaster.library/MUI_Redraw muimaster.library/MUI_RequestA muimaster.library/MUI_RejectIDCMP muimaster.library/MUI_RequestIDCMP muimaster.library/MUI_SetError 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 "sys:classes/<foobar>.mui". The MUI object generation call takes care of this situation and loads external classes automatically when they are needed. muimaster.library/MUI_AllocAslRequest muimaster.library/MUI_AllocAslRequest NAME MUI_AllocAslRequest FUNCTION 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 muimaster.library/MUI_AslRequest NAME MUI_AslRequest FUNCTION 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 muimaster.library/MUI_CreateCustomClass MUI_CreateCustomClass NAME 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 ); 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 *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. 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() muimaster.library/MUI_DeleteCustomClass MUI_DeleteCustomClass NAME MUI_DeleteCustomClass -- delete a public/private custom class. SYNOPSIS MUI_DeleteCustomClass ( mcc ) A0 BOOL MUI_DeleteCustomClass(struct MUI_CustomClass *); FUNCTION 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() muimaster.library/MUI_DisposeObject muimaster.library/MUI_DisposeObject NAME MUI_DisposeObject -- Delete a MUI object. SYNOPSIS MUI_DisposeObject( object ) A0 VOID MUI_DisposeObject( APTR ); 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. 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_NewObject(), SetAttrs(), GetAttr(). muimaster.library/MUI_Error muimaster.library/MUI_Error NAME MUI_Error -- Return extra information from the MUI system. SYNOPSIS LONG MUI_Error(VOID); 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. RESULT Currently, the following error values are defined: 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. SEE ALSO MUI_SetError() muimaster.library/MUI_FreeAslRequest muimaster.library/MUI_FreeAslRequest NAME MUI_FreeAslRequest FUNCTION 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 muimaster.library/MUI_FreeClass muimaster.library/MUI_FreeClass NAME MUI_FreeClass -- Free class. SYNOPSIS MUI_FreeClass( classptr ) A0 VOID MUI_FreeClass(struct IClass *classptr); FUNCTION This function is obsolete since MUI V8. Use MUI_DeleteCustomClass() instead. SEE ALSO MUI_CreateCustomClass(), MUI_DeleteCustomClass() muimaster.library/MUI_GetClass muimaster.library/MUI_GetClass NAME MUI_GetClass -- Get a pointer to a MUI class. SYNOPSIS class = MUI_GetClass( classid ) D0 A0 struct IClass * MUI_GetClass(char *classid); FUNCTION This function is obsolete since MUI V8. Use MUI_CreateCustomClass instead. SEE ALSO MUI_CreateCustomClass(), MUI_DeleteCustomClass() muimaster.library/MUI_MakeObjectA muimaster.library/MUI_MakeObjectA NAME 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, ...); 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 *not* a taglist! See the header file mui.h for documentation on object types and the required parameters. SEE ALSO MUI_CreateCustomClass(), MUI_DeleteCustomClass() muimaster.library/MUI_NewObjectA muimaster.library/MUI_NewObjectA NAME 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, ... ); 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. 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(). muimaster.library/MUI_Redraw muimaster.library/MUI_Redraw NAME MUI_Redraw -- Redraw yourself. SYNOPSIS MUI_Redraw( obj, flag ) A0 D0 VOID MUI_Redraw( Object *obj, ULONG flag ); 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. 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 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); 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; } /* do not call the superclass for speed reasons here. it wouldn't do anything anyway since MADF_DRAWUPDATE is reserved for custom class use. */ return; } DoSuperMethodA(cl,obj,msg); // let superclass draw frames/etc. 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 area.mui/MUIM_Draw muimaster.library/MUI_RequestA muimaster.library/MUI_RequestA NAME 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, ...); 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. 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. SEE ALSO MUIA_Text_Contents muimaster.library/MUI_RejectIDCMP muimaster.library/MUI_RejectIDCMP NAME MUI_RejectIDCMP -- Reject previously requested input events. SYNOPSIS MUI_RejectIDCMP( obj, flags ) A0 D0 VOID MUI_RejectIDCMP( Object *obj, ULONG flags ); 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. 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() muimaster.library/MUI_RequestIDCMP muimaster.library/MUI_RequestIDCMP NAME MUI_RequestIDCMP -- Request input events for your custom class. SYNOPSIS MUI_RequestIDCMP( obj, flags ) A0 D0 VOID MUI_RequestIDCMP( Object *obj, ULONG flags ); 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. 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() muimaster.library/MUI_SetError muimaster.library/MUI_SetError NAME MUI_SetError -- Set an error value. SYNOPSIS VOID MUI_SetError(LONG); FUNCTION Setup a MUI error. MUI_Error() will return this value when asked. SEE ALSO MUI_Error()