MUI_AddClipping()
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.
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().
MUI_AddClipRegion()
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.
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.
MUI_AllocAslRequest()
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.
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.
MUI_AslRequest()
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.
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.
MUI_BeginRefresh()
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().
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.
MUI_CreateCustomClass()
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.
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.
MUI_DeleteCustomClass()
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.
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.
MUI_DisposeObject()
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.
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.
MUI_EndRefresh()
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.
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.
MUI_Error()
Synopsis
LONG MUI_Error();
Function
Return zero. This obsolete compatibility entrypoint does not read
an error variable or call dos.library/IoErr().
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.
MUI_FreeAslRequest()
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.
Notes
Call after requester execution has finished. Do not use the requester
or its owned result storage after this call.
MUI_FreeClass()
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.
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.
MUI_GetClass()
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().
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.
MUI_Layout()
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.
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.
MUI_MakeObjectA()
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.
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.
MUI_NewObjectA()
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().
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.
MUI_ObtainPen()
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.
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.
MUI_Redraw()
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. The overlay
of a disabled group covers its children; a child that is redrawn on
its own gets the overlay itself. The overlay is blended on a true
colour screen, so an object that gets it is drawn as a whole: its
MADF_DRAWUPDATE is drawn as MADF_DRAWOBJECT.
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.
MUI_RejectIDCMP()
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.
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.
MUI_ReleasePen()
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.
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.
MUI_RemoveClipping()
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.
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.
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.
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.
MUI_RequestA()
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.
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.
MUI_RequestIDCMP()
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.
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.
MUI_SetError()
Synopsis
LONG MUI_SetError(
LONG num );
Function
Return zero without storing an error value. This obsolete
compatibility entrypoint does not call dos.library/SetIoErr().
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.