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

Dirlist.mui

MUIA_Dirlist_AcceptPattern

Function

Store a DOS pattern to accept only names matching it during builtin
filtering.

Inputs

Initialize, set and get in this implementation, despite the header
omitting get. Borrowed compiled pattern buffer from ParsePatternNoCase,
or NULL to disable. Default NULL.

Notes

Dirlist passes the buffer directly to MatchPatternNoCase; it does not
parse a wildcard expression or copy its storage. Keep the compiled
buffer readable until replacement or disposal. Files are tested; drawers
are tested only with FilterDrawers TRUE. A non-NULL FilterHook bypasses
this test. Set does not trigger a new scan; use ReRead or Directory Set.
Get returns the stored pointer with TRUE.

MUIA_Dirlist_Directory

Function

Select the directory to enumerate or read its stored pointer.

Inputs

Initialize, set and get, borrowed terminated STRPTR. Default NULL. No
copy, canonicalization or ownership transfer.

Notes

Keep the string readable and unchanged for scans and Path queries until
replacement or disposal. Set stores the pointer and schedules one
synchronous scan after all tags in that call have been processed, using
their final option values. Repeating Directory still scans; multiple
Directory tags use the last value.
If previous Status is Valid, the old list is cleared first and Status
becomes Invalid. NULL skips reading after that conditional clear. Other
invalid states do not cause automatic clearing. Get returns the exact
borrowed pointer with TRUE, not a normalized filesystem path. Setter
return value is inherited from List and does not report scan success.

MUIA_Dirlist_DrawersOnly

Function

Exclude entries whose fib_DirEntryType is not positive.

Inputs

Initialize, set and get in this implementation, despite the header
omitting get. BOOL, normalized to TRUE/FALSE. Default FALSE.

Notes

FilesOnly and DrawersOnly both TRUE exclude all entries in the builtin
path. A non-NULL FilterHook bypasses the builtin filtering path. Set
stores the flag without rescanning; use ReRead or Directory Set. Get
returns the stored value with TRUE.

MUIA_Dirlist_FilesOnly

Function

Exclude entries whose fib_DirEntryType is positive.

Inputs

Initialize, set and get in this implementation, despite the header
omitting get. BOOL, normalized to TRUE/FALSE. Default FALSE.

Notes

FilesOnly and DrawersOnly both TRUE exclude all entries in the builtin
path. A non-NULL FilterHook bypasses the builtin filtering path. Set
stores the flag without rescanning; use ReRead or Directory Set. Get
returns the stored value with TRUE.

MUIA_Dirlist_FilterDrawers

Function

Apply accept/reject patterns to positive-type directory entries as well
as files.

Inputs

Initialize, set and get in this implementation, despite the header
omitting get. BOOL, normalized to TRUE/FALSE. Default FALSE.

Notes

This flag affects pattern tests only; drawer/file filtering and
RejectIcons are independent. A non-NULL FilterHook bypasses the builtin
filtering path. Set stores the flag without rescanning; use ReRead or
Directory Set. Get returns the stored value with TRUE.

MUIA_Dirlist_FilterHook

Function

Provide a callback for each enumerated directory entry.

Inputs

Initialize, set and get in this implementation, despite the header
omitting get. Borrowed struct Hook pointer; default NULL.

Notes

The call is CallHookPkt(hook, dirlistObject, &exAllData). The temporary
zero-initialized ExAllData contains name, type, size, protection,
days/minutes/ticks and comment from the current FileInfoBlock. Other
fields remain zero. Name/comment pointers and the message are valid only
during the call; copy needed data before returning. Hook/object must
remain live and callbacks must not mutate or dispose the active scan.
A zero hook result skips the entry. A nonzero result also inserts
nothing because the insertion code is in the alternative no-hook branch.
Thus this implementation does not provide a functioning custom
acceptance hook. All builtin filters and counters are bypassed while the
hook is installed. Set alone does not rescan; Get returns the stored
hook with TRUE.

MUIA_Dirlist_MultiSelDirs

Function

Store a directory-multiselection option without changing selection
behavior.

Inputs

Initialize, set and get in this implementation, despite the header
omitting get. BOOL normalized to TRUE/FALSE; default FALSE.

Notes

The field is only stored and returned. No local multiselection test hook
uses it, and it does not enable or restrict drawer selection. Actual
List selection behavior remains governed by inherited List/Listview
options. Get returns TRUE with the stored flag.

MUIA_Dirlist_NumBytes

Function

Read the stored byte-count field, which remains zero in this
implementation.

Inputs

Get, LONG in the header; stored as IPTR. Initialized to zero and never
updated by the local setter or scan.

Notes

