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

List.mui

MUIA_List_Active

Function

Read or change the active entry index.

Inputs

Initialize, set, get; LONG. Default MUIV_List_Active_Off (-1).

Notes

Accepts an index or Off, Top, Bottom, Up, Down, PageUp or PageDown.
Relative movement clamps to the entry range; construction only
resolves Top/Bottom and clamps explicit values. Active does not change
selection. After setup it calls Jump even when AutoVisible is off.
Notifications can carry the supplied selector rather than the resolved
index; get the value again after setting. Read-only Listview hides the
cursor, not this setter.

MUIA_List_AdjustHeight

Function

Constrain the list height from its contents during size negotiation.

Inputs

Initialize only; BOOL, default FALSE.

Notes

For nonempty lists minimum, default and maximum height use measured
entry heights plus the title; empty lists retain 36/96/unlimited.
Drawing uses one maximum row height, so all rows need not fit. No
local setter/getter or automatic parent relayout is provided.

MUIA_List_AdjustWidth

Function

Constrain the list width from its contents during size negotiation.

Inputs

Initialize only; BOOL, default FALSE.

Notes

For nonempty lists the minimum, default and maximum width use the sum
of measured column widths, gaps and bars. Empty lists retain
40/100/unlimited. There is no local setter/getter or automatic parent
relayout on entry changes.

MUIA_List_AutoVisible

Function

Enable the active-entry adjustment performed during layout.

Inputs

Initialize, set, get; BOOL, default FALSE.

Notes

Layout scrolls when Active crosses the lower visible boundary, but
does not symmetrically handle an Active above First. Changing Active
after setup calls Jump regardless of this flag; setting it does not
scroll immediately. Get returns a flag mask, not normalized TRUE.

MUIA_List_CompareHook

Function

Supply the comparator used by Compare and Sort.

Inputs

Initialize, set; borrowed Hook pointer. NULL selects the builtin
comparator; no local getter.

Notes

CallHookPkt receives entry2 as object and entry1 as message. Return a
negative, zero or positive LONG for the entry1/entry2 order. Default
is case-insensitive Stricmp on terminated strings. Changing the hook
does not sort; keep hook and data live during synchronous comparison.

MUIA_List_ConstructHook

Function

Choose how incoming entry pointers become stored entries.

Inputs

Initialize, set; borrowed Hook pointer, NULL, or
MUIV_List_ConstructHook_String. Default NULL; no local getter.

Notes

NULL stores the input pointer unchanged. The String selector copies
text into the pool (NULL becomes empty). Custom hooks receive pool as
object and entry as message; zero means failure. Match owned data to a
Destruct hook before insertion. Changing hooks does not reconstruct
old entries.

MUIA_List_DestructHook

Function

Choose how stored entry data is released.

Inputs

Initialize, set; borrowed Hook pointer, NULL, or
MUIV_List_DestructHook_String. Default NULL; no local getter.

Notes

NULL does not free entry data. String frees only allocations from the
matching String constructor. Custom hooks receive pool and stored
entry; return values are ignored. Changing policy while entries exist
may free them incorrectly.

MUIA_List_DisplayHook

Function

Provide display strings for the columns of an entry or title.

Inputs

Initialize, set; borrowed Hook pointer or NULL. Default NULL; no local
getter.

Notes

The hook receives the string-pointer array as object and entry as
message; NULL entry denotes a title. Set all displayed columns to live
strings or NULL. The slot preceding the array carries entry metadata,
with ABI limits noted in MUIM_List_Display. Without a hook only column
zero is assigned. Changing the hook does not remeasure; request
Redraw_All.

MUIA_List_DragSortable

Function

Accept a drag from this List and move its active entry on drop.

Inputs

Initialize, set, get; BOOL, default FALSE.

Notes

DragQuery accepts this List as source only when enabled. DragDrop
moves the active entry and sets Active, not a group of selected
entries. This flag does not set Draggable or the Listview drag type.
Get returns a mask.

MUIA_List_DropMark

Function

