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

Text File | 1994-07-04 | 34.2 KB | 1,148 lines

TABLE OF CONTENTS

Application.mui/Application.mui
Application.mui/MUIM_Application_GetMenuCheck
Application.mui/MUIM_Application_GetMenuState
Application.mui/MUIM_Application_Input
Application.mui/MUIM_Application_InputBuffered
Application.mui/MUIM_Application_Load
Application.mui/MUIM_Application_PushMethod
Application.mui/MUIM_Application_ReturnID
Application.mui/MUIM_Application_Save
Application.mui/MUIM_Application_SetMenuCheck
Application.mui/MUIM_Application_SetMenuState
Application.mui/MUIM_Application_ShowHelp
Application.mui/MUIA_Application_Active
Application.mui/MUIA_Application_Author
Application.mui/MUIA_Application_Base
Application.mui/MUIA_Application_Broker
Application.mui/MUIA_Application_BrokerHook
Application.mui/MUIA_Application_BrokerPort
Application.mui/MUIA_Application_BrokerPri
Application.mui/MUIA_Application_Commands
Application.mui/MUIA_Application_Copyright
Application.mui/MUIA_Application_Description
Application.mui/MUIA_Application_DiskObject
Application.mui/MUIA_Application_DoubleStart
Application.mui/MUIA_Application_DropObject
Application.mui/MUIA_Application_ForceQuit
Application.mui/MUIA_Application_HelpFile
Application.mui/MUIA_Application_Iconified
Application.mui/MUIA_Application_Menu
Application.mui/MUIA_Application_MenuAction
Application.mui/MUIA_Application_MenuHelp
Application.mui/MUIA_Application_Menustrip
Application.mui/MUIA_Application_RexxHook
Application.mui/MUIA_Application_RexxMsg
Application.mui/MUIA_Application_RexxString
Application.mui/MUIA_Application_SingleTask
Application.mui/MUIA_Application_Sleep
Application.mui/MUIA_Application_Title
Application.mui/MUIA_Application_Version
Application.mui/MUIA_Application_Window
Application.mui/Application.mui

Application class is the master class for all
MUI applications. It serves as a kind of anchor
for all input, either coming from the user or
somewhere from the system, e.g. commodities
or ARexx messages.

An application can have any number of sub windows,
these windows are the children of the application.
Application.mui/MUIM_Application_GetMenuCheck

    NAME
    MUIM_Application_GetMenuCheck (V4) (OBSOLETE)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_GetMenuCheck,ULONG MenuID);

    FUNCTION
    Ask whether a checkmark menu item has its checkmark
    set or cleared.
    The application will ask its sub windows for a
    menu item with the given id and return the state of
    the first item it finds.

    INPUTS
    MenuID - the value you wrote into the
                 UserData field of struct NewMenu.

    SEE ALSO
    MUIM_Application_SetMenuCheck, MUIA_Application_Menu
Application.mui/MUIM_Application_GetMenuState

    NAME
    MUIM_Application_GetMenuState (V4) (OBSOLETE)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_GetMenuState,ULONG MenuID);

    FUNCTION
    Ask whether a menu item is enabled or disabled.
    The application will ask its sub windows for a
    menu item with the given id and return the state of
    the first item it finds.

    INPUTS
    MenuID - the value you wrote into the
                 UserData field of struct NewMenu.

    SEE ALSO
    MUIM_Application_SetMenuState, MUIA_Application_Menu
