<--- Cannot embed stylesheet: [Errno 2] No such file or directory: '../../../../aros.css' --->

Group.mui

MUIA_Group_ActivePage

Function

Choose a zero-based content-page index when PageMode is enabled. Default
zero. First selects zero, Last selects count minus one, Prev wraps from
zero, and Next/Advance both advance with modulo wrap. The title group,
if any, is excluded from that count.

Inputs

LONG; initialize, set, get.

Notes

A changed live page hides the previous selection, stores the new index,
lays out and shows the new selection, then redraws content. Before
PageMode is enabled this operation does nothing; initialization tag
order matters. Configure PageMode and children before using relative
selectors. The getter returns the stored index.

Bugs

Explicit indices are not clamped. Next/Advance divide by the content
count and are invalid for an empty page group. Last on an empty group
produces -1. Removing children does not repair an out-of-range active
index. See PageMode for hidden-child counting differences.

MUIA_Group_Child

Function

Append a non-NULL Area-compatible child through OM_ADDMEMBER. The
internal Family owns attached children.

Inputs

Object pointer; initialize only; repeatable.

Notes

Runtime changes use AddHead/AddTail or OM_ADDMEMBER and Remove or
OM_REMMEMBER. Any explicit NULL Child tag makes construction fail after
tag processing and disposes attached children. Earlier superclass/Family
allocation failure can occur before child adoption. Do not dispose an
attached child separately.

Bugs

When the frame request is MUIV_Frame_Register, the first Child tag also
stores the internal titlegroup pointer, even without PageMode. Removing
or independently disposing this object does not clear that pointer.

MUIA_Group_ChildList

Function

Return the borrowed child list owned by the internal Family.

Inputs

Exec List pointer; get only.

Notes

Use NextObject for traversal. Do not edit links, free the list or retain
it beyond Group disposal. Membership must remain stable during traversal
and callbacks. This is not a copied snapshot.

MUIA_Group_Columns

Function

Request a grid columns count, converted to at least one, and clear the
other dimension to zero so min/max calculation derives it from the total
child count.

Inputs

LONG declaration, stored as ULONG; initialize and set.

Notes

The last Rows/Columns tag wins. On min/max calculation, a nondivisible
request falls back to one row containing all children. Dimensions are
derived from total membership, while most cell passes skip hidden and
border-gadget children. A runtime setter requests Window recalculation
when RenderInfo exists. There is no local getter.

Bugs

Negative or oversized values are not rejected before unsigned
conversion/allocation arithmetic. There is no partial-last-row layout
guarantee. Grid-array allocation failure returns from an internal helper
without a public failure result; later Layout can do nothing.

MUIA_Group_Forward

Function

Control whether this OM_SET forwards its filtered tag list to children.
Default TRUE for each call; the last Forward tag controls that call.
FALSE still applies group/superclass changes.

Inputs

BOOL; set only, per setter call.

Notes

The flag is not stored and has no local getter. Suppression applies to
this setter's ordinary child broadcast, not to explicit child effects of
page switching or other operations. The setter mutates the caller's
writable tags to TAG_IGNORE for filtered attributes and does not restore
them.
The filter removes HelpLine, HelpNode, ObjectID, UserData, ContextMenu,
ContextMenuTrigger, ControlChar, CycleChain, Draggable, FillArea,
Group_ActivePage, Frame, FrameTitle, HorizWeight, Pressed, ShortHelp,
ShowMe, VertWeight, Weight, Virtgroup_Left/Top, AppMessage and Timer.
Selected is not explicitly filtered, but Area may already suppress an
unchanged Selected tag. Unfiltered group tags such as spacing can also
reach child groups.
Disabled is delayed: child forwarding prepends a NestedDisabled
operation and also passes Disabled, then the superclass applies the
group's Disabled tag. Repeated TRUE calls can accumulate child nesting
even though Disabled itself is Boolean. Forward FALSE omits that child
propagation.

Bugs

Multiple Disabled tags are initially changed to TAG_IGNORE, but only the
last one is restored and applied as the group's delayed value. Child
setters can mutate the shared tag list, affecting later children. There
is no tag-list copy per child.

