Most applications create their GUI by a simple call to moai.CreateApp() which is passed an XML declaration that contains the complete user interface of the whole application. In some situations, though, it might be necessary to create MOAI objects after the call to moai.CreateApp() and insert them into the existing application.
This is possible by using the moai.CreateObject() API. This function allows you to create a MOAI object from an XML declaration, pretty similar to what moai.CreateApp() does except that moai.CreateObject() doesn't allow you to create an application because there can be only one application.
For example, you can create a button using moai.CreateObject() like this:
moai.CreateObject([[<button id="mybutton">Click me</button>]]) |
It is very important to set an identifer for the MOAI object you create using moai.CreateObject() because the identifier is needed to refer to the object later. Now that we have created the button we could insert it into an existing window layout. Let's suppose our window layout currently looks like this:
<window>
<hgroup id="mygroup">
<button id="ok">OK</button>
<button id="cancel">Cancel</button>
</hgroup>
</window>
|
We could now use the Group.Insert method to insert the newly created button after the "OK" button. We would have to use the following code to do that:
moai.DoMethod("mygroup", "initchange")
moai.DoMethod("mygroup", "insert", "mybutton", "ok")
moai.DoMethod("mygroup", "exitchange")
|
You can see that we're also calling the methods Group.InitChange and Group.ExitChange. This is very important. Those methods have to be run whenever you change the children of a group, i.e. you remove or add children. RapaGUI needs you to call these methods because after removing or adding group children a window relayout becomes necessary. That's why simply calling Group.Insert or any other method that changes the number of group children isn't enough.
Of course, we can also remove children from groups. This is possible by using Group.Remove. The following code removes the "Cancel" button from the above window layout:
moai.DoMethod("mygroup", "initchange")
moai.DoMethod("mygroup", "remove", "cancel")
moai.DoMethod("mygroup", "exitchange")
|
After this call, the MOAI object with the id "cancel" has become a detached object. This means that you could also attach it to a group now again by using Group.Insert or a similar method. Note that all methods which insert MOAI objects into existing layouts only accept detached objects. It's not possible to insert the same MOAI object into multiple groups. As soon as you insert a MOAI object into a group (or menu tree), it changes its state from detached to attached. Once a MOAI object is in attached state, it can no longer be passed to methods which expect a detached object. In order to turn a MOAI object from attached to detached state, you need to use a method like Group.Remove to detach a MOAI object from a group.
As a final note, the XML code you pass to moai.CreateObject() can also be a complete tree, e.g. you could create a complete window with just a single call to moai.CreateObject(). This is all possible. moai.CreateObject() isn't limited to creating single MOAI objects but it can create multiple objects for you as well. When you're creating a window or dialog with moai.CreateObject(), though, don't forget to add it to the application object by calling Application.AddWindow since window objects are also in detached state by default unless they have been added to an application object. For dialogs, you can just use moai.CreateDialog() which will implicitly call Application.AddWindow.