Application.mui/MUIM_Application_Input

    NAME
    MUIM_Application_Input (V4)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_Input,LONGBITS *signal);

    FUNCTION
    The MUI system itself does not wait for any user input.
    It just tells your application which signal bits it
    has allocated, then it's up to you to call MUIs input
    handle function when one of these signals gets set.

    In a simple MUI application you would just Wait()
    for these signals and call MUI when one is received.
    However, you can perfectly allocate some signal bits
    yourself and include them in your Wait() command.
    You needn't even Wait(), your application could
    maybe calculate some fractal graphics or copy
    disks, the only important thing is that you call
    MUI's input method when one of the MUI allocated
    signals arrives.

    The usual way of communication with your user
    interface is via return ids. Every action happening
    to the GUI can create return ids, e.g. pressing a
    button or trying to close a window. MUI buffers these
    ids and uses them as result codes for the input method.
    Thats where you can get it from and take the appropriate
    actions.

    Now lets have a look on a usual input loop of a
    MUI application. Imagine you have an Play and a
    Cancel button and have previously told them
    to return ID_PLAY and ID_CANCEL when pressed.
    (see MUIM_Notify and MUIM_Application_ReturnID
    on information about these topics). Your input
    loop would look like this:


    while (running)
    {
       ULONG signals;

       switch (DoMethod(app,MUIM_Application_Input,&signals))
       {
          case ID_PLAY:
             PlaySound();
             break;

          case ID_CANCEL:
          case MUIV_Application_ReturnID_Quit:
             running = FALSE;
             break;
       }

       if (running && signals) Wait(signals);
    }


    So what is happening here?

    First, you have to call the MUIM_Application_Input method.
    You supply the address of a ULONG as parameter, thats
    where MUI fills in the signals it needs. Note that you can
    call the input method at any time, regardless of signal
    setting. MUI will simply return when there is nothing
    to do.

    In case the user pressed the Play or the Cancel button,
    MUIM_Application_Input will return ID_PLAY or ID_CANCEL.
    Otherwise you will receive a 0, that's why you cannot
    use 0 as one of your id values.

    There is one predefined id called
    MUIV_Application_ReturnID_Quit. This will be sent to you
    when someone tried to quit your application from outside,
    e.g. via commodities exchange or the ARexx "quit" command.
    It is required that your application handles this id,
    just treat as if the user clicked on a "Quit" button or
    selected a "Quit" menu item.

    After handling the return value, you have to examine
    if MUI wants you to wait for any signals. If this
    is the case (signals != 0), just wait for it. If
    MUI puts a 0 into signals it wants to tell you to
    immediately call the input method again, maybe some
    other return ids have received and need to be handled.
    You *must* check this because Wait()ing on a zero
    signal mask is not a good idea!

    Note: It is very important that you call the input method
    whenever a signal arrives. MUI needs this to correctly
    refresh its windows, handle resizing and iconification
    operations and commodities and ARexx messages. If you
    don't, you will annoy your user!

    If your program needs to be in a state where you are
    for some reasons unable to call the input method for
    a considerable amount of time (maybe half a second or
    more), you should put your application to sleep. See
    MUIA_Application_Sleep on how to do this.

    SEE ALSO
    MUIA_Application_Sleep, MUIM_Application_InputBuffered
Application.mui/MUIM_Application_InputBuffered

    NAME
    MUIM_Application_InputBuffered (V4)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_InputBuffered,);

    FUNCTION
    Imagine your application does some time consuming
    operation, e.g. copying a disk, and you are for
    some reasons unable to react on return ids during
    this period. One solution would be to simply
    put your application to sleep, it will get a
    busy pointer and the user knows whats going on.

    However, this will make it impossible for the user
    to resize your applications windows or iconify it,
    he will have to wait until you are done with your
    operation.

    MUIM_Application_InputBuffered offers a solution
    for this problem. Using this method, you needn't
    set to sleep your application. Just call it on a
    regular basis and MUI will be able to handle
    all actions concerning the GUI. You do not need
    to pay attention on return values, they remain
    on an internal stack until your next call to
    the non buffered input method.

    EXAMPLE
    for (track=0; track<80; track++)
    {
       read_track();
       DoMethod(app,MUIM_Application_InputBuffered);
       write_track();
       DoMethod(app,MUIM_Application_InputBuffered);
    }

    SEE ALSO
    MUIM_Application_Input, MUIA_Application_Sleep