MUIA_Group_Horiz

Function

Select horizontal one-dimensional layout when true; default FALSE
selects vertical.

Inputs

BOOL; initialize; getter also implemented.

Notes

This orientation is used when rows and columns both equal one and
neither PageMode nor LayoutHook takes precedence. There is no setter.
The getter returns the GROUP_HORIZ bit value (2 when set), not
normalized TRUE (1). Test it as nonzero.

MUIA_Group_HorizSpacing

Function

Store the horizontal gap between children or grid cells. Before setup
the unspecified value is stored as ULONG -1; setup replaces it with the
corresponding application preference.

Inputs

LONG declaration, stored as ULONG; initialize, set, get.

Notes

Explicit initialization or setting marks the value as caller-specified
so setup no longer supplies that default. The getter returns the stored
value. A spacing setter alone does not request relayout; finish a
controlled change with ExitChange when live.

Bugs

No nonnegative/range validation is performed. Negative or very large
values can wrap in unsigned/WORD layout arithmetic. Do not interpret -1
as a documented runtime reset-to-default operation.

MUIA_Group_LayoutHook

Function

Borrow a custom layout hook used when PageMode is FALSE. NULL selects
built-in layout. Keep the Hook and callback code alive until replacement
or Group disposal.

Inputs

Hook pointer; initialize; setter also implemented.

Notes

CallHookPkt passes this Group as object and a temporary MUI_LayoutMsg as
message. lm_Children is the borrowed internal list; keep membership
stable. The hook return value is ignored for both message types;
returning MUILM_UNKNOWN does not request built-in fallback. There is no
local getter and replacing the hook does not itself relayout.
For MUILM_MINMAX, child limits have already been collected. Fill all six
lm_MinMax fields with content requirements excluding this group's
frame/spacing. This stack message is not initialized for you. Group
raises maxima and defaults below minima, caps aggregate maxima to
MUI_MAXMAX, then adds its Area contribution. It does not clamp a
too-large hook default back to the maximum.
For MUILM_LAYOUT, the message starts cleared; lm_Layout.Width/Height
contain available inner dimensions. Lay out children with MUI_Layout
using coordinates relative to the group inner origin. For virtual
groups, write the resulting virtual content Width/Height back to those
same fields. The private fields have no public contract. Do not retain
the message or list as owned storage.

Bugs

A hook that omits a min/max field leaves an uninitialized value in use.
Hook failure is not propagated; Group AskMinMax and Layout return zero
regardless. Group itself does not enforce the custom layout's child size
constraints.

MUIA_Group_PageMode

Function

Enable page-group layout, default FALSE. One content child is shown at a
time; all pages contribute size constraints and are laid out.

Inputs

BOOL; initialize only.

Notes

PageMode takes precedence over LayoutHook, Rows/Columns and Horiz. With
MUIV_Frame_Register, the first Child tag is treated as a title group and
excluded from content-page counting. Its minimum height is reserved
above the content; page changes set its Group_ActivePage. Group does not
create tab objects or install title-selection notifications itself.

Bugs

Show/Hide count all children except the title group, while Draw skips
ShowMe-FALSE children before incrementing the page count. Hidden pages
can therefore make these paths select different indices. There is no
PageMode setter or local getter.

MUIA_Group_Rows

Function

Request a grid rows count, converted to at least one, and clear the
other dimension to zero so min/max calculation derives it from the total
child count.

Inputs

LONG declaration, stored as ULONG; initialize and set.

Notes

The last Rows/Columns tag wins. On min/max calculation, a nondivisible
request falls back to one column containing all children. Dimensions are
derived from total membership, while most cell passes skip hidden and
border-gadget children. A runtime setter requests Window recalculation
when RenderInfo exists. There is no local getter.

Bugs

Negative or oversized values are not rejected before unsigned
conversion/allocation arithmetic. There is no partial-last-row layout
guarantee. Grid-array allocation failure returns from an internal helper
without a public failure result; later Layout can do nothing.

MUIA_Group_SameHeight

Function

Enable same-height constraints in built-in min/max/layout calculations.
Default FALSE.

