Widgets
=======

.. note::
  Still under construction...

Immutable Widgets
-----------------

.. function:: Button(text, [options], x,y,w,h)

   :param string text: Button label.
   :param table options: Optional settings (see below).
   :param numbers x,y: Upper left corner of the widget.
   :param numbers w,h: Width and height of the widget.o
   :returns: Return state (see below).

Creates a button widget at position ``(x,y)`` with width ``w`` and height
``h``.

.. function:: Label(text, [options], x,y,w,h)

   :param string text: Label text.
   :param table options: Optional settings (see below).
   :param numbers x,y: Upper left corner of the widget.
   :param numbers w,h: Width and height of the widget.o
   :returns: Return state (see below).

Creates a label at position ``(x,y)`` with width ``w`` and height ``h``.

.. function:: ImageButton(normal, options, x,y)

   :param Image normal: Image of the button in normal state.
   :param table options: Widget options.
   :param numbers x,y: Upper left corner of the widget.
   :returns: Return state (see below).

Creates an image button widget at position ``(x,y)``.
Unlike all other widgets, an ``ImageButton`` is not affected by the current
theme.
The argument ``normal`` defines the image of the normal state as well as the
area of the widget: The button activates when the mouse is over a pixel with
non-zero alpha value.
You can provide additional ``hovered`` and ``active`` images, but the widget area
is always computed from the ``normal`` image.

**Additional Options:**

``normal``
   Image for the normal state of the widget. Defaults to widget payload.

``hovered``
   Image for the hovered state of the widget. Defaults to ``normal`` if omitted.

``active``
   Image for the active state of the widget. Defaults to ``hovered`` if omitted.

.. note::

  ``ImageButton`` does not recieve width and height parameters.  As such, it
  does not necessarily honor the cell size of a :doc:`layout`.

.. note::

  Unlike other widgets, ``ImageButton`` is tinted by the currently active
  color.  If you want the button to appear untinted, make sure the active color
  is set to white before adding the button, e.g.::

    love.graphics.setColor(255,255,255)
    suit.ImageButton(push_me, {hovered=and_then_just, active=touch_me},
                     suit.layout:row())

Mutable Widgets
---------------

.. function:: Checkbox(checkbox, [options], x,y,w,h)

   :param table checkbox: Checkbox state.
   :param table options: Optional settings (see below).
   :param numbers x,y: Upper left corner of the widget.
   :param numbers w,h: Width and height of the widget.o
   :returns: Return state (see below).

Creates a checkbox at position ``(x,y)`` with width ``w`` and height ``h``.

**State:**

``checkbox`` is a table with the following components:

``checked``
   ``true`` if the checkbox is checked, ``false`` otherwise.

``text``
   Optional label to show besides the checkbox.

.. function:: Slider(slider, [options], x,y,w,h)

   :param table slider: Slider state.
   :param table options: Optional settings (see below).
   :param numbers x,y: Upper left corner of the widget.
   :param numbers w,h: Width and height of the widget.o
   :returns: Return state (see below).

Creates a slider at position ``(x,y)`` with width ``w`` and height ``h``.
Sliders can be horizontal (default) or vertical.

**State:**

``value``
   Current value of the slider. Mandatory argument.

``min``
   Minimum value of the slider. Defaults to ``min(value, 0)`` if omitted.

``max``
   Maximum value of the slider. Defaults to ``min(value, 1)`` if omitted.

``step``
   Value stepping for keyboard input. Defaults to ``(max - min)/10`` if omitted.

**Additional Options:**

``vertical``
   Whether the slider is vertical or horizontal.

**Additional Return State:**

``changed``
   ``true`` when the slider value was changed, ``false`` otherwise.


.. function:: Input(input, [options], x,y,w,h)

   :param table input: Checkbox state
   :param table options: Optional settings (see below).
   :param numbers x,y: Upper left corner of the widget.
   :param numbers w,h: Width and height of the widget.o
   :returns: Return state (see below).

Creates an input box at position ``(x,y)`` with width ``w`` and height ``h``.
Implements typical movement (arrow keys, home and end key) and editing
(deletion with backspace and delete) facilities.

**State:**

``text``
   Current text inside the input box. Defaults to the empty string if omitted.

``cursor``
   Cursor position. Defined as the position before the character (including
   EOS), so ``1`` is the position before the first character, etc. Defaults to
   the end of ``text`` if omitted.

**Additional Return State:**

``submitted``
   ``true`` when enter was pressed while the widget has keyboard focus.


Common Options
--------------

``id``
   Identifier of the widget regarding user interaction. Defaults to the first
   argument (e.g., ``text`` for buttons) if omitted.

``font``
   Font of the label. Defaults to the current font (``love.graphics.getFont()``).

``align``
   Horizontal alignment of the label. One of ``"left"``, ``"center"``, or
   ``"right"``. Defaults to ``"center"``.

``valign``
   Vertical alignment of the label. On of ``"top"``, ``"middle"``, or
   ``"bottom"``. Defaults to ``"middle"``.

``color``
   A table to overwrite the color. Undefined colors default to the theme colors.

``cornerRadius``
  The corner radius for boxes. Overwrites the theme corner radius.

``draw``
   A function to replace the drawing function. Refer to :doc:`themes` for more information about the function signatures.


Common Return States
--------------------

``id``
   Identifier of the widget.

``hit``
   ``true`` if the mouse was pressed and released on the button, ``false``
   otherwise.

``hovered``
   ``true`` if the mouse is above the widget, ``false`` otherwise.

``entered``
   ``true`` if the mouse entered the widget area, ``false`` otherwise.

``left``
   ``true`` if the mouse left the widget area, ``false`` otherwise.
