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

List.mui

MUIA_List_Active

Function

The index of the active entry. There can be at most one active entry
in a list. The active entry is highlighted visibly, except for
read-only lists (those whose Listview has MUIA_Listview_Input set to
FALSE). Selecting an entry with the mouse, or moving through the list
with keyboard controls will also change the active entry (again
excepting read-only lists).

When set programmatically through this attribute, some special values
can be used:

MUIV_List_Active_Off
MUIV_List_Active_Top
MUIV_List_Active_Bottom
MUIV_List_Active_Up
MUIV_List_Active_Down
MUIV_List_Active_PageUp
MUIV_List_Active_PageDown

When this attribute is read, either the index of the active entry or
the special value MUIV_List_Active_Off will be returned.

Setting this attribute to a new value will additionally have the same
effect as calling the MUIM_List_Jump method with the specified or
implied index.

Notes

The concept of an active entry must not be confused with that of a
selected entry.

See Also

MUIM_List_Jump, MUIM_List_Select, MUIA_Listview_Input

MUIA_List_AutoVisible

Function

When this attribute is set to true, the active entry will be in the
visible portion of the list whenever the list is unhidden.

See Also

MUIA_List_Active

MUIA_List_CompareHook

Function

The provided hook indicates the sort ordering of two list entries.
The hook receives list-entry data pointers as its second and third
arguments. The hook should return a negative value if the first entry
should be placed before the second entry, a positive value if the
first entry should be placed after the second entry, and zero if the
entries are equal.

In addition to being used internally for sorting operations, this hook
will be called when MUIM_List_Compare is externally invoked.

If this attribute is not specified or is set to NULL, all list entries
must be strings.

MUIA_List_ConstructHook

Function

The provided hook creates a list entry. Whenever a data item is added
to the list, it is the result of this hook that is really added.

The hook receives the list's memory pool as its second argument and
the data item for the entry as its third argument. The memory pool may
be used for allocating memory for the new entry if desired. The hook
should return the new data entry, or NULL if an error occurred.

If this attribute is not specified or is set to NULL, all list entries
must be strings (which must continue to exist for the lifetime of the
list).

If you want string entries to be duplicated within the list, so that
they do not have to be preserved externally, a built-in hook for this
purpose can be used by providing the special value
MUIV_List_ConstructHook_String.

Whenever this attribute is specified, a matching hook must be
specified for the MUIA_ListDestructHook attribute.

See Also

MUIA_List_DestructHook

MUIA_List_DestructHook

Function

The provided hook destroys a list entry, and is called whenever a data
item is removed from the list. It can be used to deallocate any
resources for the entry that were allocated by the hook specified for
MUIA_List_ConstructHook.

The hook receives the list's memory pool as its second argument and
the list entry to be destroyed as its third argument. The hook should
have no return value.

If this attribute is not specified or is set to NULL, all list entries
must be strings (which must continue to exist for the lifetime of the
list).

If you want string entries to be duplicated within the list, so that
they do not have to be preserved externally, a built-in hook for this
purpose can be used by providing the special value
MUIV_List_ConstructHook_String.

This attribute must only be specified when a matching hook has been
specified for the MUIA_List_ConstructHook attribute. If you specified
MUIV_List_ConstructHook_String for MUIA_List_ConstructHook, you must
specify MUIV_List_DestructHook_String for this attribute.

See Also

MUIA_List_ConstructHook

MUIA_List_DropMark

Function

Provides the index of the last position where a list entry was
successfully dropped. The initial value before any entry has been
dropped is undefined.

See Also

MUIA_List_DragSortable, MUIA_List_ShowDropMarks,
MUIA_Listview_Draggable

MUIA_List_First

Function

The index of the first entry that can be seen (assuming nothing
obscures the list) This value of this attribute is -1 when the
list's window is not open.

Notes

Notification does not occur on this attribute in MUI.

See Also

MUIA_List_First, MUIA_List_Entries

