Application.mui

MUIA_Application_Active

Function

Store a normalized active flag, default TRUE. Activate or deactivate the

Commodities broker when one exists.

Inputs

BOOL; initialize, set, get.

Notes

This flag does not disable NewInput processing or put windows to sleep.

The ordinary setter forwards tags to Notify after updating broker state.

MUIA_Application_Author

Function

Store the application author string. Default NULL.

Inputs

STRPTR; initialize and get.

Notes

The pointer is stored without copying and is not freed. Keep the string
alive while the application uses it; there is no runtime setter for this
attribute.

MUIA_Application_Base

Function

Choose the base name for application registration, Rexx port naming, and
configuration paths. Default "UNNAMED". NULL or any of : / ( ) # ? * ,
causes construction failure.

Inputs

STRPTR; initialize and get.

Notes

The stored result is an allocated copy, freed at application disposal.
With SingleTask FALSE, the constructor tries suffixes .1 through .999
against tracked application bases. SingleTask TRUE uses the supplied
name without a suffix. The getter returns the actual borrowed stored
name.

Bugs

Suffix construction uses a 255-byte buffer and can truncate. Exhaustion
of the suffix search is not rejected; this is not an unconditional
unique-name guarantee. The validation does not make every accepted name
safe as an unquoted shell argument; OpenConfigWindow inserts it without
quoting.

MUIA_Application_Broker

Function

Return the application-owned Commodities broker, or NULL if none was

created.

Inputs

CxObj pointer; get only.

Notes

Do not delete it. The application destroys it at disposal.

UseCommodities=TRUE does not guarantee a non-NULL result.

MUIA_Application_BrokerHook

Function

Store a borrowed hook, initially NULL, called for each broker message

after default command handling.

Inputs

Hook pointer; initialize, set, get.

Notes

CallHookPkt receives the application as object and the CxMsg pointer as
message. Its result is ignored. NewInput replies immediately afterward:
do not retain or reply to the message. Disable/Enable change Active;
Kill sets SIGBREAKF_CTRL_C. Appear/Disappear have no default action.

MUIA_Application_BrokerPort

Function

Return the application-owned broker message port, or NULL.

Inputs

MsgPort pointer; get only.

Notes

Keep the application alive. NewInput consumes and replies to its
messages. Do not delete the port or compete with the event loop for its
messages. A port can exist even when broker creation failed.

MUIA_Application_BrokerPri

Function

Convert the supplied value to BYTE and use it as the broker priority.

Default zero.

Inputs

LONG in the header; initialize and get.

Notes

The getter returns the stored BYTE value through IPTR. No setter or

range validation is provided.

MUIA_Application_Commands

Function

Store a borrowed command table terminated by an entry whose mc_Name is
NULL. Default NULL. The constructor also enables the Rexx-port request
when this tag occurs.

Inputs

MUI_Command table pointer; initialize, set, get.

Notes

Each entry supplies mc_Name, optional ReadArgs mc_Template,
mc_Parameters for the IPTR argument array, and a callable mc_Hook. Keep
the table, strings, and hooks alive during input processing. A matched
hook receives the application and the parsed array, or NULL without a
template. Its return value becomes rm_Result1. RexxMsg exposes the
current request only during the hook.
The dispatcher compares case-insensitively using the length of the
incoming command word, so prefixes can match an earlier longer table
name. Command tables must not assume exact-name matching.

Bugs

Argument-buffer allocation and ReadArgs failure are not reliably checked
before the hook is called. A non-NULL template requires a valid
parameter count and suitable storage. Do not assume that hook invocation
proves successful parsing or that parsed argument pointers remain valid
after the hook.

MUIA_Application_Configdata

Function

Queue MUIM_Application_SetConfigdata on this application with the

supplied pointer. This setter does not immediately install the object.

Inputs

Object pointer; set only.

Notes

Supply a live, distinct Configdata-compatible object and keep it alive
until the queued method adopts it. Subsequent replacement and disposal
destroy the installed object. The old configuration remains active until
execution.

Bugs

Queue failure is ignored by OM_SET, and pending pushed methods are not
reclaimed by application disposal. Do not infer successful transfer of
ownership from the setter return value. Use the direct method when
controlling installation synchronously.

MUIA_Application_CopyWinPosToApp

Function

If non-NULL, read the first LONG as a byte count and CopyMem that many

bytes into the application beginning at winposused. NULL does nothing.

Inputs

CONST_APTR; set only.

Notes

The caller retains the source. Only use a trusted native-format block
with a valid nonnegative size, readable source extent, and size no
greater than the LONG header plus the 300-record destination array.

