1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
User interface 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.
Widget types
------------
.. toctree::
:maxdepth: 1
Widget: Base widget type, all the other widgets inherit its properties and events. <widgets/widget>
Text: Displays text. <widgets/text>
TextEdit: Accepts text input from the user. <widgets/textedit>
Image: Renders a texture. <widgets/image>
Flex: Aligns children in a column/row <widgets/flex>
Container: Wraps around its children <widgets/container>
Example
-------
*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 })
*clock.omwscripts*
::
PLAYER: scripts/clock.lua
|