MUIA_List_MultiTestHook

Function

The provided hook indicates whether a particular list entry
may be multiselected. The hook receives the list-entry data pointer as
its third argument, and returns a Boolean value. If this attribute is
not specified or is set to NULL, all list entries are considered
multi-selectable.

Whenever an entry is about to be selected, this hook is called if
there are other entries already selected. If the hook returns TRUE,
the entry may be multi-selected; if the hook returns FALSE, the entry
remains unselected.

Additionally, if a non-multi-selectable entry has been selected (as
the only selected entry in the list), any attempt to select an
additional entry will fail.

MUIA_List_ShowDropMarks

Function

Specifies whether a visual indication will be shown of where a list
item will be inserted if dropped during a drag-and-drop operation.
Defaults to TRUE. Only has an affect when the list is a drop target
(e.g. when MUIA_List_DragSortable is TRUE).

See Also

MUIA_List_DragSortable, MUIA_List_DropMark, MUIA_Listview_Draggable

MUIA_List_Title

Function

A heading for the list, placed above list entries. A value of NULL
means no title is used. A value of TRUE means that the custom
display hook provides a separate title for each column; the hook
must then provide column titles instead of normal column data when
the entry pointer provided is NULL.

Notes

If a string is set for this attribute, it is not cached within the
object.

See Also

MUIA_List_DisplayHook

MUIA_List_Visible

Function

The number of entries that can be seen at once with the list's
current dimensions. This value of this attribute is -1 when the
list's window is not open.

Notes

Notification does not occur on this attribute in MUI.

See Also

MUIA_List_First, MUIA_List_Entries

MUIM_List_Clear

Synopsis

DoMethod(obj, MUIM_List_Clear);

Function

Removes all entries from the list.

MUIM_List_Compare

Synopsis

DoMethod(obj, MUIM_List_Compare, APTR entry1, APTR entry2,
    LONG sort_type1, LONG sort_type2);

Function

Compare two list entries according to the current comparison hook
(MUIA_List_CompareHook).

Inputs

entry1 - the first entry data.
entry2 - the second entry data.
sort_type1 - undocumented.
sort_type2 - undocumented.

See Also

MUIA_List_CompareHook, MUIM_List_Sort.

MUIM_List_CreateImage

Synopsis

DoMethod(obj, MUIM_List_CreateImage, Object *area, ULONG flags);

Function

Creates an image to be inserted within list entries. An instance of
any Area subclass is passed in and a blackbox value is returned that
can be displayed by embedding its hexadecimal representation within
any of the list's display strings (provided either statically or by
the list's display hook. The format string to be used is
"330[%p]".

It is recommended that lists that embed images are instances of a
custom subclass so that this method can be called in the list's
MUIM_Setup method, and MUIM_List_DeleteImage can be called in the
list's MUIM_Cleanup method. However, this is not necessary as long as
MUIM_List_CreateImage is called after the list has had its MUIM_Setup
called, and MUIM_List_DeleteImage is called after the list has had its
MUIM_Cleanup method called.

Inputs

area - the area object that is used to generate the image.
flags - must be zero.

Result

A blackbox reference to the list image, or NULL on an error.

Notes

If this method returns NULL, no special action needs to be taken, as
embedding this value in a list string will simply cause no image to
appear.

The object passed in becomes a child of the list, so it cannot be used
elsewhere simultaneously.

See Also

MUIM_List_DeleteImage, MUIA_List_DisplayHook.


Connects an Area subclass object to the list, much like an object gets
connected to a window. List calls Setup and AskMinMax on that object,
keeps a reference to it (that reference will be returned).
Text engine will dereference that pointer and draw the object with its
default size.

MUIM_List_DeleteImage

Synopsis

DoMethod(obj, MUIM_List_DeleteImage, APTR image);

Function

Deletes an image created by MUIM_List_CreateImage.

Inputs

image - a blackbox reference to the list image, or NULL.

See Also

