suit/docs/layout.rst

Layout
======

.. note::
  Still under construction...

Immediate Mode Layouts
----------------------

.. function:: reset(x,y, pad_x, pad_y)

   :param numbers x,y: Origin of the layout (optional).
   :param pad_x,pad_y: Cell padding (optional).

Reset the layout, puts the origin at ``(x,y)`` and sets the cell padding to
``pad_x`` and ``pad_y``.

.. function:: padding(pad_x,pad_y)

   :param pad_x,pad_y: Cell padding.

Sets the cell padding to ``pad_x`` and ``pad_y``.

.. function:: push(x,y)

   :param numbers x,y: Origin of the inner layout (optional).

Saves the layout state (position, padding, sizes, etc.) on a stack and resets
the layout with position ``(x,y)``.

Used for nested row/column layouts.

.. function:: pop()

Restores the layout parameters from the stack and advances the layout position
according to the size of the popped layout.

Used for nested row/column layouts.

.. function:: row(w,h)

   :param mixed w,h: Cell width and height (optional).
   :returns: Position and size of the cell: ``x,y,w,h``.

Creates a new cell below the current cell with width ``w`` and height ``h``. If
either ``w`` or ``h`` is omitted, the value is set the last used value. Both
``w`` and ``h`` can be a string, which takes the following meaning:

``max``
   Maximum of all values since the last reset.

``min``
   Mimimum of all values since the last reset.

``median``
   Median of all values since the last reset.

Used to provide the last four arguments to a widget, e.g.::

    suit.Button("Start Game", suit.layout.row(100,30))
    suit.Button("Options", suit.layout.row())
    suit.Button("Quit", suit.layout.row(nil, "median"))

.. function:: col(w,h)

   :param mixed w,h: Cell width and height (optional).
   :returns: Position and size of the cell: ``x,y,w,h``.

Creates a new cell right to the current cell with width ``w`` and height ``h``.
If either ``w`` or ``h`` is omitted, the value is set the last used value. Both
``w`` and ``h`` can be a string, which takes the following meaning:

``max``
   Maximum of all values since the last reset.

``min``
   Mimimum of all values since the last reset.

``median``
   Median of all values since the last reset.

Used to provide the last four arguments to a widget, e.g.::

    suit.Button("OK", suit.layout.col(100,30))
    suit.Button("Cancel", suit.layout.col("max"))


Predefined Layouts
------------------

Apart from immediate mode layouts, you can specify layouts in advance.
The specification is a table of tables, where each inner table follows the
convention of :func:`row` and :func:`col`.
The result is a layout definition object that can be used to access the cells.

There are almost only two reasons to do so: (1) You know the area of your
layout in advance (say, the screen size), and want certain cells to dynamically
fill the available space; (2) You want to animate the cells.

.. note::
    Unlike immediate mode layouts, predefined layouts **can not be nested**.

Layout Specifications
^^^^^^^^^^^^^^^^^^^^^

Layout specifications are tables of tables, where the each inner table
corresponds to a cell. The inner tables define the width and height of the cell
according to the rules of :func:`row` and :func:`col`, with one additonal
keyword:

``fill``
   Fills the available space, determined by ``min_height`` or ``min_width`` and
   the number of cells with property ``fill``.

For example, this row specification makes the height of the second cell to
``(300 - 50 - 50) / 1 = 200``::

    {min_height = 300,
        {100, 50},
        {nil, 'fill'},
        {nil, 50},
    }

This column specification divides the space evenly among two cells::

    {min_width = 300,
        {'fill', 100}
        {'fill'}
    }

Apart from ``min_height`` and ``min_width``, layout specifications can also
define the position (upper left corner) of the layout using the ``pos`` keyword::

    {min_width = 300, pos = {100,100},
        {'fill', 100}
        {'fill'}
    }

Layout Definition Objects
^^^^^^^^^^^^^^^^^^^^^^^^^

Once constructed, the cells can be accessed in two ways:

- Using iterators::

    for i, x,y,w,h in definition() do
        suit.Button("Button "..i, x,y,w,h)
    end

- Using the ``cell(i)`` accessor::

    suit.Button("Button 1", definition.cell(1))
    suit.Button("Button 3", definition.cell(3))
    suit.Button("Button 2", definition.cell(2))

There is actually a third way: Because layout definitions are just tables, you
can access the cells directly::

    local cell = definition[1]
    suit.Button("Button 1", cell[1], cell[2], cell[3], cell[4])
    -- or suit.Button("Button 1", unpack(cell))

This is especially useful if you want to animate the cells, for example with a
`tween <http://hump.readthedocs.org/en/latest/timer.html#Timer.tween>`_::

    for i,cell in ipairs(definition)
        local destination = {[2] = cell[2]} -- save cell y position
        cell[2] = -cell[4] -- move cell just outside of the screen

        -- let the cells fall into the screen one after another
        timer.after(i / 10, function()
            timer.tween(0.7, cell, destination, 'bounce')
        end)
    end


Constructors
^^^^^^^^^^^^

.. function:: rows(spec)

   :param table spec: Layout specification.
   :returns: Layout definition object.

Defines a row layout.

.. function:: cols(spec)

   :param table spec: Layout specification.
   :returns: Layout definition object.

Defines a column layout.