Read the insertion boundary recorded by the last DragDrop call.

Inputs

Get; LONG, initially zero.

Notes

DragDrop stores the insertion boundary before moving the active entry;
Entries means after the last item. Hover drawing does not update this
attribute, and its value does not prove Move succeeded.

MUIA_List_Entries

Function

Read the current number of entries.

Inputs

Get; LONG, initially zero.

Notes

Mutators update the confirmed entry count and may notify through the
superclass. Applications must use the entry methods, not set the
count. Insertion failure can leave it inconsistent; see
MUIM_List_Insert.

MUIA_List_First

Function

Read or set the first displayed entry index.

Inputs

Get and implemented Set despite the get-only header annotation; LONG,
initially zero. No constructor parsing.

Notes

Set stores the index without validation, requests redraw and updates
the scrollbar unless Quiet. Prefer Jump after layout. Cleanup does not
reset First to -1; it does not indicate that a window is open. Set may
notify.

MUIA_List_Format

Function

Describe columns using comma-separated ReadArgs option strings.

Inputs

Initialize, set, get; borrowed terminated STRPTR or NULL. Default NULL
gives one default column.

Notes

Comma-separated columns accept DELTA=D/N, PREPARSE=P/K, WEIGHT=W/N,
MINWIDTH=MIW/N, MAXWIDTH=MAW/N, COL=C/N and BAR/S. Only DELTA,
PREPARSE, BAR and measured text widths affect layout in this
implementation; WEIGHT, MINWIDTH, MAXWIDTH and COL are stored but not
applied. BAR adds 2 pixels; PREPARSE is copied, while the Format
string remains borrowed.

Set reparses and redraws without reporting allocation failure. Prior
format storage is released first; partial growth is not rolled back.
Column growth can leave a title record undersized when a title is
enabled later. Keep the supplied Format string alive.

MUIA_List_InsertPosition

Function

Read the starting slot chosen by the latest insertion attempt.

Inputs

Get; LONG, initially zero.

Notes

Insert sets this before allocation, so failure can change it. With
sorted insertion it records the original append slot, not final sorted
positions; the method return is a different value.

MUIA_List_MinLineHeight

Function

Set the minimum measured entry height.

Inputs

Initialize only; ULONG storage despite LONG header annotation. Default
zero.

Notes

Measurement applies this to entries and title; all rows then use the
maximum height. There is no local validation or Set/Get: negative
signed values become large unsigned heights.

MUIA_List_MultiTestHook

Function

Decide whether an entry can share a selection with other entries.

Inputs

Initialize, set; borrowed Hook pointer or NULL. Default NULL permits
multiselection. No local getter.

Notes

The hook receives NULL as object and the entry as message. Zero
forbids multi-selection with that entry, but not selecting it alone.
Setting a non-NULL hook clears selection, even if unchanged; Ask does
not call it. Keep the hook valid and do not mutate List during the
call.

MUIA_List_Pool

Function

Supply the pool used for entry records, copied strings and image
handles.

Inputs

Initialize only; valid Exec pool pointer or NULL. Default NULL creates
an internal pool.

Notes

External pools are borrowed and must outlive List and its handles;
List deletes only its own pool. Pool size tags affect only pool
creation. The title record is not explicitly freed on disposal in
external pools.

MUIA_List_PoolPuddleSize

Function

Set a size passed to CreatePool when List creates its own pool.

Inputs

Initialize only; ULONG tag stored in LONG. Default 2008 bytes.

Notes

Use values valid for Exec CreatePool and representable by the stored
size. The class does not validate the size pair. Ignored for pool
creation when Pool supplies an external pool. No local setter or getter
exists; this does not resize a live pool.

MUIA_List_PoolThreshSize

Function

Set a size passed to CreatePool when List creates its own pool.

Inputs

Initialize only; ULONG tag stored in LONG. Default 1024 bytes.

Notes

Use values valid for Exec CreatePool and representable by the stored
size. The class does not validate the size pair. Ignored for pool
creation when Pool supplies an external pool. No local setter or getter
exists; this does not resize a live pool.

