Notify.mui

MUIA_AppMessage

Function

Return the last message pointer stored by OM_SET. The constructor

ignores this tag. Initial value is NULL.

Inputs

Pointer to struct AppMessage; declared get only.

Notes

AROS also accepts this tag in OM_SET despite the header access flags.
The pointer is borrowed: Notify neither copies, replies to, nor frees
the message. Keep it valid while accessing it; storage here does not
extend its lifetime.

MUIA_ApplicationObject

Function

Return the application pointer from the current global-info structure,

or NULL if that structure is absent. The returned object is borrowed.

Inputs

Object pointer; get only.

Notes

DisconnectParent does not clear global info in this implementation. A

non-NULL result is not proof that the application is still alive.

MUIA_HelpLine

Function

Store a help-line value; the initial value is zero. Notify stores and

returns it without validation.

Inputs

LONG; initialize, set, get.

Notes

Notify does not display help or interpret this value.

MUIA_HelpNode

Function

Store a borrowed help-node string pointer; the initial value is NULL.

Inputs

STRPTR; initialize, set, get.

Notes

The string is not copied or freed. Keep its storage valid while the

attribute refers to it. Notify does not open or interpret the help node.

MUIA_NoNotify

Function

Suppress this OM_SET call's entire notification pass if any supplied
MUIA_NoNotify tag has the value TRUE. Attribute storage still takes
place.

Inputs

BOOL; set only.

Notes

The flag is local to one call and is not stored. A FALSE tag later in
the same list does not cancel suppression. The comparison is exactly
against TRUE, not against any nonzero value. Notify has no getter for
this attribute.

MUIA_ObjectID

Function

Store an object identifier; the initial value is zero. Values are

converted to ULONG.

Inputs

ULONG; initialize, set, get.

Notes

Notify does not enforce uniqueness or persist data under this
identifier. Its Import and Export methods are stubs; persistence depends
on subclasses.

MUIA_Parent

Function

Return the stored parent pointer, initially NULL. The pointer is

borrowed.

Inputs

Object pointer; get only.

Notes

Notify's ConnectParent and DisconnectParent do not update this field.
Containers maintain it separately. Do not infer ownership or continued
parent lifetime solely from a non-NULL value.

MUIA_Revision

Function

Return 1 for Notify itself.

Inputs

LONG; get only.

Notes

Subclasses can override this attribute. This value describes the class,

not the library.

MUIA_UserData

Function

Store an uninterpreted application value, initially zero. Pointer-sized

values are preserved by Notify.

Inputs

IPTR storage; initialize, set, get.

Notes

The header annotation says ULONG, but mnd_UserData and the setter/getter
use IPTR. No referenced memory is owned or freed. MUIM_GetUData is an
exception: its declared udata input is ULONG; other Notify user-data
search/set messages use IPTR.

MUIA_Version

Function

Return 1 for Notify itself.

Inputs

LONG; get only.

Notes

Subclasses can override this attribute. Do not use it to infer the

muimaster.library version or availability of methods on another class.

MUIC_Notify

Superclass

rootclass

Description

Provide attributes, synchronous notifications, user-data matching, and
utility methods for Zune objects. This class has no child traversal;
container subclasses may extend the user-data methods.
Construction allocates private attribute storage and returns NULL if
allocation or superclass construction fails. Omitted HelpLine, ObjectID,
and UserData values start at zero; HelpNode, AppMessage, parent, and
global-info pointers start at NULL. Disposal frees local notification
records and attribute storage. It does not dispose of notification
destinations or free borrowed strings and messages.
Serialize access to the object and its notification list. Notifications
execute in the calling task during attribute setting; this class
provides no locking, queue, or cancellation timeout.

Notes

All method entries describe the Notify implementation. A subclass may
override its behavior or return values. Version and Revision both return
1 here; they are class values, not muimaster.library version numbers.
An OM_SET first stores recognized attributes, then examines the supplied
tags for notifications in tag order and registration order. Unchanged
values can still trigger a notification. Attributes not stored by Notify
can still be trigger attributes when their tags reach this method.
Notify returns zero from OM_SET and does not forward it to rootclass.

Bugs

