MUI Autodocs: Application.mui

Copyright © 1997, Stefan Stuntz




Application.mui Background

        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 Attributes

    Attribute                           Ver ISG Type
    ----------------------------------- --- --- --------------------
    MUIA_Application_Active             V4  ISG BOOL
    MUIA_Application_Author             V4  I.G STRPTR
    MUIA_Application_Base               V4  I.G STRPTR
    MUIA_Application_Broker             V4  ..G Broker *
    MUIA_Application_BrokerHook         V4  ISG struct Hook *
    MUIA_Application_BrokerPort         V6  ..G struct MsgPort *
    MUIA_Application_BrokerPri          V6  I.G LONG
    MUIA_Application_Commands           V4  ISG struct MUI_Command *
    MUIA_Application_Copyright          V4  I.G STRPTR
    MUIA_Application_Description        V4  I.G STRPTR
    MUIA_Application_DiskObject         V4  ISG struct DiskObject *
    MUIA_Application_DoubleStart        V4  ..G BOOL
    MUIA_Application_DropObject         V5  IS. Object *
    MUIA_Application_ForceQuit          V8  ..G BOOL
    MUIA_Application_HelpFile           V8  ISG STRPTR
    MUIA_Application_Iconified          V4  .SG BOOL
    MUIA_Application_Menu               V4  I.G struct NewMenu * (OBSOLETE)
    MUIA_Application_MenuAction         V4  ..G ULONG
    MUIA_Application_MenuHelp           V4  ..G ULONG
    MUIA_Application_Menustrip          V8  I.. Object *
    MUIA_Application_RexxHook           V7  ISG struct Hook *
    MUIA_Application_RexxMsg            V4  ..G struct RxMsg *
    MUIA_Application_RexxString         V4  .S. STRPTR
    MUIA_Application_SingleTask         V4  I.. BOOL
    MUIA_Application_Sleep              V4  .S. BOOL
    MUIA_Application_Title              V4  I.G STRPTR
    MUIA_Application_UseCommodities     V10 I.. BOOL
    MUIA_Application_UseRexx            V10 I.. BOOL
    MUIA_Application_Version            V4  I.G STRPTR
    MUIA_Application_Window             V4  I.. Object *
    MUIA_Application_WindowList         V13 ..G struct List *



Application.mui Methods

    Method                              Ver
    ----------------------------------- ---
    MUIM_Application_AboutMUI           V14 
    MUIM_Application_AddInputHandler    V11 
    MUIM_Application_CheckRefresh       V11 
    MUIM_Application_GetMenuCheck       V4   (OBSOLETE)
    MUIM_Application_GetMenuState       V4   (OBSOLETE)
    MUIM_Application_Input              V4   (OBSOLETE)
    MUIM_Application_InputBuffered      V4  
    MUIM_Application_Load               V4  
    MUIM_Application_NewInput           V11 
    MUIM_Application_OpenConfigWindow   V11 
    MUIM_Application_PushMethod         V4  
    MUIM_Application_RemInputHandler    V11 
    MUIM_Application_ReturnID           V4  
    MUIM_Application_Save               V4  
    MUIM_Application_SetConfigItem      V11 
    MUIM_Application_SetMenuCheck       V4   (OBSOLETE)
    MUIM_Application_SetMenuState       V4   (OBSOLETE)
    MUIM_Application_ShowHelp           V4  


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


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


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


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


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


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


MUIA_Application_BrokerPri


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

    FUNCTION
        Adjust the priority of an applications broker.

    SEE ALSO
        MUIA_Application_BrokerHook


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


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


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


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


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


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


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.


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


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


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


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


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


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.


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


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


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


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


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


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


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


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


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


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


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()!


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);


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


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


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


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


MUIM_Application_Input


    NAME
        MUIM_Application_Input (V4 ) (OBSOLETE)

    SYNOPSIS
        DoMethod(obj,MUIM_Application_Input,ULONG *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


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


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


MUIM_Application_NewInput


    NAME
        MUIM_Application_NewInput (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_Application_NewInput,ULONG *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


MUIM_Application_OpenConfigWindow


    NAME
        MUIM_Application_OpenConfigWindow (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_Application_OpenConfigWindow,ULONG flags, STRPTR class);

    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.


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


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


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


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


MUIM_Application_SetConfigItem


    NAME
        MUIM_Application_SetConfigItem (V11)

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

    FUNCTION
        Private method, only for PSI.


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,


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,


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





© 1997, Stefan Stuntz [MUI Homepage] [Autodoc Index] [Feedback] Updated: 29-Mar-97