Inputs

BOOL; initialize only.

Notes

The algorithms use the largest participating minimum and each child's
own limits; this is not an unconditional guarantee of identical final
dimensions. PageMode and custom hooks have their own behavior. There is
no runtime setter or local getter. SameSize sets or clears both flags;
later specific initialization tags can override one.

MUIA_Group_SameSize

Function

Enable both same-width and same-height constraints in built-in
min/max/layout calculations. Default FALSE.

Inputs

BOOL; initialize only.

Notes

The algorithms use the largest participating minimum and each child's
own limits; this is not an unconditional guarantee of identical final
dimensions. PageMode and custom hooks have their own behavior. There is
no runtime setter or local getter. SameSize sets or clears both flags;
later specific initialization tags can override one.

MUIA_Group_SameWidth

Function

Enable same-width constraints in built-in min/max/layout calculations.
Default FALSE.

Inputs

BOOL; initialize only.

Notes

The algorithms use the largest participating minimum and each child's
own limits; this is not an unconditional guarantee of identical final
dimensions. PageMode and custom hooks have their own behavior. There is
no runtime setter or local getter. SameSize sets or clears both flags;
later specific initialization tags can override one.

MUIA_Group_Spacing

Function

Set both horizontal and vertical gaps and mark both as explicit.

Inputs

LONG declaration, stored as ULONG; initialize and set.

Notes

Tag order determines the result when combined with the axis-specific
tags. There is no local combined getter or automatic relayout. Use axis
getters to inspect the stored values; spacing has the same unchecked
conversion limitations as those attributes.

MUIA_Group_VertSpacing

Function

Store the vertical gap between children or grid cells. Before setup the
unspecified value is stored as ULONG -1; setup replaces it with the
corresponding application preference.

Inputs

LONG declaration, stored as ULONG; initialize, set, get.

Notes

Explicit initialization or setting marks the value as caller-specified
so setup no longer supplies that default. The getter returns the stored
value. A spacing setter alone does not request relayout; finish a
controlled change with ExitChange when live.

Bugs

No nonnegative/range validation is performed. Negative or very large
values can wrap in unsigned/WORD layout arithmetic. Do not interpret -1
as a documented runtime reset-to-default operation.

MUIA_Group_Virtual

Function

Enable virtual-content layout, clipping and edge autoscroll; default
FALSE. The constructor marks the object as a virtual group and
connection marks descendants as inside a virtual group.

Inputs

BOOL; initialize only.

Notes

AskMinMax saves full content minima but exposes a viewport minimum of
Area's contribution plus two pixels per dimension. Layout computes
virtual extents and clamps offsets. Group implements Virtgroup_Left/Top
setters and getters plus Width/Height/MinWidth/MinHeight getters for
this machinery. It does not create scrollbar objects.
A click inside registers tick events; moving outside while tracking
scrolls four pixels per tick, clamped to extents. A later non-SELECTDOWN
button event stops tick tracking. There is no runtime Virtual setter or
local getter.

Bugs

Virtual offset setters can force Layout even without a live display;
callers must establish appropriate setup/layout state. Do not apply
virtual offsets to nonvirtual groups: the drawing cleanup path assumes
its scroll clip belongs to a virtual group.

MUIC_Group

Superclass

Area.mui

Description

Own an ordered set of Area-compatible children through an internal
Family. Arrange them horizontally, vertically, in a grid, as pages or
through a layout hook. Default orientation is vertical, with both stored
row and column counts initially one. Layout requires the connected
application's preferences and valid child min/max information.
Group owns the internal Family, its attached children and private grid
arrays. It borrows the layout Hook. Construction returns NULL on
superclass/Family creation failure or any explicit NULL Group_Child tag.
Disposal frees grid arrays and disposes the Family and remaining
children, then Area. Hide and Cleanup must already have ended active
display resources and handlers.
Only attach live compatible objects that are not already owned or linked
elsewhere. Adding adopts a child; removing unlinks without disposing it.
Serialize membership, layout and callbacks in the application task. The
implementation does not protect traversal against children destroying
themselves or changing the list.

Methods

