Synopsis

APTR MUI_AddClipping(
         struct MUI_RenderInfo * mri,
         WORD left,
         WORD top,
         WORD width,
         WORD height );

Function

Restrict drawing to a rectangle by creating a region and passing it
to MUI_AddClipRegion(). Existing MUI clipping remains in effect.

Inputs

mri - Valid rendering context for the target layer.
left, top - Rectangle origin in the layer's drawing coordinates.
width, height - Positive rectangle dimensions in pixels. Values
                greater than or equal to MUI_MAXMAX skip clipping.

Result

A removal token, which can be NULL, or (APTR)-1 if no region was
pushed. The latter includes allocation failure, a rejected region,
a skipped dimension, and a rectangle containing the current clip
region's entire bounds.

Notes

Pair this call with MUI_RemoveClipping() using the same context
and the exact token. Remove nested clips in reverse order. NULL
is a valid success token; do not test the token as a Boolean.
Failure and an unnecessary clip share the same sentinel, so this
interface cannot guarantee that a new restriction was installed.

Bugs

The result of OrRectRegion() is not checked before the region is
passed to MUI_AddClipRegion().

See also

MUI_RemoveClipping() MUI_AddClipRegion() MUI_RemoveClipRegion()

Synopsis

APTR MUI_AddClipRegion(
         struct MUI_RenderInfo * mri,
         struct Region * r );

Function

Push a region onto the rendering context's clipping stack and install
it on the window layer, or the RastPort layer when no window exists.
If another MUI clip is active, intersect r with that region first.

Inputs

mri - Non-NULL initialized rendering context. When mri_Window is
      NULL, mri_RastPort must be valid.
r - Region whose ownership is transferred to this call, or NULL.

Result

The previous layer clip-region pointer as a removal token, including
NULL when no previous region exists. Returns (APTR)-1 if r or the
target layer is NULL or the 20-entry MUI clipping stack is full.

Notes

The function modifies r and disposes of it on rejection. After a
successful push, MUI_RemoveClipRegion() disposes of it. Do not free
or modify the region after passing it here.
Remove successful pushes in reverse order using the same rendering
context. Preserve the layer and context until all clips are removed.
Refresh processing is temporarily suspended and resumed when needed.

Bugs

Failure of the region intersection is not checked. Removal restores
the previous MUI stack entry, not an arbitrary pre-existing layer
clip region represented by the returned token. Do not mix this
stack with independently installed layer clip regions.

See also

MUI_RemoveClipRegion() MUI_AddClipping() layers.library/InstallClipRegion()

Synopsis

APTR MUI_AllocAslRequest(
         ULONG reqType,
         struct TagItem * tagList );

APTR MUI_AllocAslRequestTags(
         ULONG reqType,
         TAG tag, ... );

Function

Allocate an ASL requester by forwarding reqType and tagList to
asl.library/AllocAslRequest(). No MUI-specific attributes are added.

Inputs

reqType - ASL_FileRequest, ASL_FontRequest, or ASL_ScreenModeRequest.
tagList - Requester-specific ASL tags terminated by TAG_DONE, or
          NULL to use defaults.

Result

The allocated requester, or NULL. In the AROS ASL implementation,
allocation failure sets IoErr() to ERROR_NO_FREE_STORE; an unsupported
requester type returns NULL with IoErr() set to zero.

Notes

MUI_AllocAslRequestTags() is the variadic tag-list wrapper.

Run the requester with MUI_AslRequest() and release it with
MUI_FreeAslRequest(). Refer to ASL for the lifetime of tag payloads
and requester-specific result fields.

See also

MUI_AslRequest() MUI_FreeAslRequest() asl.library/AllocAslRequest()

Synopsis

BOOL MUI_AslRequest(
         APTR requester,
         struct TagItem * tagList );

BOOL MUI_AslRequestTags(
         APTR requester,
         TAG tag, ... );

Function