MUIA_List_Quiet

Function

Defer List rendering and selected scrollbar updates during a batch.

Inputs

Set only; BOOL, initially FALSE. No local constructor parsing or getter.

Notes

Quiet defers drawing and some scrollbar updates, but is not a nesting
counter and does not suppress all notifications or callbacks. Updates
may be lost in paths that do not record pending work; restore FALSE
and request Redraw_All if necessary.

MUIA_List_ShowDropMarks

Function

Draw a provisional insertion line during drag reporting.

Inputs

Initialize, set, get; BOOL, default TRUE.

Notes

Only affects rendering in DragReport, not whether a drag is accepted or
entries move. Get returns a flag mask when enabled. The drawing position
is tracked separately from DropMark. DragFinish resets the internal y
position and delegates; it does not explicitly erase the line itself.

MUIA_List_SourceArray

Function

Insert an initial NULL-terminated array of entry pointers.

Inputs

Initialize only; readable APTR array or NULL. Default NULL.

Notes

The constructor consumes the NULL-terminated pointer array
synchronously and inserts according to ConstructHook. It does not
retain the array. Partial insertion failure is possible; see
MUIM_List_Insert.

MUIA_List_Title

Function

Show a direct title or request column titles from the display callback.

Inputs

Initialize, set, get; borrowed STRPTR, NULL for no title, or pointer
value 1 for callback titles. Default NULL.

Notes

A one-column title other than pointer value 1 is displayed directly.
With multiple columns, or value 1, Display is called with NULL entry and
entry_pos -1; provide all title strings. The string is not copied or
freed. Set requests Redraw_All. Title is not included in Entries and
cannot be retrieved as an ordinary entry index; it has a separate
internal record.

MUIA_List_Visible

Function

Read the number of complete rows calculated for the drawing area.

Inputs

Get; LONG, initially -1.

Notes

Layout/drawing divide available height after title space by the maximum
row height. The result is capacity, not the number of existing entries,
and can exceed Entries. It can be zero for a small area. AROS emits
Visible and private scrollbar notifications when recalculated. Cleanup
does not reset it to -1. Internal setters synchronize scrollbar state;
applications should not set it to fabricate layout.

MUIC_List

Superclass

Group.mui

Description

Display indexed entries in columns and manage the active cursor and
selection. List is a Group containing a drawing area and optional
vertical scrollbar; its Listview_List getter returns the List itself.

Entries are opaque pointers. By default List retains them without
copying or freeing them, but displays and compares them as terminated
strings. To own copied strings, pair MUIV_List_ConstructHook_String
with MUIV_List_DestructHook_String. Custom data needs compatible
display and comparison hooks.

List owns its entry records and internal pool, but borrows external
pools, hooks, format strings, titles and entry data. Keep borrowed
objects valid while in use; do not mutate or dispose the List during
its synchronous hooks.

Notes

Active and selected are independent. Move and Exchange preserve the
active index; Sort follows the active entry. Direct Select calls do
not send Listview_SelectChange notifications. Quiet defers drawing but
not all notifications or callbacks.

CreateImage handles require explicit DeleteImage; List does not
dispose their Area objects or automatically release all handles at
cleanup.

Bugs

Insert may leave a partially changed list on allocation or
construction failure. Format replacement is also nontransactional; its
setter does not report allocation failure. Some setters and redraw
paths trust caller indices. Clear/Remove can access stale active-entry
records while updating Active. With external pools, the title record
is not explicitly freed. See the individual method contracts for
affected cases.

MUIM_List_Clear

Synopsis

IPTR result = DoMethod(obj, MUIM_List_Clear);

Function

Remove all confirmed entries.

Inputs

obj - Live List with matching destruction policy.

Result

Always zero, including an empty list.

Notes

Calls Destruct in reverse order, frees records, resets Entries/First
and Active, and requests redraw. The title and capacity remain.
Updating Active after freeing its former entry can touch stale
storage.

