Amiga Format CD 13/amigaformatcd13.iso/mui/mui_developer/autodocs/mui_application.doc

Text File | 1997-03-10 | 47KB | 1,525 lines

TABLE OF CONTENTS

Application.mui/Application.mui
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_UseCommodities
Application.mui/MUIA_Application_UseRexx
Application.mui/MUIA_Application_Version
Application.mui/MUIA_Application_Window
Application.mui/MUIA_Application_WindowList
Application.mui/MUIM_Application_AboutMUI
Application.mui/MUIM_Application_AddInputHandler
Application.mui/MUIM_Application_CheckRefresh
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_NewInput
Application.mui/MUIM_Application_OpenConfigWindow
Application.mui/MUIM_Application_PushMethod
Application.mui/MUIM_Application_RemInputHandler
Application.mui/MUIM_Application_ReturnID
Application.mui/MUIM_Application_Save
Application.mui/MUIM_Application_SetConfigItem
Application.mui/MUIM_Application_SetMenuCheck
Application.mui/MUIM_Application_SetMenuState
Application.mui/MUIM_Application_ShowHelp
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/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
    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
    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! */

   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_Application_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_Application_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_UseCommodities

    NAME
    MUIA_Application_UseCommodities -- (V10) [I..], BOOL

    FUNCTION
    When set to FALSE, the application will run without a
    commodities interface. Think very well before using this
    tag!

    SEE ALSO
        MUIA_Application_UseRexx
Application.mui/MUIA_Application_UseRexx

    NAME
    MUIA_Application_UseRexx -- (V10) [I..], BOOL

    FUNCTION
    When set to FALSE, the application will run without an
    ARexx interface. Think very well before using this
    tag!

    SEE ALSO
        MUIA_Application_UseCommodities
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
Application.mui/MUIA_Application_WindowList

    NAME
    MUIA_Application_WindowList -- (V13) [..G], struct List *

    FUNCTION
    This attribute returns a pointer to the exec list structure
    which contains the children (i.e. windows) of an application.
    Parse this with intuition.library/NextObject()!
Application.mui/MUIM_Application_AboutMUI

    NAME
    MUIM_Application_AboutMUI (V14)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_AboutMUI,Object *refwindow);

    FUNCTION
    Show the MUI about window. Please include that in all your
    applications and link with a menu item called "About MUI...".

    INPUTS
    - refwindow: pointer to a window object as reference. If !=NULL,
    the MUI about window is centered according to this window. Note
    that this points to a MUI window object, not to a struct window.

    EXAMPLE
    DoMethod((Object *)DoMethod(strip,MUIM_FindUData,MEN_ABOUT),
       MUIM_Notify,MUIA_Menuitem_Trigger,MUIV_EveryTime,
       MUIV_Notify_Application,2,MUIM_Application_AboutMUI,mywinobj);