Run an allocated ASL requester by forwarding requester and tagList
to asl.library/AslRequest(). The call runs the ASL event loop and
waits for the requester to finish.

Inputs

requester - Requester allocated by MUI_AllocAslRequest() or
            asl.library/AllocAslRequest().
tagList - Additional requester-specific ASL tags terminated by
          TAG_DONE, or NULL to retain the existing settings.

Result

The BOOL result of AslRequest(): TRUE on successful completion,
FALSE on cancellation or failure. NULL requester returns FALSE
and sets IoErr() to ERROR_NO_FREE_STORE in AROS.

Notes

MUI_AslRequestTags() is the variadic tag-list wrapper.

Call from a process context suitable for an ASL requester. Result
fields and detailed error behavior belong to the ASL requester
type. The requester remains allocated after this call.

See also

MUI_AllocAslRequest() MUI_FreeAslRequest() asl.library/AslRequest()

Synopsis

BOOL MUI_BeginRefresh(
         struct MUI_RenderInfo * mri,
         ULONG flags );

Function

Begin a refresh pass for a damaged simple-refresh window. Set the
rendering context's refresh flag, lock the screen's LayerInfo, and
call intuition.library/BeginRefresh().

Inputs

mri - Non-NULL initialized rendering context. A present window must
      have a valid window layer and screen.
flags - Ignored by this implementation; pass zero.

Result

TRUE if a refresh pass was begun. FALSE if there is no window, the
window is not simple-refresh, its layer does not need refreshing,
or this rendering context is already in refresh mode.

Notes

Only after TRUE, complete the pass with MUI_EndRefresh() on the
same context. The LayerInfo lock remains held between these calls.
Do not close the window or change the context during that interval.

See also

MUI_EndRefresh() intuition.library/BeginRefresh()

Synopsis

struct MUI_CustomClass * MUI_CreateCustomClass(
         struct Library * base,
         ClassID supername,
         struct MUI_CustomClass * supermcc,
         ULONG datasize,
         APTR dispatcher );

Function

Create a BOOPSI class derived from a named MUI class or an existing
custom class, and return a descriptor for the new class.
If supermcc is supplied, it takes precedence over supername.

Inputs

base - Library base for a class module, or NULL for a private class.
       With a non-NULL base, its node name supplies the class ID
       through dos.library/FilePart(). The base is also passed to
       the dispatcher through the class dispatcher's data field.
supername - NUL-terminated superclass identifier, used only when
            supermcc is NULL.
supermcc - Existing superclass descriptor, or NULL to use supername.
           Its mcc_Class must be valid.
datasize - Number of instance-data bytes added by the new class.
dispatcher - Non-NULL dispatcher entrypoint using the AROS class
             dispatcher calling convention.

Result

A newly allocated MUI_CustomClass descriptor, or NULL if neither
superclass argument is supplied, the named superclass cannot be
obtained, descriptor allocation fails, or MakeClass() fails.

Notes

Keep the dispatcher and any supplied module base valid while the
class is in use. Dispose of all instances and subclasses before
releasing the descriptor with MUI_DeleteCustomClass().
The supplied superclass descriptor is not copied or freed here.

Bugs

If a named superclass was obtained and a later allocation or
MakeClass() fails, this implementation does not release that
superclass. A supplied superclass is not separately acquired,
although successful deletion calls MUI_FreeClass() on it.

See also

MUI_DeleteCustomClass() MUI_GetClass() intuition.library/MakeClass()

Synopsis

BOOL MUI_DeleteCustomClass(
         struct MUI_CustomClass * mcc );

Function

Attempt to free a custom class. If intuition.library/FreeClass()
succeeds, free the descriptor and call MUI_FreeClass() on the
stored superclass.

Inputs

mcc - Descriptor returned by MUI_CreateCustomClass(), or NULL.

Result

TRUE if the class and descriptor were freed. FALSE if mcc is NULL
or FreeClass() refuses to free the class, for example because
instances or subclasses remain.

Notes

