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.
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_UsedClasses V20 ISG STRPTR *
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 *
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
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
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
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
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
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
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
NAME
MUIA_Application_BrokerPri -- (V6 ) [I.G], LONG
FUNCTION
Adjust the priority of an applications broker.
SEE ALSO
MUIA_Application_BrokerHook
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
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
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
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
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
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
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.
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
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
NAME
MUIA_Application_Menu -- (V4 ) [I.G], struct NewMenu * (OBSOLETE)
FUNCTION
Obsolete, use MUIA_Application_Menustrip instead.
SEE ALSO
MUIA_Application_Menustrip
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
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
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.
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
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
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
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
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
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 quite 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
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
NAME
MUIA_Application_UsedClasses -- (V20) [ISG], STRPTR *
FUNCTION
Tell the MUI system what external classes your application might
use.
You have to pass a pointer to a NULL terminated string array
which lists each of the external classes used by your application.
For example, if your program uses the Listtree class, add
"Listtree.mcc" to the array.
Although MUI does not strictly require this information to run
your application, you should nevertheless make it available.
With the aid of this attribute, MUI will be able to determine
which GUI preferences pages should be presented to the user
when he adjusts your application specific MUI settings.
If you do not inform MUI about your external classes, MUI
will present lots of unnecessary pages that won't affect
your application at all. Any MUI program should therefore
use this tag.
NOTE
You only have to supply names of external classes
(i.e. classes that end in ".mcc"). There is no need to
supply default MUI classes which end in ".mui".
Also, do not specify preferences classes (".mcp") here.
MUI can automatically determine the required preferences
classes for each custom class.
If your program does not need any external classes at all,
supply an empty string array:
static STRPTR UsedClasses[] = { NULL };
EXAMPLE
/* application uses Listtree, Pophotkey, Popport,
Popposition, Textinput & Busy classes */
static STRPTR UsedClasses[] =
{
"Listtree.mcc",
"Pophotkey.mcc",
"Popport.mcc",
"Textinput.mcc",
"Textinputscroll.mcc",
"Busy.mcc",
NULL
};
...
app = ApplicationObject,
...
MUIA_Application_UsedClasses, UsedClasses,
...
End;
SEE ALSO
MUIM_Application_OpenConfigWindow,
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
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
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
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()!
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);
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 timerequest));
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
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
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
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
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
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
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
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
NAME
MUIM_Application_OpenConfigWindow (V11)
SYNOPSIS
DoMethod(obj,MUIM_Application_OpenConfigWindow,ULONG flags, STRPTR classid);
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.
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
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
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
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
NAME
MUIM_Application_SetConfigItem (V11)
SYNOPSIS
DoMethod(obj,MUIM_Application_SetConfigItem,ULONG item, APTR data);
FUNCTION
Private method, only for PSI.
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,
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,
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
| © 1998, Stefan Stuntz | [MUI Homepage] [Autodoc Index] [Feedback] | Updated: 22-Feb-98 |