MUI_Application

Application.mui

DESCRIPTION

Application.mui/Application.mui

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

	An application can have any number of sub windows,
	these windows are the children of the application

MUIA_Application_Active

(V4 ) [ISG], BOOL, 0x804260ab

DESCRIPTION

	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

MUIA_Application_Author

(V4 ) [I.G], STRPTR, 0x80424842

DESCRIPTION

	Name of the applications author

EXAMPLE

	see MUIA_Application_Title

MUIA_Application_Base

(V4 ) [I.G], STRPTR, 0x8042e07a

DESCRIPTION

	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

MUIA_Application_Broker

(V4 ) [..G], CxObj *, 0x8042dbce

DESCRIPTION

	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.

MUIA_Application_BrokerHook

(V4 ) [ISG], struct Hook *, 0x80428f4b

DESCRIPTION

	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.

MUIA_Application_BrokerPort

(V6 ) [..G], struct MsgPort *, 0x8042e0ad

DESCRIPTION

	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.

MUIA_Application_BrokerPri

(V6 ) [I.G], LONG, 0x8042c8d0

DESCRIPTION

	Adjust the priority of an applications broker

MUIA_Application_Commands

(V4 ) [ISG], struct MUI_Command *, 0x80428648

DESCRIPTION

	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

MUIA_Application_Copyright

(V4 ) [I.G], STRPTR, 0x8042ef4d

DESCRIPTION

	A copyright string, containing the year and the
	company

EXAMPLE

	see MUIA_Application_Title

MUIA_Application_Description

(V4 ) [I.G], STRPTR, 0x80421fc6

DESCRIPTION

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

EXAMPLE

	see MUIA_Application_Title

MUIA_Application_DiskObject

(V4 ) [ISG], struct DiskObject *, 0x804235cb

DESCRIPTION

	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

MUIA_Application_DoubleStart

(V4 ) [.SG], BOOL, 0x80423bc6

DESCRIPTION

	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

MUIA_Application_DropObject

(V5 ) [IS.], Boopsiobject *, 0x80421266

DESCRIPTION

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

MUIA_Application_ForceQuit

(V8 ) [.SG], BOOL, 0x804257df

DESCRIPTION

	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

(V8 ) [ISG], STRPTR, 0x804293f4

DESCRIPTION

	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

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.

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

MUIA_Application_Iconified

(V4 ) [.SG], BOOL, 0x8042a07f

DESCRIPTION

	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

MUIA_Application_IconifyTitle

(V18) [ISG], STRPTR, 0x80422cb8

DESCRIPTION

	yet undocumented, please complain in mailinglist

MUIA_Application_Menu

(V4 ) [I.G], struct NewMenu *, 0x80420e1f (OBSOLETE)

DESCRIPTION

	Obsolete, use MUIA_Application_Menustrip instead

MUIA_Application_MenuAction

(V4 ) [ISG], ULONG, 0x80428961

DESCRIPTION

	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

MUIA_Application_MenuHelp

(V4 ) [..G], ULONG, 0x8042540b

DESCRIPTION

	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

MUIA_Application_Menustrip

(V8 ) [I.G], MUIMenustrip *, 0x804252d9

DESCRIPTION

	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

(V7 ) [ISG], struct Hook *, 0x80427c42

DESCRIPTION

	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

MUIA_Application_RexxMsg

(V4 ) [.SG], struct RexxMsg *, 0x8042fd88

DESCRIPTION

	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

MUIA_Application_RexxString

(V4 ) [.S.], STRPTR, 0x8042d711

DESCRIPTION

	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

MUIA_Application_SingleTask

(V4 ) [I..], BOOL, 0x8042a2c8

DESCRIPTION

	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

MUIA_Application_Sleep

(V4 ) [.SG], BOOL, 0x80425711

DESCRIPTION

	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

MUIA_Application_Title

(V4 ) [I.G], STRPTR, 0x804281b8

DESCRIPTION

	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

MUIA_Application_UseCommodities

(V10) [I..], BOOL, 0x80425ee5

DESCRIPTION

	yet undocumented, please complain in mailinglist

MUIA_Application_UsedClasses

(V20) [ISG], STRPTR *, 0x8042e9a7

DESCRIPTION

	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

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

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

NULL

	};

	...
	app = ApplicationObject,
	   ...
	   MUIA_Application_UsedClasses, UsedClasses,
	   ...
	   End;

MUIA_Application_UseRexx

(V10) [I..], BOOL, 0x80422387

DESCRIPTION

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

MUIA_Application_UseScreenNotify

(V20) [I..], BOOL, 0x80420861

DESCRIPTION

	yet undocumented, please complain in mailinglist

MUIA_Application_Version