Application.mui/MUIM_Application_Load

    NAME
    MUIM_Application_Load (V4)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_Load,STRPTR name);

    FUNCTION
    MUIM_Application_Save, MUIM_Application_Load and
    MUIA_ExportID offer an easy way of saving and loading
    a programs configuration.

    Each gadget with a non NULL MUIA_ExportID will get
    its contents saved during MUIM_Application_Save and
    restored during MUIM_Application_Load. This makes
    it very easy to design a configuration window
    with "Save", "Use" and "Cancel" buttons to allow
    the user storing the settings. When the application
    starts, you would just have to call MUIM_Application_Load
    and the stored settings will be read and installed.

    Not all classes are able to import and export their
    contents. Currently, you may define MUIA_ExportIDs for

    String class  - MUIA_String_Contents is ex/imported.
    Radio class   - MUIA_Radio_Active is ex/imported.
    Cycle class   - MUIA_Cycle_Active is ex/imported.
    List class    - MUIA_List_Active is /ex/imported.
    Text class    - MUIA_Text_Contents is ex/imported.
    Slider class  - MUIA_Slider_Level is ex/imported.
    Area class    - MUIA_Selected is ex/imported
                    (e.g. for Checkmark gadgets)

    INPUTS
    name - Name of the file you wish to load the settings from.
           Usually you won't need to think of a real name but
           instead use one of the magic cookies
           MUIV_Application_Load_ENV or
           MUIV_Application_Load_ENVARC.

    EXAMPLE
    see the sample program "Settings.c"

    SEE ALSO
    MUIM_Application_Save, MUIA_ExportID
Application.mui/MUIM_Application_PushMethod

    NAME
    MUIM_Application_PushMethod (V4)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_PushMethod,Object *dest, LONG count, /* ... */);

    FUNCTION
    Usually, you may not talk to the MUI system from two
    tasks at the same time. MUIM_Application_PushMethod
    provides some kind of solution for this problem.

    This (and only this) method may be called from a
    second task. It takes another method as parameter
    and puts in onto a private stack of the application
    object. The next time MUIM_Application_Input
    is called, the pushed method will be executed
    in the context of the current task.

    INPUTS
    dest  - object on which to perform the pushed method.
        count - number of following arguments.
    ...   - the destination method.

    EXAMPLE
    /* set a status line from a sub task */
    DoMethod(app,MUIM_Application_PushMethod,
       txstatus,3,MUIM_Set,MUIA_Text_Contents,"reading...");

    SEE ALSO
    MUIM_Application_Input
Application.mui/MUIM_Application_ReturnID

    NAME
    MUIM_Application_ReturnID (V4)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_ReturnID,ULONG retid);

    FUNCTION
    Tell MUI to return the given id with the next call to
    MUIM_Application_Input.

    Together with the MUI's notification mechanism, this
    method connects your user interface and your program.
    If you e.g. want to be informed if the user presses
    a "Play" button, you would have define an id for
    this action and set up a notification event with
    MUIM_Notify.

    You can use any long word as return id, except
    from -255 up to 0. These values are reserved for
    MUI's internal use and for special return values
    like MUIV_Application_ReturnID_Quit.

    Note that MUI will put all incoming return ids
    onto a private fifo stack and feed this stack
    to its input methods result code later.

    EXAMPLE

    /* inform me if a button is pressed (actually released, */
    /* since this is the way amiga buttons are handled)     */

    #define ID_PLAYBUTTON 42

    ...

    DoMethod(buttonobj, MUIM_Notify,
       MUIA_Pressed, FALSE,
       appobj, 2, MUIM_Application_ReturndID, ID_PLAYBUTTON);

    ...

    while (running)
    {
       switch (DoMethod(appobj,MUIM_Application_Input,&sigs))
       {
          case ID_PLAYBUTTON:
             printf("Ok, lets play a game...");
             break;
       }
    }

    SEE ALSO
    MUIM_Application_Input, MUIM_Notify
Application.mui/MUIM_Application_Save

    NAME
    MUIM_Application_Save (V4)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_Save,STRPTR name);

    FUNCTION
    MUIM_Application_Save, MUIM_Application_Load and
    MUIA_ExportID offer an easy way of saving and loading
    a programs configuration.

    Each gadget with a non NULL MUIA_ExportID will get
    its contents saved during MUIM_Application_Save and
    restored during MUIM_Application_Load. This makes
    it very easy to design a configuration window
    with "Save", "Use" and "Cancel" buttons to allow
    the user storing the settings. When the application
    starts, you would just have to call MUIM_Application_Load
    and the stored settings will be read and installed.

    Not all classes are able to import and export their
    contents. Currently, you may define MUIA_ExportIDs for

    String class  - MUIA_String_Contents is ex/imported.
    Radio class   - MUIA_Radio_Active is ex/imported.
    Cycle class   - MUIA_Cycle_Active is ex/imported.
    List class    - MUIA_List_Active is /ex/imported.
    Text class    - MUIA_Text_Contents is ex/imported.
    Slider class  - MUIA_Slider_Level is ex/imported.
    Area class    - MUIA_Selected is ex/imported
                    (e.g. for Checkmark gadgets).

    INPUTS
    name - Name of the file you wish to save the settings to.
           Usually you won't need to think of a real name but
           instead use one of the magic cookies
           MUIV_Application_Save_ENV or
           MUIV_Application_Save_ENVARC.
           This will save your application's settings somewhere
           in env:mui/ or envarc:mui/, you needn't worry about
           it.

    EXAMPLE
    see the sample program "Settings.c"

    SEE ALSO
    MUIM_Application_Load, MUIA_ExportID
