# cp.ui.Builder

A utility class, which provides support for allowing creation of Element instances in a "builder" style.

This is useful for creating complex UI elements, such as a Table or ScrollArea, which can have custom sub-elements.

A Builder instance can be called like a function, expecting a parent and uiFinder, which are the basic values required to create a new Element instance. Specific subclasses have extra values, which a Builder can define to pass in.

For example, a Table has a headerType and rowType in its constructor, which are used to create the header and row elements when required:

local myTable = cp.ui.Table(parent, uiFinder, Group, Row)

However, its quite common for a ScrollArea to contain a Table, and in order to use the ScrollArea:containing(Table) method, you would have to provide a wrapper function that hard-codes the headerType and rowType values:

local scrollArea = ScrollArea:containing(function(parent, uiFinder)
    return Table(parent, uiFinder, Group, Row)
end)

However, Table has its own helper method for this to make it easier to use:

local scrollArea = ScrollArea:containing(Table:withRowsOf(Row):withHeaderOf(Group))
scrollArea.contents.header -- A cp.ui.Group instance
scrollArea.contents.rows[1] -- A cp.ui.Row instance

Internally, the Table:withRowsOf(rowType) function returns a Builder configured to accept "withRowsOf" and "withHeaderOf" values, which are then passed to the Table constructor.

To create your own Builder instances, you can just return a new Builder, specifying the type (typically self) and the names of the constructor arguments to accept. For example:

local MyElement = Element:subclass("foo.MyElement")

function MyElement:initialize(parent, uiFinder, leftType, rightType)
    -- TODO
end

function MyElement.static:withLeftOf(leftType)
    return Builder(self, "withLeftOf", "withRightOf"):withLeftOf(leftType)
end

The Builder instance can then be used to create new MyElement instances:

local myElementBuilder = MyElement:withLeftOf(Group):withRightOf(Button)
local myElement = myElementBuilder(parent, uiFinder)

The order of the arguments is important, because it defines what order the constructor arguments will be passed in. For example, if we added a withRightOf method definition, it would look like this:

function MyElement.static:withRightOf(rightType)
    return Builder(self, "withLeftOf", "withRightOf"):withRightOf(rightType)
end
local myElementBuilder = MyElement:withRightOf(Group):withLeftOf(Button)

The "withLeftOf" value will still be passed to the constructor first, because it is listed first in the Builder constructor.

Methods - API calls which can only be made on an object returned by a constructor

• build