Family.mui

MUIA_Family_Child

Function

Initialize the family with a child object. Repeat the tag to append
multiple children in tag order. MUIA_Group_Child is accepted as an alias
by this constructor.

Inputs

Object pointer; initialize only. Each child must be live, unattached,

and suitable for Family membership.

Notes

Successful attachment makes the family responsible for disposing of the
child. A NULL child tag makes construction fail after processing all
tags and disposing of children attached to the new family. If superclass
construction fails before attachment, the supplied children have not
been adopted. There is no Family setter or getter for this tag.

MUIA_Family_ChildCount

Function

Count the current immediate children by walking the list and return the

count through the attribute getter.

Inputs

LONG in the public header; get only. The implementation accumulates the

result in the IPTR storage supplied to OM_GET.

Notes

An empty family returns zero. Descendants below immediate children are
not counted. This is a traversal, not a cached count, and has no
synchronization against concurrent changes.

MUIA_Family_List

Function

Return a borrowed pointer to the internal child list.

Inputs

Pointer to struct MinList; get only. The implementation stores an Exec

struct List and returns its address.

Notes

The pointer is valid only while the family lives. Use NextObject to
traverse its BOOPSI children. Do not free the list or alter its links
directly; use Family methods so parent fields and ownership remain
consistent. Traversal must not overlap mutation or disposal.

MUIC_Family

Superclass

Notify.mui

Description

Maintain an ordered list of owned child objects. Construction starts
with an empty list and appends each non-NULL MUIA_Family_Child or
MUIA_Group_Child tag in order. If any child tag is NULL, construction
disposes of the family and all children successfully attached to it,
then returns NULL. If superclass construction fails, Family has not yet
attached the supplied children.
Disposal disposes of every child still in the list, then the Notify
superclass. Remove a child before disposing of it separately. Removing a
child transfers responsibility for its lifetime back to the caller. The
list and its operations are not locked; serialize traversal, mutation,
and disposal.
Family does not automatically forward ConnectParent or DisconnectParent
to children. AddHead, AddTail, and Insert call the child's ConnectParent
only if the family already has global info, and set its parent field
even without an application connection.

Methods

The inherited user-data methods are extended as follows. FindUData
compares the family first, then sends the same message to children in
list order, returning the first nonzero object result or zero. Deeper
traversal depends on each child's implementation.
GetUData gets the attribute from the family if its UserData matches;
otherwise it returns TRUE on the first child returning nonzero. TRUE
indicates a match, not a successful attribute getter. Its udata message
field is ULONG. No match leaves caller storage untouched.
SetUData sets the family on a match, sends the method to every child,
and returns TRUE even if no object matches. Setter and child return
values are ignored.
SetUDataOnce sets the family on a match and returns TRUE, otherwise
visits children until one returns nonzero. It returns FALSE when none
match. FindUData, SetUData, and SetUDataOnce use IPTR comparison values.
Do not mutate or dispose of traversed children from callbacks during
these walks.
OM_ADDMEMBER uses AddTail; OM_REMMEMBER uses Remove. Version and
Revision both return 1 for Family. Other methods, including the Notify
persistence stubs, are inherited unless a subclass overrides them.

Example

Each supplied child must be a live, unattached object:

family = MUI_NewObject(MUIC_Family,

MUIA_Family_Child, (IPTR)child,

TAG_DONE);

After success, disposing family also disposes child.

MUIM_Family_AddHead

Synopsis

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

Function

Attach child as the first child of the family.

Inputs

child - Live, unattached MUI object, or NULL.

Result

FALSE for NULL; otherwise TRUE. Child method results are not used as an

error indication.

Notes

The family takes responsibility for child disposal. Its parent field is
set to the family. If the family has global info, the child receives
ConnectParent. AddTail uses the child's OM_ADDTAIL method; AddHead links
its BOOPSI node directly.

Bugs

Membership is not checked. Do not add an object already linked to this
or another list, and do not add the family itself or create ownership
cycles.

MUIM_Family_AddTail

Synopsis

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

Function

Attach child as the last child of the family.

Inputs

