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

String.mui

MUIA_String_Accept

Function

Specify the case-sensitive set of bytes to allow during ordinary
character entry.

Inputs

Initialize, set, get; borrowed terminated STRPTR, or NULL to disable
this filter. Default NULL.

Notes

Borrowed, case-sensitive allowed-byte set; retain it while installed.
Reject is applied afterwards, so a byte in both sets is rejected. An empty
Accept rejects normal typed bytes. Filters do not apply to editing
commands, paste, or programmatic Contents, Integer and Insert; they do not
sanitize existing text.

MUIA_String_Acknowledge

Function

Read the buffer pointer associated with acknowledgement state.

Inputs

Get; borrowed STRPTR or NULL. Used as a notification trigger by the
event handler.

Notes

MUIKEY_PRESS sends an Acknowledge notification with a borrowed pointer to
mutable Contents, not a saved accepted value. Contents replacement updates
the pointer without sending this notification; keyboard update paths can
clear it. Insert and ClearSelected leave it untouched. Thus a non-NULL
getter does not prove Return was pressed. Setting this attribute does not
change the local pointer; copy text to retain it.

MUIA_String_AdvanceOnCR

Function

Advance to the next active object when the editor handles MUIKEY_PRESS.

Inputs

Initialize, set, get; BOOL. Default FALSE.

Notes

On MUIKEY_PRESS, TRUE advances Window_ActiveObject to Next and FALSE clears
focus, unless StayActive is TRUE. Acknowledge is notified; Integer is also
notified when numeric parsing succeeds. No input validation occurs.

MUIA_String_AttachedList

Function

Route list navigation keys to another object.

Inputs

Initialize, set, get; borrowed List-compatible object pointer or NULL.
Default NULL.

Notes

While active, Up/Down/PageUp/PageDown/Top/Bottom forward selectors to the
borrowed List object's List_Active. String does not copy selected text or
own the list; keep it alive until detached/disposed. NULL disables
forwarding.

MUIA_String_BufferPos

Function

Read or set the insertion cursor byte offset.

Inputs

Initialize, set, get; stored as ULONG despite the LONG header
annotation. Default zero.

Notes

Use byte positions from zero to the current text length. The setter stores
an unchecked value; drawing clamps it later, so a getter or subsequent edit
can see an unsafe offset. MUIV_String_BufferPos_End (0xffffffff) has no
immediate special handling: supply the actual length when editing before a
redraw. The setter clears marking and requests an update.

Bugs

Editing helpers trust BufferPos before indexing or moving bytes. A
negative value converted to ULONG, or another out-of-range value, is
unsafe before the deferred clamp. Do not use the sentinel as an
immediate validation guarantee.

MUIA_String_Columns

Function

Set a fixed text-width contribution to layout.

Inputs

Initialize only; stored as WORD. Default -1.

Notes

Controls font-based width in AskMinMax, not capacity. Nonnegative values
use Columns times font X size; otherwise minimum/default use 4/12 character
widths and maximum MUI_MAXMAX. Height uses font Y size. Constructor-only
WORD value; out-of-range inputs are narrowed without validation.

MUIA_String_Contents

Function

Read or replace the editable text.

Inputs

Initialize, set, get; terminated STRPTR, or NULL to clear. Default
empty.

Notes

The setter copies at most MaxLen-1 bytes, terminates the buffer and accepts
NULL to clear. NoInput and Accept/Reject do not apply. Supply
nonoverlapping source storage. The getter returns borrowed mutable storage
(also via Text_Contents): do not free it or retain its address across
disposal. Replacing text resets DisplayPos and marking, clamps the cursor
and updates Acknowledge without notifying Acknowledge. Equal non-NULL text
suppresses Contents notification; comparison happens before truncation, so
a changed source may notify even when stored text is unchanged. The
notification can carry the original input pointer, not the truncated
buffer. Text_Contents is a Set/Get alias, not a String constructor tag.

Bugs

Non-NULL initial Contents follows the uninitialized-buffer comparison
described in MUIC_String. Construct empty, then set text. Neither
replacement nor disposal securely erases prior text.

MUIA_String_DisplayPos

Function

Read or request the first displayed byte offset.

Inputs

Set, get; LONG. Initial value zero; no local constructor handling.

Notes

Setting this byte offset also sets BufferPos and clears marking. Drawing
may adjust the position to expose the cursor; replacing Contents resets it.
Supply a valid offset within the text: the setter does not validate it
before display calculations.

Bugs

Use a nonnegative offset within current text length. The setter does not
validate it; display calculations can use it before a safe range is
established. This is not an independent horizontal-scroll control.