On FALSE for a non-NULL descriptor, the descriptor remains allocated.
On TRUE, do not use the descriptor or its class again.

See also

MUI_CreateCustomClass() MUI_FreeClass() intuition.library/FreeClass()

Synopsis

VOID MUI_DisposeObject(
         Object * obj );

Function

Dispose of a MUI object, then release its class through MUI_FreeClass().
The object's OM_DISPOSE implementation determines which owned
children and other resources are released.

Inputs

obj - Object to dispose of, or NULL to do nothing.

Result

None.

Notes

The object pointer is invalid after disposal. Remove a child from
its owner before disposing of it independently. Do not separately
dispose of children that the parent has already disposed of.

See also

MUI_NewObjectA() MUI_FreeClass() intuition.library/DisposeObject()

Synopsis

VOID MUI_EndRefresh(
         struct MUI_RenderInfo * mri,
         ULONG flags );

Function

Finish a refresh pass with intuition.library/EndRefresh(window, TRUE),
unlock the screen's LayerInfo, and clear the context's refresh flag.

Inputs

mri - Rendering context for a successful MUI_BeginRefresh() call,
      with the same window and screen still valid.
flags - Ignored by this implementation; pass zero.

Result

None.

Notes

Call exactly once after MUI_BeginRefresh() returns TRUE, in the same
task. This function does not check whether refresh mode is active.
A NULL mri_Window causes an early return without clearing the flag
or releasing the lock; it is not a substitute for a matched end.

See also

MUI_BeginRefresh() intuition.library/EndRefresh()

Synopsis

LONG MUI_Error();

Function

Return zero. This obsolete compatibility entrypoint does not read
an error variable or call dos.library/IoErr().

Inputs

None.

Result

Always zero, regardless of preceding MUI calls.

Notes

Do not use this return value to determine whether another call
succeeded. Check that call's documented return value and error
interface. IoErr() is relevant only when that interface uses it.

See also

MUI_SetError() dos.library/IoErr()

Synopsis

VOID MUI_FreeAslRequest(
         APTR requester );

Function

Release an allocated ASL requester through asl.library/FreeAslRequest().
ASL also releases the requester-specific result storage it owns.

Inputs

requester - Requester allocated by MUI_AllocAslRequest() or
            asl.library/AllocAslRequest(), or NULL to do nothing.

Result

None.

Notes

Call after requester execution has finished. Do not use the requester
or its owned result storage after this call.

See also

MUI_AllocAslRequest() MUI_AslRequest() asl.library/FreeAslRequest()

Synopsis

VOID MUI_FreeClass(
         Class * cl );

Function

Release a class obtained through MUI_GetClass(). For built-in
classes, update the internal class accounting and attempt to free
the class when that accounting reaches zero. For external classes,
close the library stored in the class dispatcher's data field.

Inputs

cl - Non-NULL class pointer obtained through MUI_GetClass().

Result

None. The function does not report whether a built-in class was
actually freed.

Notes

Do not use the class after releasing it. This legacy interface
is not the disposal function for a MUI_CustomClass descriptor;
use MUI_DeleteCustomClass() for that descriptor.
The implementation obtains the MUI class semaphore and can wait.

Bugs

After FreeClass() successfully frees a built-in class, this
implementation writes to that class's dispatcher data field.
This is a use-after-free defect, not a valid class-lifetime rule.

See also

MUI_GetClass() MUI_CreateCustomClass() MUI_DeleteCustomClass()

Synopsis

struct IClass * MUI_GetClass(
         ClassID classid );

Function

Look up a built-in MUI class or load an external class module.
Built-in class names are compared case-sensitively. If no built-in
class is found, the loader tries Zune/<classid>,
Classes/Zune/<classid>, and MUI/<classid>, in that order, using
exec.library/OpenLibrary().

Inputs

classid - NUL-terminated class identifier, or NULL.

Result

The class pointer, or NULL for a NULL identifier or failed lookup.

Notes