MUIM_List_CreateImage, MUIA_List_DisplayHook.

MUIM_List_Exchange

Synopsis

DoMethod(obj, MUIM_List_Exchange, LONG pos1, LONG pos2);

Function

Exchange two entries' positions.

Inputs

pos1 - the current index of the first entry that should be moved, or
one of these special values:
MUIV_List_Exchange_Active: the active entry.
MUIV_List_Exchange_Top: the first entry.
MUIV_List_Exchange_Bottom: the last entry.
pos2 - the index of the entry that the first entry should be exchanged
with, or one of these special values:
MUIV_List_Exchange_Active: the active entry.
MUIV_List_Exchange_Top: the first entry.
MUIV_List_Exchange_Bottom: the last entry.
MUIV_List_Exchange_Next: the next entry after pos1.
MUIV_List_Exchange_Previous: the previous entry before pos1.

Notes

This method will do nothing if either index is greater than the last
index in the list, or if MUIV_List_Exchange_Next or
MUIV_List_Exchange_Previous imply an index outside the list.

See Also

MUIM_List_Move

MUIM_List_GetEntry

Synopsis

DoMethod(obj, MUIM_List_GetEntry, LONG pos, APTR *entry);

Function

Retrieves an entry from the list. If the requested entry position is
invalid, the entry will be NULL.

Inputs

pos - the index of the entry to get, or the special value
MUIV_List_GetEntry_Active to get the active entry.
entry - a pointer to a variable in which to store a pointer to the
entry data.

See Also

MUIM_List_Insert, MUIM_List_InsertSingle, MUIM_List_Remove.

MUIM_List_Insert

Synopsis

DoMethod(obj, MUIM_List_Insert, APTR *entries, LONG count, LONG pos);

Function

Adds multiple entries to the list. If a construct hook has been
installed, the results of passing the entries to this hook will be
inserted.

Inputs

entries - an array of entries to be inserted.
count - the number of entries to insert. A special value of -1 may be
used, indicating that the array of entries is NULL-terminated.
pos - the index at which to insert the new entries. The following
special values can also be used:
MUIV_List_Insert_Top: insert at index 0.
MUIV_List_Insert_Bottom: insert after all existing entries.
MUIV_List_Insert_Active: insert at the index of the active entry
(or at index 0 if there is no active entry).
MUIV_List_Insert_Sorted: keep the list sorted.

See Also

MUIM_List_InsertSingle, MUIM_List_Remove, MUIA_List_ConstructHook.

MUIM_List_InsertSingle

Synopsis

DoMethod(obj, MUIM_List_InsertSingle, APTR entry, LONG pos);

Function

Adds a single entry to the list. If a construct hook has been
installed, the result of passing the entry to this hook will be
inserted.

Inputs

entry - the entry to be inserted.
pos - the index at which to insert the new entry. The following
special values can also be used:
MUIV_List_Insert_Top: insert at index 0.
MUIV_List_Insert_Bottom: insert after all existing entries.
MUIV_List_Insert_Active: insert at the index of the active entry
(or at index 0 if there is no active entry).
MUIV_List_Insert_Sorted: keep the list sorted.

See Also

MUIM_List_Insert, MUIM_List_Remove, MUIA_List_ConstructHook.

MUIM_List_Jump

Synopsis

DoMethod(obj, MUIM_List_Jump, LONG pos);

Function

Scrolls the list so that a particular entry is visible.

Inputs

pos - index of entry that should become visible, or one of these
special values:
MUIV_List_Jump_Active: show the active entry.
MUIV_List_Jump_Top: show the first entry.
MUIV_List_Jump_Bottom: show the last entry.
MUIV_List_Jump_Up: show the previous hidden entry.
MUIV_List_Jump_Down: show the next hidden entry.

MUIM_List_Move

Synopsis

DoMethod(obj, MUIM_List_Move, LONG from, LONG to);

Function

Move a list entry to a new position.

Inputs