MUIA_String_EditHook

Function

Retain an edit-hook pointer at construction.

Inputs

Constructor storage only; borrowed struct Hook pointer, default NULL.

Notes

Only the constructor retains this borrowed pointer; no local Set/Get or
callback invocation is implemented, despite the header annotation. Keep
storage alive while retained; do not rely on editor-hook behavior.

MUIA_String_Format

Function

Choose the horizontal alignment used to draw the visible text.

Inputs

Initialize, get; LONG. MUIV_String_Format_Left (0),
MUIV_String_Format_Center (1) or MUIV_String_Format_Right (2). Default
Left.

Notes

Constructor-only alignment controls drawing and mouse placement. No local
setter exists; use only Left, Center or Right. Other values have no
alignment branch.

MUIA_String_Integer

Function

Format a numeric value as text or parse the current text as a signed
LONG.

Inputs

Initialize, set, get. The header says ULONG; the implementation uses
signed decimal formatting and StrToLong.

Notes

Setting formats signed decimal text through a bounded local buffer, then
uses Contents (which can truncate at MaxLen). The getter uses AROS
StrToLong: optional whitespace/sign, decimal prefix, trailing text
accepted, invalid input returns zero; overflow is not checked. This is not
a numeric-only editor. An unchanged parsed value suppresses the Integer
setter's own notification, though Contents may still notify. MUIKEY_PRESS
sends Integer only when parsing succeeds. The formatter passes an IPTR
value to %ld without an explicit cast; do not infer cross-ABI formatting
guarantees.

Bugs

The formatting call passes the IPTR tag value directly to %ld without a
cast. No additional cross-ABI formatting guarantee is established here.
Initial Integer text takes the same uninitialized comparison path as
non-NULL initial Contents.

MUIA_String_KeyDownFocus

Function

Identify an unimplemented compatibility attribute.

Inputs

Public header identifier only; no supported local initialization, setter
or getter.

Notes

Not implemented: no local initialization, setter, getter or focus transfer.
Up/Down keys instead forward navigation to AttachedList when set.
Superclass tag delegation is not this feature.

MUIA_String_KeyUpFocus

Function

Identify an unimplemented compatibility attribute.

Inputs

Public header identifier only; no supported local initialization, setter
or getter.

Notes

Not implemented: no local initialization, setter, getter or focus transfer.
Up/Down keys instead forward navigation to AttachedList when set.
Superclass tag delegation is not this feature.

MUIA_String_LonelyEditHook

Function

Store the constructor flag associated with edit-hook handling.

Inputs

Constructor storage only; BOOL, default FALSE.

Notes

Stored at construction only. No local setter/getter uses this flag, and it
does not activate EditHook callbacks.

MUIA_String_MaxLen

Function

Choose the fixed buffer allocation size, including the terminating zero.

Inputs

Initialize, get; stored as ULONG. Default 80, allowing 79 text bytes.

Notes

Includes the NUL byte (default 80 permits 79 text bytes). Zero becomes one;
no resize setter exists. Contents truncates and insertion stops before
overflow. Secret mode allocates another buffer of this size; allocation
failure aborts construction. Negative LONG inputs become large unsigned
lengths. WORD/UWORD indexing and secret-fill loops impose further practical
limits: keep text sizes small.

Bugs

Negative LONG tag values become large unsigned sizes, not a request for
the default. WORD-based selection/measurement and the UWORD secret-fill
loop limit usable sizes independently of allocation success. The class
does not enforce a comprehensive maximum; use short, application-bounded
single-line text.

MUIA_String_NoInput

Function

Disable text-changing keyboard commands handled by String.

Inputs

Initialize, set, get; BOOL, default FALSE.

Notes

TRUE blocks keyboard insertion, paste, deletion and cut, but permits
copying, cursor/selection commands, focus and acknowledgement. Programmatic
Contents, Integer, Insert, ClearSelected and Import still modify text. It
does not disable the gadget.

MUIA_String_Reject

Function

Specify the case-sensitive set of bytes to exclude during ordinary
character entry.

Inputs

Initialize, set, get; borrowed terminated STRPTR, or NULL to disable
this filter. Default NULL.

Notes

Borrowed, case-sensitive rejected-byte set; retain it while installed.
Reject is checked after Accept. An empty Reject excludes nothing; an empty
Accept blocks normal typing. Neither filter applies to editing commands,
paste or programmatic edits, or removes existing text.

MUIA_String_Secret

Function

Mask displayed text with asterisks.

Inputs

Initialize, get; BOOL, default FALSE.

Notes