Bugs

There is no size, sign, format, or record validation. A malformed block

can overwrite instance data; this is not a checked import interface.

MUIA_Application_Copyright

Function

Store the application copyright string. Default NULL.

Inputs

STRPTR; initialize and get.

Notes

The pointer is stored without copying and is not freed. Keep the string
alive while the application uses it; there is no runtime setter for this
attribute.

MUIA_Application_Description

Function

Store the application description string. Default "?".

Inputs

STRPTR; initialize and get.

Notes

The pointer is stored without copying and is not freed. Keep the string
alive while the application uses it; there is no runtime setter for this
attribute.

MUIA_Application_DiskObject

Function

Store a borrowed icon used when iconifying. Default NULL; a missing icon

triggers fallback lookup when iconification is requested.

Inputs

DiskObject pointer; initialize, set, get.

Notes

The application does not free a supplied DiskObject. Keep it alive while
an AppIcon uses it. Iconification writes do_CurrentX and do_CurrentY to
NO_ICON_POSITION in the supplied object. Replacing the attribute does
not rebuild an already installed AppIcon.

MUIA_Application_DoubleStart

Function

A duplicate SingleTask construction queues a setter tag with TRUE on the

existing application, which can trigger Notify registrations.

Inputs

BOOL event; declared get only.

Notes

No persistent DoubleStart field is stored by Application.

Bugs

The getter returns TRUE without writing the supplied storage. It cannot

be used to read a defined Boolean value; use the notification event.

MUIA_Application_DropObject

Function

This attribute is declared but has no Application implementation.

Inputs

Object pointer; declared initialize and set.

Notes

The constructor ignores it and the getter has no matching case. Setter
tags are forwarded to Notify without an Application state change. The
legacy Menu attribute is not an alias for Menustrip.

MUIA_Application_ForceQuit

Function

Return the app_ForceQuit field. It is initially FALSE and is never set

by this implementation.

Inputs

BOOL; get only.

Notes

Commodities Kill sets SIGBREAKF_CTRL_C instead. Do not wait for this

attribute as an implemented quit event.

MUIA_Application_GetWinPos

Function

Find SearchWinId in occupied slots until the first empty slot and return

a borrowed record pointer, or NULL when absent or the query ID is zero.

Inputs

Pointer to struct windowpos; get only.

Notes

The getter returns TRUE even for NULL. Records live inside the
application and can change through SetWinPos or CopyWinPosToApp; do not
free them.

MUIA_Application_GetWinPosAddr

Function

Return a borrowed pointer to the LONG winposused field immediately

preceding the internal position array.

Inputs

APTR; get only.

Notes

The payload begins with a 32-bit LONG size even on 64-bit systems,
followed by native struct windowpos records. Query GetWinPosSize first.
No copy or byte-order conversion is made. Keep the application alive and
prevent position changes while consuming the bytes.

MUIA_Application_GetWinPosSize

Function

Count occupied records until the first zero w1 in the first 299 slots.
Return zero for none, otherwise sizeof(LONG) plus the record bytes, and
store that size in the serialized header.

Inputs

LONG byte count; get only.

Notes

This getter mutates winposused. Call it before using GetWinPosAddr to

obtain a current serialized header; there is no lock around the pair.

MUIA_Application_HelpFile

Function

Store a borrowed help-file pointer, initially NULL.

Inputs

STRPTR; initialize, set, get.

Notes

The class does not open it. ShowHelp is not implemented. Keep the string

alive while stored; it is not copied or freed.

MUIA_Application_Iconified

Function

Treat exactly 1 as iconify and any other value as restore. On a state
change, store the flag, propagate inverse ShowMe to windows, and add or
remove a Workbench AppIcon.

Inputs

BOOL; set and get.

Notes

Initially FALSE. Fallback icons are application-owned; supplied
DiskObject remains borrowed. A no-argument AppIcon activation handled by
NewInput restores the application.

Bugs

The flag and window visibility are changed before icon creation
succeeds. Failed fallback lookup or AddAppIcon does not roll back the
iconified state; TRUE is not proof of a visible AppIcon.

MUIA_Application_MenuAction

Function

Store and return the last application menu-action value, initially zero.

The window menu-pick path sets it from the selected item's UserData.

Inputs

ULONG; declared get only; also accepted by OM_SET.

Notes

The setter forwards the tag to Notify, so repeated values can trigger
notifications. The same window path also queues ReturnID. Values are
converted to the ULONG field; this is not pointer-sized storage on
64-bit targets.