This legacy superclass lookup interface is deprecated in favor of
MUI_CreateCustomClass(). Pair a successful lookup with
MUI_FreeClass() when the class is no longer needed.
Loading an external class can perform file I/O and execute the
module's initialization and MCC_Query entrypoint. Do not call this
interface from an interrupt handler.

See also

MUI_FreeClass() MUI_CreateCustomClass() MUI_DeleteCustomClass()

Synopsis

BOOL MUI_Layout(
         Object * obj,
         LONG left,
         LONG top,
         LONG width,
         LONG height,
         ULONG flags );

Function

Set a child object's geometry relative to its parent's inner origin,
then invoke MUIM_Layout on the child. For a virtual-group parent,
subtract the parent's horizontal and vertical scroll offsets first.

Inputs

obj - Non-NULL Area-derived child with a valid parent and initialized
      layout data. This helper is used by group layout code.
left, top - Position relative to the parent's inner origin before
            virtual-group scroll offsets are subtracted.
width, height - Dimensions stored in the child's geometry.
flags - Ignored by this implementation; pass zero.

Result

Always TRUE after the layout method returns. The result of
MUIM_Layout is discarded.

Notes

This helper neither validates the dimensions against the child's
minimum and maximum sizes nor requests a redraw. The layout owner
must supply suitable geometry. NULL objects and parentless objects
are not accepted.

See also

MUI_Redraw()

Synopsis

Object * MUI_MakeObjectA(
         LONG type,
         IPTR * params );

Object * MUI_MakeObject(
         LONG type,
         TAG tag, ... );

Function

Construct a predefined MUI object from positional arguments.
The type selects a class or an object tree and the attributes used
to construct it. The parameter array is not a tag list.

Inputs

type - One of the MUIO_* values listed below.
params - Array of IPTR-sized values in the order listed for type.
         Cast pointer and integer arguments to IPTR. No terminator
         follows the positional arguments.

MUIO_Label: label, flags
    Text label. flags select SingleFrame or DoubleFrame,
    LeftAligned or Centered, and FreeVert using the corresponding
    MUIO_Label_* bits. Right alignment is the default. The low
    byte selects the highlight character; zero uses an underscore
    marker in the label. SingleFrame takes precedence over
    DoubleFrame, and LeftAligned over Centered.

MUIO_Button: label
    Text button with relative-verify input and cycle-chain entry.
    The character after the first underscore is its control key.

MUIO_Checkmark: label
    Toggle image. The label supplies the control key; it is not
    displayed beside the image.

MUIO_Cycle: label, entries
MUIO_Radio: label, entries
    Cycle or radio gadget. entries is a NULL-terminated array of
    string pointers. The label supplies the control key.

MUIO_Slider: label, minimum, maximum
    Slider with MUIA_Numeric_Min and MUIA_Numeric_Max set from the
    signed limits. The label supplies the control key.

MUIO_String: label, maxlen
    Framed string gadget. maxlen becomes MUIA_String_MaxLen;
    the label supplies the control key, not initial contents.

MUIO_PopButton: imagespec
    Relative-verify image button using MUIA_Image_Spec.

MUIO_HSpace: width
MUIO_VSpace: height
    Rectangle with fixed width or height, respectively.

MUIO_HBar: height
MUIO_VBar: width
    Horizontal or vertical separator with the specified thickness.

MUIO_MenustripNM: newmenu, flags
    Menustrip from an NM_END-terminated NewMenu array. NM_TITLE
    precedes its items; NM_SUB follows its parent NM_ITEM.
    Labels, shortcuts, user data, exclusion masks, and the supported
    disabled/check/toggle flags are passed to the menu objects.
    MUIO_MenustripNM_CommandKeyCheck enables the special label
    handling described under BUGS.

MUIO_Menuitem: label, shortcut, flags, userdata
    Menu item. flags use CHECKIT, CHECKED, MENUTOGGLE, and
    NM_ITEMDISABLED. userdata becomes MUIA_UserData.

