MUIM_Notify

Add a notification event handler to an object

Declaration

Source position: mui.pas line 708

Description

DoMethod(obj, MUIM_Notify, [TrigAttr: LongWord, TrigVal: LongWord, DestObj: APTR, FollowParams: LongWord, ... );

TrigAttr

attribute that triggers the notification.

TrigValue

value that triggers the notification. The special value MUIV_EveryTime makes MUI execute the notification method every time when TrigAttr changes. In this case, the special value MUIV_TriggerValue in the notification method will be replaced with the value that TrigAttr has been set to. You can use MUIV_TriggerValue up to four times in one notification method. Since version 8 of muimaster.library, you can also use MUIV_NotTriggerValue here. In this case, MUI will replace True values with False and False values with True. This can become quite useful when you try to set "negative" attributes like MUIA_Disabled.

DestObj

object on which to perform the notification method. Either supply a valid object pointer or one of the following special values (V10) which will be resolved at the time the event occurs: MUIV_Notify_Self - notifies the object itself. MUIV_Notify_Window - notifies the object's parent window. MUIV_Notify_Application - notifies the object's application.

FollowParams

number of following parameters. If you e.g. have a notification method with three parts (maybe MUIM_Set,attr,val), you have to set FollowParams to 3. This allows MUI to copy the complete notification method into a private buffer for later use.

...

following is the notification method.

Add a notification event handler to an object. Notification is essential for every MUI application.

A notification statement consists of a source object, an attribute/value pair, a destination object and a notification method. The attribute/value pair belongs to the source object and determines when the notification method will be executed on the destination object.

Whenever the source object gets the given attribute set to the given value (this can happen because of the user pressing some gadgets or because of your program explicitly setting the attribute with SetAttrs()), the destination object will execute the notification method.

With some special values, you can trigger the notification every time the attribute is changing. In this case, you can include the triggering attributes value within the notification method. See below.

One big problem with notification are endless loops. Imagine you have a prop gadget and want to show its state with a gauge object. You connect MUIA_Prop_First with MUIA_Gauge_Max and everything is fine, the gauge gets updated when the user drags around the gadget. On the other hand, if your program sets the gauge to a new value, you might want your prop gadget to immediately show this change and connect MUIA_Gauge_Max width MUIA_Prop_First. Voila, a perfect endless loop.

To avoid these conditions, MUI always checks new attribute values against the current state and cancels notification when both values are equal. Thus, setting MUIA_Prop_First to 42 if the prop gadgets first position is already 42 won't trigger any notification event.