MUIA_Application_MenuHelp

Function

This attribute is declared but has no Application implementation.

Inputs

ULONG; declared get only.

Notes

The constructor ignores it and the getter has no matching case. Setter
tags are forwarded to Notify without an Application state change. The
legacy Menu attribute is not an alias for Menustrip.

MUIA_Application_Menustrip

Function

Supply the application-wide menu tree, initially NULL. The constructor

connects it to this application, and application disposal disposes it.

Inputs

Object pointer; initialize; getter also implemented.

Notes

Ownership transfers when the constructor stores the tag. Do not attach
the same owned object elsewhere. There is no setter for replacement. The
getter returns a borrowed pointer.

MUIA_Application_RexxHook

Function

Store a borrowed fallback hook for Rexx commands not matched by

Commands. Default NULL.

Inputs

Hook pointer; initialize, set, get.

Notes

The hook receives the application and the live RexxMsg; its return value
becomes rm_Result1. Without it, unmatched requests receive RC_ERROR. The
message is replied to after the callback. Keep the hook alive and do not
retain or reply to the message yourself.

MUIA_Application_RexxMsg

Function

Return the current Rexx request during a command or fallback hook; NULL

outside those callbacks.

Inputs

RexxMsg pointer; get only.

Notes

The pointer is borrowed and valid only during the callback. NewInput

clears the field before replying to the request.

MUIA_Application_RexxString

Function

Replace the application-owned copy of the Rexx result string. When
RXFF_RESULT is requested, NewInput creates an Argstring from the current
copy for the reply.

Inputs

STRPTR; set only.

Notes

The previous copy is freed before StrDup reads the supplied pointer; do
not pass storage that aliases it. Input must remain valid through the
setter. Copy failure leaves no stored string and is not reported by the
setter.

Bugs

The stored result string is not automatically reset for each incoming
command. Set it deliberately in each callback that supplies a result;
otherwise a prior result can be reused. This attribute does not execute
an ARexx command.

MUIA_Application_SearchWinId

Function

Store the window identifier used by the next GetWinPos query. Initial

value zero.

Inputs

ULONG; set only.

Notes

This is mutable shared query state, not a parameter to GetWinPos.

Serialize the set/get pair. Identifier zero is never searched.

MUIA_Application_SetWinPos

Function

Copy a position record into the first matching occupied slot or the

first empty slot. An occupied slot has nonzero w1.

Inputs

Pointer to struct windowpos; set only.

Notes

Supply a non-NULL readable record. The first 299 slots of the
MAXWINS=300 array are examined. A full examined range silently ignores a
new ID. A zero w1 marks the stored slot empty and can terminate later
scans. The record is copied, not retained.

MUIA_Application_SingleTask

Function

Use a shared unsuffixed base when true; default FALSE. If a tracked
application already has the base, queue MUIM_Set of DoubleStart=TRUE on
that application and fail this construction.

Inputs

BOOL; initialize only.

Notes

The notification is deferred through the other application's
pushed-method queue. This attribute does not make the application or its
objects safe for concurrent use.

Bugs

The target application's lifetime until the queued notification executes
is not retained. Registration and name lookup do not provide a general
cross-task lifetime guarantee.

MUIA_Application_Sleep

Function

Set Window_Sleep to TRUE for each current window when the value is

nonzero, or FALSE when it is zero.

Inputs

BOOL; set only.

Notes

No application-level sleep flag is stored and no getter is implemented.
Newly added windows do not inherit a remembered application sleep state.
Callback-driven membership changes during this traversal are not
protected.

MUIA_Application_Title

Function

Store the application title string. Default "Unnamed".

Inputs

STRPTR; initialize and get.

Notes

The pointer is stored without copying and is not freed. Keep the string
alive while the application uses it; there is no runtime setter for this
attribute.

MUIA_Application_UseCommodities

Function

Request a Commodities broker and message port when commodities.library

is available. Default TRUE.

Inputs

BOOL; initialize only.

Notes

Broker creation failure is tolerated. Inspect Broker if the application

requires it; this attribute has no getter or setter.

MUIA_Application_UseRexx

Function

Request a public Rexx message port named from the uppercased actual

Base. Default FALSE.

Inputs

BOOL; initialize only.

Notes

A Commands initialization tag also sets the request to TRUE, even for a
NULL table. Constructor tag order matters: a later UseRexx tag can
override it. Optional port creation failure does not fail the
application. Setting Commands later does not create a missing port.

MUIA_Application_UsedClasses

Function

For each class name, call MUI_GetClass and, if it succeeds,