MUIO_BarTitle: label
    Horizontal separator with MUIA_Rectangle_BarTitle set to label.

MUIO_NumericButton: label, minimum, maximum, format
    Numericbutton with signed limits. A non-NULL format sets
    MUIA_Numeric_Format; NULL retains the class default.

MUIO_CoolButton: label, image, flags
    Image-and-text button when compiled with HAVE_COOLIMAGES and
    an image is available. image is a CoolImage pointer, or an image
    ID when MUIO_CoolButton_CoolImageID is set. Falls back to
    MUIO_Button when the image facility or image is unavailable.

MUIO_ImageButton: label, imagepath
    Image-and-text button when the path can be locked for reading;
    otherwise a text button. The image specification is formed in
    a 512-byte buffer containing the prefix 3: and the path.

Result

The constructed object, or NULL for an unsupported type or failed
construction. A non-NULL menustrip can be incomplete if allocation
of an individual menu or item failed.

Notes

Dispose of an independently owned result with MUI_DisposeObject(),
or transfer ownership to an appropriate parent. The parameter array
itself is not retained; pointed-to data follows the constructed
class's ownership rules. In particular, menu titles and shortcuts
and Numericbutton format strings are borrowed, not copied here.
MUI_MakeObject() is the variadic positional-argument wrapper.

Bugs

MUIO_Menuitem_CopyStrings is declared but not implemented.
With MUIO_MenustripNM_CommandKeyCheck, a label whose second byte
is NUL is advanced by two bytes and that advanced pointer is used
for both title and shortcut. This does not implement the apparent
intent of separate shortcut and display strings.
Long ImageButton paths are silently truncated in the image
specification, although the original path was used for the lock.

See also

MUI_NewObjectA() MUI_DisposeObject()

Synopsis

Object * MUI_NewObjectA(
         ClassID classid,
         struct TagItem * tags );

Object * MUI_NewObject(
         ClassID classid,
         TAG tag, ... );

Function

Create an instance of the named MUI class with the supplied attributes.
The class is looked up through MUI_GetClass(), then instantiated
through intuition.library/NewObjectA().

Inputs

classid - NUL-terminated class identifier. Built-in class names are
          case-sensitive. Use the MUIC_* identifiers where available.
tags - Attribute/value pairs terminated by TAG_DONE, or NULL for
       the class defaults. Attribute types and ownership are defined
       by the selected class.

Result

The new object, or NULL if the class lookup or construction fails.

Notes

MUI_NewObject() is the variadic tag-list wrapper.

Release an independently owned object with MUI_DisposeObject(). If
ownership is transferred to a parent, follow that parent's disposal
contract instead of disposing of the child twice.
This function does not establish a separate MUI error code.

See also

MUI_DisposeObject() MUI_GetClass() intuition.library/NewObjectA()

Synopsis

LONG MUI_ObtainPen(
         struct MUI_RenderInfo * mri,
         struct MUI_PenSpec * spec,
         ULONG flags );

Function

Resolve a MUI pen specification against the rendering context.
MUI and system pens refer to existing pens. A colormap specification
selects an existing entry; negative indices count from the end of
the colormap. An RGB specification uses ObtainBestPenA(), falling
back to FindColor() when allocation fails.

Inputs

mri - Initialized rendering context with a colormap and the draw
      information required by the selected specification.
spec - NUL-terminated pen specification in a MUI_PenSpec structure.
       Supported prefixes are m (MUI pen), p (colormap index),
       s (system pen), and r (three hexadecimal RGB components).
       RGB components are separated by commas; r may be omitted.
flags - Ignored by this implementation; pass zero.

Result

A pen token, or -1 if mri, spec, or the colormap is NULL, parsing
fails, or a checked pen index is out of range. Use MUIPEN(token)
to obtain the drawing pen number. Bit 16 records an allocated pen.

Notes

Pass the complete token, not its masked pen number, to
MUI_ReleasePen() with the same rendering context when finished.
Keep that context and its colormap alive until the pen is released.

