Name
moai.CreateObject -- create MOAI object from an XML source
Synopsis
moai.CreateObject(xml$[, parent$])
Function
This function can be used to dynamically create a MOAI object from an XML source. When 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.

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.

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.

Inputs
xml$
a string containing an XML MOAI object description
parent$
optional: desired parent for the object; see above for details
Example
moai.CreateObject([[
<window id="newwindow" title="A new window">
  <vgroup>
      <button>Hello World!</button>
   </vgroup>
</window>
]])

mui.DoMethod("app", "addwindow", "newwindow")
mui.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")

mui.DoMethod("mygroup", "initchange")
mui.DoMethod("mygroup", "append", "newbutton")
mui.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".

Show TOC