Notification dispatch does not protect its current list node against
deletion by a callback. Do not dispose of the source object or remove
active notification records during notification dispatch. Suppression of
recursive delivery for one active record is not a lifetime guard.

Example

Copy each UserData tag value to ObjectID on the same object:

DoMethod(obj, MUIM_Notify, MUIA_UserData, MUIV_EveryTime,

MUIV_Notify_Self, 3, MUIM_Set, MUIA_ObjectID,

MUIV_TriggerValue);

MUIM_CallHook

Synopsis

IPTR result = DoMethod(obj, MUIM_CallHook, (IPTR)hook, param1);

Function

Invoke the hook synchronously with obj as the hook object and the

address of param1 as its message.

Inputs

hook - Non-NULL readable Hook structure.
param1 - First IPTR of the hook-specific message; append further
arguments as required by the hook.

Result

The hook result, or FALSE if h_Entry is NULL.

Notes

No argument storage is copied or retained. The hook must not retain
pointers into the transient method message. A NULL hook pointer is not
checked.

MUIM_ConnectParent

Synopsis

IPTR result = DoMethod(obj, MUIM_ConnectParent, (IPTR)parent);

Function

Copy the parent's global-info pointer into this object.

Inputs

parent - Non-NULL live object with Notify-compatible instance data.

Result

Always TRUE after copying the pointer.

Notes

This borrows the global-info structure; it does not retain the parent or
application. Notify does not set MUIA_Parent, insert the object into a
container, or propagate the connection to children. Containers provide
those operations separately.

MUIM_DisconnectParent

Synopsis

IPTR result = DoMethod(obj, MUIM_DisconnectParent);

Function

Return without changing this object's connection fields.

Inputs

No arguments beyond MethodID.

Result

Always zero; no disconnection work is performed by Notify.

Notes

AROS deliberately retains the global-info pointer here. This method also
leaves MUIA_Parent unchanged. Container methods may clear their parent
field separately. The retained pointer does not keep the application or
configuration object alive.

MUIM_Export

Synopsis

IPTR result = DoMethod(obj, MUIM_Export, (IPTR)dataspace);

Function

Return TRUE without reading or writing any state. Notify implements this

method as a stub in its dispatcher.

Inputs

dataspace - Declared Dataspace object argument; ignored by Notify.

Result

Always TRUE. This does not mean that state was transferred.

Notes

Subclasses must implement their own persistence. Notify does not

traverse children or use MUIA_ObjectID here.

MUIM_FindUData

Synopsis

IPTR result = DoMethod(obj, MUIM_FindUData, udata);

Function

Compare this object's MUIA_UserData with udata.

Inputs

udata - IPTR value to match.

Result

The borrowed object pointer on equality; zero otherwise.

Notes

Only this object is examined. A container subclass may also search

children. The result does not transfer ownership or retain the object.

MUIM_GetConfigItem

Synopsis

IPTR result = DoMethod(obj, MUIM_GetConfigItem, id, (IPTR)storage);

Function

Look up id with MUIM_Dataspace_Find on the configuration object

referenced by this object's global info.

Inputs

id - ULONG record identifier.
storage - Writable IPTR location for the payload pointer.
obj - Object with live global info and a valid mgi_Configdata object.

Result

TRUE and a borrowed payload pointer in storage if found; FALSE with

storage unchanged otherwise.

Notes

No payload length is returned. Do not free the pointer.
Configuration-record replacement, removal, or disposal can invalidate
it; coordinate its use with changes to the configuration dataspace.

Bugs

The method dereferences global info without checking for NULL. It is not
safe on an unconnected object merely because the object supports Notify
methods.

MUIM_GetUData

Synopsis

IPTR result = DoMethod(obj, MUIM_GetUData, udata, attr, (IPTR)storage);

Function

If UserData matches, request attr from this object into storage.

Inputs

udata - ULONG comparison value in struct MUIP_GetUData.
attr - Attribute identifier.
storage - Writable IPTR result location, required on a match.

Result

TRUE for a UserData match, FALSE otherwise. The attribute getter's

success result is ignored.

Notes

No match leaves storage untouched. On a match, an unsupported getter may
also leave it unchanged; TRUE is not proof of a valid attribute result.
Only this object is examined.

