moai.CreateObject(xml$[, parent$])
moai.CreateObject() returns, the newly created MOAI object won't be attached
to any parent object and will live in a state of isolation from your application
object created by moai.CreateApp(). Thus, to break this state
of isolation you first have to attach the object to a parent object which can be
either a group object, a menu object, or an application object. If your newly allocated MOAI object
is a window object, you will have to to attach it to the application object by using the
Application.AddWindow method. To attach menu objects you have to use the
Menubar.Prepend, Menubar.Append, Menubar.Insert,
Menu.Prepend, Menu.Append, or Menu.Insert methods.
All other objects can be attached by using the group methods Group.Prepend,
Group.Append and Group.Insert.
For most MOAI classes you have to specify a parent object in the second parameter. RapaGUI won't attach the new object to the parent but it still needs to know the parent for determining certain settings. The only MOAI classes which do not require you to specify a parent object are the following:
All other MOAI classes require you to specify the identifier of the parent object.
Normally, you just have to pass the identifier of the window that you want to
attach the MOAI object to as the parent. There is one exception: If you plan to
add the MOAI object to a group with a frame, i.e. an instance of Group class
with Group.Frame set to True, then you have to pass this group object
as the parent. Note that this only applies to groups with a frame. If you plan
to add the MOAI object to a normal group that doesn't have a frame, you just have
to pass the identifier of the window to moai.CreateObject(). Note,
though, that in case the normal group is itself just a child embedded somewhere
in the hierarchy of a framed group, then you have to pass the identifier of the
framed group. Also, when adding objects to scrollgroups, you need to pass the
scrollgroup as the parent.
To put it in abstract terms: The parent must be set to the next object in the layout hierarchy that has a visual representation. Normal groups are just layout tools, they don't exist as widgets. Framed groups, however, are layout tools but they are also widgets since they have a visual representation. Thus, if your object is going to be embedded somewhere in a framed group, the framed group must be passed as the parent. If it is embedded in a normal group, then the top-level window must be the parent. Don't forget to think in hierarchies: Even if you want to attach your object to a normal group it could still be the case that the normal group is itself embedded in a framed group which means that you would still have to pass the framed group as the parent. The same applies to scrollgroups since they also have a visual representation.
In contrast to moai.CreateApp() you can call moai.CreateObject()
as often as you like as it doesn't create an application object for you but just
detached MOAI objects of which you can have as many as you like.
It is important that you specify an ID for your MOAI object in the XML declaration because you need this ID to refer to this object when you want to add it to an application, menu or group object.
Once this function returns, you can talk to the newly created MOAI object (and to all of its children) using the moai.Set(), moai.Get() and moai.DoMethod() functions.
Detached MOAI objects can be freed using the moai.FreeObject() function but you only have to call this in specific cases, e.g. if you are dealing with lots of dynamically allocated MOAI objects and you want to do some housekeeping to save on memory and resources.
moai.CreateObject([[
<window id="newwindow" title="A new window">
<vgroup>
<button id="btn">Hello World!</button>
</vgroup>
</window>
]])
moai.DoMethod("app", "addwindow", "newwindow")
moai.Set("newwindow", "open", True)
The code above creates a new window, adds it to the existing application object and
opens it.
moai.CreateObject([[
<button id="newbutton">Dynamically created button!</button>
]], "mywindow")
moai.DoMethod("mygroup", "initchange")
moai.DoMethod("mygroup", "append", "newbutton")
moai.DoMethod("mygroup", "exitchange", false)
The code above dynamically creates a new button object and adds it as the last
child to the group that has the ID "mygroup".