MUIM_List_Compare

Synopsis

IPTR result = DoMethod(obj, MUIM_List_Compare, (IPTR)entry1,
(IPTR)entry2, sort_type1, sort_type2);

Function

Compare entry1 with entry2.

Inputs

entry1, entry2 - Live data suitable for the current comparator.
sort_type1, sort_type2 - Declared LONG fields; ignored locally.

Result

Hook result; interpret as signed LONG ordering, negative/zero/positive.

Notes

Custom CompareHook receives entry2 as object and entry1 as message;
default is case-insensitive Stricmp. This method does not sort or
copy.

MUIM_List_Construct

Synopsis

IPTR result = DoMethod(obj, MUIM_List_Construct, (IPTR)entry,
(IPTR)pool);

Function

Create the data pointer to store for an entry.

Inputs

entry - Input data interpreted by the construction policy.
pool - Live pool supplied to that policy.

Result

Stored pointer, or zero on failure.

Notes

NULL hook returns the input pointer. String mode copies text into a
pool allocation with its size stored immediately before the string;
NULL input becomes empty text. Custom hooks receive pool and entry.
The returned pointer must be released with the matching Destruct
policy. This call does not insert an entry.

MUIM_List_CreateImage

Synopsis

IPTR result = DoMethod(obj, MUIM_List_CreateImage, (IPTR)area, flags);

Function

Create a list-image handle referring to an Area object.

Inputs

area - Live Area-compatible object not simultaneously used in another
parent hierarchy.
flags - ULONG; ignored here, use zero.

Result

Opaque handle, or zero for NULL area or handle allocation failure.

Notes

Allocates a pooled handle that borrows the Area. Setup is attempted
immediately when List is set up, without checking success. Embed it as
ESC followed by uppercase O and [hexadecimal handle] in display text.
Keep Area and handle valid until all references are removed; call
DeleteImage explicitly. List does not dispose the Area or walk handles
at Cleanup/Dispose.

MUIM_List_DeleteImage

Synopsis

IPTR result = DoMethod(obj, MUIM_List_DeleteImage, (IPTR)listimg);

Function

Disconnect an image object and release its handle.

Inputs

listimg - Live handle returned by this List's CreateImage, or NULL.

Result

Always zero. NULL is a no-op.

Notes

Cleanup/DisconnectParent the Area, unlink the pooled handle and
release it; the Area is not disposed. Handles are not checked for
membership or setup state: remove text references and delete each once
during a matching setup lifecycle.

MUIM_List_Destruct

Synopsis

IPTR result = DoMethod(obj, MUIM_List_Destruct, (IPTR)entry,
(IPTR)pool);

Function

Release entry data using the current destruction policy.

Inputs

entry - Data produced by the matching construction policy.
pool - Same live pool used for allocation.

Result

Always zero; custom-hook return is ignored.

Notes

NULL hook does nothing. String mode frees only allocations made by its
matching String constructor; custom hooks receive pool and stored
entry. Direct calls do not remove List records: do not free data still
referenced.

MUIM_List_Display

Synopsis

IPTR result = DoMethod(obj, MUIM_List_Display, (IPTR)entry, (IPTR)array,
entry_pos, (IPTR)preparses);

Function

Fill display-column string pointers.

Inputs

entry - Stored data, or NULL for title.
array - Writable STRPTR array with a writable preceding pointer slot
when using a hook.
entry_pos - LONG index, or -1 for title.
preparses - Declared array; ignored by the base method.

Result

1 without a hook; otherwise the hook result. Rendering callers ignore
that result.

Notes

Without a hook only array[0] is assigned. A hook receives the array as
object and entry as message. The preceding slot holds entry position,
written as ULONG here but pointer-sized on an internal row path; title
handling differs. Do not rely on consistent pointer-sized metadata.
All used column strings must survive measurement and drawing. Format
preparses are prepared internally; this base method does not pass its
preparses argument separately to the hook.

MUIM_List_Exchange

Synopsis