MUIM_Import

Synopsis

IPTR result = DoMethod(obj, MUIM_Import, (IPTR)dataspace);

Function

Return TRUE without reading or writing any state. Notify implements this

method as a stub in its dispatcher.

Inputs

dataspace - Declared Dataspace object argument; ignored by Notify.

Result

Always TRUE. This does not mean that state was transferred.

Notes

Subclasses must implement their own persistence. Notify does not

traverse children or use MUIA_ObjectID here.

MUIM_KillNotify

Synopsis

IPTR result = DoMethod(obj, MUIM_KillNotify, TrigAttr);

Function

Remove and free the first registered notification whose trigger

attribute matches TrigAttr.

Inputs

TrigAttr - ULONG trigger-attribute identifier.

Result

1 if a record was removed; 0 if none matched or no notification list

exists.

Notes

It does not remove all matching records. Repeat outside notification
dispatch if all matches must be removed. The destination object remains
caller-owned.

Bugs

Removing an active record, or disposing of its source during a callback,

can invalidate notification dispatch's pointers.

MUIM_KillNotifyObj

Synopsis

IPTR result = DoMethod(obj, MUIM_KillNotifyObj, TrigAttr, (IPTR)dest);

Function

Remove the first notification with both the specified trigger attribute

and stored destination.

Inputs

TrigAttr - ULONG trigger-attribute identifier.

dest - The exact destination value supplied at registration.

Result

1 if a record was removed; 0 if no record matched.

Notes

Destination comparison uses the stored value, not its resolved target.
For a Self registration, use MUIV_Notify_Self, not the object pointer.
Only one record is removed; no destination object is disposed of.

Bugs

Do not remove notification records during notification dispatch; its

list traversal is not protected against deletion.

MUIM_MultiSet

Synopsis

IPTR result = DoMethod(obj, MUIM_MultiSet, attr, val, (IPTR)first, ...,
(IPTR)NULL);

Function

Set one attribute on each object in a NULL-terminated list, in list

order.

Inputs

attr - Attribute identifier.
val - IPTR value.
first, ... - Live destination object pointers followed by NULL. A NULL
first entry gives an empty list.

Result

Always TRUE after traversing the list, including an empty list.

Individual setter return values are ignored.

Notes

The call can synchronously trigger notifications on every destination.
It does not retain the objects or copy data referenced by val. A missing
terminator causes reads beyond the method message.

MUIM_NoNotifySet

Synopsis

IPTR result = DoMethod(obj, MUIM_NoNotifySet, attr, val);

Function

Call SetAttrs with MUIA_NoNotify set to TRUE and the requested

attribute/value pair.

Inputs

attr - Attribute identifier.

val - IPTR attribute value.

Result

The SetAttrs result. Notify's own OM_SET returns zero even when it

stores the value.

Notes

Suppression applies to Notify's notification pass for this set call.
Subclass behavior and setter side effects still apply; this is not a
persistent notification-disable switch.

MUIM_Notify

Synopsis

IPTR result = DoMethod(obj, MUIM_Notify, TrigAttr, TrigVal,
(IPTR)DestObj, FollowParams, ...);

Function

Append a notification that sends a copied method message when a matching

tag reaches Notify's OM_SET.

Inputs

TrigAttr - ULONG attribute identifier.
TrigVal - IPTR value to match, or MUIV_EveryTime. For
MUIA_Window_InputEvent with a non-EveryTime value, supply a readable
ParseIX description string instead.
DestObj - Live object pointer, MUIV_Notify_Self,
MUIV_Notify_Application, or MUIV_Notify_Window.
FollowParams - Number of following IPTR words, including the destination
MethodID; must be at least 1. Supply exactly that many words.
... - Destination MethodID followed by its arguments.

Result

TRUE if the notification was registered; FALSE for fewer than one follow
word, allocation failure, or an invalid input-event description. No
destination call is made during registration.

Notes