Setup calls Area then sets up every child, including children with
ShowMe FALSE. On child failure it cleans only the previously successful
children and returns FALSE; it does not clean the failing child or the
successful Area setup itself. Cleanup calls every child then Area.
Show/Hide select the active page or eligible visible children; child
results are ignored. Draw returns FALSE while InitChange is active.
AskMinMax asks visible children and finalizes their sizes, then uses
page layout, a custom hook or built-in layout in that priority order. It
returns zero regardless of results. Layout uses the same priority and
also returns zero, even after a hook failure or incomplete built-in
layout. The library MUI_Layout sets a child's box and returns TRUE
without propagating the child's Layout result.
FindUData/GetUData match Group first, then delegate through its internal
Family, whose own default UserData can also match. GetUData reports a
match without checking getter success. SetUData may set Group, whose
setter can already broadcast, and then visits the Family, so assignments
can repeat; SetUDataOnce stops at the first match. Export/Import visit
children only and return zero; they do not call Area's own
Selected-state serialization.
OM_GET tries Group, then Area/Notify, then children until one getter
succeeds. Unknown methods normally go to every child before Area; child
results are discarded. Explicit lifecycle/utility/drag cases have
different routes. DoMethodNoForward controls only the paths that inspect
its forwarding flag, not every explicit child traversal.

Notes

MUIM_Notify first probes the group's trigger getter with child-get
forwarding disabled. If recognized locally, it registers through the
superclass. Otherwise it probes each child and registers on those
reporting support. This is a Group override of Notify, so an event-only
attribute without a getter is not automatically registered locally.
Probe storage is a fixed 30-IPTR stack array; getters must not write
beyond it. Return TRUE on the child path does not prove that any
registration succeeded.
Version and Revision getters both return 1. Family_GetChild is delegated
to the internal Family. Group also implements virtual offset/extent
attributes used by Virtgroup. The locally defined Group_Insert and
Group_ChildCount are internal source interfaces; the header's
ExitChange2 is explicitly private.

Bugs

Add/remove helpers ignore child and Family results and adjust a stored
count without validating membership. Setup has incomplete failure
unwinding. Page indices and grid dimensions are not generally
range-checked. Several layout intermediates are WORD values, and
allocation/arithmetic failures have no comprehensive status. Treat
documented results as implementation results, not stronger success
guarantees.

MUIM_Group_AddHead

Synopsis

IPTR result = DoMethod(obj, MUIM_Group_AddHead, (IPTR)child);

Function

Insert a child at the beginning of the internal Family and increase the
stored count. Set its parent to this Group, connect it when application
information exists, and set it up immediately when the Group is set up.

Inputs

child - Non-NULL live Area-compatible object, not already owned or
linked elsewhere. Ownership transfers through attachment.

Result

Always TRUE; Family, child connection and child Setup results are
ignored.

Notes

For live structural changes, bracket the operations with
InitChange/ExitChange. Addition alone does not show or lay out the
child. If the group is disabled, the added child receives a no-notify
NestedDisabled increment and Disabled=TRUE. OM_ADDMEMBER uses the
AddTail path.

Bugs

No NULL/membership validation is provided by the Group helper; it
dereferences child even if Family rejects the insertion. A reported TRUE
does not establish successful setup. Subsequent removal does not undo
inherited disabled state.

MUIM_Group_AddTail

Synopsis

IPTR result = DoMethod(obj, MUIM_Group_AddTail, (IPTR)child);

Function

Insert a child at the end of the internal Family and increase the stored
count. Set its parent to this Group, connect it when application
information exists, and set it up immediately when the Group is set up.

Inputs

child - Non-NULL live Area-compatible object, not already owned or
linked elsewhere. Ownership transfers through attachment.

Result

Always TRUE; Family, child connection and child Setup results are
ignored.

Notes

For live structural changes, bracket the operations with
InitChange/ExitChange. Addition alone does not show or lay out the
child. If the group is disabled, the added child receives a no-notify
NestedDisabled increment and Disabled=TRUE. OM_ADDMEMBER uses the
AddTail path.

Bugs