MUI_FreeClass. A NULL array is ignored.

Inputs

NULL-terminated STRPTR array; initialize only.

Notes

No class list is retained or returned. Individual failures do not abort
construction. Keep the array and strings valid during construction; this
is not a guarantee that every named class remains loaded.

MUIA_Application_Version

Function

Store the supplied version pointer. If explicitly set to NULL, and both
Title and Version_Number are non-NULL, allocate "$VER: <title> <number>"
with optional " (<date>)" and " [<extra>]" suffixes.

Inputs

STRPTR; initialize and get.

Notes

A supplied string is borrowed. An automatically generated string is
owned by the application and freed at disposal. The getter returns a
borrowed pointer in either case. Failed generation leaves NULL without
failing construction.

Bugs

Omission does not request generation: the constructor initializes
Version to "Unnamed 0.0". This differs from the header comment that
promises generation when the attribute is unspecified.

MUIA_Application_Version_Date

Function

Store the application version date string. Default NULL.

Inputs

STRPTR; initialize and get.

Notes

The pointer is stored without copying and is not freed. Keep the string
alive while the application uses it; there is no runtime setter for this
attribute. This value participates in version-string construction only
when Version is explicitly NULL; Date is not format-validated.

MUIA_Application_Version_Extra

Function

Store the application version extra string. Default NULL.

Inputs

STRPTR; initialize and get.

Notes

The pointer is stored without copying and is not freed. Keep the string
alive while the application uses it; there is no runtime setter for this
attribute. This value participates in version-string construction only
when Version is explicitly NULL; Date is not format-validated.

MUIA_Application_Version_Number

Function

Store the application version number string. Default NULL.

Inputs

STRPTR; initialize and get.

Notes

The pointer is stored without copying and is not freed. Keep the string
alive while the application uses it; there is no runtime setter for this
attribute. This value participates in version-string construction only
when Version is explicitly NULL; Date is not format-validated.

MUIA_Application_Window

Function

Append a non-NULL Window-compatible child through OM_ADDMEMBER and

connect it to the application.

Inputs

Object pointer; initialize only; repeatable.

Notes

The application owns attached windows. A NULL Window tag marks
construction failure; after processing tags, disposal removes and
disposes attached windows. Earlier construction failure can occur before
child tags are processed. Runtime changes use OM_ADDMEMBER and
OM_REMMEMBER. Neither operation validates existing membership or
propagates child failure results.

MUIA_Application_WindowList

Function

Return the borrowed child list of the internal window Family.

Inputs

Pointer to an Exec list; get only.

Notes

Use NextObject for traversal. Do not free or modify the links directly.
Keep the application and membership stable during iteration; the list
becomes invalid at disposal.

MUIC_Application

Superclass

Notify.mui

Description

Own the application window family, optional menustrip, configuration
object, message ports, and event queues. Construction binds the
application to the creating task. Process input and perform ordinary
object mutations in that task; the pushed-method queue has a separate
semaphore but does not protect object lifetimes.
Window tags attach owned children. OM_ADDMEMBER appends through the
internal Family and connects the child to this application; OM_REMMEMBER
disconnects and unlinks without disposing it. Both member methods return
TRUE without checking child results. Supply live, correctly owned
Window-compatible children and remove them before separate disposal.
Application disposal removes and disposes remaining windows, the
menustrip, and configuration data, then releases its own resources.
Caller-supplied metadata strings, hooks, command tables, and DiskObject
remain borrowed unless an attribute explicitly documents copying. Stop
input processing and callbacks, remove input handlers, and resolve
queued methods before disposal.

Methods

FindUData and GetUData examine the application first, then delegate to
the internal window Family. That Family itself participates in matching
before its children, including its default UserData value zero. GetUData
returns a match result, not the attribute getter's success.
SetUData sets the application on a match, visits the internal Family,
and returns TRUE regardless of matches. SetUDataOnce stops at the
application or first delegated match. The application menustrip is not
traversed by these overrides. Keep membership stable during callbacks.
MUIA_ShowMe is also accepted by the setter and propagated to windows.
The iteration rereads the window list after each setter and assumes that
a processed window does not remove itself. Local MUIA_Version and
MUIA_Revision both return 1.

Notes

Normal construction returns NULL on required allocation, port, timer,
configuration, or child validation failure. Optional broker or Rexx-port
creation failure does not fail construction. The constructor creates
configuration notification for ENV:zune/<base>.prefs when possible;
failure to watch that file is not reported. NewInput processes changes
and queues configuration replacement.
Disposal can perform configuration-file I/O and wait for timer
completion. Depending on the configured window-position mode, it
snapshots windows and writes ENV preferences; mode 2 also reloads and
saves ENVARC preferences to retain persistent settings while updating
positions.