The method words are copied; pointed-to objects and data are not. Keep
those live until no registered notification can use them. Duplicate
registrations are accepted and run in registration order. Sizes must fit
the ULONG allocation calculation; there is no overflow check.
For MUIV_EveryTime only, argument words after MethodID equal to
MUIV_TriggerValue or MUIV_NotTriggerValue are replaced with the current
tag value or its logical negation. An ordinary fixed-value notification
does not substitute these markers.
Self resolves to the source object. Application requires live global
info. Window requires an Area-compatible object with valid render-info
storage; delivery is skipped when that pointer is NULL. A record already
executing is skipped on recursive delivery; other records may still run.
Destination method results are ignored.

Bugs

MUIV_Notify_Parent is declared in the header but has no special handling
in this implementation. It falls through as a literal destination
pointer and must not be used as a selector. Application resolution does
not check global info for NULL. Do not remove active records or dispose
of the source from a notification callback.

MUIM_Set

Synopsis

IPTR result = DoMethod(obj, MUIM_Set, attr, val);

Function

Set one attribute on this object through the normal setter.

Inputs

attr - Attribute identifier.

val - IPTR attribute value.

Result

The setter result. Notify's OM_SET returns zero even after storing

recognized attributes.

Notes

This can deliver notifications synchronously. Ownership and copying of

data referenced by val depend on the target attribute.

MUIM_SetAsString

Synopsis

IPTR result = DoMethod(obj, MUIM_SetAsString, attr, (IPTR)format, val,
...);

Function

Format a temporary string with RawDoFmt, set attr to its pointer, then

immediately free the string.

Inputs

attr - String attribute whose setter consumes or copies the string
during the call.
format - Readable RawDoFmt format string.
val, ... - Arguments in the RawDoFmt data-stream layout required by the
format and target ABI; not a printf va_list.

Result

FALSE if temporary-string allocation fails; otherwise TRUE. The

attribute setter's result is ignored.

Notes

The format is processed twice, first to count output bytes and then to
write them. Keep the format and arguments valid and consistent across
both passes. The final length must fit LONG and the allocation size.

Bugs

Do not use this method with an attribute that merely borrows the
supplied string, including Notify's MUIA_HelpNode: the stored pointer
would refer to freed memory after return.

MUIM_SetUData

Synopsis

IPTR result = DoMethod(obj, MUIM_SetUData, udata, attr, val);

Function

Set attr to val if this object's MUIA_UserData matches udata.

Inputs

udata - IPTR comparison value.
attr - Attribute identifier.
val - IPTR attribute value.

Result

TRUE on a UserData match, FALSE otherwise. The setter result is ignored.

Notes

Notify examines only itself and uses the same implementation for
SetUData and SetUDataOnce. A container may override these methods to
visit all matches or stop after the first match. Normal setter
notifications can run synchronously.

MUIM_SetUDataOnce

Synopsis

IPTR result = DoMethod(obj, MUIM_SetUDataOnce, udata, attr, val);

Function

Set attr to val if this object's MUIA_UserData matches udata.

Inputs

udata - IPTR comparison value.
attr - Attribute identifier.
val - IPTR attribute value.

Result

TRUE on a UserData match, FALSE otherwise. The setter result is ignored.

Notes

Notify examines only itself and uses the same implementation for
SetUData and SetUDataOnce. A container may override these methods to
visit all matches or stop after the first match. Normal setter
notifications can run synchronously.

MUIM_WriteLong

Synopsis

IPTR result = DoMethod(obj, MUIM_WriteLong, val, (IPTR)memory);

Function

Write val to the ULONG location addressed by memory.

Inputs

val - ULONG value.

memory - Non-NULL, suitably aligned, writable ULONG pointer.

Result

Always TRUE after the write.

Notes

This writes one ULONG, not an IPTR-sized value on 64-bit targets. No
bounds, alignment, or NULL checks are performed. Ownership of memory
does not change.

MUIM_WriteString

Synopsis

IPTR result = DoMethod(obj, MUIM_WriteString, (IPTR)str, (IPTR)memory);

Function

Copy the complete NUL-terminated string with strcpy.

Inputs

str - Readable NUL-terminated source string.
memory - Writable destination with room for the string and its
terminating NUL; source and destination must not overlap.

Result

Always TRUE after the copy.

Notes

No size or NULL checks are performed. The caller retains both buffers;

the method neither allocates nor frees storage.