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 / MUI_Notify.doc < prev next >

Wrap

Text File | 1994-07-04 | 17.5 KB | 611 lines

TABLE OF CONTENTS Notify.mui/Notify.mui Notify.mui/MUIM_CallHook Notify.mui/MUIM_FindUData Notify.mui/MUIM_GetUData Notify.mui/MUIM_KillNotify Notify.mui/MUIM_MultiSet Notify.mui/MUIM_Notify Notify.mui/MUIM_Set Notify.mui/MUIM_SetAsString Notify.mui/MUIM_SetUData Notify.mui/MUIM_WriteLong Notify.mui/MUIM_WriteString Notify.mui/MUIA_AppMessage Notify.mui/MUIA_HelpFile Notify.mui/MUIA_HelpLine Notify.mui/MUIA_HelpNode Notify.mui/MUIA_NoNotify Notify.mui/MUIA_Revision Notify.mui/MUIA_UserData Notify.mui/MUIA_Version Notify.mui/Notify.mui Notify class is superclass of all other MUI classes. It's main purpose is to handle MUI's notification mechanism, but it also contains some other methods and attributes useful for every object. Notify.mui/MUIM_CallHook NAME MUIM_CallHook (V4) SYNOPSIS DoMethod(obj,MUIM_CallHook,struct Hook *Hook, ULONG param1, /* ... */); FUNCTION Call a standard amiga callback hook, defined by a Hook structure. Together with MUIM_Notify, you can easily bind hooks to buttons, your hook will be called when the button is pressed. The hook will be called with a pointer to the hook structure in a0, a pointer to the calling object in a2 and a pointer to the first parameter in a1. INPUTS Hook pointer to a struct Hook. param1,... zero or more parameters. The hook function will receive a pointer to the first parameter in register a1. EXAMPLE standalone: DoMethod(obj,MUIM_CallHook,&hookstruct,13,42,"foobar","barfoo"); within a notification statement: DoMethod(propobj,MUIM_Notify,MUIA_Prop_First,MUIV_EveryTime, propobj,3,MUIM_CallHook,&prophook,MUIV_TriggerValue); prophook will be called every time the knob is moving and gets a pointer to the knobs current level in a1. Notify.mui/MUIM_FindUData NAME MUIM_FindUData (V8) SYNOPSIS DoMethod(obj,MUIM_FindUData,ULONG udata); FUNCTION This method tests if the MUIA_UserData of the object contains the given <udata> and returns the object pointer in this case. Altough this sounds not very useful for single objects, performing this method on objects that handle children can become very handy. In this case, all the children (any maybe their children) are tested against <udata> and the first matching object is returned. This method is especially useful if you created your menu tree with a NewMenu structure and you want to find the object pointer for a single menu item. INPUTS udata - userdata to look for. RESULT A pointer to the first object with the specified user data or NULL if no object is found. NOTES If you have many objects in your application, MUIM_FindUData may take quite long. You can limit the amount of time by performing the method not on the application but on the window or even on the group/family your object is place in. SEE ALSO MUIM_GetUData, MUIM_SetUData Notify.mui/MUIM_GetUData NAME MUIM_GetUData (V8) SYNOPSIS DoMethod(obj,MUIM_GetUData,ULONG udata, ULONG attr, ULONG *storage); FUNCTION This method tests if the MUIA_UserData of the object contains the given <udata> and gets <attr> to <storage> for itself in this case. Altough this sounds not very useful for single objects, performing this method on objects that handle children can become very handy. In this case, all the children (any maybe their children) are searched against <udata> and the first matching objects will be asked for the specified attribute. INPUTS udata - userdata to look for. attr - attribute to get. storage - place to store the attribute. NOTES If you have many objects in your application, MUIM_GetUData may take quite long. You can limit the amount of time by performing the method not on the application but on the window or even on the group/family your objects are place in. SEE ALSO MUIM_SetUData, MUIM_FindUData Notify.mui/MUIM_KillNotify NAME MUIM_KillNotify (V4) SYNOPSIS DoMethod(obj,MUIM_KillNotify,ULONG TrigAttr); FUNCTION MUIM_KillNotify kills previously given notifications on specific attributes. INPUTS TrigAttr - Attribute for which the notify was specified. If you set up more than one notify for an attribute, only the first one will be killed. EXAMPLE DoMethod(button,MUIM_KillNotify,MUIA_Pressed); SEE ALSO MUIM_Notify Notify.mui/MUIM_MultiSet NAME MUIM_MultiSet (V7) SYNOPSIS DoMethod(obj,MUIM_MultiSet,ULONG attr, ULONG val, APTR obj, /* ... */); FUNCTION Set an attribute for multiple objects. Receiving an attribute/value pair and a list of objects, this method sets the new value for all the objects in the list. This is especially useful for disabling/enabling lots of objects with one singe function call. The object that executes this method isn't affected! Note: This method was implemented in version 7 of notify class. INPUTS attr attribute to set. value new value for the attribute. obj, ... list of MUI objects, terminated with a NULL pointer. EXAMPLE /* disable all the address related gadgets... */ DoMethod(xxx, MUIM_MultiSet, MUIA_Disabled, TRUE, ST_Name, ST_Street, ST_City, ST_Country, ST_Phone, NULL); /* note that the xxx object doesn't get disabled! */ SEE ALSO MUIM_Set, MUIM_Notify Notify.mui/MUIM_Notify NAME MUIM_Notify (V4) SYNOPSIS DoMethod(obj,MUIM_Notify,ULONG TrigAttr, ULONG TrigVal, APTR DestObj, ULONG FollowParams, /* ... */); FUNCTION Add a notification event handler to an object. Notification is essential for every MUI application. A notification statement consists of a source object, an attribute/value pair, a destination object and a notification method. The attribute/value pair belongs to the source object and determines when the notification method will be executed on the destination object. Whenever the source object gets the given attribute set to the given value (this can happen because of the user pressing some gadgets or because of your program explicitly setting the attribute with SetAttrs()), the destination object will execute the notification method. With some special values, you can trigger the notification every time the attribute is changing. In this case, you can include the triggering attributes value within the notification method. See below. One big problem with notification are endless loops. Imagine you have a prop gadget and want to show its state with a gauge object. You connect MUIA_Prop_First with MUIA_Gauge_Max and everything is fine, the gauge gets updated when the user drags around the gadget. On the other hand, if your program sets the gauge to a new value, you might want your prop gadget to immediately show this change and connect MUIA_Gauge_Max width MUIA_Prop_First. Voila, a perfect endless loop. To avoid these conditions, MUI always checks new attribute values against the current state and cancels notification when both values are equal. Thus, setting MUIA_Prop_First to 42 if the prop gadgets first position is already 42 won't trigger any notification event. INPUTS TrigAttr attribute that triggers the notification. TrigValue value that triggers the notification. The special value MUIV_EveryTime makes MUI execute the notification method every time when TrigAttr changes. In this case, the special value MUIV_TriggerValue in the notification method will be replaced with the value that TrigAttr has been set to. You can use MUIV_TriggerValue up to four times in one notification method. Since version 8 of muimaster.library, you can also use MUIV_NotTriggerValue here. In this case, MUI will replace TRUE values with FALSE and FALSE values with TRUE. This can become quite useful when you try to set "negative" attributes like MUIA_Disabled. DestObj object on which to perform the notification method. FollowParams number of following parameters. If you e.g. have a notification method with three parts (maybe MUIM_Set,attr,val), you have to set FollowParams to 3. This allows MUI to copy the complete notification method into a private buffer for later use. ... following is the notification method. EXAMPLE /* ** Every time when the user releases a button ** (and the mouse is still over it), the button object ** gets its MUIA_Pressed attribute set to FALSE. ** Thats what a program can react on with notification, ** e.g. by openening another window. */ DoMethod(buttonobj,MUIM_Notify, MUIA_Pressed, FALSE, /* attribute/value pair */ windowobj, /* destination object */ 3, /* 3 following words */ MUIM_Set, MUIA_Window_Open, TRUE); /* notification method */ /* ** Lets say we want to show the current value of a ** prop gadget somewhere in a text field: */ DoMethod(propobj,MUIM_Notify, /* notification is triggered */ MUIA_Prop_First, MUIV_EveryTime /* every time the attr changes */ textobj /* destination object */ 4, /* 4 following words */ MUIM_SetAsString, MUIA_Text_Contents, "value is %ld !", MUIV_TriggerValue); /* MUIV_TriggerValue will be replaced with the current value of MUIA_Prop_First */ /* ** Inform our application when the user hits return ** in a string gadget: */ DoMethod(stringobj,MUIM_Notify, MUIA_String_Acknowledge, MUIV_EveryTime, appobj, 2, MUIM_Application_ReturnID, ID_FOOBAR); Notify.mui/MUIM_Set NAME MUIM_Set (V4) SYNOPSIS DoMethod(obj,MUIM_Set,ULONG attr, ULONG val); FUNCTION Set an attribute to a value. Normally, you would set attributes with intuition.library SetAttrs() or with the OM_SET method as with any other boopsi objects. But since these calls need a complete tag list, not just a single attribute/value pair, they are not useful within a MUIM_Notify method. INPUTS attr attribute you want to set. val value to set the attribute to. EXMAPLE DoMethod(strobj,MUIM_Set,MUIA_String_Contents,"foobar"); and SetAttrs(strobj,MUIA_String_Contents,"foobar",TAG_DONE); are equal. SEE ALSO MUIM_SetAsString, MUIM_Notify Notify.mui/MUIM_SetAsString NAME MUIM_SetAsString (V4) SYNOPSIS DoMethod(obj,MUIM_SetAsString,ULONG attr, char *format, ULONG val, /* ... */); FUNCTION Set a (text kind) attribute to a string. This can be useful if you want to connect a numeric attribute of an object with a text attribute of another object. INPUTS attr attribute to set. format C like formatting string, remember to use "%ld" ! val,... one or more paremeters for the format string. EXAMPLE stand alone: DoMethod(txobj,MUIM_SetAsString,MUIA_Text_Contents, "My name is %s and I am %ld years old.",name,age); within a notification statement: DoMethod(propobj,MUIM_Notify,MUIA_Prop_First,MUIV_EveryTime, txobj,4,MUIM_SetAsString,MUIA_Text_Contents, "prop gadget shows %ld.",MUIV_TriggerValue); SEE ALSO MUIM_Set, MUIM_Notify Notify.mui/MUIM_SetUData NAME MUIM_SetUData (V8) SYNOPSIS DoMethod(obj,MUIM_SetUData,ULONG udata, ULONG attr, ULONG val); FUNCTION This method tests if the MUIA_UserData of the object contains the given <udata> and sets <attr> to <val> for itself in this case. Altough this sounds not very useful for single objects, performing this method on objects that handle children can become very handy. In this case, all the children (any maybe their children) are tested against <udata> and all matching objects will get the attribute set. If you e.g. want to clear several string gadgets in your applciation at once, you simply give them the same MUIA_UserData and use DoMethod(app,MUIM_SetUData,MyUDATA,MUIA_String_Contents,NULL); INPUTS udata - userdata to look for. attr - attribute to set. val - value to set attribute to. NOTES If you have many objects in your application, MUIM_SetUData may take quite long. You can limit the amount of time by performing the method not on the application but on the window or even on the group your gadgets are place in. SEE ALSO MUIM_GetUData, MUIM_FindUData Notify.mui/MUIM_WriteLong NAME MUIM_WriteLong (V6) SYNOPSIS DoMethod(obj,MUIM_WriteLong,ULONG val, ULONG *memory); FUNCTION This method simply writes a longword somewhere to memory. Although this seems quite useless, it might become handy if used within a notify statement. For instance, you could easily connect the current level of a slider with some member of your programs data structures. INPUTS val - value to write memory - location to write the value to EXAMPLE /* Let the slider automagically write its level to a variable */ static LONG level; DoMethod(slider,MUIM_Notify,MUIA_Slider_Level,MUIV_EveryTime, slider,3,MUIM_WriteLong,MUIV_TriggerValue,&level); SEE ALSO MUIM_WriteString, MUIM_Notify Notify.mui/MUIM_WriteString NAME MUIM_WriteString (V6) SYNOPSIS DoMethod(obj,MUIM_WriteString,char *str, char *memory); FUNCTION This method simply copies a string somewhere to memory. Although this seems quite useless, it might become handy if used within a notify statement. For instance, you could easily connect the current contents of a string gadget with some member of your programs data structures. Note: The string is copied with strcpy(), you must assure that the destination points to enough memory. INPUTS str - string to copy memory - location to write the value to EXAMPLE static char buffer[256]; DoMethod(string,MUIM_Notify,MUIA_String_Contents,MUIV_EveryTime, string,3,MUIM_WriteString,MUIV_TriggerValue,buffer); SEE ALSO MUIM_WriteLong, MUIM_Notify Notify.mui/MUIA_AppMessage NAME MUIA_AppMessage -- (V5) [..G], struct AppMessage * FUNCTION When your window is an AppWindow, i.e. you have set the MUIA_Window_AppWindow attribute to TRUE, you will be able to get AppMessages by listening to MUIA_AppMessage. Whenever an AppMessage arrives, this attribute will be set to a pointer to that message. MUIA_AppMessage is object specific. You can e.g. set up different notifications for different objects in your window, they will only get exectued when icons are dropped over the specific object. If you wait on MUIA_AppMessage with a window object, your notify will always get executed when icons are dropped on the window. Notes: - You should use the MUIM_CallHook method to call a hook function when an AppMessage arrives (see below). The pointer to the AppMessage is valid only as long as the notification method is executed. - AppWindows are only possible on the workench screen. EXAMPLE /* Call the AppMsgHook when an icon is dropped on a listview */ DoMethod(lvobj,MUIM_Notify,MUIA_AppMessage,MUIV_EveryTime, lvobj,3,MUIM_CallHook,&AppMsgHook,MUIV_TriggerValue); /* Call the AppMsgHook when an icon is dropped on the window */ DoMethod(winobj,MUIM_Notify,MUIA_AppMessage,MUIV_EveryTime, winobj,3,MUIM_CallHook,&AppMsgHook,MUIV_TriggerValue); SEE ALSO MUIA_Window_AppWindow, MUIA_Application_DropObject, MUIM_CallHook Notify.mui/MUIA_HelpFile NAME MUIA_HelpFile -- (V4) [ISG], STRPTR (OBSOLETE) FUNCTION Since muimaster.library V8, this attribute is obsolete and replaced by MUIA_Application_HelpFile. SEE ALSO MUIA_Application_HelpFile, MUIA_HelpNode, MUIA_HelpLine Notify.mui/MUIA_HelpLine NAME MUIA_HelpLine -- (V4) [ISG], LONG FUNCTION Define a line in a help file specified with MUIA_Application_HelpFile. SEE ALSO MUIA_Application_HelpFile, MUIA_HelpNode Notify.mui/MUIA_HelpNode NAME MUIA_HelpNode -- (V4) [ISG], STRPTR FUNCTION Define a node in a help file specified with MUIA_Application_HelpFile. SEE ALSO MUIA_Application_HelpFile, MUIA_HelpLine Notify.mui/MUIA_NoNotify NAME MUIA_NoNotify -- (V7) [.S.], BOOL FUNCTION If you set up a notify on an attibute to react on user input, you will also recognize events when you change this attribute under program control with SetAttrs(). Setting MUIA_NoNotify together with your attribute will prevent this notification from being triggered. NOTE MUIA_NoNotify is a "one time" attribute. Its only valid during the current SetAttrs() call! EXAMPLE SetAttrs(slider,MUIA_NoNotify,TRUE,MUIA_Slider_Level,26,TAG_DONE); Notify.mui/MUIA_Revision NAME MUIA_Revision -- (V4) [..G], LONG FUNCTION Get the revision number of an objects class. Although MUIA_Revision is documented at notify class, you will of course receive the revision number of the objects true class. EXAMPLE strobj = MUI_NewObject(MUIC_String,...,TAG_DONE); ... get(strobj,MUIA_Version ,&v); get(strobj,MUIA_Revision,&r); printf("String class version %ld.%ld\n",v,r); SEE ALSO MUIA_Version Notify.mui/MUIA_UserData NAME MUIA_UserData -- (V4) [ISG], ULONG FUNCTION A general purpose value to fill in any kind of information. Notify.mui/MUIA_Version NAME MUIA_Version -- (V4) [..G], LONG FUNCTION Get the version number of an objects class. Although MUIA_Version is documented at notify class, you will of course receive the version number of the objects true class. EXAMPLE strobj = MUI_NewObject(MUIC_String,...,TAG_DONE); ... get(strobj,MUIA_Version ,&v); get(strobj,MUIA_Revision,&r); printf("String class version %ld.%ld\n",v,r); SEE ALSO MUIA_Revision