Popstring.mui

MUIA_Popstring_Button

Function

Supply the button that requests opening.

Inputs

Initialize only in this implementation, Object pointer. No default

object and no local getter despite the header annotation.

Notes

The button becomes a Group child on successful construction; do not
dispose it independently. Its Pressed FALSE notification opens the
popup. A successful non-toggle open disables it; a close with a non-NULL
close hook enables it immediately. Button replacement is not
implemented.

MUIA_Popstring_CloseHook

Function

Supply the queued closing hook.

Inputs

Initialize and set, pointer to struct Hook; default NULL. No local

getter despite the header annotation.

Notes

The hook is borrowed. MUIM_CallHook passes the Popstring object as hook
object and a pointer to argument words as message. The first word is the
String object and the second is the Close result. Its return is ignored.
Close queues the hook only while logically open; with no hook it does
not reset state or enable the button. Retain hook and data until queued
execution completes.

MUIA_Popstring_OpenHook

Function

Supply the synchronous opening hook.

Inputs

Initialize and set, pointer to struct Hook; default NULL. No local

getter despite the header annotation.

Notes

The hook is borrowed. MUIM_CallHook passes the Popstring object as hook
object and a pointer to argument words as message. The first word is the
String object. A nonzero hook return marks the popup logically open;
zero leaves it closed. With no hook Open does nothing.

MUIA_Popstring_String

Function

Supply or retrieve the string-side child.

Inputs

Initialize and get, Object pointer; default NULL. No local setter.

Notes

A non-NULL object becomes a Group child. Get returns a borrowed pointer.
Hooks receive this pointer unchanged and must accept NULL if no string
was supplied. Subclasses that interpret String_Contents require a
compatible live string object. The base class neither copies text nor
updates string contents.

MUIA_Popstring_Toggle

Function

Control repeated Open requests while logically open.

Inputs

Initialize and set, BOOL; default FALSE. No local getter despite the

header annotation.

Notes

With TRUE and a non-NULL OpenHook, an Open request while already open
invokes Close with FALSE. With FALSE, an already-open request does
nothing and successful opening disables the button. Changing Toggle does
not immediately synchronize button-disabled state. A close requires
CloseHook to reset logical state.

MUIC_Popstring

Superclass

Group.mui

Description

Combine a caller-supplied button and optional string object in a
horizontal group with zero spacing. Successful construction places these
objects in the Group child hierarchy. No default button or string is
created. Supply a valid button; construction passes it as Child without
a NULL guard. The optional string pointer may be NULL only if the hooks
can handle it.
The button's Pressed FALSE notification invokes Open. OpenHook and
CloseHook are borrowed, default NULL; Toggle defaults FALSE. This base
class supplies hook dispatch and logical open state, not a popup window
or requester.

Methods

Setup delegates to Group and installs a raw-key event handler in the
containing window; Cleanup removes it before delegating. MUIKEY_POPUP
invokes Open and consumes the event regardless of opening success. Other
events return zero.
The open hook is synchronous. Close queues a CallHook through the
application and immediately resets logical open state and enables the
button. The queued call contains the hook pointer, string pointer and
result value. There is no local cancellation, queue-success check or
wait. Cleanup does not call Close or wait for queued hooks.

Notes

Keep the application, Popstring, children, hook structures and
referenced hook data alive through queued execution. Do not assume a
zero Open/Close result signals failure or completion. Avoid reopening
while a previous close callback remains queued: logical state has
already changed, but the old callback can still affect popup resources.
Hook replacement does not change a hook pointer already copied into a
queued call.
Only String has a local getter. The header's getter annotations for
Button, OpenHook, CloseHook and Toggle do not correspond to local getter
implementations.

MUIM_Popstring_Close

Synopsis

IPTR rc = DoMethod(obj, MUIM_Popstring_Close, result);

Function

Queue the close hook for a logically open popup.

Inputs

result - LONG passed to the close hook; subclasses commonly interpret

nonzero as accept and zero as cancel.

Result

Zero in all cases.

Notes

With CloseHook and logical open state, enqueue CallHook, clear that
state and enable the button immediately. The hook runs later through the
application; allocation/enqueue failure is not checked. With no hook or
already closed, do nothing. This is not an ASL abort or a synchronous
completion barrier.

MUIM_Popstring_Open

Synopsis

IPTR rc = DoMethod(obj, MUIM_Popstring_Open);

Function

Call the open hook or request a toggle-close.

Inputs

No additional arguments.

Result

Zero in all cases.

Notes

A nonzero synchronous OpenHook result sets logical open state and
disables the button when Toggle is FALSE. With no hook nothing happens.
If already open, Toggle TRUE requests Close(FALSE), otherwise nothing
happens. The public result does not expose the hook result.