Constructor-only visual masking uses a separate asterisk display buffer.
Contents, Integer, Acknowledge, export and clipboard copy still expose
plaintext, and buffers are not securely erased. Do not treat this as
confidential storage.

MUIA_String_SelectSize

Function

Read the signed length of the current marked range.

Inputs

Get; signed LONG result in IPTR storage. Zero when there is no nonempty
marked range.

Notes

Getter returns signed marked-range length based on byte, space-delimited
word or whole-string selection; negative when MarkPos is below BufferPos.
Internal positions use WORD. The setter is unimplemented: a Set tag may
still notify the superclass without changing selection.

Bugs

The setter is an explicit TODO and changes no selection state. No
constructor behavior exists. A Set tag can still reach superclass
notifications even though the requested selection is not applied.

MUIA_String_StayActive

Function

Keep focus when acknowledging text and avoid local deactivation on an
outside click.

Inputs

Initialize, set, get; BOOL, default FALSE.

Notes

TRUE overrides AdvanceOnCR on MUIKEY_PRESS and prevents local outside-click
deactivation. It does not lock Window_ActiveObject or prevent GoInactive
and window-close handling.

MUIC_String

Superclass

Area.mui

Description

Single-line byte-string editor. Owns a fixed buffer of MaxLen bytes,
including the NUL terminator (default 80); positions count bytes.
Contents is copied and truncated. Accept, Reject, AttachedList and
EditHook pointers are borrowed. Use the GUI task; no locking is provided.

Methods

Keyboard/mouse editing supports selection, cursor movement and
clipboard operations. Paste deletes selection before checking the
clipboard, so a read failure can still remove text. Normal edits may
notify Contents; MUIKEY_PRESS notifies Acknowledge and, when parsing
succeeds, Integer. Insert and ClearSelected do not notify either.
Export/Import use Dataspace and require valid terminated text records.

Notes

Secret masks the display, not stored or exported text. Text buffers are
freed without secure erasure. WORD/UWORD-based helpers limit usable
lengths independently of allocation size. Construct without initial
text and set Contents afterwards: non-NULL initial Contents/Integer
can trigger comparison against an uninitialized allocated buffer.

Bugs

EditHook/LonelyEditHook and KeyUpFocus/KeyDownFocus are not operative;
SelectSize has no setter. FileNameStart returns the buffer pointer,
not a position. BufferPos is clamped only during drawing; unsafe
positions can reach editing or rendering first. Ordinary-key input
can skip CloseLocale; clipboard I/O failures are incompletely reported.

MUIM_String_ClearSelected

Synopsis

IPTR result = DoMethod(obj, MUIM_String_ClearSelected);

Function

Remove the current marked range and request a redraw.

Inputs

obj - Live String with valid buffer and selection state. No payload
arguments.

Result

Always zero, whether text was removed or no range was selected.

Notes

Removes the marked range (if nonempty), moves the cursor to its start and
redraws; always clears marking. NoInput does not block it. No
Contents/Acknowledge notification is sent and Acknowledge state is
unchanged.

MUIM_String_FileNameStart

Synopsis

IPTR result = DoMethod(obj, MUIM_String_FileNameStart, (IPTR)buffer,
pos);

Function

Return the internal text-buffer pointer from an unfinished compatibility
method.

Inputs

obj - Live String.
buffer - Declared STRPTR argument; ignored.
pos - Declared LONG argument; ignored.

Result

Borrowed STRPTR cast to IPTR, pointing to the object's current text
buffer.

Notes

Unimplemented filename-position calculation: ignores buffer and pos,
returning the borrowed mutable internal STRPTR as IPTR, not a byte index or
volume marker. No ownership transfer occurs; the pointer expires with the
object.

MUIM_String_Insert

Synopsis

IPTR result = DoMethod(obj, MUIM_String_Insert, (IPTR)text, pos);

Function

Insert bytes at a chosen position until the text ends or the buffer is
full.

Inputs

obj - Live String with valid current cursor.
text - Non-NULL terminated STRPTR readable for the call, independent of
the destination buffer.
pos - LONG byte offset from zero through current length, or a declared
selector.

Result

Always zero, including invalid position, partial insertion and no space.
No inserted-byte count is returned.

Notes

Position selectors StartOfString, EndOfString and BufferPos resolve to
start, end and cursor; invalid offsets are ignored. Insert copies up to
available capacity without Accept/Reject, NoInput or printable-byte
filtering. It does not replace a selection or notify Contents/Acknowledge.
The old cursor advances when at/after the insertion point. If nothing fits
at a valid position, BufferPos can move there without redraw; marking and
Acknowledge stay unchanged. The result is always zero, even for partial
insertion.