(V4 ) [I.G], STRPTR, 0x8042b33f

DESCRIPTION

	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

MUIA_Application_Window

(V4 ) [I..], Boopsiobject *, 0x8042bfe0

DESCRIPTION

	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

MUIA_Application_WindowList

(V13) [..G], struct List *, 0x80429abe

DESCRIPTION

	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

MUIM_Application_AboutMUI (V14) 0x8042d21d

SYNOPSIS

	DoMethod(obj,MUIM_Application_AboutMUI,MUIWindow *refwindow);

DESCRIPTION

	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

MUIM_Application_AddInputHandler (V11) 0x8042f099

SYNOPSIS

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

DESCRIPTION

	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.

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

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.

MUIM_Application_BuildSettingsPanel

MUIM_Application_BuildSettingsPanel (V20) 0x8042b58f

SYNOPSIS

	DoMethod(obj,MUIM_Application_BuildSettingsPanel,ULONG number);

DESCRIPTION

	yet undocumented, please complain in mailinglist

MUIM_Application_CheckRefresh

MUIM_Application_CheckRefresh (V11) 0x80424d68

SYNOPSIS

	DoMethod(obj,MUIM_Application_CheckRefresh);

DESCRIPTION

	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

MUIM_Application_DefaultConfigItem

MUIM_Application_DefaultConfigItem (V20) 0x8042d934

SYNOPSIS

	DoMethod(obj,MUIM_Application_DefaultConfigItem,ULONG cfgid);

DESCRIPTION

	yet undocumented, please complain in mailinglist

MUIM_Application_GetMenuCheck

MUIM_Application_GetMenuCheck (V4 ) 0x8042c0a7 (OBSOLETE)

SYNOPSIS

	DoMethod(obj,MUIM_Application_GetMenuCheck,ULONG MenuID);

DESCRIPTION

	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

MUIM_Application_GetMenuState

MUIM_Application_GetMenuState (V4 ) 0x8042a58f (OBSOLETE)

SYNOPSIS

	DoMethod(obj,MUIM_Application_GetMenuState,ULONG MenuID);

DESCRIPTION

	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

MUIM_Application_Input

MUIM_Application_Input (V4 ) 0x8042d0f5 (OBSOLETE)

SYNOPSIS

	DoMethod(obj,MUIM_Application_Input,ULONG *signal);

DESCRIPTION

	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

MUIM_Application_InputBuffered

MUIM_Application_InputBuffered (V4 ) 0x80427e59

SYNOPSIS

	DoMethod(obj,MUIM_Application_InputBuffered);

DESCRIPTION

	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

MUIM_Application_Load

MUIM_Application_Load (V4 ) 0x8042f90d

SYNOPSIS

	DoMethod(obj,MUIM_Application_Load,STRPTR name);

