Graphics Plus/Graphics Plus.iso/amiga/gui/mui/mui14-dv.lha/MUI/Developer/Autodocs/MUI_Notify.doc

Text File | 1993-10-28 | 13.3 KB | 465 lines

TABLE OF CONTENTS

Notify.mui/Notify.mui
Notify.mui/MUIM_CallHook
Notify.mui/MUIM_Notify
Notify.mui/MUIM_Set
Notify.mui/MUIM_SetAsString
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_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

    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_Notify

    NAME
    MUIM_Notify

    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.

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

    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

    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_WriteLong

    NAME
    MUIM_WriteLong

    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

    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 -- [..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 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 -- [ISG], STRPTR

    FUNCTION
    This attribute allows defining an AmigaGuide style file
    to be displayed when the user requests online help.

    When the HELP button is pressed, MUI tries to obtain
    MUIA_HelpFile from the current object (the one under
    the mouse pointer). If MUIA_HelpFile is not defined,
    MUI continues asking the parent object for this
    attribute (usually a group, but remember: the parent
    of a windows root object is the window itself, the
    parent of a window is the application).

    When a non NULL MUIA_HelpFile is found, the same procedure
    is applied to MUIA_HelpNode and MUIA_HelpLine. Then MUI
    puts the application to sleep and displays the file at
    the position specified width MUIA_HelpNode and/or MUIA_HelpLine.

    This behaviour allows you e.g. to define one MUIA_HelpFile
    for your application object and different help nodes
    and lines for your applications windows and/or gadgets.

    EXAMPLE

    ApplicationObject,
       ...
       MUIA_HelpFile, "progdir:myapp.guide",
       ...,
       SubWindow, WindowObject,
          MUIA_Window_Title, "Prefs Window",
          ...,
          MUIA_HelpNode, "prefs-section",
          ...,
          End,

       SubWindow, WindowObject,
          MUIA_Window_Title, "Play Window",
          ...
          MUIA_HelpNode, "play-section",
          ...
          WindowContents, VGroup,
             ...,
             Child, StringObject,
                MUIA_HelpNode, "play-string",
                ...,
                End,
             End,
          End,
       End;

    In this case, the user will get the prefs-section chapter
    of "myapp.guide" when he requests help in the Prefs window,
    the play-string chapter when he requests help over the
    string gadget in the Play window or the play-section
    chapter somewhere else in the Play window.

    SEE ALSO
    MUIA_HelpNode, MUIA_HelpLine
Notify.mui/MUIA_HelpLine

    NAME
    MUIA_HelpLine -- [ISG], LONG

    FUNCTION
    Define a line in a help file specified with MUIA_HelpFile.

    SEE ALSO
    MUIA_HelpFile, MUIA_HelpNode
Notify.mui/MUIA_HelpNode

    NAME
    MUIA_HelpNode -- [ISG], STRPTR

    FUNCTION
    Define a node in a help file specified with MUIA_HelpFile.

    SEE ALSO
    MUIA_HelpFile, MUIA_HelpLine
Notify.mui/MUIA_Revision

    NAME
    MUIA_Revision -- [..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 -- [ISG], ULONG

    FUNCTION
    A general purpose value to fill in any kind of information.
Notify.mui/MUIA_Version

    NAME
    MUIA_Version -- [..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