Child Method

The Child method allows you to access the child elements of stacks, sections, and tables without having to explicitly name each element. For example,

<stack name="myStack">
  <p name="par1">Words in the first paragraph</p>
  <p>Words in the second paragraph</p>
</stack>

The above stack contains two paragraphs, which can be referenced using myStack:Child(1) and myStack:Child(2), respectively. To change the text of the first paragraph, use myStack:Child(1) in the same way that you would use the name and scope of the paragraph element, i.e.

<script>
   myStack.par1.Text = "New words in the first paragraph"
   -- is the same as
   myStack:Child(1).Text = "New words in the first paragraph"
</script>

The child method helps to reduce code when altering many child elements programmatically. See below for two common use cases.

Tables

The first use case allows you to access the cells of a table through a function. In the below example, a function is used to fill out the table cells. A similar method can be used to read the table cell values.

<script>
  function fillOutTable()
   for i = 2,3 do
    for j = 1,3 do
      myTable:Child(i):Child(j):Child(1).Text = string.format("(%d, %d)", i-1,j)
    end
   end
  end
</script>

<table name="myTable" widths="33% 33% 34%">
  <head>
    <column>
      <p>Column 1</p>
    </column>
    <column>
      <p>Column 2</p>
    </column>
    <column>
      <p>Column 3</p>
    </column>
  </head>
  <row>
    <column>
      <p />
    </column>
    <column>
      <p />
    </column>
    <column>
      <p />
    </column>
  </row>
  <row>
    <column>
      <p />
    </column>
    <column>
      <p />
    </column>
    <column>
      <p />
    </column>
  </row>
</table>

Calling the fillOutTable() method from a button results in

The index i in the above example starts at 2 because the <head> element is the first child in the table.

Radio Buttons

The second use case allows you to create radio-like buttons by altering the colour of the selected and deselected buttons.

<style name="setButtons">
  <foreground color="white" />
  <background color="gainsboro" />
</style>

<script>
  local priorSelection = -1;

  function chooseButton(i)
    if priorSelection > 0 then
      stack:Child(priorSelection).Style.BackgroundColor = color.gainsboro;
    end
    stack:Child(i).Style.BackgroundColor = color.seaGreen;
    priorSelection = i;
  end
</script>

<stack name="stack" orientation="horizontal">
  <button content="One" style="setButtons">
    <onClick>
      chooseButton(1)
    </onClick>
  </button>
  <button content="Two" style="setButtons">
    <onClick>
      chooseButton(2)
    </onClick>
  </button>
  <button content="Three" style="setButtons">
    <onClick>
      chooseButton(3)
    </onClick>
  </button>
</stack>

Note that children elements are 1-indexed, where the first element is Child(1) and not Child(0). Styles do not count as children.