205 lines
5.9 KiB
ReStructuredText
205 lines
5.9 KiB
ReStructuredText
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.
|