Something went wrong. Try again.
OpenMW is an open implementation of the Morrowind engine
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138UI 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` interactive2. `Windows` interactive3. `Notification` non-interactive4. `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
For Morrowind-themed UI examples, visit `MWUI Interface <./interface_mwui.html#examples>`_.