Amiga Format CD 5/amigaformatcd05.iso/mui/developer/autodocs/mui_notify.doc

Text File | 1996-08-13 | 22.0 KB | 770 lines

TABLE OF CONTENTS

Notify.mui/Notify.mui
Notify.mui/MUIA_ApplicationObject
Notify.mui/MUIA_AppMessage
Notify.mui/MUIA_HelpLine
Notify.mui/MUIA_HelpNode
Notify.mui/MUIA_NoNotify
Notify.mui/MUIA_Parent
Notify.mui/MUIA_Revision
Notify.mui/MUIA_UserData
Notify.mui/MUIA_Version
Notify.mui/MUIM_CallHook
Notify.mui/MUIM_Export
Notify.mui/MUIM_FindUData
Notify.mui/MUIM_GetUData
Notify.mui/MUIM_Import
Notify.mui/MUIM_KillNotify
Notify.mui/MUIM_MultiSet
Notify.mui/MUIM_NoNotifySet
Notify.mui/MUIM_Notify
Notify.mui/MUIM_Set
Notify.mui/MUIM_SetAsString
Notify.mui/MUIM_SetUData
Notify.mui/MUIM_SetUDataOnce
Notify.mui/MUIM_WriteLong
Notify.mui/MUIM_WriteString
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/MUIA_ApplicationObject

    NAME
    MUIA_ApplicationObject -- (V4 ) [..G], Object *

    FUNCTION
    You can obtain a pointer to the application object
    that some gadget belongs to by using this attribute.
    Useful mainly within callback hooks if you do not want
    to deal with global variables.

    If your object is not currently attached to an application,
    you will receive NULL.

    SEE ALSO
    MUIA_WindowObject
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_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_Parent

    NAME
    MUIA_Parent -- (V11) [..G], Object *

    FUNCTION
    Get a pointer to the parent object of the current object.
    The parent obect is always the group/family object which
    contains the current object. If an object has no parent
    group, this attribute will be NULL.

    SEE ALSO
    group.mui/MUIA_Group_Child
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
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_Export

    NAME
    MUIM_Export (V12)

    SYNOPSIS
    DoMethod(obj,MUIM_Export,Object *dataspace);

    FUNCTION
    This method is called for each object in the application tree
    (including menus) during execution of MUIM_Application_Save.
    It's purpose is to export an objects "contents" to a dataspace
    object for later saving to an IFF file.

    If you override this method to export your custom data, you
    are supposed to use your MUIA_ObjectID as ID for the dataspace
    entry. Don't export if your MUIA_ObjectID is 0.

    RESULT
    Always return 0 or the value from DoSuperMethod() if you want
    your parent classes to be able to import theirselves.

    EXAMPLE
    ULONG mExport(struct IClass *cl,Object *obj,struct MUIP_Export *msg)
    {
       struct Data *mydata = INST_DATA(cl,obj);
       ULONG id;
       ULONG exp=0;

       if (id=(muiNotifyData(obj)->mnd_ObjectID))
       {
          DoMethod(msg->dataspace,MUIM_Dataspace_Add,
                   &mydata->myvalue,sizeof(LONG),id);
       }

       return(0);
    }

    SEE ALSO
    MUIM_Import, application.mui/MUIM_Application_Load,
    application.mui/MUIM_Application_Save
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.

    Although this is 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 placed 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.

    Although this is 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_Import

    NAME
    MUIM_Import (V12)

    SYNOPSIS
    DoMethod(obj,MUIM_Import,Object *dataspace);

    FUNCTION
    This method is called for each object in the application tree
    (including menus) during execution of MUIM_Application_Load.
    It's purpose is to import an objects "contents" from a dataspace
    object after loading from an IFF file.

    If you override this method to import your custom data, you
    are supposed to use your MUIA_ObjectID as ID for the dataspace
    entry. Don't import if your MUIA_ObjectID is 0.

    RESULT
    Always return 0 or the value from DoSuperMethod() if you want
    your parent classes to be able to import theirselves.

    EXAMPLE
    ULONG mImport(struct IClass *cl,Object *obj,struct MUIP_Import *msg)
    {
       struct Data *mydata = INST_DATA(cl,obj);
       ULONG id;
       ULONG *data;

       if (id=(muiNotifyData(obj)->mnd_ObjectID))
       {
          if (data = (ULONG *)DoMethod(msg->dataspace,MUIM_Dataspace_Find,id))
          {
             mydata->myvalue = *data;
          }
       }

       return(0);
    }

    SEE ALSO
    MUIM_Import, application.mui/MUIM_Application_Load,
    application.mui/MUIM_Application_Save
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_NoNotifySet

    NAME
    MUIM_NoNotifySet (V9 )

    SYNOPSIS
    DoMethod(obj,MUIM_NoNotifySet,ULONG attr, char *format, ULONG val, /* ... */);

    FUNCTION
    Acts like MUIM_Set but doesn't trigger any notification.
    This can become useful to avoid deadlocks with bi-directional
    connections.

    INPUTS
    attr  attribute you want to set.
    val   value to set the attribute to.

    EXMAPLE
    DoMethod(editor,MUIM_Notify,EDIT_Top,MUIV_EveryTime,
       sbar,3,MUIM_NoNotifySet,MUIA_Prop_First,MUIV_TriggerValue);

    DoMethod(sbar,MUIM_Notify,MUIA_Prop_First,MUIV_EveryTime,
       editor,3,MUIM_NoNotifySet,EDIT_Top,MUIV_TriggerValue);

    SEE ALSO
    MUIM_Set
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. Either supply a valid object pointer or
                 one of the following special values (V10) which
                 will be resolved at the time the event occurs:
                 MUIV_Notify_Self        - notifies the object
                                           itself.
                 MUIV_Notify_Window      - notifies the object's
                                           parent window.
                 MUIV_Notify_Application - notifies the object's
                                           application.

    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,
       MUIV_Notify_Application, 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, MUIM_NoNotifySet
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 is 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, MUIM_SetUDataOnce
Notify.mui/MUIM_SetUDataOnce

    NAME
    MUIM_SetUDataOnce (V11)

    SYNOPSIS
    DoMethod(obj,MUIM_SetUDataOnce,ULONG udata, ULONG attr, ULONG val);

    FUNCTION
    This method performs like MUIM_SetUData, but stops when it has
    found an object with the given user data. If you don't have
    objects with equal user datas and don't rely on setting all
    of them, MUIM_SetUDataOnce is preferrable because it's more
    efficient.

    SEE ALSO
    MUIM_SetUData, MUIM_GetUData

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