Application.mui/MUIM_Application_AddInputHandler

    NAME
    MUIM_Application_AddInputHandler (V11)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_AddInputHandler,struct MUI_InputHandlerNode *ihnode);

    FUNCTION
    Up to MUI 2.3, it was not easy to build custom classes which
    should react on signals of private message ports. For example,
    a clock class would want to be notified every second to update
    its display. Old versions of MUI forced you to Wait() for
    a timer signal in the main loop and notify the custom class.

    Since MUI 3, the existance of so called "input handlers"
    (don't mix up with input.device input handler) eliminates
    the need of dealing with the main loop in these cases.
    A class can create message ports and react on their
    signals on its own without interferring the main program.

    For a clock class, this would mean that you simply create
    the object into any MUI window and it starts updating
    itself every second automatically. A game class could open
    the gameport.device and react on joystick messages, an
    html class could talk to network ports all on its own.

    All this helps to further encapsulate your program into
    subclasses and make it a lot more easy to maintain. Let
    me repeat the main loop of an ideal MUI application here:

    ULONG sigs = 0;

    while (DoMethod(app,MUIM_Application_NewInput,&sigs)
           != MUIV_Application_ReturnID_Quit)
    {
        if (sigs)
        {
            sigs = Wait(sigs | SIGBREAKF_CTRL_C);
            if (sigs & SIGBREAKF_CTRL_C) break;
        }
    }

    To be able to react on signals, you must fill out a
    MUI_InputHandlerNode structure (probably located in
    your classes instance data) and call
    MUIM_Application_AddInputHandler with the structure
    as parameter. From now on, your class will receive
    the specified method whenever one of the given signals
    arrives.

    Since we're talking about a method of application
    class here, it's clear that you cannot call it until
    you know about your application object. Good places
    for MUIM_Application_AddInputHandler/RemInputHandler
    are probably the MUIM_Setup/MUIM_Cleanup methods
    of your class.

    INPUTS
    ihnode - Pointer to an initialized MUI_InputHandlerNode
             structure:
             ihn_Object  - fill in a pointer to your object.
             ihn_Signals - signals you wish to be notified on.
                           You can set more than one bit here.
             ihn_Flags   - always set to 0 for now.
             ihn_Method  - method that you want to receive
                           when one of ihn_Signals is set.

    RESULT
    MUIM_Application_AddInputHandler cannot fail, the result
    value of the method is currently undefined.

    NOTES
    You must match each AddInputHandler with exatly
    one RemInputHandler method. Do not add a
    MUI_InputHandlerNode which is currently in use.

    IMPORTANT: Your trigger method might also be
    called when none of your signals arrived. You *must*
    make sure that you check your conditions in
    the trigger method (if (GetMsg(port) ... or
    if (CheckIO(req)) ...). Also, please make these
    checks quick and return FALSE as fast as possible
    when none of your conditions was met. Return TRUE
    if you have "used" the trigger method.

    TIMER
    Since muimaster.library V13, MUIs application class
    implements a builtin timer. By using this one instead
    of creating your own IO requests, you avoid the problem
    of having each instance of your object allocating a
    signal bit.

    To make use of this timer, use the above described procedure
    of initializing and adding your MUI_InputHandlerNode structure,
    but set the MUIIHNF_TIMER in ihn_Flags. Furthermore, specify
    the number of milliseconds after which you want to receive your
    method in ihn_Millis. Note that ihn_Millis is in fact part of a
    union placed at the same memory location as ihn_Signals, do not
    use ihn_Signals when MUIIHNF_TIMER is set.

    Besides from MUIIHNF_TIMER and ihn_Millis instead of ihn_Signals,
    using the timer is similiar to other input handlers. Removing
    with MUIM_Application_RemInputHandler is not different at all.

    EXAMPLE
    OM_NEW:
       data->port = CreateMsgPort();
       data->req = CreateIORequest(data->port,sizeof(struct timer));
       OpenDevice(TIMERNAME,UNIT_VBLANK,(struct IORequest *)data->req,0);
       data->ihnode.ihn_Object  = obj;
       data->ihnode.ihn_Signals = IO_SIGMASK(data->req);
       data->ihnode.ihn_Flags   = 0;
       data->ihnode.ihn_Method  = MY_TRIGGER_METHOD;

    OM_DISPOSE:
       CloseDevice((struct IORequest *)data->req);
       DeleteIORequest(data->req);
       DeleteMsgPort(data->port);

    MUIM_Setup:
       data->req->tr_node.io_Command = TR_ADDREQUEST;
       data->req->tr_time.tv_secs    = 1;
       data->req->tr_time.tv_micro   = 0;
       SendIO((struct IORequest *)data->req);
       DoMethod(_app(obj),MUIM_Application_AddInputHandler,&data->ihnode);

    MUIM_Cleanup:
       DoMethod(_app(obj),MUIM_Application_RemInputHandler,&data->ihnode);
       if (!CheckIO(data->req)) AbortIO(data->req);
       WaitIO(data->req);

    MY_TRIGGER_METHOD:
       if (CheckIO(data->req))
       {
          WaitIO(data->req);

          /* update display or do anything else here ... */

          /* send a new timer event */
          data->req->tr_node.io_Command = TR_ADDREQUEST;
          data->req->tr_time.tv_secs    = 1;
          data->req->tr_time.tv_micro   = 0;
          SendIO((struct IORequest *)data->req);

          return(TRUE);
       }
       return(FALSE);

    SEE ALSO
    MUIM_Application_RemInputHandler, MUIM_Application_Input
Application.mui/MUIM_Application_CheckRefresh

    NAME
    MUIM_Application_CheckRefresh (V11)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_CheckRefresh);

    FUNCTION
    This method checks all currently open windows if they
    need refreshing and refreshes them if necessary.

    You won't need to call this method if you are within
    your traditional MUI main loop. However, if you e.g.
    spawn some kind of synchronous requester (AslRequest),
    MUI cannot react on IDCMP_REFRESHWINDOW messages.

    The result is that the user may see a damaged MUI window
    if he moves around a file requester and MUI is configured
    for simple refresh.

    MUIA_Application_CheckRefresh is the solution for this
    problem. Just open your requesters with

    ASLFR_UserData    , ApplicationObject,
    ASLFR_IntuiMsgFunc, &IntuiMsgHook,

    and let IntuiMsgHook point to something like this:

    SAVEDS ASM VOID IntuiMsgFunc(
       _a1 struct IntuiMessage *imsg,
       _a2 struct FileRequester *req)
    {
       if (imsg->Class==IDCMP_REFRESHWINDOW)
          DoMethod(req->fr_UserData,MUIM_Application_CheckRefresh);
    }

    RESULT
    Windows with damage will be refreshed. This may result in
    MUI calling MUIM_Draw of some of your custom classes.
    The result value of this method is undefined.

    SEE ALSO
    MUIM_Application_InputBuffered
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 ) (OBSOLETE)

    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,
    MUIM_Application_NewInput
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_ObjectID offer an easy way of saving and loading
    a programs configuration.

    Each gadget with a non NULL MUIA_ObjectID 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 a MUIA_ObjectID 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.
    Numeric class  - MUIA_Numeric_Value is ex/imported.
    Area class     - MUIA_Selected is ex/imported
                     (e.g. for Checkmark gadgets)
   Menuitem class - MUIA_Menuitem_Checked is ex/imported (V9).
    Group class    - MUIA_Group_ActivePage is ex/imported (V8).

    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, notify.mui/MUIA_ObjectID,
    MUIM_Export, MUIM_Import