IPTR result = DoMethod(obj, MUIM_List_Exchange, pos1, pos2);

Function

Exchange two entry records.

Inputs

pos1 - LONG index or MUIV_List_Exchange_Top, Active or Bottom.
pos2 - Same choices, plus MUIV_List_Exchange_Next or Previous relative
to the resolved first index.

Result

TRUE when distinct valid indices were changed; FALSE for invalid indices
or the same index.

Notes

Exchange swaps two records, preserving their selection bits. Active
keeps its index and may name different data afterwards. No
Construct/Destruct or Active notification occurs. Unlike Move,
Exchange does not record the same pending full update under Quiet.

MUIM_List_GetEntry

Synopsis

IPTR result = DoMethod(obj, MUIM_List_GetEntry, pos, (IPTR)entry);

Function

Return the stored data pointer at an index.

Inputs

pos - LONG index or MUIV_List_GetEntry_Active.
entry - Non-NULL writable APTR result location.

Result

Stored pointer as IPTR, also written to the entry output; zero with a
NULL output value for an invalid position.

Notes

Returns borrowed data. Sorting/moving changes indices; removing or
clearing entries may destroy the pointer. No copy is made. The output
pointer must not be NULL.

MUIM_List_Insert

Synopsis

IPTR result = DoMethod(obj, MUIM_List_Insert, (IPTR)entries, count,
pos);

Function

Construct and insert a sequence of entries.

Inputs

entries - Readable APTR array for the call.
count - Positive LONG count, or -1 for a NULL-terminated array.
pos - LONG insertion slot or MUIV_List_Insert_Top, Active, Sorted or
Bottom.

Result

On completion, the pre-sort index of the last inserted slot, cast to
ULONG. On nonpositive count or failure, all-bits-one IPTR (~0). This is
not a Boolean or count.

Notes

Top inserts at zero, Bottom appends, Active uses its index or zero,
and Sorted appends then sorts. Other positions are clamped.
ConstructHook supplies each stored pointer; the input array is not
retained. InsertPosition is the pre-sort slot; sorting can also affect
Active.

This operation is not atomic. An allocation or Construct failure can
leave partial entries and inconsistent counts; failure paths do not
roll back and may calculate invalid move lengths. The return value
cannot certify a recoverable partial state. Do not mutate List
reentrantly from its hooks.

MUIM_List_InsertSingle

Synopsis

IPTR result = DoMethod(obj, MUIM_List_InsertSingle, (IPTR)entry, pos);

Function

Insert one entry through Insert.

Inputs

entry - Input interpreted by ConstructHook; NULL is allowed only if that
policy produces a non-NULL stored value.
pos - Same index/selectors as Insert.

Result

Exactly the Insert result for a count of one: pre-sort slot or
all-bits-one failure.

Notes

Passes the message entry to Insert synchronously. Construction,
sorting, error handling and ownership follow MUIM_List_Insert.

MUIM_List_Jump

Synopsis

IPTR result = DoMethod(obj, MUIM_List_Jump, pos);

Function

Scroll until a requested index is in the visible range.

Inputs

pos - LONG index or MUIV_List_Jump_Top, Active, Bottom, Up or Down.
obj - Laid-out List with a positive visible-row count for meaningful
scrolling.

Result

Always TRUE; not proof that an existing entry was displayed.

Notes

Up targets First-1, Down First+Visible. The method clamps the target
and changes First only when needed; Active is unchanged. TRUE does not
confirm a visible entry when the list is empty or unlaid-out.

MUIM_List_Move

Synopsis

IPTR result = DoMethod(obj, MUIM_List_Move, from, to);

Function

Move one entry to another index.

Inputs

from - LONG index or MUIV_List_Move_Top, Active or Bottom.
to - Same choices, plus MUIV_List_Move_Next or Previous relative to the
resolved first index.

Result

TRUE when distinct valid indices were changed; FALSE for invalid indices
or the same index.

Notes

Move shifts records; selection bits follow the data. Active keeps its
index and may name different data afterwards. No Construct/Destruct or
Active notification occurs. Quiet defers the full redraw.

