3.7 Attribute notifications

RapaGUI's event handling is based on the values of certain attributes of the different MOAI classes. You can listen to the values of all attributes that have an applicability of N. If you set up a listener on an attribute value, RapaGUI will run your event callback whenever the attribute value changes.

For example, you could set up a listener on the Listview.Active attribute which contains the active item of a listview widget. If you do this, your event handler will be called whenever the active item of the respective listview widget changes. To install a listener on a certain attribute, you have to set up a notification for this attribute in your object declaration. This is done directly in the XML file by using the Notify attribute that is accepted by all MOAI classes:

 
<listview id="lv" notify="active">
   <column>
      <item>One</item>
      <item>Two</item>
      <item>Three</item>
   </column>
</listview>

The code above will run your event callback whenever the active item of the listview object that has the id lv changes because you've requested to listen to the value of the Listview.Active attribute.

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

 
<listview id="lv" notify="active; doubleclick">
...
</listview>

As you can see, the code above installs listeners on both attributes, Listview.Active and Listview.DoubleClick, so that your event callback is also invoked when the user double clicks on a listview entry.

Alternatively, you can also set up or remove notifications at run-time using the moai.Notify() function from your code.

To print the currently active listview item from your event handler, you could then use the following code:

 
Function p_EventHandler(msg)
    Switch msg.action
    Case "RapaGUI":
       Switch msg.attribute
       Case "Active":
          Switch msg.id
          Case "lv":
             DebugPrint("Active listview item:", msg.triggervalue)
          EndSwitch
       EndSwitch
    EndSwitch
EndFunction

Keep in mind, though, that attribute values can also be changed manually. For example, your program might want to manually activate a certain listview item by doing something like this:

 
moai.Set("lv", "active", 5)  ; activate item number 6

Since the call above changes the value of the Listview.Active attribute as well, your event handler callback will be triggered by this call, too. If you don't want this, you can use the special attribute MOAI.NoNotify in your call to moai.Set(). Whenever MOAI.NoNotify is set to True, the attribute's value will be changed without invoking any event handlers. Thus, to change the active listview item without triggering any event callbacks, you would just write:

 
moai.Set("lv", "active", 5, "nonotify", True)

Finally, as already mentioned in the previous section, there are some attributes that RapaGUI always listens to. These are: Button.Pressed, Button.Selected, Toolbarbutton.Pressed, Toolbarbutton.Selected, and Menuitem.Selected. Since these are so common and widely used and you will normally always want to listen to attributes like Button.Pressed because pressing a button will always cause a reaction, RapaGUI listens to them automatically. Thus, you don't have to explicitly request a notification on these attributes, i.e. writing the following is redundant:

 
<button id="btn" notify="pressed">Click me</button>

Instead, you can just write:

 
<button id="btn">Click me</button>

The same is true for menu items and toolbar buttons.

Show TOC