Bugs

The early disposal path dereferences mgi_Prefs whenever app_Base is
non-NULL. Failure after assigning the base but before preferences are
available can therefore access NULL instead of cleanly returning
construction failure.
Disposal does not drain or free app_MethodQueue and does not enumerate
and remove registered timer handlers. Pending method payloads and
handler resources must not be assumed to be reclaimed by application
disposal. Cross-task queue insertion is not an application-lifetime
guarantee.

MUIM_Application_AboutMUI

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_AboutMUI, (IPTR)refwindow);

Function

Create the Aboutmui window on first use, cache it, and request that it

open. Later calls reuse the same window.

Inputs

refwindow - Optional live Window object used as the reference during

first construction; NULL omits the reference tag.

Result

Always zero, including construction or opening failure.

Notes

The Aboutmui constructor attaches the window to this application, which
owns it. Later refwindow arguments do not reposition the cached window.
Keep a supplied reference window alive while the cached window uses it.
Do not dispose of the cached window separately and leave this
application alive.

MUIM_Application_AddInputHandler

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_AddInputHandler,
(IPTR)ihnode);

Function

repeating timer when MUIIHNF_TIMER is set.

Inputs

ihnode - Non-NULL, stable, writable node not already registered. Set
ihn_Object to a live target and ihn_Method to its no-argument method.
For signals set ihn_Signals; for timers set ihn_Millis (UWORD
milliseconds).

Result

Always TRUE, including timer-request allocation failure.

Notes

Signal nodes are linked directly into the application list. Timer
registration stores an allocated timer-request pointer in
ihn_Node.mln_Pred; do not overwrite it. NewInput restarts a completed
timer before calling its target. Keep node and target alive until
removal has completed.

Bugs

Timer allocation failure leaves no valid registered timer request but
still reports TRUE. A later RemInputHandler cannot safely assume success
from this return value. No duplicate-registration or interval validation
is performed.

MUIM_Application_CheckRefresh

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_CheckRefresh);

Function

Send MUIM_Window_Refresh to every window in the internal family.

Inputs

No arguments beyond MethodID. Keep the application and window list alive

throughout the call.

Result

Always zero; child results are ignored.

Notes

This is the refresh entry point used from modal-requester IntuiMessage
hooks. It does not itself dequeue or reply to the hook message. Supply
any native-window requester tags only while that window is open; they
are not necessarily valid during construction.

MUIM_Application_Execute

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_Execute);

Function

Run NewInput and Wait repeatedly until the quit ReturnID or

SIGBREAKF_CTRL_C is received.

Inputs

No arguments beyond MethodID. Call in the application's creating task.

Result

Always zero on leaving the loop.

Notes

The loop waits on the NewInput mask plus Ctrl-C when the mask is
nonzero. It ignores other ReturnIDs, does not dispose of the
application, and has no timeout.

Bugs

It uses an IPTR local for an interface that writes ULONG signals. The
mismatch is not portable to all 64-bit byte orders. Queued non-quit IDs
and callback changes to masks inherit NewInput's limitations.

MUIM_Application_GetMenuCheck

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_GetMenuCheck, MenuID);

Function

Declared in application.h, but not handled by the Application
dispatcher. The message is forwarded through Notify to rootclass without
implementing this operation.

Inputs

MenuID - ULONG menu identifier.

Result

The inherited unhandled-method result is zero. It is not a completion or

menu-state result.

Notes

Use the implemented attributes and object interfaces only where their
documented behavior meets the need. A method name alone does not
establish compatibility.

MUIM_Application_GetMenuState

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_GetMenuState, MenuID);

Function

Declared in application.h, but not handled by the Application
dispatcher. The message is forwarded through Notify to rootclass without
implementing this operation.

Inputs

MenuID - ULONG menu identifier.

Result

The inherited unhandled-method result is zero. It is not a completion or

menu-state result.

Notes

Use the implemented attributes and object interfaces only where their
documented behavior meets the need. A method name alone does not
establish compatibility.

MUIM_Application_Iconify

Synopsis

DoMethodA(obj, message);

Function

Declared in application.h, but not handled by the Application
dispatcher. The message is forwarded through Notify to rootclass without
implementing this operation.

Inputs

The header defines the MethodID but no corresponding method structure or

implemented argument contract.

Result

The inherited unhandled-method result is zero. It is not a completion or