Application.mui/MUIM_Application_NewInput

    NAME
    MUIM_Application_NewInput (V11)

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

    FUNCTION
    This is an enhanced replacement for MUIM_Application_Input.
    It depends on receiving the return value from your Wait()
    or 0 as input to be able to perform the necessary actions
    more efficient.

    MUIM_Application_NewInput is generally preferrable over
    MUIM_Application_Input.

    EXAMPLE
    /*
    ** This is the ideal input loop for an object oriented MUI
    ** application. Everything is encapsulated in classes, no
    ** return ids need to be used, we just check if the program
    ** shall terminate.
    ** Note that MUIM_Application_NewInput expects sigs to
    ** contain the result from Wait() (or 0). This makes the
    ** input loop significantly faster.
    */

    {
       ULONG sigs = 0;

       while (DoMethod(app,MUIM_Application_NewInput,&sigs)
              !=MUIV_Application_ReturnID_Quit)
       {
          if (sigs)
          {
             sigs = Wait(sigs | SIGBREAKF_CTRL_C);
             if (sigs & SIGBREAKF_CTRL_C) break;
          }
       }
    }

    SEE ALSO
    MUIM_Application_Input

Application.mui/MUIM_Application_OpenConfigWindow

    NAME
    MUIM_Application_OpenConfigWindow (V11)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_OpenConfigWindow,ULONG flags);

    FUNCTION
    Since MUI 3, applications can open their own MUI configuration
    window to allow users to adjust the local preferences without
    the need of an external program. Programmers are supposed to
    include a "Settings/MUI..." menu item which simply calls
    MUIM_Application_OpenConfigWindow. MUI will then automatically
    show the preferences window without blocking the rest of the
    program.

    Currently no flags are defined; pass 0 for the time being.
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.

    RESULT
    TRUE if successful, FALSE otherwise.

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

    NOTE
    MUIM_Application_PushMethod has a limit of 7 arguments!

    SEE ALSO
    MUIM_Application_Input
Application.mui/MUIM_Application_RemInputHandler

    NAME
    MUIM_Application_RemInputHandler (V11)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_RemInputHandler,struct MUI_InputHandlerNode *ihnode);

    FUNCTION
    Remove an input handler.
    MUI will no longer call your trigger method after you have
    removed the MUI_InputHandlerNode. You can add/remove
    input handler nodes any time as long as you know
    about your application object.

    RESULT
    MUIM_Application_RemInputHandler cannot fail, the result
    value of the method is currently undefined.

    INPUTS
    ihnode - input handler node structure you passed to
             MUIM_Application_AddInputHandler previously.

    SEE ALSO
    MUIM_Application_AddInputHandler, 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.

    NOTE
    The usage of ReturnIDs is no good MUI programming style.
    You should build your application with sub classes and
    hooks instead! See the PublicScreenManager source code
    for an example of good MUI programming!

    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_ReturnID, 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_ObjectID offer an easy way of saving and loading
    a programs configuration.

    Each gadget with a non NULL MUIA_ObjectID 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 a MUIA_ObjectID 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.
    Numeric class  - MUIA_Numeric_Value is ex/imported.
    Area class     - MUIA_Selected is ex/imported
                     (e.g. for Checkmark gadgets)
   Menuitem class - MUIA_Menuitem_Checked is ex/imported (V9).
    Group class    - MUIA_Group_ActivePage is ex/imported (V8).

    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, Notify.mui/MUIA_ObjectID
    MUIM_Export, MUIM_Import
Application.mui/MUIM_Application_SetConfigItem

    NAME
    MUIM_Application_SetConfigItem (V11)

    SYNOPSIS
    DoMethod(obj,MUIM_Application_SetConfigItem,ULONG item, APTR data);

    FUNCTION
    Private method, only for PSI.
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, help will appear on default public
                          screen then. May also be (Object *)0xffffffff,
                          MUI will use the first open child window of
                          application as reference for the screen
                          (since muimaster.library V18).

    name   - (char *)   - name of the help file. If set to NULL, MUI
                          will use contents of MUIA_Application_HelpFile
                          instead (since muimaster.library V18).

    node   - (char *)   - name of a node in this help file.

    line   - (LONG)     - line number.

    SEE ALSO
    MUIA_HelpFile, MUIA_HelpNode, MUIA_HelpLine