Bugs

System-pen indices are not range-checked. Supply a valid index into
the rendering context's DrawInfo pen array. The RGB parser does
not fully validate separators or the end of the specification.

See also

MUI_ReleasePen() graphics.library/ObtainBestPenA() graphics.library/FindColor()

Synopsis

VOID MUI_Redraw(
         Object * obj,
         ULONG flags );

Function

Redraw an Area-derived object immediately if it is drawable.
Account for enclosing virtual groups, update the rendering context's
clip rectangle, store the requested drawing flags, and dispatch
MUIM_Draw. Apply the disabled overlay when required and copy a
buffered result to the window when buffering is active.

Inputs

obj - Non-NULL Area-derived object. A drawable object must have a
      valid rendering context and drawing resources.
flags - Drawing flags, such as MADF_DRAWOBJECT or MADF_DRAWUPDATE.
        Only bits in MADF_DRAWFLAGS are retained.

Result

None. An object without MADF_CANDRAW is left unchanged.

Notes

This call dispatches drawing synchronously; it does not queue a
redraw or return the result of MUIM_Draw. Call in the owning GUI
task. Drawing may change RastPort state and the context's clip
rectangle. Do not assume that those values are preserved.

See also

MUI_Layout() MUI_AddClipRegion() MUI_RemoveClipRegion()

Synopsis

VOID MUI_RejectIDCMP(
         Object * obj,
         ULONG flags );

Function

Remove IDCMP event bits from an Area-derived object's legacy input
handler. If the object is set up and has a window, unregister the
handler before changing its mask, then register it again only if
event bits remain. Otherwise, update the stored mask.

Inputs

obj - Non-NULL Area-derived object.
flags - IDCMP event bits to remove. Other bits remain set.

Result

None.

Notes

This is the counterpart of MUI_RequestIDCMP(). It does not remove
separately registered event-handler nodes. Call in the object's
owning GUI task.

See also

MUI_RequestIDCMP()

Synopsis

VOID MUI_ReleasePen(
         struct MUI_RenderInfo * mri,
         LONG pen );

Function

Release the colormap allocation recorded in a MUI_ObtainPen() token.
Existing, unallocated pens require no release and are left alone.

Inputs

mri - Non-NULL rendering context used to obtain the token, with its
      original colormap still valid.
pen - Complete token returned by MUI_ObtainPen(), or -1 to do nothing.

Result

None.

Notes

Release each allocated token once. Do not mask the token with
MUIPEN() before passing it here: doing so removes the allocation
flag. A -1 token is ignored before mri is accessed.

See also

MUI_ObtainPen() graphics.library/ReleasePen()

Synopsis

VOID MUI_RemoveClipping(
         struct MUI_RenderInfo * mri,
         APTR handle );

Function

Remove a rectangular clip by forwarding the token to
MUI_RemoveClipRegion(). The region allocated for the clip is freed.

Inputs

mri - Rendering context used for the corresponding MUI_AddClipping().
handle - Exact token returned by MUI_AddClipping(), including NULL
         or the no-push sentinel (APTR)-1.

Result

None.

Notes

Remove nested clips in reverse order. A token other than (APTR)-1
pops the top MUI clipping region; it does not select a stack entry.
The rendering context must remain valid even for the sentinel.

See also

MUI_AddClipping() MUI_RemoveClipRegion()

Synopsis

VOID MUI_RemoveClipRegion(
         struct MUI_RenderInfo * mri,
         APTR handle );

Function

Pop and dispose of the most recently pushed MUI clipping region.
Install the preceding MUI region, or NULL when the stack becomes
empty. Refresh processing is suspended and resumed when necessary.

Inputs

mri - Valid rendering context used when the region was pushed.
handle - Token from the matching add call. (APTR)-1 does nothing;
         all other values, including NULL, request a stack pop.

Result

None.

Notes

