Add documentation

docs/core.rst

@@ -0,0 +1,191 @@
+Core Functions
+==============
+
+.. note::
+   Work in progress...
+
+The core functions can be divided into two parts: Functions of interest to the
+user and functions of interest to the (widget) developer.
+
+External Interface
+------------------
+
+Drawing
+-------
+
+.. function:: draw()
+
+Draw the GUI - call in ``love.draw``.
+
+.. data:: theme
+
+The current theme. See :doc:`themes`.
+
+
+Mouse Input
+^^^^^^^^^^^
+
+.. function:: updateMouse(x,y, buttonDown)
+
+   :param number x,y: Position of the mouse.
+   :param boolean buttonDown: Whether the mouse button is down.
+
+Update mouse position and button status. You do not need to call this function,
+unless you use some screen transformation (e.g., scaling, camera systems, ...).
+
+Keyboard Input
+^^^^^^^^^^^^^^
+
+.. function:: keypressed(key)
+
+   :param KeyConstant key: The pressed key.
+
+Forwards a ``love.keypressed(key)`` event to SUIT.
+
+.. function:: textinput(char)
+
+   :param string char: The pressed character
+
+Forwards a ``love.textinput(key)`` event to SUIT.
+
+
+Internal Helpers
+----------------
+
+.. function:: getOptionsAndSize(...)
+
+   :param mixed ...: Varargs.
+   :returns: ``options, x,y,w,h``.
+
+Converts varargs to option table and size definition. Used in the widget
+functions.
+
+.. function:: registerDraw(f, ...)
+
+   :param function f: Function to call in ``draw()``.
+   :param mixed ...: Arguments to f.
+
+Registers a function to be executed during :func:`draw()`. Used by widgets to
+make themselves visible.
+
+.. function:: enterFrame()
+
+Prepares GUI state when entering a frame.
+
+.. function:: exitFrame()
+
+Clears GUI state when exiting a frame.
+
+GUI State
+^^^^^^^^^
+
+.. function:: anyHot()
+
+   :returns: ``true`` if any widget is in the ``hot`` state.
+
+Checks if any widget is in the hot state
+
+.. function:: isHot(id)
+
+   :param mixed id: Identifier of the widget.
+   :returns: ``true`` if the widget is in the ``hot`` state.
+
+Checks if the widget identified by ``id`` is hovered by the mouse.
+
+.. function:: wasHot(id)
+
+   :param mixed id: Identifier of the widget.
+   :returns: ``true`` if the widget was in the ``hot`` state in the last frame.
+
+Checks if the widget identified by ``id`` was hovered by the mouse in the last frame.
+
+.. function:: isActive(id)
+
+   :param mixed id: Identifier of the widget.
+   :returns: ``true`` if the widget is in the ``active`` state.
+
+Checks whether the mouse button is pressed on the widget identified by ``id``.
+
+
+Mouse Input
+^^^^^^^^^^^
+
+.. function:: mouseInRect(x,y,w,h)
+
+   :param numbers x,y,w,h: Rectangle definition.
+   :returns: ``true`` if the mouse cursor is in the rectangle.
+
+Checks whether the mouse cursor is in the rectangle defined by ``x,y,w,h``.
+
+.. function:: registerMouseHit(id, ul_x, ul_y, hit)
+
+   :param mixed id: Identifier of the widget.
+   :param numbers ul_x, ul_y: Upper left corner of the widget.
+   :param function hit: Function to perform the hit test.
+
+Registers a hit-test defined by the function ``hit`` for the widget identified
+by ``id``. Sets the widget to ``hot`` if th hit-test returns ``true``. Sets the
+widget to ``active`` if the hit-test returns ``true`` and the mouse button is
+pressed.
+
+The hit test receives coordinates in the coordinate system of the widget, i.e.
+``(0,0)`` is the upper left corner of the widget.
+
+.. function:: registerHitbox(id, x,y,w,h)
+
+   :param mixed id: Identifier of the widget.
+   :param numbers x,y,w,h: Rectangle definition.
+
+Registers a hitbox for the widget identified by ``id``. Literally this function::
+
+    function registerHitbox(id, x,y,w,h)
+        return registerMouseHit(id, x,y, function(u,v)
+            return u >= 0 and u <= w and v >= 0 and v <= h
+        end)
+    end
+
+.. function:: mouseReleasedOn(id)
+
+   :param mixed id: Identifier of the widget.
+   :returns: ``true`` if the mouse was released on the widget.
+
+Checks whether the mouse button was released on the widget identified by ``id``.
+
+.. function:: getMousePosition()
+
+   :returns: Mouse positon ``mx, my``.
+
+Get the mouse position.
+
+Keyboard Input
+^^^^^^^^^^^^^^
+
+.. function:: getPressedKey()
+
+   :returns: KeyConstant
+
+Get the currently pressed key (if any).
+
+.. function:: grabKeyboardFocus(id)
+
+   :param mixed id: Identifier of the widget.
+
+Try to grab keyboard focus. Successful only if the widget is in the ``active``
+state.
+
+.. function:: hasKeyboardFocus(id)
+
+   :param mixed id: Identifier of the widget.
+   :returns: ``true`` if the widget has keyboard focus.
+
+Checks whether the widget identified by ``id`` currently has keyboard focus.
+
+.. function:: keyPressedOn(id, key)
+
+   :param mixed id: Identifier of the widget.
+   :param KeyConstant key: Key to query.
+   :returns: ``true`` if ``key`` was pressed on the widget.
+
+Checks whether the key ``key`` was pressed while the widget identified by
+``id`` has keyboard focus.
+