UI reference
============

.. include:: version.rst

Layouts
-------

Every widget is defined by a layout, which is a Lua table with the following fields (all of them are optional):

1. `type`: One of the available widget types from `openmw.ui.TYPE`.
2. | `props`: A Lua table, containing all the properties values.
   | Properties define most of the information about the widget: its position, data it displays, etc.
   | See the widget pages (table below) for details on specific properties.
   | Properties of the basic Widget are inherited by all the other widgets.
3. | `events`: A Lua table, containing `openmw.async.callback` values, which trigger on various interactions with the widget.
   | See the Widget pages for details on specific events.
   | Events of the basic Widget are inherited by all the other widgets.
4. `content`: a Content (`openmw.ui.content`), which contains layouts for the children of this widget.
5. | `name`: an arbitrary string, the only limitatiion is it being unique within a `Content`.
   | Helpful for navigatilng through the layouts.
6. `layer`: only applies for the root widget. (Windows, HUD, etc)
7. `template`: a Lua table which pre-defines a layout for this widget. See Templates below for more details.
8. `external`: similar to properties, but they affect how other widgets interact with this one. See the widget pages for details.

Layers
------
Layers control how widgets overlap - layers with higher indexes render over layers with lower indexes.
Widgets within the same layer which were added later overlap the ones created earlier.
A layer can also be set as non-interactive, which prevents all mouse interactions with the widgets in that layer.

.. TODO: Move this list when layers are de-hardcoded

Pre-defined OpenMW layers:

1. `HUD` interactive
2. `Windows` interactive
3. `Notification` non-interactive
4. `MessageBox` interactive

Elements
--------

Element is the root widget of a layout.
It is an independent part of the UI, connected only to a specific layer, but not any other layouts.
Creating or destroying an element also creates/destroys all of its children.

Content
-------

A container holding all the widget's children. It has a few important differences from a Lua table:

1. All the keys are integers, i. e. it is an "array"
2. Holes are not allowed. At any point all keys from `1` to the highest `n` must contain a value.
3. | You can access the values by their `name` field as a `Content` key.
   | While there is nothing preventing you from changing the `name` of a table inside a content, it is not supported, and will lead to undefined behaviour.
   | If you have to change the name, assign a new table to the index instead.

Templates
---------

Templates are Lua tables with the following (optional) fields:

1. `props`: Same as in layouts, defines the behaviour of this widget. Can be overwritten by `props` values in the layout.
2. | `content`: Extra children to add to the widget. For example, the frame and caption for Window widgets.
   | Contains normal layouts

Events
------

| A table mapping event names to `openmw.async.callback` s.
| When an event triggers, the callback is called with two arguments:
   an event-specific value, and that widget's layout table.
| See the Widget type pages for information on what events exist, and which first argument they pass. 

.. toctree::
   :maxdepth: 1
   :hidden:

   Widget <widgets/widget>
   Container <widgets/container>
   Flex <widgets/flex>
   Image <widgets/image>
   Text <widgets/text>
   TextEdit <widgets/textedit>

Example
-------

.. tab-set::

   .. tab-item:: scripts/clock.lua

      .. code-block:: lua

         local ui = require('openmw.ui')
         local util = require('openmw.util')
         local calendar = require('openmw_aux.calendar')
         local time = require('openmw_aux.time')

         local element = ui.create {
            -- important not to forget the layer
            -- by default widgets are not attached to any layer and are not visible
            layer = 'HUD',
            type = ui.TYPE.Text,
            props = {
               -- position in the top right corner
               relativePosition = util.vector2(1, 0),
               -- position is for the top left corner of the widget by default
               -- change it to align exactly to the top right corner of the screen
               anchor = util.vector2(1, 0),
               text = calendar.formatGameTime('%H:%M'),
               textSize = 24,
               -- default black text color isn't always visible
               textColor = util.color.rgb(0, 1, 0),
            },
         }

         local function updateTime()
            -- formatGameTime uses current time by default
            -- otherwise we could get it by calling `core.getGameTime()`
            element.layout.props.text = calendar.formatGameTime('%H:%M')
            -- the layout changes won't affect the widget unless we request an update
            element:update()
         end

         -- we are showing game time in hours and minutes
         -- so no need to update more often than once a game minute
         time.runRepeatedly(updateTime, 1 * time.minute, { type = time.GameTime })


   .. tab-item:: clock.omwscripts

      .. code-block::

         PLAYER: scripts/clock.lua

