Difference between revisions of "LuaAPI/types/widget"

From The Battle for Wesnoth Wiki
< LuaAPI‎ | types
(Apply the new style guide)
(Add some missing details about the API)
Line 15: Line 15:
  
 
* ''widget''.'''selected''' &harr; ''boolean''
 
* ''widget''.'''selected''' &harr; ''boolean''
* [toggle_button], [toggle_panel]
+
* Available on: '''[toggle_button]''', '''[toggle_panel]'''
  
 
Whether the item is selected or not.
 
Whether the item is selected or not.
Line 22: Line 22:
  
 
* ''widget''.'''selected_index''' &harr; ''index''
 
* ''widget''.'''selected_index''' &harr; ''index''
* [listbox], [multi_page], [stacked_widget], selectable_item ([menu_button], [toggle_button], [toggle_panel])
+
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[menu_button]''', '''[toggle_button]''', '''[toggle_panel]'''
  
The selected index of the item.
+
The selected index of the item. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (0 or 1) instead of a boolean.
  
 
=== text ===
 
=== text ===
  
 
* ''widget''.'''text''' &harr; ''text''
 
* ''widget''.'''text''' &harr; ''text''
* [text_box]
+
* Available on: '''[text_box]'''
  
 
The text of the textbox.
 
The text of the textbox.
Line 36: Line 36:
  
 
* ''widget''.'''value''' &harr; ''position''
 
* ''widget''.'''value''' &harr; ''position''
* [slider]
+
* Available on: '''[slider]'''
 +
 
 +
The current position of the slider.
  
 
=== percentage ===
 
=== percentage ===
  
 
* ''widget''.'''percentage''' &harr; ''position''
 
* ''widget''.'''percentage''' &harr; ''position''
* [progress_bar]
+
* Available on: '''[progress_bar]'''
 +
 
 +
The current position of the progress bar, between 0 and 1.
  
 
=== selected_item_path ===
 
=== selected_item_path ===
  
 
* ''widget''.'''selected_item_path''' &rarr; ''array of indices''
 
* ''widget''.'''selected_item_path''' &rarr; ''array of indices''
* [slider]
+
* Available on: '''[treeview]'''
  
A table describing the currently selected node. If for example, in the following treeview. Item 9 is selected, the result will be {2,1,3}.
+
A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.
  
 
  +Section1
 
  +Section1
Line 72: Line 76:
  
 
* ''widget''.'''path''' &rarr; ''array of indices''
 
* ''widget''.'''path''' &rarr; ''array of indices''
* [tree_view_node]
+
* Available on: '''[tree_view_node]'''
  
See selected_item_path for the syntax.
+
A table describing this node in the overall treeview. See [[#selected_item_path|selected_item_path]] for the meaning of the table..
  
 
=== unfolded ===
 
=== unfolded ===
  
 
* ''widget''.'''unfolded''' &larr; ''boolean''
 
* ''widget''.'''unfolded''' &larr; ''boolean''
* [tree_view_node]
+
* Available on: '''[tree_view_node]'''
 +
 
 +
Control whether a tree node is currently expanded or not.
  
 
=== unit ===
 
=== unit ===
  
 
* ''widget''.'''unit''' &larr; ''unit or unit type''
 
* ''widget''.'''unit''' &larr; ''unit or unit type''
* [unit_preview_pane]
+
* Available on: '''[unit_preview_pane]'''
 +
 
 +
Change the displayed unit or unit type in the preview pane.
  
 
=== item_count ===
 
=== item_count ===
  
 
* ''widget''.'''item_count''' &rarr; ''number of items''
 
* ''widget''.'''item_count''' &rarr; ''number of items''
* [multi_page], [listbox]
+
* Available on: '''[multi_page]''', '''listbox'''
 +
 
 +
The number of items in the container widget.
  
 
=== use_markup ===
 
=== use_markup ===
  
 
* ''widget''.'''use_markup''' &rarr; ''boolean''
 
* ''widget''.'''use_markup''' &rarr; ''boolean''
* most widgets, in particular [label], [button]
+
* Available on: Most widgets, in particular '''[label]''', '''[button]'''
 +
 
 +
Sets whether the widget's label will parse [[Pango formatting]].
  
 
=== label ===
 
=== label ===
  
 
* ''widget''.'''label''' &larr; ''text''
 
* ''widget''.'''label''' &larr; ''text''
* most widgets, in particular [label], [button], [image]
+
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''
  
The label, technically this is a special string used in the widgets wml definition. It usually does what one would expect, but also sets the image for [image] widgets.
+
The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for '''image''' widgets.
  
 
=== marked_up_text ===
 
=== marked_up_text ===
  
 
* ''widget''.'''marked_up_text''' &larr; ''text''
 
* ''widget''.'''marked_up_text''' &larr; ''text''
* most widgets, in particular [label], [button]
+
* Available on: Most widgets, in particular '''[label]''', '''[button]'''
  
 
Shortcut for setting label and use_markup=yes.
 
Shortcut for setting label and use_markup=yes.
Line 113: Line 125:
  
 
* ''widget''.'''enabled''' &larr; ''boolean''
 
* ''widget''.'''enabled''' &larr; ''boolean''
* all widgets
+
* Available on: All widgets
  
 
=== tooltip ===
 
=== tooltip ===
  
 
* ''widget''.'''tooltip''' &larr; ''text''
 
* ''widget''.'''tooltip''' &larr; ''text''
* all widgets
+
* Available on: All widgets
  
 
=== visible ===
 
=== visible ===
  
 
* ''widget''.'''visible''' &larr; ''visibility string''
 
* ''widget''.'''visible''' &larr; ''visibility string''
* all widgets
+
* Available on: All widgets
  
The following visibility statuses are recognized:
+
Determines whether the widget is visible onscreen. The following visibility statuses are recognized:
 
{| clasS="wikitable"
 
{| clasS="wikitable"
 
! String value !! Boolean shorthand !! Meaning
 
! String value !! Boolean shorthand !! Meaning
Line 139: Line 151:
  
 
* ''widget''.'''type''' &rarr; ''string''
 
* ''widget''.'''type''' &rarr; ''string''
* all widgets
+
* Available on: All widgets
 +
 
 +
Returns a string specifying the type of the widget.
 +
 
 +
== Widget callbacks ==
  
== widget callbacks ==
 
 
=== on_modified ===
 
=== on_modified ===
  
 
* ''widget''.'''on_modified''' &larr; ''function''
 
* ''widget''.'''on_modified''' &larr; ''function''
* all widgets the allow the user to select a value of any type.
+
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''
 +
 
 +
Triggers when the user changes the value of the widget.
  
 
=== on_left_click ===
 
=== on_left_click ===
  
 
* ''widget''.'''on_left_click''' &larr; ''function''
 
* ''widget''.'''on_left_click''' &larr; ''function''
* all widgets
+
* Available on: All widgets
 +
 
 +
Triggers when the user clicks on the widget.
  
 
=== on_button_click ===
 
=== on_button_click ===
  
 
* ''widget''.'''on_button_click''' &larr; ''function''
 
* ''widget''.'''on_button_click''' &larr; ''function''
* button type widgets
+
* Available on: '''[button]''', '''[repeating_button]'''
  
== widget methods ==
+
Triggers when the user clicks on the button. This can differ from '''on_left_click''', depending on the type of widget. For example, on a '''[repeating_button]''' it will fire multiple times if the user holds the mouse button down.
 +
 
 +
== Widget methods ==
  
 
=== focus ===
 
=== focus ===
Line 173: Line 194:
 
<syntaxhighlight lang=lua>
 
<syntaxhighlight lang=lua>
 
-- draw two rectangles in the upper-left corner of the window (assume dialog is the window widget)
 
-- draw two rectangles in the upper-left corner of the window (assume dialog is the window widget)
dialog:set_canvas(2, {
+
dialog.set_canvas(2, {
 
     wml.tag.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
 
     wml.tag.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
 
     wml.tag.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
 
     wml.tag.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
Line 183: Line 204:
 
=== add_item ===
 
=== add_item ===
  
* ''widget'':'''add_item'''() &rarr; ''the new item''
+
* ''widget'':'''add_item'''([''position'']) &rarr; ''the new item'', ''position''
  
Add an item to a widget, for example a listbox. Returns the created item as a widget userdata.
+
Add an item to a container widget, for example a listbox. Returns the created item as a widget userdata. You can pass a negative position to count from the end of the container, but the returned position is always positive.
  
 
=== add_item_of_type ===
 
=== add_item_of_type ===
  
* '''widget'':'''add_item_of_type'''(''category'') &rarr; ''the new item''
+
* '''widget'':'''add_item_of_type'''(''category''[, ''position'']) &rarr; ''the new item'', ''position''
  
Add an item to a widget which is a heterogeneous container of different types of widgets, in particular multi_pages and treeviews.
+
Add an item to a widget which is a heterogeneous container of different types of widgets, in particular multi_pages and treeviews. You can pass a negative position to count from the end of the container, but the returned position is always positive.
  
 
=== remove_items_at ===
 
=== remove_items_at ===
Line 203: Line 224:
 
* ''widget'':'''find'''(''path, to, widget'')
 
* ''widget'':'''find'''(''path, to, widget'')
  
Finds a child widget of the widget of the given path. For example, here it searches for the widget with the id 'preview_panel' of the second item of the widget with the id 'unit_list'
+
Finds a child widget of the widget of the given path. For example, here it searches for the widget with the id 'preview_panel' of the second item of the widget with the id 'unit_list':
 +
 
 +
<syntaxhighlight lang=lua>
 +
dialog:find(unit_list, 2, preview_panel)
 +
</syntaxhighlight>

Revision as of 22:37, 27 September 2020

The widget userdata offers access to a widget of a GUI2 dialog. While there is only one type of widget userdata that covers all widgets including the window itself, the properties of a widget userdata are different for each type of widget. Indexing a widget's userdata can either be used to access a child widget or to set or get a property of a widget. Some properties are read-only; the properties depend on the type of the widget.

An example of accessing a child widget:

function preshow(dialog)
  local okay_button = dialog.okay_button
  -- okay_button is now a handle to the the widgets child with the id 'okay_button' 
end

Widget Attributes

selected

  • widget.selectedboolean
  • Available on: [toggle_button], [toggle_panel]

Whether the item is selected or not.

selected_index

  • widget.selected_indexindex
  • Available on: [listbox], [multi_page], [stacked_widget], [menu_button], [toggle_button], [toggle_panel]

The selected index of the item. For [toggle_button] and [toggle_panel], this is the same as selected only encoded as a number (0 or 1) instead of a boolean.

text

  • widget.texttext
  • Available on: [text_box]

The text of the textbox.

value

  • widget.valueposition
  • Available on: [slider]

The current position of the slider.

percentage

  • widget.percentageposition
  • Available on: [progress_bar]

The current position of the progress bar, between 0 and 1.

selected_item_path

  • widget.selected_item_patharray of indices
  • Available on: [treeview]

A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.

+Section1
 +Subsection11
  *Item1
  *Item2
  *Item3
 +Subsection12
  *Item4
  *Item5
  *Item6
+Section2
 +Subsection21
  *Item7
  *Item8
  *Item9
 +Subsection22
  *Item10
  *Item11
  *Item12

path

  • widget.patharray of indices
  • Available on: [tree_view_node]

A table describing this node in the overall treeview. See selected_item_path for the meaning of the table..

unfolded

  • widget.unfoldedboolean
  • Available on: [tree_view_node]

Control whether a tree node is currently expanded or not.

unit

  • widget.unitunit or unit type
  • Available on: [unit_preview_pane]

Change the displayed unit or unit type in the preview pane.

item_count

  • widget.item_countnumber of items
  • Available on: [multi_page], listbox

The number of items in the container widget.

use_markup

  • widget.use_markupboolean
  • Available on: Most widgets, in particular [label], [button]

Sets whether the widget's label will parse Pango formatting.

label

  • widget.labeltext
  • Available on: Most widgets, in particular [label], [button], [image]

The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for image widgets.

marked_up_text

  • widget.marked_up_texttext
  • Available on: Most widgets, in particular [label], [button]

Shortcut for setting label and use_markup=yes.

enabled

  • widget.enabledboolean
  • Available on: All widgets

tooltip

  • widget.tooltiptext
  • Available on: All widgets

visible

  • widget.visiblevisibility string
  • Available on: All widgets

Determines whether the widget is visible onscreen. The following visibility statuses are recognized:

String value Boolean shorthand Meaning
visible true The widget is visible and handles events.
hidden The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
invisible false The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.

type

  • widget.typestring
  • Available on: All widgets

Returns a string specifying the type of the widget.

Widget callbacks

on_modified

  • widget.on_modifiedfunction
  • Available on: Most widgets, in particular [slider], [toggle_button], [listbox], [menu_button], [text_box]

Triggers when the user changes the value of the widget.

on_left_click

  • widget.on_left_clickfunction
  • Available on: All widgets

Triggers when the user clicks on the widget.

on_button_click

  • widget.on_button_clickfunction
  • Available on: [button], [repeating_button]

Triggers when the user clicks on the button. This can differ from on_left_click, depending on the type of widget. For example, on a [repeating_button] it will fire multiple times if the user holds the mouse button down.

Widget methods

focus

  • widget:focus()

Switches the keyboard focus to the widget. This is often useful for dialogs containing a central listbox, so that it can be controlled with the keyboard as soon as it is displayed.

set_canvas

  • widget:set_canvas(layer index, content)

Sets the WML passed as the second argument as the canvas content (index given by the first argument) of the widget. The content of the WML table is described at GUICanvasWML.

-- draw two rectangles in the upper-left corner of the window (assume dialog is the window widget)
dialog.set_canvas(2, {
    wml.tag.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
    wml.tag.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
})

The meaning of the canvas index depends on the chosen widget. It may be the disabled / enabled states of the widget, or its background / foreground planes, or... For instance, overwriting canvas 1 of the window with an empty canvas causes the window to become transparent.

add_item

  • widget:add_item([position]) → the new item, position

Add an item to a container widget, for example a listbox. Returns the created item as a widget userdata. You can pass a negative position to count from the end of the container, but the returned position is always positive.

add_item_of_type

  • widget:'add_item_of_type(category[, position]) → the new item, position

Add an item to a widget which is a heterogeneous container of different types of widgets, in particular multi_pages and treeviews. You can pass a negative position to count from the end of the container, but the returned position is always positive.

remove_items_at

  • widget:'remove_items_at(position)

Removes the widget at the given index of a container type widget (like treeviews).

find

  • widget:find(path, to, widget)

Finds a child widget of the widget of the given path. For example, here it searches for the widget with the id 'preview_panel' of the second item of the widget with the id 'unit_list':

dialog:find(unit_list, 2, preview_panel)