For each accepted file the scan emits a NumBytes tag with stored
numbytes plus fib_Size. Since numbytes is not stored, these
notifications carry individual file sizes, not a cumulative total. Reset
tags also do not change storage. Get returns zero with TRUE regardless
of listed file sizes. The attribute cannot be used to calculate a
reliable directory total.

MUIA_Dirlist_NumDrawers

Function

Read the accumulated count of accepted drawer records encountered by
builtin filtering.

Inputs

Get, LONG in the header; stored as ULONG. Initially zero.

Notes

The scan increments the field before attempting each matching insertion,
emits its value through Set and ignores insertion success. FilterHook
scans do not increment it. ReRead and Directory changes emit zero
counter tags but the setter has no case to store them; the count
therefore accumulates across scans rather than representing the current
list. Failed insertions and unsigned overflow are not accounted for. Get
returns TRUE. Do not use these values as verified current-directory
totals.

MUIA_Dirlist_NumFiles

Function

Read the accumulated count of accepted file records encountered by
builtin filtering.

Inputs

Get, LONG in the header; stored as ULONG. Initially zero.

Notes

The scan increments the field before attempting each matching insertion,
emits its value through Set and ignores insertion success. FilterHook
scans do not increment it. ReRead and Directory changes emit zero
counter tags but the setter has no case to store them; the count
therefore accumulates across scans rather than representing the current
list. Failed insertions and unsigned overflow are not accounted for. Get
returns TRUE. Do not use these values as verified current-directory
totals.

MUIA_Dirlist_Path

Function

Build a path for the active entry when Status is Valid.

Inputs

Get, borrowed STRPTR result. The getter returns TRUE even when it stores
NULL.

Notes

Every query first frees the previous generated Path. With Valid status
and an active List entry, it allocates a buffer, copies Directory and
appends fib_FileName with AddPart. No active entry, unsuitable status,
allocation failure or AddPart failure yields NULL. Directory and active
record must remain valid; the length calculation uses WORD without
overflow checking, so the combined string lengths plus three must fit a
positive WORD.
The returned path is owned by Dirlist. Do not modify or free it; copy it
before another Path query or disposal. Directory/selection changes do
not update an already returned string automatically. Path creates no
lock and does not prove that the named entry still exists.

MUIA_Dirlist_RejectIcons

Function

Exclude names ending in .info, using a case-insensitive suffix
comparison.

Inputs

Initialize, set and get in this implementation, despite the header
omitting get. BOOL, normalized to TRUE/FALSE. Default FALSE.

Notes

The suffix test also applies to drawers regardless of FilterDrawers. It
does not inspect file contents or require a valid icon datatype. A
non-NULL FilterHook bypasses the builtin filtering path. Set stores the
flag without rescanning; use ReRead or Directory Set. Get returns the
stored value with TRUE.

MUIA_Dirlist_RejectPattern

Function

Store a DOS pattern to exclude names matching it during builtin
filtering.

Inputs

Initialize, set and get in this implementation, despite the header
omitting get. Borrowed compiled pattern buffer from ParsePatternNoCase,
or NULL to disable. Default NULL.

Notes

Dirlist passes the buffer directly to MatchPatternNoCase; it does not
parse a wildcard expression or copy its storage. Keep the compiled
buffer readable until replacement or disposal. Files are tested; drawers
are tested only with FilterDrawers TRUE. A non-NULL FilterHook bypasses
this test. Set does not trigger a new scan; use ReRead or Directory Set.
Get returns the stored pointer with TRUE.

MUIA_Dirlist_SortDirs

Function

Store the requested drawer placement without sorting entries.

Inputs

Initialize, set and get in this implementation. Declared LONG values:
First (0), Last (1), Mix (2). Default zero.

Notes

The setter reduces every nonzero value to TRUE and stores it in a BYTE;
Last and Mix therefore both read back as one. The field is not used by
scanning or comparison. Entries are appended in ExNext order. Get
returns TRUE, but neither the stored value nor a notification proves
sorting occurred.

MUIA_Dirlist_SortHighLow

Function

Store a reverse-sort flag without reversing the list.

Inputs

Initialize, set and get in this implementation. BOOL normalized to
TRUE/FALSE; default FALSE.

Notes

The flag has no consumer in this class. No scan or setter invokes a
sorting operation based on it. Get returns TRUE with the stored flag;
inherited explicit List operations are separate.

MUIA_Dirlist_SortType

Function

Store a sort-mode value without applying it.

Inputs

Initialize, set and get in this implementation. LONG in the header,
stored as BYTE. Declared values Name (0), Date (1), Size (2); default
zero.

Notes

No validation, comparison hook or sorting operation uses this value.
Large inputs truncate to BYTE. Scan insertion remains in ExNext order.
Get returns TRUE with the stored value; do not infer name/date/size
ordering.

MUIA_Dirlist_Status

