The Storyboard gredom Lua module provides a limited access to the hierarchical model
used by the Storyboard Engine. This functionality is provided as an external Lua module and is located
in the lib/gredom.so file of the Storyboard Engine target distributions.
The DOM module provides two sets of function interfaces. The first set of functions are associated with the gredom namespace and are used to lookup or access an Lua object (table) that contains a special set of methods (metatable entries) that are used to extract additional information about the object. In this documentation the object returned from the gredom namespace functions will be referred to as a DOMOBJECT object. Methods associated with the DOMOBJECT object must be invoked using the Lua colon (:) notation for example DOMOBJECT:get_name()
gre.get_application()
Get an object handle for the application root
Returns:
A DOMOBJECT object that represents the application.
gre.get_object(fqn)
Get an object handle for the
Parameters:
fqn The fully qualified name of the model entry (screen, layer, control), or a short name to
autosearch for a match
Returns:
A DOMOBJECT object that represents the named model object.
DOMOBJECT:get_name()
Gets the name of the specified DOM Object
Returns:
The name of the specified DOMOBJECT
DOMOBJECT:get_type()
Gets the Storyboard type of the specified DOMOBJECT. The type may be one of gredom.APP, gredom.SCREEN, gredom.LAYER, gredom.LAYER_INSTANCE, gredom.GROUP grecom.CONTROL, gredom.TABLE, gredom.TEMPLATE.
Returns:
A the type of the specified DOMOBJECT.
DOMOBJECT:get_parents()
Gets the parent DOMOBJECT objects for the specified DOMOBJECT. An array of parents is returned because in some cases, such as for a layer, there may be more than one parent representation.
Returns:
An array table containing the parent DOMOBJECT entries.
DOMOBJECT:get_children()
Gets the child DOMOBJECT objects for the specified DOMOBJECT. This function returns only the model objects and does not include the variables.
Returns:
An array table containing the child DOMOBJECT entries
DOMOBJECT:get_variables()
Gets variables associated with the specified DOMOBJECT
Returns:
An array table containing the variables associated with this object.
require("gredom")
-- Print a list of all of the user variables associated with a specified
-- control
function print_variables(control_name)
-- Get the DOM object for the control name passed in
local domObject = gredom.get_object(control_name)
if(domObject == nil) then
print("Can't find name for " .. tostring(control_name))
return
end
-- Get the variables defined on this DOM object
local vars = domObject:get_variables()
if(vars == nil or #vars == 0) then
print("No variables for " .. control_name)
else
print("Variables for " .. control_name)
for i=1,#vars do
print("# " .. tostring(vars[i]))
end
end
end
-- Print out all of the screens where this control's container layer is
-- being used
function print_used_on_screens(control_name)
-- Get the DOM object for the control name passed in
local domObject = gredom.get_object(control_name)
if(domObject == nil) then
print("Can't find name for " .. tostring(control_name))
return
end
-- Build up the full path to this object
-- Walk up the tree looking at all parents adding screens we find
local screen_list = {}
local parent_list = {}
table.insert(parent_list, domObject:get_parents())
local i = 1
while i <= #parent_list do
local parents = parent_list[i]
for p=1,#parents do
-- If this was a screen, add it to our collection
if parents[p]:get_type() == gredom.SCREEN then
screen_list[parents[p]] = true
else
-- If this has parents of its own, then add them to the search
-- list
parents = parents[p]:get_parents()
if(parents ~= nil and #parents > 0) then
table.insert(parent_list, parents)
end
end
end
i = i + 1
end
-- Print out all of the screens that we have identified
print(control_name .. " is used on the following screens:")
for screen,v in pairs(screen_list) do
print("# " .. screen:get_name())
end
end
-- Invoke our DOM example functions with the context control
function CBDom(mapargs)
print_used_on_screens(mapargs.context_control)
print_variables(mapargs.context_control)
end