menu-state result.

Notes

Use the implemented attributes and object interfaces only where their
documented behavior meets the need. A method name alone does not
establish compatibility.

MUIM_Application_Input

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_Input, (IPTR)signals);

Function

Construct a polling mask and invoke NewInput. This is the legacy input

method.

Inputs

signals - Writable ULONG pointer; the incoming value is replaced.

Result

The ReturnID result from NewInput; the location receives its wait mask.

Notes

Use NewInput for signal-driven processing.

Bugs

This implementation combines handler flags rather than ihn_Signals and
omits the broker signal from its constructed mask. It does not
faithfully poll every registered source.

MUIM_Application_InputBuffered

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_InputBuffered);

Function

Drain pushed methods, then process at most one queued window

IntuiMessage.

Inputs

No arguments beyond MethodID.

Result

Always TRUE.

Notes

Reply behavior follows the Window event path. GADGETUP and an eaten
IDCMPUPDATE currently lack a reply. This method does not
drain all window events, process timer/Rexx/broker/AppMessage sources,
or return queued ReturnIDs. Continuously self-replenishing pushed
methods can prevent completion.

MUIM_Application_Load

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_Load, (IPTR)name);

Function

Read a PREF/MUIO chunk into a temporary Dataspace, then send MUIM_Import

to each application window.

Inputs

name - Filename, or MUIV_Application_Load_ENV (NULL) for
ENV:Zune/<base>.cfg, or MUIV_Application_Load_ENVARC for
ENVARC:Zune/<base>.cfg. Explicit filenames must be NUL-terminated and
shorter than 1023 bytes.

Result

Always zero, including allocation, file, IFF, and child-method failures.

Notes

Import is attempted even when the file could not be opened or parsed,
using an empty or partially populated dataspace. There is no rollback of
child state.
The temporary dataspace is disposed before return; child methods must
not retain it or borrowed payloads. I/O can block. These .cfg state
files are separate from the .prefs configuration file.

Bugs

Underlying results are ignored. The explicit-name strncpy path does not
append a terminator for an overlong name. The return value cannot
establish successful loading.

MUIM_Application_NewInput

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_NewInput, (IPTR)signals);

Function

Process pending pushed methods, handle selected event sources, drain

newly pushed methods, and remove at most one ReturnID from its FIFO.

Inputs

signals - Non-NULL readable and writable ULONG pointer. On entry supply
the signals returned by Wait, or zero for polling all current sources.
On return it contains the computed wait mask.
obj - Live application processed in its creating task.

Result

The next queued ULONG ReturnID, or zero when none is queued. A queued

zero is indistinguishable from no ID.

Notes

This method itself does not call Wait. Callbacks and invoked operations
can still block. A zero input mask treats all registered signal sources
as signaled, including user handlers; it does not test which handler
signals actually occurred.
The wait mask is computed before event callbacks and the final queue
drain. Callback changes to registrations are not reflected until a later
call. Pending ReturnIDs do not themselves force a zero wait mask. A
pushed method can enqueue more work, extending the drain indefinitely.

Bugs

Do not dispose of this application while NewInput is active. Keep
handler and window traversals valid through callbacks. The command-table
path has unchecked allocation/parsing failures; see Commands.

MUIM_Application_OpenConfigWindow

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_OpenConfigWindow, flags);

Function

Launch sys:prefs/Zune asynchronously with the application base and

object address on its command line.

Inputs

flags - ULONG declared in the message; ignored.

Result

0 if SystemTagList returns -1; otherwise 1. This does not report whether

the preferences program completed successfully.

Notes

The command is built in a 255-byte buffer. Child standard input and

output are disabled; the stack size is AROS_STACKSIZE.

Bugs

The base is inserted without shell quoting and may be truncated along
with the command. Accepted Base characters are not a shell-escaping
guarantee. The method does not establish that the externally used
application object remains alive.

MUIM_Application_OpenWindows

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_OpenWindows,
(IPTR)windows);

Function

Request opening of selected windows, or all current application windows

when windows is NULL.

Inputs

windows - NULL, or an owned Exec List allocated with AllocVec whose
nodes were individually allocated with AllocVec and hold live window
pointers in ln_Name.

Result

Always zero; window setter results are ignored.

Notes

A non-NULL list and every removed node are consumed and freed with
FreeVec. Do not pass the borrowed Application_WindowList or stack
storage. The referenced windows are not freed. For NULL, traverse the
internal Family without taking ownership of its list.

MUIM_Application_PushMethod

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_PushMethod, (IPTR)dest,
count, ...);