Application.mui/MUIM_Application_SetMenuCheck

    NAME
    MUIM_Application_SetMenuCheck (V4) (OBSOLETE)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_SetMenuCheck,ULONG MenuID, LONG stat);

    FUNCTION
    Set or clear the checkmark of a menu item.
    The application will ask its sub windows for menu items
    with the given id and set/clear all found
    entries.

    INPUTS
    MenuID - the value you wrote into the
                 UserData field of struct NewMenu.

    set    - TRUE to set checkmark, FALSE to clear

    SEE ALSO
    MUIM_Application_GetMenuCheck, MUIA_Application_Menu,
Application.mui/MUIM_Application_SetMenuState

    NAME
    MUIM_Application_SetMenuState (V4) (OBSOLETE)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_SetMenuState,ULONG MenuID, LONG stat);

    FUNCTION
    Enable or disable a menu item.
    The application will ask its sub windows for menu items
    with the given id and enable/disable all found
    entries.

    INPUTS
    MenuID - the value you wrote into the
                 UserData field of struct NewMenu.

    set    - TRUE to enable item, FALSE to disable.

    SEE ALSO
    MUIM_Application_GetMenuState, MUIA_Application_Menu,
Application.mui/MUIM_Application_ShowHelp

    NAME
    MUIM_Application_ShowHelp (V4)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_ShowHelp,Object *window, char *name, char *node, LONG line);

    FUNCTION
    Show an AmigaGuide help file. The application will be
    put to sleep until the file is displayed.

    Usually, you don't need to call this method directly.
    MUI comes with a sophisticated online help system,
    you just need to supply your gadgets with help nodes
    and everything will be handled automatically.

    INPUTS
    window - (Object *) - Help will appear on this windows
                          screen. May be NULL.
    name   - (char *)   - name of the help file
    node   - (char *)   - name of a node in this help file
    line   - (char *)   - line number

    SEE ALSO
    MUIA_HelpFile, MUIA_HelpNode, MUIA_HelpLine
Application.mui/MUIA_Application_Active

    NAME
    MUIA_Application_Active -- (V4) [ISG], BOOL

    FUNCTION
    This attribute reflects the state that the user adjusted
    with commodities Exchange. MUI itself doesn't pay any
    attention to it, this is up to you.

    SEE ALSO
    MUIA_Application_Broker
Application.mui/MUIA_Application_Author

    NAME
    MUIA_Application_Author -- (V4) [I.G], STRPTR

    FUNCTION
    Name of the applications author.

    EXAMPLE
    see MUIA_Application_Title

    SEE ALSO
    MUIA_Application_Title, MUIA_Application_Copyright,
    MUIA_Application_Version, MUIA_Application_Description,
    MUIA_Application_Base
Application.mui/MUIA_Application_Base

    NAME
    MUIA_Application_Base -- (V4) [I.G], STRPTR

    FUNCTION
    The basename for an application. This name is used
    for the builtin ARexx port and for some internal
    file management.

    A basename must neither contain spaces nor any
    special characters such as ":/()#?*...".

    When your program is a single task application
    (i.e. MUIA_Application_SingleTask is TRUE), the
    base name will be used without further modification.

    Otherwise, it gets a ".1", ".2", etc. appended,
    depending on how many applications are already
    running. If you need to know the name of your
    ARexx port, you can query the base name attribute
    after the application is created.

    EXAMPLE
    see MUIA_Application_Title

    SEE ALSO
    MUIA_Application_Title, MUIA_Application_Version,
    MUIA_Application_Author, MUIA_Application_Copyright,
    MUIA_Application_Description