child - Live, unattached MUI object, or NULL.

Result

FALSE for NULL; otherwise TRUE. Child method results are not used as an

error indication.

Notes

The family takes responsibility for child disposal. Its parent field is
set to the family. If the family has global info, the child receives
ConnectParent. AddTail uses the child's OM_ADDTAIL method; AddHead links
its BOOPSI node directly.

Bugs

Membership is not checked. Do not add an object already linked to this
or another list, and do not add the family itself or create ownership
cycles.

MUIM_Family_GetChild

Synopsis

IPTR result = DoMethod(obj, MUIM_Family_GetChild, nr, (IPTR)ref);

Function

Return a borrowed immediate-child pointer selected by position or by a

reference child.

Inputs

nr - Nonnegative zero-based index, MUIV_Family_GetChild_First (0), Last
(-1), Next (-2), or Previous (-3).
ref - Existing immediate child for Next or Previous. Ignored for an
index, First, or Last; pass NULL in those cases.

Result

The selected object pointer, or NULL for an empty list, out-of-range
index, absent reference, missing neighbor, or unsupported negative
selector.

Notes

No ownership is transferred. Keep the family and child alive and prevent
mutation while using the result. Descendants below immediate children
are not searched.

MUIM_Family_Insert

Synopsis

IPTR result = DoMethod(obj, MUIM_Family_Insert, (IPTR)child,
(IPTR)pred);

Function

Attach child immediately after pred in the family list.

Inputs

child - Live, unattached MUI object, or NULL.

pred - Non-NULL immediate child already in this family.

Result

FALSE for a NULL child; otherwise TRUE.

Notes

The family adopts the child, sets its parent field, and sends
ConnectParent if global info is available. Neither predecessor
membership nor existing child membership is checked. Use AddHead to
insert at the beginning.

Bugs

The implementation applies _OBJECT to pred before calling Exec Insert.
Passing NULL as pred is not a supported way to request head insertion in
this implementation.

MUIM_Family_Remove

Synopsis

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

Function

Send DisconnectParent, clear the child's stored parent, then send

OM_REMOVE to unlink it.

Inputs

child - Immediate child currently belonging to this family, or NULL.

Result

FALSE for NULL; otherwise TRUE, regardless of child method results.

Notes

The child is not disposed of. After successful removal, the caller must
dispose of it or transfer it to another owner. A Notify child retains
its global-info pointer because Notify's DisconnectParent is a no-op.

Bugs

The family does not verify membership. Passing an unrelated object can

unlink it from another list or operate on invalid node links.

MUIM_Family_Sort

Synopsis

IPTR result = DoMethod(obj, MUIM_Family_Sort, (IPTR)child1, ...,
(IPTR)NULL);

Function

Reset the child-list header and relink objects in the supplied order. No

comparator is called.

Inputs

child1, ... - Every current immediate child exactly once, in the desired

order, followed by NULL. For an empty family, pass only NULL.

Result

Always TRUE after relinking.

Notes

Ownership, parent fields, and global-info pointers are not changed. The

sequence is read directly from the method message and is not copied.

Bugs

The implementation does not check completeness, duplicates, membership,
or termination. Omitted children are not disposed of or disconnected but
disappear from the family list. Duplicates or foreign objects can
corrupt list ownership. Use this only to reorder the complete current
membership.

MUIM_Family_Transfer

Synopsis

IPTR result = DoMethod(obj, MUIM_Family_Transfer, (IPTR)family);

Function

Remove each current child from the source and append it to the

destination in source order.

Inputs

family - Different, live Family-compatible destination object that
accepts every child. It must not be a source descendant that would
create an ownership cycle.

Result

Always TRUE after the traversal. Remove and AddTail results are ignored.

Notes

Existing destination children remain before transferred children. The
destination becomes responsible for disposal; parent and connection
changes follow Remove and AddTail. No rollback or destination validation
is performed. Keep both containers and all children alive and avoid
callback-driven membership changes.

Bugs

The source and destination must differ. There is no self-transfer guard,

and a failed destination attachment is not reported or rolled back.