Function

Copy message words into a FIFO entry, enqueue it under the method

semaphore, and signal the creating task using the window-port signal.

Inputs

dest - Live destination object to keep alive until execution or
cancellation.
count - LONG whose low four bits specify the number of following IPTR
words, including MethodID. Use 1 through 15.
... - Destination MethodID followed by its message arguments.

Result

An opaque IPTR queue-entry token, or zero on allocation failure. The

token is valid only while that entry remains queued.

Notes

Only words are copied; referenced storage and objects remain borrowed.
NewInput and InputBuffered execute queued messages outside the semaphore
and discard their results. There is no completion acknowledgement.
Cancel pending work before destroying its target; cancellation cannot
stop a method already dequeued.

Bugs

Count is masked with 0xf, not range-checked. Zero creates an entry
without a MethodID; 16 becomes zero. The source explicitly notes that
extracting words after count is broken on 64-bit big-endian systems.
Disposal does not free outstanding queue entries.

MUIM_Application_RemInputHandler

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_RemInputHandler,
(IPTR)ihnode);

Function

Unlink a registered signal node, or abort if necessary, wait for, and

free its timer request.

Inputs

ihnode - The same node successfully registered with AddInputHandler. Its

flags and internal timer pointer must remain intact.

Result

Always TRUE after removal.

Notes

Timer removal can wait for I/O completion. The caller owns the node and
target. A timer callback can remove itself because NewInput resubmits
before invoking it.

Bugs

An unregistered node, repeated removal, or a failed timer registration
is not checked. Signal-list iteration does not protect a callback that
removes its current node and frees it before NewInput advances.

MUIM_Application_ReturnID

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_ReturnID, retid);

Function

Append a ULONG return value to the application ReturnID FIFO.

Inputs

retid - ULONG value; MUIV_Application_ReturnID_Quit is the conventional

quit value.

Result

TRUE if allocation and insertion succeed; FALSE on allocation failure.

Notes

NewInput removes one ID per call. This method neither signals the
application task nor locks the ReturnID queue. Use it in the application
task; external tasks can request it through PushMethod while separately
ensuring object lifetime.

MUIM_Application_Save

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_Save, (IPTR)name);

Function

Export each window into a temporary Dataspace, then write an IFF PREF

file containing PRHD and MUIO chunks.

Inputs

name - Filename, or MUIV_Application_Save_ENV (NULL) for
ENV:Zune/<base>.cfg, or MUIV_Application_Save_ENVARC for
ENVARC:Zune/<base>.cfg. Explicit filenames must be NUL-terminated and
shorter than 1023 bytes.

Result

Always zero, including allocation, file, IFF, and child-method failures.

Notes

Opening with MODE_NEWFILE can replace existing content. Output is not
atomic and failures can leave a partial file. Exported state depends on
each child's implementation.
The temporary dataspace is disposed before return; child methods must
not retain it or borrowed payloads. I/O can block. These .cfg state
files are separate from the .prefs configuration file.

Bugs

Underlying results are ignored. The explicit-name strncpy path does not
append a terminator for an overlong name. The return value cannot
establish successful saving.

MUIM_Application_SetConfigItem

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_SetConfigItem, item,
(IPTR)data);

Function

Set a supported string-valued configuration item with

MUIM_Configdata_SetString. Other item IDs do nothing.

Inputs

item - One of the supported identifiers listed below.
data - Non-NULL readable NUL-terminated string.
Supported IDs: MUICFG_Keyboard_Press, MUICFG_Keyboard_Toggle,
MUICFG_Keyboard_Up, MUICFG_Keyboard_Down, MUICFG_Keyboard_PageUp,
MUICFG_Keyboard_PageDown, MUICFG_Keyboard_Top, MUICFG_Keyboard_Bottom,
MUICFG_Keyboard_Left, MUICFG_Keyboard_Right, MUICFG_Keyboard_WordLeft,
MUICFG_Keyboard_WordRight, MUICFG_Keyboard_LineStart,
MUICFG_Keyboard_LineEnd, MUICFG_Keyboard_NextGadget,
MUICFG_Keyboard_PrevGadget, MUICFG_Keyboard_GadgetOff,
MUICFG_Keyboard_CloseWindow, MUICFG_Keyboard_NextWindow,
MUICFG_Keyboard_PrevWindow, MUICFG_Keyboard_Help, MUICFG_Keyboard_Popup,
MUICFG_Drag_LMBModifier, MUICFG_Drag_MMBModifier,
MUICFG_Iconification_Hotkey, MUICFG_Font_Normal, MUICFG_Font_List,
MUICFG_Font_Tiny, MUICFG_Font_Fixed, MUICFG_Font_Title, MUICFG_Font_Big,
MUICFG_Font_Button, MUICFG_Font_Knob, MUICFG_String_Background,
MUICFG_String_Text, MUICFG_String_ActiveBackground,
MUICFG_String_ActiveText, MUICFG_String_Cursor,
MUICFG_String_MarkedBackground, MUICFG_String_MarkedText,
MUICFG_ActiveObject_Color, MUICFG_PublicScreen.

