| 54 | |
---|
| 55 | == Element == |
---|
| 56 | The ''Element'' global table contains a table named ''As'', where you would find the child types of ''Element'' to cast to. For example, if you are using RocketControls, to convert an element from an event to an ''ElementFormControlInput'', you could put `local input = Element.As.ElementFormControlInput(element)`. |
---|
| 57 | |
---|
| 58 | The ''Element'' class has no constructor; it must be instantiated through a ''[wiki:documentation/LuaManual/APIReference#Document Document]'' object instead. It has the following methods and properties: |
---|
| 59 | |
---|
| 60 | `void `'''AddEventListener'''(`string` ''event'', `string|function` ''listener''[, `bool` ''in_capture_phase'']):: |
---|
| 61 | Attaches ''listener'' to this element, listening for occurrences of ''event'' in either the bubble or capture phase. If not specified, ''in_capture_phase'' will default to false. [wiki:documentation/LuaManual/AttachingToEvents See also][[br]]''NOTE: Events added from Lua cannot be removed.'' |
---|
| 62 | |
---|
| 63 | `void `'''AppendChild'''(`Element` ''element''):: |
---|
| 64 | Appends ''element'' as a child to this element. |
---|
| 65 | |
---|
| 66 | `void `'''Blur'''():: |
---|
| 67 | Removes input focus from this element. |
---|
| 68 | |
---|
| 69 | `void `'''Click'''():: |
---|
| 70 | Fakes a click on this element. |
---|
| 71 | |
---|
| 72 | `void `'''DispatchEvent'''(`string` ''event'', `{}` ''parameters'', `bool` ''interruptible''):: |
---|
| 73 | Dispatches an event to this element. The event is of type ''event''. Parameters to the event are given in the table ''parameters''; the table must only contain string keys and floating-point, integer, boolean, Lua userdata, or string values. ''interruptible'' determines if the event can be forced to stop propagation early. |
---|
| 74 | |
---|
| 75 | `void `'''Focus'''():: |
---|
| 76 | Gives input focus to this element. |
---|
| 77 | |
---|
| 78 | ''[wiki:documentation/LuaManual/Variant variant]''` `'''GetAttribute'''(`string` ''name''):: |
---|
| 79 | Returns the value of the attribute named ''name''. If no such attribute exists, the empty string will be returned. |
---|
| 80 | |
---|
| 81 | `Element `'''GetElementById'''(`string` ''id''):: |
---|
| 82 | Returns the descendant element with an id of ''id''. |
---|
| 83 | |
---|
| 84 | `{Element} `'''GetElementsByTagName'''(`string` ''tag_name''):: |
---|
| 85 | Returns a list of all descendant elements with the tag of ''tag_name''. |
---|
| 86 | |
---|
| 87 | `bool `'''HasAttribute'''(`string` ''name''):: |
---|
| 88 | Returns True if the element has a value for the attribute named ''name'', False if not. |
---|
| 89 | |
---|
| 90 | `bool `'''HasChildNodes'''():: |
---|
| 91 | Returns True if the element has at least one child node, false if not. |
---|
| 92 | |
---|
| 93 | `void `'''InsertBefore'''(`Element` ''element'', `Element` ''adjacent_element''):: |
---|
| 94 | Inserts the element ''element'' as a child of this element, directly before ''adjacent_element'' in the list of children. |
---|
| 95 | |
---|
| 96 | `bool `'''IsClassSet'''(`string` name''):: |
---|
| 97 | Returns true if the class ''name'' is set on the element, false if not. |
---|
| 98 | |
---|
| 99 | `void `'''RemoveAttribute'''(`string` ''name''):: |
---|
| 100 | Removes the attribute named ''name'' from the element. |
---|
| 101 | |
---|
| 102 | `bool `'''RemoveChild'''(`Element` ''element''):: |
---|
| 103 | Removes the child element ''element'' from this element. |
---|
| 104 | |
---|
| 105 | `void `'''ReplaceChild'''(`Element` ''inserted_element'', `Element` ''replaced_element''):: |
---|
| 106 | Replaces the child element ''replaced_element'' with ''inserted_element'' in this element's list of children. If ''replaced_element'' is not a child of this element, ''inserted_element'' will be appended onto the list instead. |
---|
| 107 | |
---|
| 108 | `void `'''ScrollIntoView'''(`bool` ''align_with_top''):: |
---|
| 109 | Scrolls this element into view if its ancestors have hidden overflow. If ''align_with_top'' is True, the element's top edge will be aligned with the top (or as close as possible to the top) of its ancestors' viewing windows. If False, its bottom edge will be aligned to the bottom. |
---|
| 110 | |
---|
| 111 | `void `'''SetAttribute'''(`string` ''name'', `string` ''value''):: |
---|
| 112 | Sets the value of the attribute named ''name'' to ''value''. |
---|
| 113 | |
---|
| 114 | `void `'''SetClass'''(`string` ''name'', `bool` ''value''):: |
---|
| 115 | Sets (if ''value'' is true) or clears (if ''value'' is false) the class ''name'' on the element. |
---|
| 116 | |
---|
| 117 | '''attributes'''` `(`{k=string`,`v=`''[wiki:documentation/LuaManual/Variant variant]''`}`):: |
---|
| 118 | The array of attributes on the element. Read-only [wiki:documentation/LuaManual/ProxyTables proxy table]. |
---|
| 119 | |
---|
| 120 | '''child_nodes'''` `(`{Element}`):: |
---|
| 121 | The array of child nodes on the element. Read-only. |
---|
| 122 | |
---|
| 123 | '''class_name'''` `(`string`):: |
---|
| 124 | The space-separated list of classes on the element. Read & write. |
---|
| 125 | |
---|
| 126 | '''client_left'''` `(`float`):: |
---|
| 127 | The distance between the left border edge and the left client edge of the element. Read-only. |
---|
| 128 | |
---|
| 129 | '''client_height'''` `(`float`):: |
---|
| 130 | The height of the element's client area. Read-only. |
---|
| 131 | |
---|
| 132 | '''client_top'''` `(`float`):: |
---|
| 133 | The distance between the top border edge and the top client edge of the element. Read-only. |
---|
| 134 | |
---|
| 135 | '''client_width'''` `(`float`):: |
---|
| 136 | The width of the element's client area. Read-only. |
---|
| 137 | |
---|
| 138 | '''first_child'''` `(`Element`):: |
---|
| 139 | The first child of the element, or nil if the client has no children. Read-only. |
---|
| 140 | |
---|
| 141 | '''id'''` `(`string`):: |
---|
| 142 | The ID of the element, or the empty string if the element has no ID. Read & write. |
---|
| 143 | |
---|
| 144 | '''inner_rml'''` `(`string`):: |
---|
| 145 | The element's RML content. Read & write. |
---|
| 146 | |
---|
| 147 | '''last_child'''` `(`Element`):: |
---|
| 148 | The last child of the element, or nil if the client has no children. Read-only. |
---|
| 149 | |
---|
| 150 | '''next_sibling'''` `(`Element`):: |
---|
| 151 | The element's next sibling, or None if it is the last sibling. Read-only. |
---|
| 152 | |
---|
| 153 | '''offset_height'''` `(`float`):: |
---|
| 154 | The height of the element, excluding margins. Read-only. |
---|
| 155 | |
---|
| 156 | '''offset_left'''` `(`float`):: |
---|
| 157 | The distance between the element's offset parent's left border edge and this element's left border edge. Read-only. |
---|
| 158 | |
---|
| 159 | '''offset_parent'''` `(`Element`):: |
---|
| 160 | The element's offset parent. Read only. |
---|
| 161 | |
---|
| 162 | '''offset_top'''` `(`float`):: |
---|
| 163 | The distance between the element's offset parent's top border edge and this element's top border edge. Read-only. |
---|
| 164 | |
---|
| 165 | '''offset_width'''` `(`float`):: |
---|
| 166 | The width of the element, excluding margins. Read-only. |
---|
| 167 | |
---|
| 168 | '''owner_document'''` `(`Document`):: |
---|
| 169 | The document this element is part of. Read-only. |
---|
| 170 | |
---|
| 171 | '''parent_node'''` `(`Element`):: |
---|
| 172 | The element this element is directly parented to. Read-only. |
---|
| 173 | |
---|
| 174 | '''previous_sibling'''` `(`Element`):: |
---|
| 175 | The element's previous sibling, or nil if it is the first sibling. Read-only. |
---|
| 176 | |
---|
| 177 | '''scroll_height'''` `(`float`):: |
---|
| 178 | The height of this element's content. This will be at least as high as the client height. Read-only. |
---|
| 179 | |
---|
| 180 | '''scroll_left'''` `(`float`):: |
---|
| 181 | The offset between the left edge of this element's client area and the left edge of the content area. Read & write. |
---|
| 182 | |
---|
| 183 | '''scroll_top'''` `(`float`):: |
---|
| 184 | The offset between the top edge of this element's client area and the top edge of the content area. Read & write. |
---|
| 185 | |
---|
| 186 | '''scroll_width'''` `(`float`):: |
---|
| 187 | The width of this element's content. This will be at least as wide as the client width. Read-only. |
---|
| 188 | |
---|
| 189 | '''style'''` `(`{k=string`,`v=string}`):: |
---|
| 190 | An object used to access this element's style information. Read & write [wiki:documentation/LuaManual/ProxyTables proxy table]. |
---|
| 191 | |
---|
| 192 | '''tag_name'''` `(`string`):: |
---|
| 193 | The tag name used to instance this element. Read-only. |
---|
| 194 | |
---|
| 195 | == ElementText == |
---|
| 196 | |
---|
| 197 | ''ElementText'' derives from ''Element''. ''ElementText'' is an interface, and therefore cannot be instanced directly. A concrete ''ElementText'' must be instantiated through a ''[wiki:documentation/LuaManual/APIReference#Document Document]'' object instead. It has the following property: |
---|
| 198 | |
---|
| 199 | '''text'''` `(`string`):: |
---|
| 200 | The raw text content of the text element in UTF-8 encoding. |
---|
| 201 | |
---|
| 202 | == Document == |
---|
| 203 | |
---|
| 204 | ''Document'' derives from ''Element''. ''Document'' has no constructor; it must be instantiated through a ''[wiki:documentation/PythonManual/APIReference#Context Context]'' object instead, either by loading an external RML file or creating an empty document. It has the following methods and properties: |
---|
| 205 | |
---|
| 206 | `void `'''PullToFront'''():: |
---|
| 207 | Pulls the document in front of other documents within its context with a similar z-index. |
---|
| 208 | |
---|
| 209 | `void `'''PushToBack'''():: |
---|
| 210 | Pushes the document behind other documents within its context with a similar z-index. |
---|
| 211 | |
---|
| 212 | `void `'''Show'''([''flags'']):: |
---|
| 213 | Shows the document. ''flags'' is either ''Document.NONE'', ''Document.FOCUS'' or ''Document.MODAL''. ''flags'' defaults to ''Document.FOCUS''. |
---|
| 214 | |
---|
| 215 | `void `'''Hide'''():: |
---|
| 216 | Hides the document. |
---|
| 217 | |
---|
| 218 | `void `'''Close'''():: |
---|
| 219 | Hides and closes the document, destroying its contents. |
---|
| 220 | |
---|
| 221 | `Element `'''CreateElement'''(`string` ''tag_name''):: |
---|
| 222 | Instances an element with a tag of ''tag_name''. |
---|
| 223 | |
---|
| 224 | `ElementText `'''CreateTextNode'''(`string` ''text''):: |
---|
| 225 | Instances a text element containing the string ''text''. |
---|
| 226 | |
---|
| 227 | '''title'''` `(`string`):: |
---|
| 228 | The title of the document, as initially set by the <title> tag in the document's header. Read & write. |
---|
| 229 | |
---|
| 230 | '''context'''` `(`Context`):: |
---|
| 231 | The context the document belongs to. Read-only. |
---|
| 232 | |
---|
| 233 | == Event == |
---|
| 234 | |
---|
| 235 | The Event class has no constructor; it is generated internally. It has the following methods and properties: |
---|
| 236 | |
---|
| 237 | `void `'''StopPropagation'''():: |
---|
| 238 | Stops the propagation of the event through the event cycle, if allowed. |
---|
| 239 | |
---|
| 240 | '''current_element'''` `(`Element`):: |
---|
| 241 | The element the event has propagated to. Read-only. |
---|
| 242 | |
---|
| 243 | '''type'''` `(`string`):: |
---|
| 244 | The string name of the event. Read-only. |
---|
| 245 | |
---|
| 246 | '''target_element'''` `(`Element`):: |
---|
| 247 | The element the event was originally targeted at. Read-only. |
---|
| 248 | |
---|
| 249 | '''parameters'''` `(`{k=string`,`v=`''[wiki:documentation/LuaManual/Variant variant]''`}`):: |
---|
| 250 | A dictionary like object containing all the parameters in the event. Read-only [wiki:documentation/LuaManual/ProxyTables proxy table]. |
---|
| 251 | |
---|
| 252 | == Context == |
---|
| 253 | The ''Context'' class has no constructor; it must be instantiated through the ''rocket.CreateContext()'' function. It has the following methods and properties: |
---|
| 254 | |
---|
| 255 | `void `'''AddEventListener'''(`string` ''event'', `string|function` ''script'', `Element` ''element_context'', `bool` ''in_capture_phase''):: |
---|
| 256 | Adds the inline Lua script, ''script'', as an event listener to the context. Rules for ''script'' are the same as the ''listener'' argument to ''Element.AddEventListener''. ''element_context'' is an optional Element; if it is not nil, then the script will be executed as if it was bound to that element. |
---|
| 257 | |
---|
| 258 | `void `'''AddMouseCursor'''(`Document` ''cursor_document''):: |
---|
| 259 | Adds a cursor document loaded by another context into this context. The cursor document will be returned. |
---|
| 260 | |
---|
| 261 | `Document `'''CreateDocument'''(`string` ''tag''):: |
---|
| 262 | Creates a new document with the tag name of ''tag''. |
---|
| 263 | |
---|
| 264 | `Document `'''LoadDocument'''(`string` ''document_path''):: |
---|
| 265 | Attempts to load a document from the RML file found at ''document_path''. If successful, the document will be returned with a reference count of one. |
---|
| 266 | |
---|
| 267 | `Document `'''LoadMouseCursor'''(`string` ''cursor_document_path''):: |
---|
| 268 | Attempts to load a document from the RML file found at ''cursor_document_path'' as a cursor. If successful, the cursor's document will be returned with a reference count of one. |
---|
| 269 | |
---|
| 270 | `bool `'''Render'''():: |
---|
| 271 | Renders the context. |
---|
| 272 | |
---|
| 273 | `void `'''ShowMouseCursor'''(`bool` ''show''):: |
---|
| 274 | If ''show'' is True, this shows the mouse cursor, otherwise hides it. |
---|
| 275 | |
---|
| 276 | `void `'''UnloadAllDocuments'''():: |
---|
| 277 | Closes all documents currently loaded with the context. |
---|
| 278 | |
---|
| 279 | `void `'''UnloadAllMouseCursors'''():: |
---|
| 280 | Unloads all cursors currently loaded with the context. |
---|
| 281 | |
---|
| 282 | `void `'''UnloadDocument'''(`Document` ''document''):: |
---|
| 283 | Unloads a specific document within the context. |
---|
| 284 | |
---|
| 285 | `void `'''UnloadMouseCursor'''(`string` ''cursor_name''):: |
---|
| 286 | Unloads a specific cursor by name. |
---|
| 287 | |
---|
| 288 | `bool `'''Update'''():: |
---|
| 289 | Updates the context. |
---|
| 290 | |
---|
| 291 | '''dimensions'''` `(`Vector2i`):: |
---|
| 292 | The dimensions of the context, as a ''Vector2i'' type. Read & write. |
---|
| 293 | |
---|
| 294 | '''documents'''` `(`k=int|string`,`v=Document`):: |
---|
| 295 | Returns an array of the documents within the context. This can be looked up as an array or a dictionary. Read-only [wiki:documentation/LuaManual/ProxyTables proxy table]. |
---|
| 296 | |
---|
| 297 | '''focus_element'''` `(`Element`):: |
---|
| 298 | Returns the leaf of the context's focus tree. Read-only. |
---|
| 299 | |
---|
| 300 | '''hover_element'''` `(`Element`):: |
---|
| 301 | Returns the element under the context's cursor. Read-only. |
---|
| 302 | |
---|
| 303 | '''name'''` `(`string`):: |
---|
| 304 | The name of the context, specified at construction. Read-only. |
---|
| 305 | |
---|
| 306 | '''root_element'''` `(`Element`):: |
---|
| 307 | Returns the context's root element. Read-only. |
---|
| 308 | ----- |
---|
| 309 | = Controls API Reference = |
---|
| 310 | |
---|
| 311 | |
---|
| 312 | == ElementForm == |
---|
| 313 | |
---|
| 314 | ''ElementForm'' derives from ''Element''. The form element has the following method: |
---|
| 315 | |
---|
| 316 | `void `'''Submit'''([`string` ''name'' [, `string` ''submit_value'']]):: |
---|
| 317 | Submits the form, optionally with the given ''name'' and ''submit_value''. Both default to empty strings. |
---|
| 318 | |
---|
| 319 | == ElementFormControl == |
---|
| 320 | |
---|
| 321 | ''ElementFormControl'' derives from ''Element''. The form element control has the following properties: |
---|
| 322 | |
---|
| 323 | '''disabled'''` `(`bool`):: |
---|
| 324 | The disabled status of the control. Read & write. |
---|
| 325 | |
---|
| 326 | '''name'''` `(`string`):: |
---|
| 327 | The name of the control, initial set with the "name" attribute. |
---|
| 328 | |
---|
| 329 | '''value'''` `(`string`):: |
---|
| 330 | The current value of the control. |
---|
| 331 | |
---|
| 332 | == ElementFormControlSelect == |
---|
| 333 | |
---|
| 334 | ''ElementFormControlSelect'' derives from ''ElementFormControl''. The control has the following methods and properties: |
---|
| 335 | |
---|
| 336 | `int `'''Add'''(`string` ''rml'', ` string `''value''[, `int` ''before'']):: |
---|
| 337 | Adds a new option to the select box. The new option has the string value of ''value'' and is represented by the elements created by the RML string ''rml''. The new option will be inserted by the index specified by ''before''; if this is out of bounds (the default), then the new option will be appended onto the list. The index of the new option will be returned. |
---|
| 338 | |
---|
| 339 | `void `'''Remove'''(`int `''index''):: |
---|
| 340 | Removes an existing option from the selection box. |
---|
| 341 | |
---|
| 342 | '''options'''` `(`{ {"element"=Element,"value"=string} }`:: |
---|
| 343 | The array of options available in the select box. Each entry in the array has the property ''value'', the string value of the option, and ''element'', the root of the element hierarchy that represents the option in the list. Read-only [wiki:documentation/LuaManual/ProxyTables proxy table]. |
---|
| 344 | |
---|
| 345 | '''selection'''` `(`int`):: |
---|
| 346 | The index of the currently selected option. |
---|
| 347 | |
---|
| 348 | == ElementFormControlDataSelect == |
---|
| 349 | |
---|
| 350 | ''ElementFormControlDataSelect'' derives from ''ElementFormControlSelect''. It has the following additional method: |
---|
| 351 | |
---|
| 352 | `void `'''SetDataSource'''(`string` ''data_source_name''):: |
---|
| 353 | Sets the name and table of the new data source to be used by the select box. |
---|
| 354 | |
---|
| 355 | == ElementFormControlInput == |
---|
| 356 | |
---|
| 357 | ''ElementFormControlInput'' derives from ''ElementFormControl''. The control has the following properties, only appropriate on the relevant types: |
---|
| 358 | |
---|
| 359 | '''checked'''` `(`bool`):: |
---|
| 360 | Relevant for ''radio'' and ''checkbox'' types. The checked status of the input. Read & write. |
---|
| 361 | |
---|
| 362 | '''maxlength'''` `(`int`):: |
---|
| 363 | Relevant for ''text'' types. The maximum number of characters permitted in the text field. Read & write. |
---|
| 364 | |
---|
| 365 | '''size'''` `(`int`):: |
---|
| 366 | Relevant for ''text'' types. The approximate number of characters the text field shows horizontally at once. Read & write. |
---|
| 367 | |
---|
| 368 | '''max'''` `(`int`):: |
---|
| 369 | Relevant for ''range'' types. The value of the control on the bottom / right of the slider. Read & write. |
---|
| 370 | |
---|
| 371 | '''min'''` `(`int`):: |
---|
| 372 | Relevant for ''range'' types. The value of the control on the top / left of the slider. Read & write. |
---|
| 373 | |
---|
| 374 | '''step'''` `(`int`):: |
---|
| 375 | Relevant for ''range'' types. The step the control's value changes in. Read & write. |
---|
| 376 | |
---|
| 377 | == ElementFormControlTextArea == |
---|
| 378 | |
---|
| 379 | ''ElementFormControlTextArea'' derives from ''ElementFormControl''. The control has the following properties: |
---|
| 380 | |
---|
| 381 | '''cols'''` `(`int`):: |
---|
| 382 | The approximate number of characters the text area shows horizontally at once. Read & write. |
---|
| 383 | |
---|
| 384 | '''maxlength'''` `(`int`):: |
---|
| 385 | The maximum number of characters permitted in the text area. Read & write. |
---|
| 386 | |
---|
| 387 | '''rows'''` `(`int`):: |
---|
| 388 | The number of lines the text area shows at once. Read & write. |
---|
| 389 | |
---|
| 390 | '''word_wrap'''` `(`bool`):: |
---|
| 391 | True if lines are split to fit into the text area, false if not. Read & write. |
---|
| 392 | |
---|
| 393 | == ElementTabSet == |
---|
| 394 | |
---|
| 395 | ''ElementTabSet'' derives from ''Element''. The control has the following methods and properties: |
---|
| 396 | |
---|
| 397 | `void `'''SetPanel'''(`int` ''index'', `string` ''rml''):: |
---|
| 398 | Sets the contents of a panel to the RML content ''rml''. If ''index'' is out-of-bounds, a new panel will be added at the end. |
---|
| 399 | |
---|
| 400 | `void `'''SetTab'''(`int` ''index'', `string` ''rml''):: |
---|
| 401 | Sets the contents of a tab to the RML content ''rml''. If ''index'' is out-of-bounds, a new tab will be added at the end. |
---|
| 402 | |
---|
| 403 | '''active_tab'''` `(`int`):: |
---|
| 404 | Index of the active panel. Read & write. |
---|
| 405 | |
---|
| 406 | '''num_tabs'''` `(`int`):: |
---|
| 407 | The number of tabs in the tab set. Read-only. |
---|
| 408 | |
---|
| 409 | == ElementDataGrid == |
---|
| 410 | |
---|
| 411 | `void `'''AddColumn'''(`string` ''fields'', `string` ''formatter'', `float` ''initial_width'', `string` ''header_rml''):: |
---|
| 412 | Adds a new column to the data grid. The column will read the columns ''fields'' (in CSV format) from the grid's data source, processing it through the data formatter named ''formatter''. ''header_rml'' specifies the RML content of the column's header. |
---|
| 413 | |
---|
| 414 | `void `'''SetDataSource'''(`string` ''data_source_name''):: |
---|
| 415 | Sets the name and table of the new data source to be used by the data grid. |
---|
| 416 | |
---|
| 417 | '''rows'''` `(`{ElementDataGridRow}`):: |
---|
| 418 | Returns an array containing all the rows in the data grid. Read-only. |
---|
| 419 | |
---|
| 420 | == ElementDataGridRow == |
---|
| 421 | |
---|
| 422 | ''ElementDataGridRow'' derives from ''Element''. The data grid row has the following properties: |
---|
| 423 | |
---|
| 424 | '''row_expanded'''` `(`bool`):: |
---|
| 425 | The expanded state of the row, either True or False. Read & write. |
---|
| 426 | |
---|
| 427 | '''parent_relative_index'''` `(`int`):: |
---|
| 428 | The index of the row, relative to its parent row. So if you are the third row in your parent, then it will be 3. Read-only. |
---|
| 429 | |
---|
| 430 | '''table_relative_index'''` `(`int`):: |
---|
| 431 | The index of the row, relative to the data grid it is in. This takes into account all previous rows and their children. Read-only. |
---|
| 432 | |
---|
| 433 | '''parent_row'''` `(`ElementDataGridRow`):: |
---|
| 434 | The parent row of this row; nil if it at the top level. Read-only. |
---|
| 435 | |
---|
| 436 | '''parent_grid'''` `(`ElementDataGrid`):: |
---|
| 437 | The data grid that this row belongs to. Read-only. |
---|
| 438 | |
---|
| 439 | == DataFormatter == |
---|
| 440 | |
---|
| 441 | Abstract DataFormatter interface. Create one by calling ''DataFormatter.new'' and set the ''FormatData'' property to an appropriate Lua function. |
---|
| 442 | |
---|
| 443 | `DataFormatter `'''new'''([`string` ''name''[, `function` 'format_function']]):: |
---|
| 444 | Create a new DataFormatter object for use in Lua. ''name'' defaults to an empty string, and ''format_function'' must match the function signature that you would pass to the property ''FormatData''. Both are optional, but if you do not set format_function in ''new'', then you must set it on the property. Where to set the function is solely personal preference, neither is "better" than the other. |
---|
| 445 | |
---|
| 446 | '''FormatData'''` `=function(`{string}') return `string` end:: |
---|
| 447 | Set this to a Lua function that takes an array of strings, and returns a string. |
---|
| 448 | |
---|
78 | | |
---|
79 | | == Element == |
---|
80 | | The ''Element'' global table contains a table named ''As'', where you would find the child types of ''Element'' to cast to. For example, if you are using RocketControls, to convert an element from an event to an ''ElementFormControlInput'', you could put `local input = Element.As.ElementFormControlInput(element)`. |
---|
81 | | |
---|
82 | | The ''Element'' class has no constructor; it must be instantiated through a ''[wiki:documentation/LuaManual/APIReference#Document Document]'' object instead. It has the following methods and properties: |
---|
83 | | |
---|
84 | | `void `'''AddEventListener'''(`string` ''event'', `string` OR `function` ''listener''[, `bool` ''in_capture_phase'']):: |
---|
85 | | Attaches ''listener'' to this element, listening for occurrences of ''event'' in either the bubble or capture phase. If not specified, ''in_capture_phase'' will default to false. [wiki:documentation/LuaManual/AttachingToEvents See also][[br]]''NOTE: Events added from Lua cannot be removed.'' |
---|
86 | | |
---|
87 | | `void `'''AppendChild'''(`Element` ''element''):: |
---|
88 | | Appends ''element'' as a child to this element. |
---|
89 | | |
---|
90 | | `void `'''Blur'''():: |
---|
91 | | Removes input focus from this element. |
---|
92 | | |
---|
93 | | `void `'''Click'''():: |
---|
94 | | Fakes a click on this element. |
---|
95 | | |
---|
96 | | `void `'''DispatchEvent'''(`string` ''event'', `{}` ''parameters'', `bool` ''interruptible''):: |
---|
97 | | Dispatches an event to this element. The event is of type ''event''. Parameters to the event are given in the table ''parameters''; the table must only contain string keys and floating-point, integer, boolean, Lua userdata, or string values. ''interruptible'' determines if the event can be forced to stop propagation early. |
---|
98 | | |
---|
99 | | `void `'''Focus'''():: |
---|
100 | | Gives input focus to this element. |
---|
101 | | |
---|
102 | | ''[wiki:documentation/LuaManual/Variant variant]''` `'''GetAttribute'''(`string` ''name''):: |
---|
103 | | Returns the value of the attribute named ''name''. If no such attribute exists, the empty string will be returned. |
---|
104 | | |
---|
105 | | `Element `'''GetElementById'''(`string` ''id''):: |
---|
106 | | Returns the descendant element with an id of ''id''. |
---|
107 | | |
---|
108 | | `{`Element} `'''GetElementsByTagName'''(`string` ''tag_name''):: |
---|
109 | | Returns a list of all descendant elements with the tag of ''tag_name''. |
---|
110 | | |
---|
111 | | `bool `'''HasAttribute'''(`string` ''name''):: |
---|
112 | | Returns True if the element has a value for the attribute named ''name'', False if not. |
---|
113 | | |
---|
114 | | `bool `'''HasChildNodes'''():: |
---|
115 | | Returns True if the element has at least one child node, false if not. |
---|
116 | | |
---|
117 | | `void `'''InsertBefore'''(`Element` ''element'', `Element` ''adjacent_element''):: |
---|
118 | | Inserts the element ''element'' as a child of this element, directly before ''adjacent_element'' in the list of children. |
---|
119 | | |
---|
120 | | ''bool''` `'''IsClassSet'''(''string name''):: |
---|
121 | | Returns true if the class ''name'' is set on the element, false if not. |
---|
122 | | |
---|
123 | | ''void''` `'''RemoveAttribute'''(''name''):: |
---|
124 | | Removes the attribute named ''name'' from the element. |
---|
125 | | |
---|
126 | | ''bool''` `'''RemoveChild'''(''Element element''):: |
---|
127 | | Removes the child element ''element'' from this element. |
---|
128 | | |
---|
129 | | ''void''` `'''ReplaceChild'''(''Element inserted_element'', ''Element replaced_element''):: |
---|
130 | | Replaces the child element ''replaced_element'' with ''inserted_element'' in this element's list of children. If ''replaced_element'' is not a child of this element, ''inserted_element'' will be appended onto the list instead. |
---|
131 | | |
---|
132 | | ''void''` `'''ScrollIntoView'''(''bool align_with_top''):: |
---|
133 | | Scrolls this element into view if its ancestors have hidden overflow. If ''align_with_top'' is True, the element's top edge will be aligned with the top (or as close as possible to the top) of its ancestors' viewing windows. If False, its bottom edge will be aligned to the bottom. |
---|
134 | | |
---|
135 | | ''void''` `'''SetAttribute'''(''string name'', ''string value''):: |
---|
136 | | Sets the value of the attribute named ''name'' to ''value''. |
---|
137 | | |
---|
138 | | ''void''` `'''SetClass'''(''string name'', ''bool value''):: |
---|
139 | | Sets (if ''value'' is true) or clears (if ''value'' is false) the class ''name'' on the element. |
---|
140 | | |
---|
141 | | '''attributes'''` `(`{k`=''string'',`v`=''[wiki:documentation/LuaManual/Variant variant]''`}`):: |
---|
142 | | The array of attributes on the element. Read-only [wiki:documentation/LuaManual/ProxyTables proxy table]. |
---|
143 | | |
---|
144 | | '''child_nodes'''` `(`{`''Element''`}`):: |
---|
145 | | The array of child nodes on the element. Read-only. |
---|
146 | | |
---|
147 | | '''class_name'''` `(''string''):: |
---|
148 | | The space-separated list of classes on the element. Read & write. |
---|
149 | | |
---|
150 | | '''client_left'''` `(''float''):: |
---|
151 | | The distance between the left border edge and the left client edge of the element. Read-only. |
---|
152 | | |
---|
153 | | '''client_height'''` `(''float''):: |
---|
154 | | The height of the element's client area. Read-only. |
---|
155 | | |
---|
156 | | '''client_top'''` `(''float''):: |
---|
157 | | The distance between the top border edge and the top client edge of the element. Read-only. |
---|
158 | | |
---|
159 | | '''client_width'''` `(''float''):: |
---|
160 | | The width of the element's client area. Read-only. |
---|
161 | | |
---|
162 | | '''first_child'''` `(''Element''):: |
---|
163 | | The first child of the element, or nil if the client has no children. Read-only. |
---|
164 | | |
---|
165 | | '''id'''` `(''string''):: |
---|
166 | | The ID of the element, or the empty string if the element has no ID. Read & write. |
---|
167 | | |
---|
168 | | '''inner_rml'''` `(''string''):: |
---|
169 | | The element's RML content. Read & write. |
---|
170 | | |
---|
171 | | '''last_child'''` `(''Element''):: |
---|
172 | | The last child of the element, or nil if the client has no children. Read-only. |
---|
173 | | |
---|
174 | | '''next_sibling'''` `(''Element''):: |
---|
175 | | The element's next sibling, or None if it is the last sibling. Read-only. |
---|
176 | | |
---|
177 | | '''offset_height'''` `(''float''):: |
---|
178 | | The height of the element, excluding margins. Read-only. |
---|
179 | | |
---|
180 | | '''offset_left'''` `(''float''):: |
---|
181 | | The distance between the element's offset parent's left border edge and this element's left border edge. Read-only. |
---|
182 | | |
---|
183 | | '''offset_parent'''` `(''Element''):: |
---|
184 | | The element's offset parent. Read only. |
---|
185 | | |
---|
186 | | '''offset_top'''` `(''float''):: |
---|
187 | | The distance between the element's offset parent's top border edge and this element's top border edge. Read-only. |
---|
188 | | |
---|
189 | | '''offset_width'''` `(''float''):: |
---|
190 | | The width of the element, excluding margins. Read-only. |
---|
191 | | |
---|
192 | | '''owner_document'''` `(''Document''):: |
---|
193 | | The document this element is part of. Read-only. |
---|
194 | | |
---|
195 | | '''parent_node'''` `(''Element''):: |
---|
196 | | The element this element is directly parented to. Read-only. |
---|
197 | | |
---|
198 | | '''previous_sibling''':: |
---|
199 | | The element's previous sibling, or nil if it is the first sibling. Read-only. |
---|
200 | | |
---|
201 | | '''scroll_height'''` `(''float''):: |
---|
202 | | The height of this element's content. This will be at least as high as the client height. Read-only. |
---|
203 | | |
---|
204 | | '''scroll_left'''` `(''float''):: |
---|
205 | | The offset between the left edge of this element's client area and the left edge of the content area. Read & write. |
---|
206 | | |
---|
207 | | '''scroll_top'''` `(''float''):: |
---|
208 | | The offset between the top edge of this element's client area and the top edge of the content area. Read & write. |
---|
209 | | |
---|
210 | | '''scroll_width'''` `(''float''):: |
---|
211 | | The width of this element's content. This will be at least as wide as the client width. Read-only. |
---|
212 | | |
---|
213 | | '''style'''` `(`{k=`''string'',`v=`''string''`}`):: |
---|
214 | | An object used to access this element's style information. Read & write [wiki:documentation/LuaManual/ProxyTables proxy table]. |
---|
215 | | |
---|
216 | | '''tag_name'''` `(''string''):: |
---|
217 | | The tag name used to instance this element. Read-only. |
---|
218 | | |
---|
219 | | == ElementText == |
---|
220 | | |
---|
221 | | ''ElementText'' derives from ''Element''. ''ElementText'' is an interface, and therefore cannot be instanced directly. A concrete ''ElementText'' must be instantiated through a ''[wiki:documentation/LuaManual/APIReference#Document Document]'' object instead. It has the following property: |
---|
222 | | |
---|
223 | | '''text'''` `(''string''):: |
---|
224 | | The raw text content of the text element in UTF-8 encoding. |
---|
225 | | |
---|
226 | | == Document == |
---|
227 | | |
---|
228 | | ''Document'' derives from ''Element''. ''Document'' has no constructor; it must be instantiated through a ''[wiki:documentation/PythonManual/APIReference#Context Context]'' object instead, either by loading an external RML file or creating an empty document. It has the following methods and properties: |
---|
229 | | |
---|
230 | | ''void''` `'''PullToFront'''():: |
---|
231 | | Pulls the document in front of other documents within its context with a similar z-index. |
---|
232 | | |
---|
233 | | ''void''` `'''PushToBack'''():: |
---|
234 | | Pushes the document behind other documents within its context with a similar z-index. |
---|
235 | | |
---|
236 | | ''void''` `'''Show'''([''flags'']):: |
---|
237 | | Shows the document. ''flags'' is either ''Document.NONE'', ''Document.FOCUS'' or ''Document.MODAL''. ''flags'' defaults to ''Document.FOCUS''. |
---|
238 | | |
---|
239 | | ''void''` `'''Hide'''():: |
---|
240 | | Hides the document. |
---|
241 | | |
---|
242 | | ''void''` `'''Close'''():: |
---|
243 | | Hides and closes the document, destroying its contents. |
---|
244 | | |
---|
245 | | ''Element''` `'''CreateElement'''(''tag_name''):: |
---|
246 | | Instances an element with a tag of ''tag_name''. |
---|
247 | | |
---|
248 | | ''ElementText''` `'''CreateTextNode'''(''text''):: |
---|
249 | | Instances a text element containing the string ''text''. |
---|
250 | | |
---|
251 | | '''title'''` `(''string''):: |
---|
252 | | The title of the document, as initially set by the <title> tag in the document's header. Read & write. |
---|
253 | | |
---|
254 | | '''context'''` `(''Context''):: |
---|
255 | | The context the document belongs to. Read-only. |
---|
256 | | |
---|
257 | | == Event == |
---|
258 | | |
---|
259 | | The Event class has no constructor; it is generated internally. It has the following methods and properties: |
---|
260 | | |
---|
261 | | ''void''` `'''StopPropagation'''():: |
---|
262 | | Stops the propagation of the event through the event cycle, if allowed. |
---|
263 | | |
---|
264 | | '''current_element'''` `(''Element''):: |
---|
265 | | The element the event has propagated to. Read-only. |
---|
266 | | |
---|
267 | | '''type'''` `(''string''):: |
---|
268 | | The string name of the event. Read-only. |
---|
269 | | |
---|
270 | | '''target_element'''` `(''Element''):: |
---|
271 | | The element the event was originally targeted at. Read-only. |
---|
272 | | |
---|
273 | | '''parameters'''` `(`{k=`''string'',`v=`''[wiki:documentation/LuaManual/Variant variant]''):: |
---|
274 | | A dictionary like object containing all the parameters in the event. Read-only [wiki:documentation/LuaManual/ProxyTables proxy table]. |
---|
275 | | |
---|
276 | | == Context == |
---|
277 | | The ''Context'' class has no constructor; it must be instantiated through the ''rocket.CreateContext()'' function. It has the following methods and properties: |
---|
278 | | |
---|
279 | | ''void''` `'''AddEventListener'''(''string event'', ''string OR function script'', ''Element element_context'', ''bool in_capture_phase''):: |
---|
280 | | Adds the inline Lua script, ''script'', as an event listener to the context. Rules for ''script'' are the same as the ''listener'' argument to ''Element.AddEventListener''. ''element_context'' is an optional Element; if it is not nil, then the script will be executed as if it was bound to that element. |
---|
281 | | |
---|
282 | | ''void''` `'''AddMouseCursor'''(''cursor_document''):: |
---|
283 | | Adds a cursor document loaded by another context into this context. The cursor document will be returned. |
---|
284 | | |
---|
285 | | '''CreateDocument'''(''tag''):: |
---|
286 | | Creates a new document with the tag name of ''tag''. |
---|
287 | | |
---|
288 | | '''LoadDocument'''(''document_path''):: |
---|
289 | | Attempts to load a document from the RML file found at ''document_path''. If successful, the document will be returned with a reference count of one. |
---|
290 | | |
---|
291 | | '''LoadMouseCursor'''(''cursor_document_path''):: |
---|
292 | | Attempts to load a document from the RML file found at ''cursor_document_path'' as a cursor. If successful, the cursor's document will be returned with a reference count of one. |
---|
293 | | |
---|
294 | | '''Render'''():: |
---|
295 | | Renders the context. |
---|
296 | | |
---|
297 | | '''ShowMouseCursor'''(''show''):: |
---|
298 | | If ''show'' is True, this shows the mouse cursor, otherwise hides it. |
---|
299 | | |
---|
300 | | '''UnloadAllDocuments'''():: |
---|
301 | | Closes all documents currently loaded with the context. |
---|
302 | | |
---|
303 | | '''UnloadAllMouseCursors'''():: |
---|
304 | | Unloads all cursors currently loaded with the context. |
---|
305 | | |
---|
306 | | '''UnloadDocument'''(''document''):: |
---|
307 | | Unloads a specific document within the context. |
---|
308 | | |
---|
309 | | '''UnloadMouseCursor'''(''cursor_name''):: |
---|
310 | | Unloads a specific cursor by name. |
---|
311 | | |
---|
312 | | '''Update'''():: |
---|
313 | | Updates the context. |
---|
314 | | |
---|
315 | | '''dimensions''':: |
---|
316 | | The dimensions of the context, as a ''Vector2i'' type. |
---|
317 | | |
---|
318 | | '''documents''':: |
---|
319 | | Returns an array of the documents within the context. This can be looked up as an array or a dictionary. Read-only. |
---|
320 | | |
---|
321 | | '''focus_element''':: |
---|
322 | | Returns the leaf of the context's focus tree. Read-only. |
---|
323 | | |
---|
324 | | '''hover_element''':: |
---|
325 | | Returns the element under the context's cursor. Read-only. |
---|
326 | | |
---|
327 | | '''name''':: |
---|
328 | | The name of the context, specified at construction. Read-only. |
---|
329 | | |
---|
330 | | '''root_element''':: |
---|
331 | | Returns the context's root element. Read-only. |
---|
332 | | |
---|
333 | | = Controls API Reference = |
---|
334 | | |
---|
335 | | == ElementForm == |
---|
336 | | |
---|
337 | | '''class''' ElementForm |
---|
338 | | |
---|
339 | | ''ElementForm'' derives from ''Element''. The form element has the following method: |
---|
340 | | |
---|
341 | | '''Submit'''(''submit_value''):: |
---|
342 | | Submits the form with a submit value of ''submit_value''. |
---|
343 | | |
---|
344 | | == ElementFormControl == |
---|
345 | | |
---|
346 | | '''class''' IElementFormControl |
---|
347 | | |
---|
348 | | ''IElementFormControl'' derives from ''Element''. The form element control has the following properties: |
---|
349 | | |
---|
350 | | '''disabled''':: |
---|
351 | | The disabled status of the control, either True or False. |
---|
352 | | |
---|
353 | | '''name''':: |
---|
354 | | The name of the control, initial set with the "name" attribute. |
---|
355 | | |
---|
356 | | '''value''':: |
---|
357 | | The current value of the control. |
---|
358 | | |
---|
359 | | == ElementFormControlSelect == |
---|
360 | | |
---|
361 | | '''class''' ElementFormControlSelect |
---|
362 | | |
---|
363 | | ''ElementFormControlSelect'' derives from ''IElementFormControl''. The control has the following methods and properties: |
---|
364 | | |
---|
365 | | '''Add'''(''rml'', ''value''[, ''before'']):: |
---|
366 | | Adds a new option to the select box. The new option has the string value of ''value'' and is represented by the elements created by the RML string ''rml''. The new option will be inserted by the index specified by ''before''; if this is out of bounds (the default), then the new option will be appended onto the list. The index of the new option will be returned. |
---|
367 | | |
---|
368 | | '''Remove'''(''index''):: |
---|
369 | | Removes an existing option from the selection box. |
---|
370 | | |
---|
371 | | '''options''':: |
---|
372 | | The array of options available in the select box. Each entry in the array has the property ''value'', the string value of the option, and ''element'', the root of the element hierarchy that represents the option in the list. |
---|
373 | | |
---|
374 | | '''selection''':: |
---|
375 | | The index of the currently selected option. |
---|
376 | | |
---|
377 | | == ElementFormControlDataSelect == |
---|
378 | | |
---|
379 | | '''class''' ElementFormControlDataSelect |
---|
380 | | |
---|
381 | | ''ElementFormControlDataSelect'' derives from ''ElementFormControlSelect''. It has the following additional method: |
---|
382 | | |
---|
383 | | '''SetDataSource'''(''data_source_name''):: |
---|
384 | | Sets the name and table of the new data source to be used by the select box. |
---|
385 | | |
---|
386 | | == ElementFormControlInput == |
---|
387 | | |
---|
388 | | '''class''' ElementFormControlInput |
---|
389 | | |
---|
390 | | ''ElementFormControlInput'' derives from ''IElementFormControl''. The control has the following properties, only appropriate on the relevant types: |
---|
391 | | |
---|
392 | | '''checked''':: |
---|
393 | | Relevant for ''radio'' and ''checkbox'' types. The checked status of the input. |
---|
394 | | |
---|
395 | | '''max_length''':: |
---|
396 | | Relevant for ''text'' types. The maximum number of characters permitted in the text field. |
---|
397 | | |
---|
398 | | '''size''':: |
---|
399 | | Relevant for ''text'' types. The approximate number of characters the text field shows horizontally at once. |
---|
400 | | |
---|
401 | | '''max''':: |
---|
402 | | Relevant for ''range'' types. The value of the control on the bottom / right of the slider. |
---|
403 | | |
---|
404 | | '''min''':: |
---|
405 | | Relevant for ''range'' types. The value of the control on the top / left of the slider. |
---|
406 | | |
---|
407 | | '''step''':: |
---|
408 | | Relevant for ''range'' types. The step the control's value changes in. |
---|
409 | | |
---|
410 | | == ElementFormControlTextArea == |
---|
411 | | |
---|
412 | | '''class''' ElementFormControlTextArea |
---|
413 | | |
---|
414 | | ''ElementFormControlTextArea'' derives from ''IElementFormControl''. The control has the following properties: |
---|
415 | | |
---|
416 | | '''cols''':: |
---|
417 | | The approximate number of characters the text area shows horizontally at once. |
---|
418 | | |
---|
419 | | '''max_length''':: |
---|
420 | | The maximum number of characters permitted in the text area. |
---|
421 | | |
---|
422 | | '''rows''':: |
---|
423 | | The number of lines the text area shows at once. |
---|
424 | | |
---|
425 | | '''word_wrap''':: |
---|
426 | | True if lines are split to fit into the text area, False if not. |
---|
427 | | |
---|
428 | | == ElementTabSet == |
---|
429 | | |
---|
430 | | '''class''' ElementTabSet |
---|
431 | | |
---|
432 | | ''ElementTabSet'' derives from ''Element''. The control has the following methods and properties: |
---|
433 | | |
---|
434 | | '''SetPanel'''(''index'', ''rml''):: |
---|
435 | | Sets the contents of a panel to the RML content ''rml''. If ''index'' is out-of-bounds, a new panel will be added at the end. |
---|
436 | | |
---|
437 | | '''SetTab'''(''index'', ''rml''):: |
---|
438 | | Sets the contents of a tab to the RML content ''rml''. If ''index'' is out-of-bounds, a new tab will be added at the end. |
---|
439 | | |
---|
440 | | '''active_tab''':: |
---|
441 | | Index of the active panel. |
---|
442 | | |
---|
443 | | '''num_tabs''':: |
---|
444 | | |
---|
445 | | The number of tabs in the tab set. Read-only. |
---|
446 | | |
---|
447 | | == ElementDataGrid == |
---|
448 | | |
---|
449 | | '''class'' ElementDataGrid |
---|
450 | | |
---|
451 | | ''ElementDataGrid'' derives from ''Element''. The data grid has the following methods and properties: |
---|
452 | | |
---|
453 | | '''AddColumn'''(''fields'', ''formatter'', ''initial_width'', ''header_rml''):: |
---|
454 | | Adds a new column to the data grid. The column will read the columns ''fields'' (in CSV format) from the grid's data source, processing it through the data formatter named ''formatter''. ''header_rml'' specifies the RML content of the column's header. |
---|
455 | | |
---|
456 | | '''SetDataSource'''(''data_source_name''):: |
---|
457 | | Sets the name and table of the new data source to be used by the data grid. |
---|
458 | | |
---|
459 | | '''rows''':: |
---|
460 | | Returns an array containing all the rows in the data grid. |
---|
461 | | |
---|
462 | | == ElementDataGridRow == |
---|
463 | | |
---|
464 | | '''class''' ElementDataGridRow |
---|
465 | | |
---|
466 | | ''ElementDataGridRow'' derives from ''Element''. The data grid row has the following properties: |
---|
467 | | |
---|
468 | | '''row_expanded''':: |
---|
469 | | The expanded state of the row, either True or False. |
---|
470 | | |
---|
471 | | '''parent_relative_index''':: |
---|
472 | | The index of the row, relative to its parent row. So if you are the third row in your parent, then it will be 3. |
---|
473 | | |
---|
474 | | '''table_relative_index''':: |
---|
475 | | The index of the row, relative to the data grid it is in. This takes into account all previous rows and their children. |
---|
476 | | |
---|
477 | | '''parent_row''':: |
---|
478 | | The parent row of this row. None if it at the top level. |
---|
479 | | |
---|
480 | | '''parent_grid''':: |
---|
481 | | The data grid that this row belongs to. |