DESCRIPTION

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

	Each object 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
	saving & loading of 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).
	Balance class  - weight of children is ex/imported (MorphOS 3.10

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

MUIM_Application_NewInput

MUIM_Application_NewInput (V11) 0x80423ba6

SYNOPSIS

	DoMethod(obj,MUIM_Application_NewInput,ULONG *signal);

DESCRIPTION

	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

MUIM_Application_OpenConfigWindow

MUIM_Application_OpenConfigWindow (V11) 0x804299ba

SYNOPSIS

	DoMethod(obj,MUIM_Application_OpenConfigWindow,ULONG flags, STRPTR classid);

DESCRIPTION

	yet undocumented, please complain in mailinglist

MUIM_Application_PushMethod

MUIM_Application_PushMethod (V4 ) 0x80429ef8

SYNOPSIS

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

DESCRIPTION

	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!

MUIM_Application_RemInputHandler

MUIM_Application_RemInputHandler (V11) 0x8042e7af

SYNOPSIS

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

DESCRIPTION

	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

INPUTS

	ihnode - input handler node structure you passed to
	         MUIM_Application_AddInputHandler previously

RESULT

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

MUIM_Application_ReturnID

MUIM_Application_ReturnID (V4 ) 0x804276ef

SYNOPSIS

	DoMethod(obj,MUIM_Application_ReturnID,ULONG retid);

DESCRIPTION

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

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

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

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

EXAMPLE

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

	#define ID_PLAYBUTTON 42

	...

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

	...

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

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!

MUIM_Application_Run

MUIM_Application_Run (V20) 0x90420103

SYNOPSIS

	DoMethod(obj,MUIM_Application_Run);

DESCRIPTION

	Run the main event loop. This method returns when CTRL-C or
   MUIV_Application_ReturnID_Quit event is received

MUIM_Application_Save

MUIM_Application_Save (V4 ) 0x804227ef

SYNOPSIS

	DoMethod(obj,MUIM_Application_Save,STRPTR name);

DESCRIPTION

	see MUIM_Application_Load

INPUTS

	name - see MUIM_Application_Load

EXAMPLE

	see the sample program "Settings.c

MUIM_Application_SetConfigItem

MUIM_Application_SetConfigItem (V11) 0x80424a80

SYNOPSIS

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

DESCRIPTION

	Private method, only for PSI

MUIM_Application_SetMenuCheck

MUIM_Application_SetMenuCheck (V4 ) 0x8042a707 (OBSOLETE)

SYNOPSIS

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

DESCRIPTION

	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

MUIM_Application_SetMenuState

MUIM_Application_SetMenuState (V4 ) 0x80428bef (OBSOLETE)

SYNOPSIS

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

DESCRIPTION

	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

MUIM_Application_ShowHelp

MUIM_Application_ShowHelp (V4 ) 0x80426479

SYNOPSIS

	DoMethod(obj,MUIM_Application_ShowHelp,MUIWindow *window, STRPTR name, STRPTR node, LONG line);

DESCRIPTION

	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

MUIM_Application_UnpushMethod

MUIM_Application_UnpushMethod (V20) 0x804211dd

SYNOPSIS

	DoMethod(obj,MUIM_Application_UnpushMethod,Boopsiobject *targetobj, ULONG methodid, ULONG method);

DESCRIPTION

	Kill method scheduled for exceution by MUIM_Application_PushMethod.
	This method will work only if the method wasn't executed yet. 
	Each method in a queue is matched to the values supplied. If any
	of arguments is 0/NULL it's not taken into account. If all arguments
	are 0/NULL then all methods will be removed from the queue

INPUTS

	targetobj - (Object *) - Object which was a target for
	                      MUIM_Application_PushMethod.

	methodid  - (ULONG)    - Method identifier returned by 
	                      MUIM_Application_PushMethod.

	method    - (ULONG)    - Method which was supposed to be executed

RESULT

	Number of methods removed from a queue

EXAMPLE

	ULONG methodid = DoMethod(appobj, MUIM_Application_PushMethod, obj, 1, MUIM_TestMethod);

	/* kill all methods pushed for "obj" */

	DoMethod(appobj, MUIM_Application_UnpushMethod, obj, 0, 0);

	/* kill only one method */

	DoMethod(appobj, MUIM_Application_UnpushMethod, NULL, methodid, 0);

	/* same thing, but with different params */

	DoMethod(appobj, MUIM_Application_UnpushMethod, obj, methodid, 0);

	/* kill all MUIM_TestMethod methods pushed for an object */

	DoMethod(appobj, MUIM_Application_UnpushMethod, obj, 0, MUIM_TestMethod

MUI_Application

Application.mui

DESCRIPTION

MUIA_Application_Active

DESCRIPTION

SEE ALSO

MUIA_Application_Author

DESCRIPTION

EXAMPLE

SEE ALSO

MUIA_Application_Base

DESCRIPTION

EXAMPLE

SEE ALSO

MUIA_Application_Broker

DESCRIPTION

NOTES

SEE ALSO

MUIA_Application_BrokerHook

DESCRIPTION

NOTES

SEE ALSO

MUIA_Application_BrokerPort

DESCRIPTION

NOTES

SEE ALSO

MUIA_Application_BrokerPri

DESCRIPTION

SEE ALSO

MUIA_Application_Commands

DESCRIPTION

EXAMPLE

SEE ALSO

MUIA_Application_Copyright

DESCRIPTION

EXAMPLE

SEE ALSO

MUIA_Application_Description

DESCRIPTION

EXAMPLE

SEE ALSO

MUIA_Application_DiskObject

DESCRIPTION

EXAMPLE

SEE ALSO

MUIA_Application_DoubleStart

DESCRIPTION

SEE ALSO

MUIA_Application_DropObject

DESCRIPTION

SEE ALSO

MUIA_Application_ForceQuit

DESCRIPTION

MUIA_Application_HelpFile

DESCRIPTION

NOTES

EXAMPLE

SEE ALSO

MUIA_Application_Iconified

DESCRIPTION

EXAMPLE

SEE ALSO

MUIA_Application_IconifyTitle

DESCRIPTION

MUIA_Application_Menu

DESCRIPTION

SEE ALSO

MUIA_Application_MenuAction

DESCRIPTION

SEE ALSO

MUIA_Application_MenuHelp

DESCRIPTION

SEE ALSO

MUIA_Application_Menustrip

DESCRIPTION

MUIA_Application_RexxHook

DESCRIPTION

SEE ALSO

MUIA_Application_RexxMsg

DESCRIPTION