Result

Always zero, including unsupported IDs or ignored underlying failures.

Notes

Keyboard bindings, drag modifiers, and the iconification hotkey are set
directly. Font IDs, String color/pen IDs, ActiveObject_Color, and
PublicScreen close currently open windows and queue reopening after the
change. Configdata copies the string or removes a value equal to its
default. This does not save preferences to disk.

Bugs

The close/reopen path shares SetConfigdata's incomplete-allocation and

queue-failure limitations; no rollback or success status is provided.

MUIM_Application_SetConfigdata

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_SetConfigdata,
(IPTR)configdata);

Function

Close currently open windows, dispose of the old configuration, install

the new object, read its ZunePrefs pointer, and queue reopening.

Inputs

configdata - Live Configdata-compatible object, distinct from the
currently installed object. Ownership transfers to the application when
installed.

Result

Always zero, without an installation or reopening success indication.

Notes

Previously borrowed configuration/prefs pointers become invalid. The
method closes windows immediately but reopens them through PushMethod.
The new configuration must provide valid ZunePrefs.

Bugs

No NULL, identity, or getter-success check is performed before adopting
the replacement. Passing the old object disposes it before reuse. If
saving the open-window list fails, NULL later means reopen all windows;
failed node allocation can omit individual windows. Queue failure can
leave windows closed and leak the saved list.

MUIM_Application_SetMenuCheck

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_SetMenuCheck, MenuID,
stat);

Function

Declared in application.h, but not handled by the Application
dispatcher. The message is forwarded through Notify to rootclass without
implementing this operation.

Inputs

MenuID - ULONG menu identifier.

stat - LONG state.

Result

The inherited unhandled-method result is zero. It is not a completion or

menu-state result.

Notes

Use the implemented attributes and object interfaces only where their
documented behavior meets the need. A method name alone does not
establish compatibility.

MUIM_Application_SetMenuState

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_SetMenuState, MenuID,
stat);

Function

Declared in application.h, but not handled by the Application
dispatcher. The message is forwarded through Notify to rootclass without
implementing this operation.

Inputs

MenuID - ULONG menu identifier.

stat - LONG state.

Result

The inherited unhandled-method result is zero. It is not a completion or

menu-state result.

Notes

Use the implemented attributes and object interfaces only where their
documented behavior meets the need. A method name alone does not
establish compatibility.

MUIM_Application_ShowHelp

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_ShowHelp, (IPTR)window,
(IPTR)name, (IPTR)node, line);

Function

Declared in application.h, but not handled by the Application
dispatcher. The message is forwarded through Notify to rootclass without
implementing this operation.

Inputs

window - Object pointer.
name, node - String pointers.
line - LONG. These fields are declared but unused by Application.

Result

The inherited unhandled-method result is zero. It is not a completion or

menu-state result.

Notes

Use the implemented attributes and object interfaces only where their
documented behavior meets the need. A method name alone does not
establish compatibility.

MUIM_Application_UnpushMethod

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_UnpushMethod, (IPTR)dest,
methodid, method);

Function

Remove and free every queued method matching all supplied filters.

Inputs

dest - Destination pointer or NULL for any destination.
methodid - Queue-entry token from PushMethod, or zero for any token.
method - Destination MethodID, or zero for any method.

Result

Number of queued entries removed.

Notes

The queue is locked while filtering. This neither waits for nor cancels
an entry already dequeued for execution. Freed tokens may be reused by
allocation; do not retain them as permanent identifiers.

MUIM_Application_UpdateMenus

Synopsis

IPTR result = DoMethod(obj, MUIM_Application_UpdateMenus);

Function

Send MUIM_Window_UpdateMenu synchronously to every current application

window.

Inputs

No arguments beyond MethodID. Keep membership stable during traversal.

Result

Always zero; window results are ignored.

Notes

Window menu updates can free native Menu and MenuItem structures before
rebuilding them. Do not retain their pointers across this method. This
is not a success report for menu allocation or attachment.