3.6 Notifications

The central element for controlling a MUI application is the notification mechanism. To understand how it works, it's important to know that most objects feature lots of attributes that define their current state. Notification makes it possible to react on changes of these attributes.

Attributes are changed either directly by the programmer (with a call to mui.Set()) or by the user manipulation of some gadgets. If he e.g. changes the active entry of a cycle gadget, the Cycle.Active attribute will continously be updated and reflect the currently active entry.

If you want to be informed whenever the value of a certain object attribute changes, you first have to setup a notification for this attribute in your object declaration. This is done directly in the XML file by using the "Notify" tag:

 
<cycle id="mycycle" notify="active">
   <item>One</item>
   <item>Two</item>
   <item>Three</item>
</cycle>

If you want to listen to multiple notifications on the same MUI object, you have to separate them using semicolons, e.g.:

 
<cycle id="mycycle" notify="active; appmessage">
...
</cycle>

Note that you can also setup or remove notifications at run-time using the mui.Notify() function from your code.

The next thing you have to do is setup an event handler for events from MUI Royale using the InstallEventHandler() Hollywood function. You have to pass a Hollywood function that shall act as an event handler to the InstallEventHandler() function. Here is an example:

 
InstallEventHandler({MUIRoyale = p_MUIHandler})

Whenever a MUI event occurs, MUI Royale will then call the event handler callback function that you passed to InstallEventHandler(). The function will receive a table as its parameter with the following fields initialized:

Action:
Initialized to "MUIRoyale".

Class:
Contains the name of the MUI class this event comes from, e.g. "Cycle".

Attribute:
Contains the name of the class attribute that has triggered the event, e.g. "Active".

ID:
Contains the ID of the MUI object that triggered this event, e.g. "mycycle".

TriggerValue:
Contains the current value of the attribute that triggered this event. You could also find this out by doing a mui.Get() on the object but it is more convenient to get the current value directly to your event callback.

MUIUserData:
If the object was assigned certain userdata, it will be passed to the event handler callback in this tag. See Notify.UserData for details.

NotifyData:
If the object was assigned certain notify data, it will be passed to the event handler callback in this tag. See Notify.NotifyData for details.


Show TOC