\section{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.

\subsection[MUIM\_Application\_GetMenuCheck]{MUIM\_Application\_GetMenuCheck (V4) (OBSOLETE)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_Application\_GetMenuCheck,ULONG MenuID);

\subsubsection*{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.

\subsubsection*{INPUTS}
\begin{description}
\item[MenuID] - the value you wrote into the
UserData field of struct NewMenu.
\end{description}

\subsubsection*{SEE ALSO}
MUIM\_Application\_SetMenuCheck, MUIA\_Application\_Menu

\subsection[MUIM\_Application\_GetMenuState]{MUIM\_Application\_GetMenuState (V4) (OBSOLETE)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_Application\_GetMenuState,ULONG MenuID);

\subsubsection*{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.

\subsubsection*{INPUTS}
   \begin{description}
\item[MenuID] - the value you wrote into the
UserData field of struct NewMenu.
\end{description}

\subsubsection*{SEE ALSO}
MUIM\_Application\_SetMenuState, MUIA\_Application\_Menu

\subsection[MUIM\_Application\_Input]{MUIM\_Application\_Input (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_Application\_Input,LONGBITS $\ast$signal);

\subsubsection*{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:
\small \begin{verbatim}

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

\end{verbatim} \normalsize
   
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 $\ast$must$\ast$ check this because Wait()ing on a zero
signal mask is not a good idea!

\subsubsection*{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.

\subsubsection*{SEE ALSO}
MUIA\_Application\_Sleep, MUIM\_Application\_InputBuffered

\subsection[MUIM\_Application\_InputBuffered]{MUIM\_Application\_InputBuffered (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_Application\_InputBuffered,);

\subsubsection*{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.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
for (track=0; track<80; track++)
{
   read_track();
   DoMethod(app,MUIM_Application_InputBuffered);
   write_track();
   DoMethod(app,MUIM_Application_InputBuffered);
}

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIM\_Application\_Input, MUIA\_Application\_Sleep

\subsection[MUIM\_Application\_Load]{MUIM\_Application\_Load (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_Application\_Load,STRPTR name);

\subsubsection*{FUNCTION}
MUIM\_Application\_Save, MUIM\_Application\_Load and
MUIA\_ExportID offer an easy way of saving and loading
a programs configuration.

Each gadget with a non NULL MUIA\_ExportID will get
its contents saved during MUIM\_Application\_Save and
restored during MUIM\_Application\_Load. This makes
it very easy to design a configuration window
with ''Save'', ''Use'' and ''Cancel'' buttons to allow
the user storing the settings. When the application
starts, you would just have to call MUIM\_Application\_Load
and the stored settings will be read and installed.

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

\begin{center} \begin{tabular}{lcl}
String class   &-& MUIA\_String\_Contents is ex/imported.\\
Radio class    &-& MUIA\_Radio\_Active is ex/imported.\\
Cycle class    &-& MUIA\_Cycle\_Active is ex/imported.\\
List class     &-& MUIA\_List\_Active is /ex/imported.\\
Text class     &-& MUIA\_Text\_Contents is ex/imported.\\
Slider class   &-& MUIA\_Slider\_Level is ex/imported.\\
Area class     &-& MUIA\_Selected is ex/imported\\
&&(e.g. for Checkmark gadgets)\\
Menuitem class &-& MUIA\_Checked is ex/imported (V9).\\
Group class    &-& MUIA\_Group\_ActivePage is ex/imported (V8).\\
\end{tabular} \end{center}
   

\subsubsection*{INPUTS}
   \begin{description}
\item[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
\begin{itemize}
\item MUIV\_Application\_Load\_ENV or
\item MUIV\_Application\_Load\_ENVARC.
\end{itemize}
\end{description}

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
see the sample program "Settings.c"

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIM\_Application\_Save, MUIA\_ExportID

\subsection[MUIM\_Application\_PushMethod]{MUIM\_Application\_PushMethod (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_Application\_PushMethod,Object $\ast$dest, LONG count, /$\ast$ ... $\ast$/);

\subsubsection*{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.

\subsubsection*{INPUTS}
   \begin{description}
\item[dest]  - object on which to perform the pushed method.
\item[count] - number of following arguments.
\item[...]   - the destination method.
\end{description}

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
/* set a status line from a sub task */
DoMethod(app,MUIM_Application_PushMethod,
   txstatus,3,MUIM_Set,MUIA_Text_Contents,"reading...");

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIM\_Application\_Input

\subsection[MUIM\_Application\_ReturnID]{MUIM\_Application\_ReturnID (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_Application\_ReturnID,ULONG retid);

\subsubsection*{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.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}

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

#define ID_PLAYBUTTON 42

...

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

...

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

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIM\_Application\_Input, MUIM\_Notify

\subsection[MUIM\_Application\_Save]{MUIM\_Application\_Save (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_Application\_Save,STRPTR name);

\subsubsection*{FUNCTION}
MUIM\_Application\_Save, MUIM\_Application\_Load and
MUIA\_ExportID offer an easy way of saving and loading
a programs configuration.

Each gadget with a non NULL MUIA\_ExportID will get
its contents saved during MUIM\_Application\_Save and
restored during MUIM\_Application\_Load. This makes
it very easy to design a configuration window
with ''Save'', ''Use'' and ''Cancel'' buttons to allow
the user storing the settings. When the application
starts, you would just have to call MUIM\_Application\_Load
and the stored settings will be read and installed.

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

\begin{center} \begin{tabular}{lcl}
String class   &-& MUIA\_String\_Contents is ex/imported.\\
Radio class    &-& MUIA\_Radio\_Active is ex/imported.\\
Cycle class    &-& MUIA\_Cycle\_Active is ex/imported.\\
List class     &-& MUIA\_List\_Active is /ex/imported.\\
Text class     &-& MUIA\_Text\_Contents is ex/imported.\\
Slider class   &-& MUIA\_Slider\_Level is ex/imported.\\
Area class     &-& MUIA\_Selected is ex/imported\\
&&(e.g. for Checkmark gadgets)\\
Menuitem class &-& MUIA\_Checked is ex/imported (V9).\\
Group class    &-& MUIA\_Group\_ActivePage is ex/imported (V8).\\
\end{tabular} \end{center}

\subsubsection*{INPUTS}
   \begin{description}
\item[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
\begin{itemize}
\item MUIV\_Application\_Save\_ENV or
\item MUIV\_Application\_Save\_ENVARC.
\end{itemize}
\end{description}

This will save your application's settings somewhere
in env:mui/ or envarc:mui/, you needn't worry about
it.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
see the sample program "Settings.c"

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIM\_Application\_Load, MUIA\_ExportID

\subsection[MUIM\_Application\_SetMenuCheck]{MUIM\_Application\_SetMenuCheck (V4) (OBSOLETE)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_Application\_SetMenuCheck,ULONG MenuID, LONG stat);

\subsubsection*{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.

\subsubsection*{INPUTS}
   \begin{description}
\item[MenuID] - the value you wrote into the
UserData field of struct NewMenu.

\item[set]    - TRUE to set checkmark, FALSE to clear
\end{description}

\subsubsection*{SEE ALSO}
MUIM\_Application\_GetMenuCheck, MUIA\_Application\_Menu,

\subsection[MUIM\_Application\_SetMenuState]{MUIM\_Application\_SetMenuState (V4) (OBSOLETE)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_Application\_SetMenuState,ULONG MenuID, LONG stat);

\subsubsection*{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.

\subsubsection*{INPUTS}
   \begin{description}
\item[MenuID] - the value you wrote into the
UserData field of struct NewMenu.

\item[set]    - TRUE to enable item, FALSE to disable.
\end{description}

\subsubsection*{SEE ALSO}
MUIM\_Application\_GetMenuState, MUIA\_Application\_Menu,

\subsection[MUIM\_Application\_ShowHelp]{MUIM\_Application\_ShowHelp (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_Application\_ShowHelp,Object $\ast$window, char $\ast$name, char $\ast$node, LONG line);

\subsubsection*{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.

\subsubsection*{INPUTS}
   \begin{description}
\item[window] - (Object $\ast$) - Help will appear on this windows
screen. May be NULL.
\item[name]   - (char $\ast$)   - name of the help file
\item[node]   - (char $\ast$)   - name of a node in this help file
\item[line]   - (char $\ast$)   - line number
\end{description}

\subsubsection*{SEE ALSO}
MUIA\_HelpFile, MUIA\_HelpNode, MUIA\_HelpLine

\subsection[MUIA\_Application\_Active]{MUIA\_Application\_Active -- (V4) [ISG], BOOL}

\subsubsection*{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.

\subsubsection*{SEE ALSO}
MUIA\_Application\_Broker

\subsection[MUIA\_Application\_Author]{MUIA\_Application\_Author -- (V4) [I.G], STRPTR}

\subsubsection*{FUNCTION}
Name of the applications author.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
see MUIA_Application_Title

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Application\_Title, MUIA\_Application\_Copyright,
MUIA\_Application\_Version, MUIA\_Application\_Description,
MUIA\_Application\_Base

\subsection[MUIA\_Application\_Base]{MUIA\_Application\_Base -- (V4) [I.G], STRPTR}

\subsubsection*{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 '':/()\#?$\ast$...''.

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.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
see MUIA_Application_Title

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Application\_Title, MUIA\_Application\_Version,
MUIA\_Application\_Author, MUIA\_Application\_Copyright,
MUIA\_Application\_Description

\subsection[MUIA\_Application\_Broker]{MUIA\_Application\_Broker -- (V4) [..G], Broker $\ast$}

\subsubsection*{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.

\subsubsection*{NOTE}
Unless you have set MUIA\_Application\_RequiresCX, you must be
prepared to receive a NULL pointer. In this case, the
commodities interface is not available, maybe because the
user installed a light version of MUI.

\subsubsection*{SEE ALSO}
MUIA\_Application\_BrokerHook

\subsection[MUIA\_Application\_BrokerHook]{MUIA\_Application\_BrokerHook -- (V4) [ISG], struct Hook $\ast$}

\subsubsection*{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.

\subsubsection*{NOTE}
The commodities interface isn't available in the
memory saving ''light'' version of MUI. Your hook
will never be called in this case.

\subsubsection*{SEE ALSO}
MUIA\_Application\_Broker

\subsection[MUIA\_Application\_BrokerPort]{MUIA\_Application\_BrokerPort -- (V6) [..G], struct MsgPort $\ast$}

\subsubsection*{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.

\subsubsection*{NOTE}
Unless you have set MUIA\_Application\_RequiresCX, you must be
prepared to receive a NULL pointer. In this case, the
commodities interface is not available, maybe because the
user installed a light version of MUI.

\subsubsection*{SEE ALSO}
MUIA\_Application\_BrokerHook

\subsection[MUIA\_Application\_BrokerPri]{MUIA\_Application\_BrokerPri -- (V6) [I.G], LONG}

\subsubsection*{FUNCTION}
Adjust the priority of an applications broker.

\subsubsection*{SEE ALSO}
MUIA\_Application\_BrokerHook

\subsection[MUIA\_Application\_Commands]{MUIA\_Application\_Commands -- (V4) [ISG], struct MUI\_Command $\ast$}

\subsubsection*{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:

\small \begin{verbatim}
   
   struct MUI_Command
   {
      char        *mc_Name;
      char        *mc_Template;
      LONG         mc_Parameters;
      struct Hook *mc_Hook;
      LONG         mc_Reserved[5];
   };
   
\end{verbatim} \normalsize

\begin{description}
\item[mc\_Name]       contains the name of your command.
Commands are not case sensitive.

\item[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.

\item[mc\_Parameters] is the number of parameters specified
in the template array.

\item[mc\_Hook]       is a pointer to the callback hook defining
the function to be called.
\end{description}

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.

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

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Application\_RexxMsg, MUIA\_Application\_RexxString

\subsection[MUIA\_Application\_Copyright]{MUIA\_Application\_Copyright -- (V4) [I.G], STRPTR}

\subsubsection*{FUNCTION}
A copyright string, containing the year and the
company.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
see MUIA_Application_Title

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Application\_Title, MUIA\_Application\_Version,
MUIA\_Application\_Author, MUIA\_Application\_Description,
MUIA\_Application\_Base

\subsection[MUIA\_Application\_Description]{MUIA\_Application\_Description -- (V4) [I.G], STRPTR}

\subsubsection*{FUNCTION}
Short description, about 40 characters.
Shown e.g. in commodities exchange.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
see MUIA_Application_Title

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Application\_Title, MUIA\_Application\_Version,
MUIA\_Application\_Author, MUIA\_Application\_Copyright,
MUIA\_Application\_Base

\subsection[MUIA\_Application\_DiskObject]{MUIA\_Application\_DiskObject -- (V4) [ISG], struct DiskObject $\ast$}

\subsubsection*{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.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
...
MUIA_Application_DiskObject, 
   dobj = GetDiskObject("PROGDIR:MyApp"),
...

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

\end{verbatim} \normalsize
\subsubsection*{NOTE}
Unless you have set MUIA\_Application\_RequiresIconification,
this attribute might have no effect, maybe because the
user installed a light version of MUI. You must be prepared
to receive a NULL pointer when you try to read it!

\subsubsection*{SEE ALSO}
MUIA\_Application\_Iconified

\subsection[MUIA\_Application\_DoubleStart]{MUIA\_Application\_DoubleStart -- (V4) [..G], BOOL}

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

\subsubsection*{SEE ALSO}
MUIA\_Application\_SingleTask

\subsection[MUIA\_Application\_DropObject]{MUIA\_Application\_DropObject -- (V5) [IS.], Object $\ast$}

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

\subsubsection*{SEE ALSO}
MUIA\_Window\_AppWindow, MUIM\_CallHook

\subsection[MUIA\_Application\_ForceQuit]{MUIA\_Application\_ForceQuit -- (V8) [..G], BOOL}

\subsubsection*{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.

\subsection[MUIA\_Application\_HelpFile]{MUIA\_Application\_HelpFile -- (V8) [ISG], STRPTR}

\subsubsection*{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.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}

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;

\end{verbatim} \normalsize
   
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.

   \subsubsection*{NOTE}
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.

\subsubsection*{SEE ALSO}
MUIA\_HelpNode, MUIA\_HelpLine

\subsection[MUIA\_Application\_Iconified]{MUIA\_Application\_Iconified -- (V4) [.SG], BOOL}

\subsubsection*{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.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}

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

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Application\_DiskObject

\subsection[MUIA\_Application\_Menu]{MUIA\_Application\_Menu -- (V4) [I.G], struct NewMenu $\ast$ (OBSOLETE)}

\subsubsection*{FUNCTION}
Obsolete, use MUIA\_Application\_Menustrip instead.

\subsubsection*{SEE ALSO}
MUIA\_Application\_Menustrip

\subsection[MUIA\_Application\_MenuAction]{MUIA\_Application\_MenuAction -- (V4) [..G], ULONG}

\subsubsection*{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.

\subsubsection*{SEE ALSO}
MUIA\_Application\_Menu, MUIA\_Application\_MenuAction

\subsection[MUIA\_Application\_MenuHelp]{MUIA\_Application\_MenuHelp -- (V4) [..G], ULONG}

\subsubsection*{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.

\subsubsection*{SEE ALSO}
MUIA\_Application\_Menu, MUIA\_Application\_ShowHelp

\subsection[MUIA\_Application\_Menustrip]{MUIA\_Application\_Menustrip -- (V8) [I..], Object $\ast$}

\subsubsection*{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.

\subsection[MUIA\_Application\_RexxHook]{MUIA\_Application\_RexxHook -- (V7) [ISG], struct Hook $\ast$}

\subsubsection*{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.

\subsubsection*{SEE ALSO}
MUIA\_Application\_Commands

\subsection[MUIA\_Application\_RexxMsg]{MUIA\_Application\_RexxMsg -- (V4) [..G], struct RxMsg $\ast$}

\subsubsection*{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

\subsubsection*{SEE ALSO}
MUIA\_Application\_Commands, MUIA\_Application\_RexxString

\subsection[MUIA\_Application\_RexxString]{MUIA\_Application\_RexxString -- (V4) [.S.], STRPTR}

\subsubsection*{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.

\subsubsection*{SEE ALSO}
MUIA\_Application\_Commands, MUIA\_Application\_RexxMsg

\subsection[MUIA\_Application\_SingleTask]{MUIA\_Application\_SingleTask -- (V4) [I..], BOOL}

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

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

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

\subsubsection*{SEE ALSO}
MUIA\_Application\_DoubleStart

\subsection[MUIA\_Application\_Sleep]{MUIA\_Application\_Sleep -- (V4) [.S.], BOOL}

\subsubsection*{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.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
set(app,MUIA_Application_Sleep,TRUE ); // go to bed
calc_fractals();
set(app,MUIA_Application_Sleep,FALSE); // wake up

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Window\_Sleep, MUIM\_Application\_InputBuffered

\subsection[MUIA\_Application\_Title]{MUIA\_Application\_Title -- (V4) [I.G], STRPTR}

\subsubsection*{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 '':/()\#?$\ast$...'' 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!

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
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",
   ...

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Application\_Version, MUIA\_Application\_Copyright,
MUIA\_Application\_Author, MUIA\_Application\_Description,
MUIA\_Application\_Base

\subsection[MUIA\_Application\_UseCommodities]{MUIA\_Application\_UseCommodities -- (V10) [I..], BOOL}

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

\subsubsection*{SEE ALSO}
MUIA\_Application\_UseRexx

\subsection[MUIA\_Application\_UseRexx]{MUIA\_Application\_UseRexx -- (V10) [I..], BOOL}

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

\subsubsection*{SEE ALSO}
MUIA\_Application\_UseCommodities

\subsection[MUIA\_Application\_Version]{MUIA\_Application\_Version -- (V4) [I.G], STRPTR}

\subsubsection*{FUNCTION}
Define a version string for an application.
This string shall follow standard version string
convetions but must {\bf not} contain a leading ''$\backslash$0''.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
see MUIA_Application_Title

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Application\_Title, MUIA\_Application\_Copyright,
MUIA\_Application\_Author, MUIA\_Application\_Description,
MUIA\_Application\_Base

\subsection[MUIA\_Application\_Window]{MUIA\_Application\_Window -- (V4) [I..], Object $\ast$}

\subsubsection*{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.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
Please refer to one of the example programs.

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}