Application.mui/MUIA_Application_Broker

    NAME
    MUIA_Application_Broker -- (V4) [..G], Broker *

    FUNCTION
    If you need to attach some additional commodities objects
    to your application (e.g. because you need lots of hotkeys),
    you can obtain a pointer to the applications Broker structure
    and add some commodities objects.

    MUI will free the complete broker when the application is
    disposed, no need for you to free your objects yourself.

    To receive input from your objects, you will also need to
    install a MUIA_Application_BrokerHook.

    NOTES
    Unless you have set MUIA_Application_RequiresCX, you must be
    prepared to receive a NULL pointer. In this case, the
    commodities interface is not available, maybe because the
    user installed a light version of MUI.

    SEE ALSO
    MUIA_Application_BrokerHook
Application.mui/MUIA_Application_BrokerHook

    NAME
    MUIA_Application_BrokerHook -- (V4) [ISG], struct Hook *

    FUNCTION
    You specify a pointer to hook structure. The function
    will be called whenever a commodities message arrives
    (between MUI's GetMsg() and ReplyMsg()).

    You receive a pointer to the application object
    as object in a2 and a pointer to commodities
    CxMsg message in a1.

    NOTES
    The commodities interface isn't available in the
    memory saving "light" version of MUI. Your hook
    will never be called in this case.

    SEE ALSO
    MUIA_Application_Broker
Application.mui/MUIA_Application_BrokerPort

    NAME
    MUIA_Application_BrokerPort -- (V6) [..G], struct MsgPort *

    FUNCTION
    Get a pointer to the applications commodities message port.
    If you want to add own Hotkeys to your application, you
    need a message port. Instead of creating your own, you
    should better use this one.

    NOTES
    Unless you have set MUIA_Application_RequiresCX, you must be
    prepared to receive a NULL pointer. In this case, the
    commodities interface is not available, maybe because the
    user installed a light version of MUI.

    SEE ALSO
    MUIA_Application_BrokerHook
Application.mui/MUIA_Application_BrokerPri

    NAME
    MUIA_Application_BrokerPri -- (V6) [I.G], LONG

    FUNCTION
    Adjust the priority of an applications broker.

    SEE ALSO
    MUIA_Application_BrokerHook
Application.mui/MUIA_Application_Commands

    NAME
    MUIA_Application_Commands -- (V4) [ISG], struct MUI_Command *

    FUNCTION
    This attribute allows an application to include
    its own set of ARexx commands. You specify a
    pointer to an array of MUI_Command structures,
    which look like this:

    struct MUI_Command
    {
       char        *mc_Name;
       char        *mc_Template;
       LONG         mc_Parameters;
       struct Hook *mc_Hook;
       LONG         mc_Reserved[5];
    };

    mc_Name       contains the name of your command.
                  Commands are not case sensitive.

    mc_Template   is an argument template that follows
                  the same rules as dos.library/ReadArgs().
                  It may be NULL, in which case your command
                  doesn't need any parameters.

    mc_Parameters is the number of parameters specified
                  in the template array.

    mc_Hook       is a pointer to the callback hook defining
                  the function to be called.

    You may specify any number of MUI_Command structures,
    but you must terminate your array with a NULL field.

    When a command shows up an applications ARexx port,
    MUI parses the arguments according to the given
    template and calls the hook with the application
    object as hook object in a2 and a pointer to
    an array of longwords containing the parameters
    in a1.

    The result code of your hook will be replied to
    ARexx as rc.

    If you have some simple ARexx commands that just
    emulate some user action (e.g. clicking a button),
    you can use the magic cookie MC_TEMPLATE_ID for
    mc_Template and a return id value for mc_Parameters.
    In this case, MUI will do no argument parsing and
    instead simply return the specified id value on the
    next call to MUIM_Application_Input.

    For more sophisticated possibilities in ARexx
    callback hooks, please refer to
    MUIA_Application_RexxMsg and MUIA_Application_RexxString.

    EXAMPLE
    static struct MUI_Command commands[] =
    {
       { "rescan", MC_TEMPLATE_ID, ID_RESCAN, NULL     },
       { "select", "PATTERN/A"   , 1        , &selhook },
       { NULL    , NULL          , NULL     , NULL     }
    };

    SEE ALSO
    MUIA_Application_RexxMsg, MUIA_Application_RexxString
Application.mui/MUIA_Application_Copyright

    NAME
    MUIA_Application_Copyright -- (V4) [I.G], STRPTR

    FUNCTION
    A copyright string, containing the year and the
    company.

    EXAMPLE
    see MUIA_Application_Title

    SEE ALSO
    MUIA_Application_Title, MUIA_Application_Version,
    MUIA_Application_Author, MUIA_Application_Description,
    MUIA_Application_Base
Application.mui/MUIA_Application_Description

    NAME
    MUIA_Application_Description -- (V4) [I.G], STRPTR

    FUNCTION
    Short description, about 40 characters.
    Shown e.g. in commodities exchange.

    EXAMPLE
    see MUIA_Application_Title

    SEE ALSO
    MUIA_Application_Title, MUIA_Application_Version,
    MUIA_Application_Author, MUIA_Application_Copyright,
    MUIA_Application_Base
Application.mui/MUIA_Application_DiskObject

    NAME
    MUIA_Application_DiskObject -- (V4) [ISG], struct DiskObject *

    FUNCTION
    Pointer to a struct DiskObject, e.g. obtained
    from GetDiskObject(). If present, MUI will use
    this object for the AppIcon when your application
    gets iconified.

    Otherwise MUI will try to locate "env:sys/dev_mui.info"
    and, if not present, fall back to a default icon.

    EXAMPLE
    ...
    MUIA_Application_DiskObject,
       dobj = GetDiskObject("PROGDIR:MyApp"),
    ...

    /* note that you have to free dobj yourself! */

    NOTES
    Unless you have set MUIA_Application_RequiresIconification,
    this attribute might have no effect, maybe because the
    user installed a light version of MUI. You must be prepared
    to receive a NULL pointer when you try to read it!

   SEE ALSO
    MUIA_Application_Iconified
Application.mui/MUIA_Application_DoubleStart

    NAME
    MUIA_Application_DoubleStart -- (V4) [..G], BOOL

    FUNCTION
    This attribute is set automatically when the user
    tries to start a MUIA_SingleTask application twice.
    You can react on this and take appropriate actions,
    e.g. pop up a requester or quit yourself.

    SEE ALSO
    MUIA_Application_SingleTask
Application.mui/MUIA_Application_DropObject

    NAME
    MUIA_Application_DropObject -- (V5) [IS.], Object *

    FUNCTION
    If your application is iconified and the user drops
    icons onto the AppIcon, the object specified here will
    receive the AppMessage.

    SEE ALSO
    MUIA_Window_AppWindow, MUIM_CallHook
Application.mui/MUIA_Application_ForceQuit

    NAME
    MUIA_Application_ForceQuit -- (V8) [..G], BOOL

    FUNCTION
    When your input loop receives a MUIV_Application_ReturnID_Quit,
    you should query this attribute. In case its TRUE, your program
    should exit quietly without popping up any safety requesters or
    other stuff.

    MUI will e.g. set this if the user issued a "QUIT FORCE" ARexx
    command to your application.
Application.mui/MUIA_Application_HelpFile

    NAME
    MUIA_Application_HelpFile -- (V8) [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 and the application
    defines a MUIA_Application_HelpFile, MUI tries to obtain
    MUIA_HelpNode from the current object (the one under
    the mouse pointer). If MUIA_HelpNode 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_HelpNode is found, the same procedure
    is applied to MUIA_HelpLIne. Then MUI puts the application
    to sleep and displays the file at the position specified
    with MUIA_HelpNode and/or MUIA_HelpLine.

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

    EXAMPLE

    ApplicationObject,
       ...
       MUIA_Application_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.

    NOTES
    Since muimaster.library V8, this attribute replaces the old
    and obsolete MUIA_HelpFile attribute. MUI no longer supports
    the possibility to specify different help files for different
    parts of your application. This step was necessary due to
    some other internal changes and enhancements.

    SEE ALSO
    MUIA_HelpNode, MUIA_HelpLine
Application.mui/MUIA_Application_Iconified

    NAME
    MUIA_Application_Iconified -- (V4) [.SG], BOOL

    FUNCTION
    Setting this attribute to TRUE causes the application
    to become iconified. Every open window will be closed
    and a (configurable) AppIcon will appear on the workbench.

    Same thing happens when the user hits the iconify gadget
    in the window border or uses commodities Exchange to
    hide your applications interface.

    There is no way for you to prevent your application from
    being iconified. However, you can react on the iconification
    by listening to the MUIA_Application_Iconified attribute
    with notification. This allows you to free some resources
    you don't need in iconified state.

    When an application is iconified and you try to open a
    window, the window won't open immediately. Instead MUI
    remembers this action and opens the window once the
    application is uniconified again.

    EXAMPLE

    /* inform the main input loop of iconification events */

    #define ID_HIDE 42
    #define ID_SHOW 24

    DoMethod(app,MUIM_Notify,
       MUIA_Application_Iconified, TRUE,
       app, 2, MUIM_Application_ReturnID, ID_HIDE);

    DoMethod(app,MUIM_Notify,
       MUIA_Application_Iconified, FALSE,
       app, 2, MUIM_Application_ReturnID, ID_SHOW);

    SEE ALSO
    MUIA_Application_DiskObject
Application.mui/MUIA_Application_Menu

    NAME
    MUIA_Application_Menu -- (V4) [I.G], struct NewMenu * (OBSOLETE)

    FUNCTION
    Obsolete, use MUIA_Application_Menustrip instead.

    SEE ALSO
    MUIA_Application_Menustrip
Application.mui/MUIA_Application_MenuAction

    NAME
    MUIA_Application_MenuAction -- (V4) [..G], ULONG

    FUNCTION
    Whenever a menu item is selected, this attribute will be
    set to the corresponding UserData field of the gadtools
    NewMenu structure. This allows reacting on menu items
    via broadcasting.

    SEE ALSO
    MUIA_Application_Menu, MUIA_Application_MenuAction
Application.mui/MUIA_Application_MenuHelp

    NAME
    MUIA_Application_MenuHelp -- (V4) [..G], ULONG

    FUNCTION
    Whenever a menu item is selected with the help key, this
    attribute will be set to the corresponding UserData field
    of the gadtools NewMenu structure. Together with
    MUIM_Application_ShowHelp this allows creation of
    menu help texts.

    SEE ALSO
    MUIA_Application_Menu, MUIA_Application_ShowHelp
Application.mui/MUIA_Application_Menustrip

    NAME
    MUIA_Application_Menustrip -- (V8) [I..], Object *

    FUNCTION
    Specify a menu strip object for the application. The object
    is treated as a child of the application and will be disposed
    when the application is disposed.

    Menustrip objects defined for the application are used
    as menu for every window of the application, as long as
    the window doesn't define its private menu.

    MUIA_Application_Menustrip replaces the old and obsolete
    MUIA_Application_Menu tag.

    Usually, you will create the menu object with MUI's builtin
    object library from a gadtools NewMenu structure, but its
    also OK to define the menu tree "by hand" using the
    Family class.
Application.mui/MUIA_Application_RexxHook

    NAME
    MUIA_Application_RexxHook -- (V7) [ISG], struct Hook *

    FUNCTION
    When specified, MUI calls this hook whenever a rexx message
    arrives and MUI can't map it to a builtin or a programmer
    specified command. The hook will be called with a pointer
    to itself in A0, a pointer to the application object in A2
    and a pointer to a struct RexxMsg in A1.

    The return code from the hook is used as result code
    when replying the message, the secondary result can
    be set with MUIA_Application_RexxString.

    SEE ALSO
    MUIA_Application_Commands
Application.mui/MUIA_Application_RexxMsg

    NAME
    MUIA_Application_RexxMsg -- (V4) [..G], struct RxMsg *

    FUNCTION
    Within an ARexx callback hook, you can obtain
    a pointer to the RexxMsg that came with the
    command. This allows you to use some ARexx
    support functions coming with amiga.lib

    SEE ALSO
    MUIA_Application_Commands, MUIA_Application_RexxString
Application.mui/MUIA_Application_RexxString

    NAME
    MUIA_Application_RexxString -- (V4) [.S.], STRPTR

    FUNCTION
    ARexx allows returning a string as result of a
    function call. This attribute allows setting the
    result string within an ARexx callback hook.

    The string is temporarily copied.

    SEE ALSO
    MUIA_Application_Commands, MUIA_Application_RexxMsg
Application.mui/MUIA_Application_SingleTask

    NAME
    MUIA_Application_SingleTask -- (V4) [I..], BOOL

    FUNCTION
    Boolean value to indicate whether or not your application
    is a single task program. When set to TRUE, MUI will
    refuse to create more than one application object.

    In this case, the already running application gets its
    MUIA_DoubleStart attribute set to TRUE. You can listen
    to this and take appropriate actions, e.g. pop up
    a requester.

    Examples for single task applications are the system
    preferences program. It doesn't make sense for them
    to run more than once.

    SEE ALSO
    MUIA_Application_DoubleStart
Application.mui/MUIA_Application_Sleep

    NAME
    MUIA_Application_Sleep -- (V4) [.S.], BOOL

    FUNCTION
    This attribute can be used to put a whole application
    to sleep. All open windows get disabled and a busy
    pointer appears.

    This attribute contains a nesting count, if you tell
    your application to sleep twice, you will have to tell
    it to wake up twice too.

    If you need to do some time consuming actions, you
    always should set this attribute to inform the user
    that you are currently unable to handle input.

    A sleeping application's windows cannot be resized.

    EXAMPLES
    set(app,MUIA_Application_Sleep,TRUE ); // go to bed
    calc_fractals();
    set(app,MUIA_Application_Sleep,FALSE); // wake up

    SEE ALSO
    MUIA_Window_Sleep, MUIM_Application_InputBuffered
Application.mui/MUIA_Application_Title

    NAME
    MUIA_Application_Title -- (V4) [I.G], STRPTR

    FUNCTION
    This tag defines the title of an application.
    The title is e.g. shown in Commodities Exchange
    or in the MUI preferences program.

    An application title shall not contain any version
    information, just the pure title. Also, special
    characters such as ":/()#?*..." are not allowed.

    You should use a quiet long and unique name for
    your applications. Naming it "Viewer" or "Browser"
    is not a wise choice.

    The length of the name must not exceed 30 characters!

    EXAMPLE
    ApplicationObject,
       MUIA_Application_Title      , "WbMan",
       MUIA_Application_Version    , "$VER: WbMan 0.24 (19.7.93)",
       MUIA_Application_Copyright  , "© 1993 by Klaus Melchior",
       MUIA_Application_Author     , "Klaus Melchior",
       MUIA_Application_Description, "Manages the WBStartup.",
       MUIA_Application_Base       , "WBMAN",
       ...

    SEE ALSO
    MUIA_Application_Version, MUIA_Application_Copyright,
    MUIA_Application_Author, MUIA_Application_Description,
    MUIA_Application_Base
Application.mui/MUIA_Application_Version

    NAME
    MUIA_Application_Version -- (V4) [I.G], STRPTR

    FUNCTION
    Define a version string for an application.
    This string shall follow standard version string
    convetions but must *not* contain a leading "\0".

    EXAMPLE
    see MUIA_Application_Title

    SEE ALSO
    MUIA_Application_Title, MUIA_Application_Copyright,
    MUIA_Application_Author, MUIA_Application_Description,
    MUIA_Application_Base
Application.mui/MUIA_Application_Window

    NAME
    MUIA_Application_Window -- (V4) [I..], Object *

    FUNCTION
    A pointer to a MUI object of Window class. An
    application may have any number of sub windows,
    each of them being a child of the application.

    When the application receives some kind of user
    input through its IDCMP, it diverts the message
    down to its children, as long as they are opened.

    Things like iconification or preferences changes
    cause the application object to temporarily close
    every open window (and reopen it later). Your
    main program normally doesn't need to deal with
    these things.

    As with the children of group class, it's common
    to use a call to MUI_NewObject() as value for
    this attribute. No error checking needs to be
    done, the application object handles every
    failure automatically.

    When you dispose your application, its sub windows
    will also get deleted. Thus, the only thing to do
    to remove your application is a

    MUI_DisposeObject(ApplicationObject);

    Every window, every gadget, every memory will be
    freed by this single call.

    EXAMPLE
    Please refer to one of the example programs.

    SEE ALSO