Add documentation

docs/widgets.rst

@@ -0,0 +1,186 @@
+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(options, x,y)
+
+   :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 options table must at least contain an image for the ``normal`` state.
+The pixels with non-zero alpha value define the active area of the widget.
+You can provide additional ``hot`` and ``active`` images, but the widget area
+is always computed from the ``normal`` image.
+
+Note that ``ImageButton`` does not recieve width and height parameters. As
+such, it does not necessarily honor the cell size of a :doc:`layout`.
+
+**Additional Options:**
+
+``normal``
+   Image for the normal state of the widget. Mandatory.
+
+``hot``
+   Image for the hot state of the widget. Defaults to ``normal`` if omitted.
+
+``active``
+   Image for the active state of the widget. Defaults to ``
+
+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``
+   Table overwriting the color. Undefined colors default to the theme colors.
+
+
+
+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.