No NULL/membership validation is provided by the Group helper; it
dereferences child even if Family rejects the insertion. A reported TRUE
does not establish successful setup. Subsequent removal does not undo
inherited disabled state.

MUIM_Group_DoMethodNoForward

Synopsis

IPTR result = DoMethod(obj, MUIM_Group_DoMethodNoForward, methodid,
...);

Function

Set the private no-forward flag, dispatch the embedded method on this
object and clear the flag before returning.

Inputs

methodid - ULONG MethodID beginning the embedded message.
... - Its correctly laid-out argument fields. Keep the Group alive
through the call.

Result

The embedded method's result.

Notes

This suppresses Group_DispatchMsg broadcasts and OM_GET fallback to
children. It does not suppress explicit loops in Setup/Cleanup,
Import/Export, user-data searches or the Group Notify override. It is
therefore not a universal self-only execution mechanism.

Bugs

The flag is set to one and later reset to zero rather than
saved/restored. Nested use can clear an outer suppression early. The
implementation passes the address of the declared ULONG DoMethodID field
as a message; use the ABI-defined structure layout for direct messages,
not an invented IPTR-array layout on every target.

MUIM_Group_ExitChange

Synopsis

IPTR result = DoMethod(obj, MUIM_Group_ExitChange);

Function

Clear changing/changed flags and request Window recalculation when set
up, unless an ancestor group is still changing.

Inputs

No arguments beyond MethodID. Requires a valid connected Group ancestor
chain for live recalculation.

Result

Always TRUE, including when recalculation is skipped or its result
ignored.

Notes

Recalculation is attempted even without a recorded structural change;
the changed-only guard is disabled. An outer group's later exit is
responsible for updating a nested change. This is not a commit-success
report or a restoration of failed operations.

MUIM_Group_InitChange

Synopsis

IPTR result = DoMethod(obj, MUIM_Group_InitChange);

Function

Clear the changed marker and set the changing flag. Drawing returns
FALSE while that flag is set.

Inputs

No arguments beyond MethodID. Keep the group and application alive
throughout the change sequence.

Result

Always TRUE.

Notes

Pair with ExitChange around live add/remove or layout changes. This
begins neither a lock nor a rollback transaction. It does not hide
children or defer their connection/setup/cleanup.

Bugs

There is one flag, not a nesting counter. Calling InitChange twice on
the same object does not require two exits and clears the prior changed
marker.

MUIM_Group_Remove

Synopsis

IPTR result = DoMethod(obj, MUIM_Group_Remove, (IPTR)child);

Function

Hide the child when the Group is drawable, clean it when the Group is
set up, disconnect it, decrement the stored count and remove it through
Family.

Inputs

child - Non-NULL live child currently attached to this Group.

Result

Always TRUE; child and Family results are ignored.

Notes

The child is not disposed; the caller resumes responsibility for its
lifetime. OM_REMMEMBER uses this path. Use InitChange/ExitChange for
live removal. Family removal also disconnects the child, so the
connected path can send DisconnectParent twice. The final Family removal
clears the parent pointer.

Bugs

No membership/count validation occurs. Passing an unrelated child can
corrupt ownership/counts. The titlegroup pointer and active page are not
repaired. Removal leaves any disabled state previously imposed on the
child intact.

MUIM_Group_Sort

Synopsis

IPTR result = DoMethod(obj, MUIM_Group_Sort, (IPTR)first, ... ,
(IPTR)NULL);

Function

Replace the internal Family child order with the supplied
NULL-terminated sequence. The method temporarily changes MethodID to
Family_Sort, invokes Family, then restores Group_Sort.

Inputs

first, ... - Every currently attached child exactly once in the desired
order, followed by NULL. A retained method message must be writable.

Result

Always TRUE; Family result is ignored.

Notes

This is explicit ordering, not a comparison callback sort. It does not
update the stored child count, reconnect children, change active
page/titlegroup, mark a change or relayout. Use InitChange/ExitChange
for a live reorder.

Bugs

The implementation resets the list without validating completeness,
uniqueness or membership. Omitting a child detaches its list node
without cleanup/disposal/count repair; duplicates or foreign objects can
corrupt the list.