Use strict reverse order and remove each successful push once.
Except for the sentinel, an unmatched call underflows the stack.
mri is accessed before the sentinel is checked and must not be NULL.
If the target layer is absent, no region is popped or freed.

Bugs

The token is not used to restore a previous independently installed
layer clip region. Preserve the MUI-owned stack discipline; do not
interleave independent InstallClipRegion() calls.

See also

MUI_AddClipRegion() MUI_AddClipping() MUI_RemoveClipping()

Synopsis

LONG MUI_RequestA(
         APTR app,
         APTR win,
         LONGBITS flags,
         CONST_STRPTR title,
         CONST_STRPTR gadgets,
         CONST_STRPTR format,
         APTR params );

LONG MUI_Request(
         APTR app,
         APTR win,
         LONGBITS flags,
         CONST_STRPTR title,
         CONST_STRPTR gadgets,
         CONST_STRPTR format,
         TAG tag, ... );

Function

Display a requester and wait for a response. With a MUI application,
create a temporary window and process the application's input until
a requester return ID is received. With app == NULL, delegate to
intuition.library/EasyRequestArgs() instead.

Inputs

app - MUI Application object, or NULL for the Intuition fallback.
win - MUI Window object used as the reference window, or NULL.
      Ignored by the Intuition fallback.
flags - Ignored by this implementation; pass zero.
title - Requester title. With a MUI application, NULL selects
        MUIA_Application_Title.
gadgets - Non-NULL NUL-terminated button labels separated by |.
          Supply at least one label and no more than 32 labels.
          On the MUI path, a leading * selects the active button;
          if several labels have it, the last one takes precedence.
format - Non-NULL RawDoFmt-compatible message format.
params - Array of IPTR-sized format arguments in AROS, in format
         order. Supply a valid array whenever arguments are used.
         This is neither a tag list nor an already packed RAWARG.

Result

On the MUI path, buttons except the last return their one-based
position; the last returns 0. A single button returns 1. Allocation
or window-opening failure also returns 0. On the fallback path,
return the result of EasyRequestArgs() unchanged.

Notes

This is a synchronous GUI call. Application methods and input
handlers may run before it returns; the application is not put to
sleep. The temporary requester is removed and disposed of before
returning. Keep input strings, formatting arguments, and referenced
objects valid for the duration of the call.
MUI_Request() supplies positional formatting arguments, not tags.

Bugs

The 32-button array has no bounds check. More labels can overwrite
memory. A button-construction failure can leave a partial requester.
On 32-bit AROS, one IPTR slot cannot preserve the full value of
an eight-byte formatting argument during the packing step.
Application return IDs are neither saved nor replayed. IDs from
1 through the number of constructed buttons plus 1 can terminate
the requester even if they came from another application action;
other return IDs are consumed without being returned to the caller.

See also

exec.library/RawDoFmt() intuition.library/EasyRequestArgs()

Synopsis

VOID MUI_RequestIDCMP(
         Object * obj,
         ULONG flags );

Function

Add IDCMP event bits to an Area-derived object's legacy input handler.
If the object is set up and has a window, remove the existing
handler, update its event mask, and register the resulting handler.
Otherwise, store the bits for subsequent setup.

Inputs

obj - Non-NULL Area-derived object.
flags - IDCMP event bits to add; existing bits are retained.

Result

None.

Notes

Matching events use the legacy MUIM_HandleInput delivery path.
Area setup registers the stored handler; cleanup removes it.
For new class implementations, prefer MUIM_Window_AddEventHandler
with MUIM_HandleEvent. Call in the object's owning GUI task.

See also

MUI_RejectIDCMP()

Synopsis

LONG MUI_SetError(
         LONG num );

Function

Return zero without storing an error value. This obsolete
compatibility entrypoint does not call dos.library/SetIoErr().

Inputs

num - Ignored.

Result

Always zero. This is not the previous error value.

Notes

Calling this function does not change the result of MUI_Error()
or the process's DOS error value.

See also

MUI_Error() dos.library/SetIoErr()