from - the current index of the entry that should be moved, or one of
these special values:
MUIV_List_Move_Active: the active entry.
MUIV_List_Move_Top: the first entry.
MUIV_List_Move_Bottom: the last entry.
to - the index of the entry's new position, or one of
these special values:
MUIV_List_Move_Active: the active entry.
MUIV_List_Move_Top: the first entry.
MUIV_List_Move_Bottom: the last entry.

Notes

The active index does not change, so the active entry may do so.

See Also

MUIM_List_Exchange

MUIM_List_NextSelected

Synopsis

DoMethod(obj, MUIM_List_NextSelected, LONG *pos);

Function

Allows iteration through a list's selected entries by providing the
index of the next selected entry after the specified index.

Inputs

pos - the address of a variable containing the index of the previous
selected entry. The variable must be initialised to the special
value MUIV_List_NextSelected_Start to find the first selected
entry. When this method returns, the variable will contain the
index of the next selected entry, or MUIV_List_NextSelected_End if
there are no more.

Notes

If there are no selected entries but there is an active entry, the
index of the active entry will be stored (when
MUIV_List_NextSelected_Start is specified).

Some selected entries may be skipped if any entries are removed
between calls to this method during an iteration of a list.

MUIV_List_NextSelected_Start and MUIV_List_NextSelected_End may have
the same numeric value.

See Also

MUIM_List_Select, MUIM_List_Remove.

MUIM_List_Remove

Synopsis

DoMethod(obj, MUIM_List_Remove, LONG pos);

Function

Removes entries from the list. If a destruct hook has been
installed, it will be called for the removed entry.

Inputs

pos - the index of the entry to be removed. The following
special values can also be used:
MUIV_List_Remove_First: remove the first entry.
MUIV_List_Remove_Last: remove the last entry.
MUIV_List_Remove_Active: remove the active entry.
MUIV_List_Remove_Selected: remove all selected entries
(or the active entry if there are no selected entries).

Notes

When the active entry is removed, the next entry becomes active
(if there is no entry below the active entry, the previous entry
becomes active instead).

See Also

MUIM_List_Insertsingle, MUIM_List_Insert, MUIA_List_DestructHook.


It was not possible to use MUIM_List_NextSelected here because that method
may skip entries if entries are removed during an iteration.

MUIM_List_Select

Synopsis

DoMethod(obj, MUIM_List_Select, LONG pos, LONG seltype, LONG *state);

Function

Selects or deselects entries in the list and/or enquires about their
current selection state. If a multiselection test hook has been
installed via MUIA_List_MultiTestHook, it will be called to validate
the requested selection.

This method may also be used to count the number of selected entries
(see below).

Inputs

pos - the index of the entry to be selected. The following
special values can also be used:
MUIV_List_Select_Active: Select the active entry.
MUIV_List_Select_All: Select all entries.
seltype - the new selection state; one of the following:
MUIV_List_Select_Off: Select the entry.
MUIV_List_Select_On: Deselect the entry.
MUIV_List_Select_Toggle: Switch to the alternate selection state.
MUIV_List_Select_Ask: Do not change the selection state, just
retrieve the current state. If 'pos' is MUIV_List_Select_All,
the number of selected entries will be retrieved instead (V9).
state - a pointer in which to fill in the previous selection state
(either MUIV_List_Select_On or MUIV_List_Select_Off) or the
number of selected entries. May be NULL.

Notes

If pos is MUIV_List_Select_All and seltype is not
MUIV_List_Select_Ask, the value filled in 'state' is undefined.

See Also

MUIA_List_Active, MUIA_List_MultiTestHook.

MUIM_List_Sort

Synopsis

DoMethod(obj, MUIM_List_Sort);

Function

Sort the list's entries according to the current comparison hook
(MUIA_List_CompareHook).

Notes

The active index does not change, so the active entry may do so.

See Also

MUIA_List_CompareHook, MUIM_List_Compare.