MUIM_List_NextSelected

Synopsis

IPTR result = DoMethod(obj, MUIM_List_NextSelected, (IPTR)pos);

Function

Find the next selected entry index.

Inputs

pos - Non-NULL writable LONG. Start with MUIV_List_NextSelected_Start;
otherwise supply a valid previous index.

Result

Always TRUE. The pos output receives the next index or
MUIV_List_NextSelected_End.

Notes

Start and End are both -1. An initial call without selected entries
returns Active if set; later calls scan strictly after the supplied
index. End restarts on another call. Do not mutate the list or pass
invalid negative/overflowing indices while iterating.

MUIM_List_Redraw

Synopsis

IPTR result = DoMethod(obj, MUIM_List_Redraw, pos, (IPTR)entry);

Function

Recalculate measurements and request a row or full redraw.

Inputs

pos - Valid LONG index, MUIV_List_Redraw_Active, All or Entry.
entry - Data pointer matched by identity for Entry; ignored otherwise.

Result

Always zero.

Notes

Entry locates the first pointer-equal entry; All remeasures and
redraws. Cached maxima can grow without shrinking. Quiet defers
drawing. Numeric indices other than -1 are not fully validated and may
access outside the array; supply both method arguments.

MUIM_List_Remove

Synopsis

IPTR result = DoMethod(obj, MUIM_List_Remove, pos);

Function

Destroy and remove one entry or the selected entries.

Inputs

pos - LONG index or MUIV_List_Remove_First, Active, Last or Selected.

Result

Always zero, including invalid index or empty list.

Notes

Selected removes flagged entries, or Active if none are flagged. The
method destroys records, shifts survivors and adjusts Active. The
UWORD selected scan does not support unrestricted counts; updating
Active can reference stale records. Do not remove entries while
traversing them with NextSelected; use Remove_Selected instead.

MUIM_List_Select

Synopsis

IPTR result = DoMethod(obj, MUIM_List_Select, pos, seltype, (IPTR)info);

Function

Change selection bits or query their state.

Inputs

pos - LONG index, MUIV_List_Select_Active or All.
seltype - MUIV_List_Select_Off deselects; On selects; Toggle reverses;
Ask only queries.
info - Optional writable LONG result pointer.

Result

Always zero. For All+Ask, the info output is the selected count.
Otherwise it is the last processed entry's previous selection bit; no
processed entry yields zero. An invalid explicit index returns before
writing info.

Notes

Off deselects and On selects; MultiTestHook may refuse a combination.
Active is unchanged. Calls request redraw but do not emit
Listview_SelectChange. Quiet may suppress redraw without marking all
rows pending. Use Ask to verify the selection state.

MUIM_List_Sort

Synopsis

IPTR result = DoMethod(obj, MUIM_List_Sort);

Function

Sort the entire list using Compare.

Inputs

obj - Live List with a consistent comparator and valid entry data.

Result

Always zero, even when reordered.

Notes

Uses unstable quadratic selection sort. Selection flags follow
entries; Active follows its entry without an Active notification.
Synchronous comparators must not mutate or dispose List. Quiet defers
redraw.

MUIM_List_TestPos

Synopsis

IPTR result = DoMethod(obj, MUIM_List_TestPos, x, y, (IPTR)res);

Function

Map window-relative coordinates to row and column information.

Inputs

x, y - LONG coordinates. Both MUI_MAXMAX select the last stored
mouse-release position.
res - Non-NULL writable MUI_List_TestPos_Result.
obj - Laid-out List with valid measured row height.

Result

Always TRUE. Inspect entry, column and flags rather than treating TRUE
as a hit.

Notes

Returns entry/column (-1 if absent) and hit flags; xoffset and yoffset
are written only on the corresponding hit paths, so initialize the
result before calling. Both coordinates MUI_MAXMAX use cached release
coordinates, not live mouse position. Visible-row bounds do not
subtract First; invalid scroll state can yield out-of-range entry
indices.