Function

Read the stored enumeration status.

Inputs

Get, LONG in the header, stored as BYTE. Invalid (0) initially; Reading
(1) and Valid (2) are declared.

Notes

This implementation never emits Reading automatically. It marks Invalid
when clearing a previously Valid list, and Valid after entering and
leaving the ExNext loop, including an error exit. Allocation, Lock and
Examine failures do not independently publish an error result. A partial
scan or a FilterHook scan that inserted nothing can still be Valid.
An internal setter stores this tag and ordinary Set can reach it despite
the get-only header. Do not set it to manufacture success: list clearing
and Path generation depend on this field. Get returns TRUE with the
stored value. Valid is not evidence of complete enumeration, correct
totals or an existing active path.

MUIC_Dirlist

Superclass

List.mui

Description

Enumerate a DOS directory synchronously into List entries containing
copied FileInfoBlock records. Construction installs local construct,
destruct and display hooks, then applies Dirlist tags through its
setter. A non-NULL Directory tag can therefore perform filesystem I/O
before construction returns. Directory and pattern strings and
FilterHook are borrowed; list records and the generated Path string are
owned by the object.
The default display has six columns in this order: name, size or drawer
image, DOS date, time, protection flags and comment. The display hook
always writes six slots. A caller-supplied List_Format is accepted
without adapting the hook; retain a compatible six-column format. Its
temporary size/date/time/protection strings are instance buffers
overwritten by later display calls. DateToStr status is ignored.
Protection display shows script, pure, archive and owner
read/write/execute/delete flags, not an exhaustive protection-word
display.
The constructor replaces the List construction/destruction/display hooks
after superclass construction. Do not preload incompatible
List_SourceArray entries or replace these hooks while copied directory
records are present. Entries retrieved through List methods are borrowed
records with a FileInfoBlock as their first member; they become invalid
when removed, cleared or disposed.
A directory scan allocates one FileInfoBlock, takes a shared lock,
examines the target and iterates ExNext only for a positive directory
type. Entries with positive fib_DirEntryType are drawers; other types
follow the file path. There is no recursion, background worker, UI input
pumping, cancellation method or timeout. Filesystem operations and
filter callbacks can block the caller.

Methods

Directory Set triggers a scan even when the pointer or string is
unchanged. ReRead scans the current Directory while forcing List_Quiet
TRUE and then FALSE. Changing other filters alone does not reread. If
the stored Status is Valid, both paths clear the old list and send
Invalid plus zero counter tags before reading. Those counter tags do not
reset the implementation's stored counters. If Status was not Valid,
existing list contents are not cleared.
The builtin filtering path applies FilesOnly/DrawersOnly, then
RejectIcons, then accept/reject patterns for files and optionally
drawers. Matching is case-insensitive and requires compiled DOS
patterns. Successful matches are appended in enumeration order. There is
no local compare hook or sorting operation implementing the advertised
sort attributes.
Getters return the stored options, counters and status, including
getters omitted by several header access annotations. Unknown queries
delegate to List. Disposal frees the last generated Path string, then
delegates record and child disposal to List; it never frees borrowed
Directory, patterns or FilterHook.

Bugs

With FilterHook non-NULL, its callback is called for each enumerated
entry, but insertion and counter updates exist only in the no-hook
branch. Returning either TRUE or FALSE from that hook therefore inserts
nothing in this implementation. The hook also bypasses all builtin
filters.
NumFiles and NumDrawers are incremented before insertion, without
checking insertion success, and are not reset by the zero tags emitted
on reread. They accumulate across scans. NumBytes is never assigned
after zero initialization; emitted NumBytes tag values describe
individual file sizes rather than a stored total.
After the ExNext loop, Status is set to Valid even if enumeration ended
with an error other than ERROR_NO_MORE_ENTRIES. Reading is never set
automatically. Valid does not prove a complete scan or correct totals.
Allocation, lock and Examine failures have no separate returned scan
status; a cleared old list is not restored.

MUIM_Dirlist_ReRead

Synopsis

IPTR result = DoMethod(obj, MUIM_Dirlist_ReRead);

Function

Synchronously scan the currently stored Directory again.

Inputs

obj - Live Dirlist with valid borrowed directory/filter storage and no
concurrent mutation or disposal.

Result

Always zero. No scan success, completeness or filesystem error is
returned.

Notes

Set List_Quiet TRUE; when Status is Valid, clear entries and send
Invalid plus zero counter tags; scan a non-NULL Directory; set Quiet
FALSE. The previous Quiet value is not restored. The counter-reset tags
are not stored, so counts accumulate and NumBytes remains zero. No
Directory means no filesystem scan. Callbacks and notifications can run
synchronously; they must not invalidate the instance or scan state. See
class filtering and Status limitations.