Difference between revisions of "LuaAPI/types/widget"

Revision as of 21:52, 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

w.selected = value
boolean
get/set
[toggle_button], [toggle_panel]

Whether the item is selected or not.

selected_index

w.selected_index = value
number
get/set
[listbox], [multi_page], [stacked_widget], selectable_item ([menu_button], [toggle_button], [toggle_panel])

The selected index of the item.

text

w.text = value
string
get/set
[text_box]

The text of the textbox.

value

w.value = value
number
get/set
[slider]

percentage

w.percentage = value
number
get/set
[progress_bar]

selected_item_path

value = w.selected_item_path
array of integers
get
[slider]

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

value = w.path
array of integers
get
[tree_view_node]

See selected_item_path for the syntax.

unfolded

w.unfolded = value
boolean
set
[tree_view_node]

unit

w.unit = value
unit or unit type
set
[unit_preview_pane]

item_count

value = w.item_count
number
get
[multi_page], [listbox]

use_markup

w.use_markup = value
boolean
set
most widgets, in particular [label], [button]

label

w.label = value
string
set
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.

marked_up_text

w.marked_up_text = value
string
set
most widgets, in particular [label], [button]

Shortcut for setting label and use_markup=yes.

enabled

w.enabled = value
boolean
set
all widgets

tooltip

w.tooltip = value
string
set
all widgets

visible

w.visible = value
string
set
all widgets

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

value = w.type
string
get
all widgets

widget callbacks

on_modified

function w.on_modified() .... end
all widgets the allow the user to select a value of any type.

on_left_click

function w.on_left_click() .... end
all widgets

on_button_click

function w.on_button_click() .... end
button type widgets

widget methods

focus

w.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

w.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

w.add_item()

Add an item to a widget, for example a listbox. Returns the created item as a widget userdata.

add_item_of_type

w.add_item_of_type("category")

Add an item to a widget which is a heterogeneous container of different types of widgets, in particular multi_pages and treeviews.

remove_items_at

w.remove_items_at(2)

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

find

dialog.find(unit_list, 2, preview_panel)

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'

@@ Line 1: / Line 1: @@
-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 userdataq are different for each widgets. Indexing a widgets userdata can either be used to
+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.
-* Access a child widget
+An example of accessing a child widget:
-Example code
-```
+<syntaxhighlight lang=lua>
 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
-``` or to
+</syntaxhighlight>
-* Set/Get a property of a widget Some Properties are read-only, the propertied depends on the type of  the widget, the following properties exist:
+== Widget Attributes ==
+=== selected ===
-=== widget attributes ===
-==== selected ====
 * '''w.selected = value'''
 * '''boolean'''
 * '''get/set'''
 * [toggle_button], [toggle_panel]
-whether the item is selected or not
-==== selected_index ====
+Whether the item is selected or not.
+=== selected_index ===
 * '''w.selected_index = value'''
 * '''number'''
 * '''get/set'''
 * [listbox], [multi_page], [stacked_widget], selectable_item ([menu_button], [toggle_button], [toggle_panel])
-the selected index of the item
-==== text ====
+The selected index of the item.
+=== text ===
 * '''w.text = value'''
 * '''string'''
 * '''get/set'''
 * [text_box]
-the text of the textbox
-==== value ====
+The text of the textbox.
+=== value ===
 * '''w.value = value'''
 * '''number'''
 * '''get/set'''
 * [slider]
-==== percentage ====
+=== percentage ===
 * '''w.percentage = value'''
 * '''number'''
 * '''get/set'''
 * [progress_bar]
-==== selected_item_path ====
+=== selected_item_path ===
 * '''value = w.selected_item_path'''
 * '''array of integers'''
 * '''get'''
 * [slider]
-a table descibing the currently selected node. If for example in this 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
@@ Line 65: / Line 80: @@
     *Item11
     *Item12
-Item 9 is selected the value will be {2,1,3}
-==== path ====
+=== path ===
 * '''value = w.path'''
 * '''array of integers'''
 * '''get'''
 * [tree_view_node]
 See selected_item_path for the syntax.
-==== unfolded ====
+=== unfolded ===
 * '''w.unfolded = value'''
 * '''boolean'''
 * '''set'''
 * [tree_view_node]
-==== unit ====
+=== unit ===
 * '''w.unit = value'''
 * '''unit''' or '''unit type'''
 * '''set'''
 * [unit_preview_pane]
-==== item_count ====
+=== item_count ===
 * '''value = w.item_count'''
 * '''number'''
 * '''get'''
 * [multi_page], [listbox]
-==== use_markup ====
+=== use_markup ===
 * '''w.use_markup = value'''
 * '''boolean'''
 * '''set'''
 * most widgets, in particular [label], [button]
-==== label ====
+=== label ===
 * '''w.label = value'''
 * '''string'''
 * '''set'''
 * most widgets, in particular [label], [button], [image]
-the label, technically the is a special string used in the widgets wml definition, it usualyl does what one would expect but also sets the image for [image] widgets
-==== marked_up_text ====
+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.
+=== marked_up_text ===
 * '''w.marked_up_text = value'''
 * '''string'''
 * '''set'''
 * most widgets, in particular [label], [button]
-shortcut for setting label and use_markup=yes
-==== enabled ====
+Shortcut for setting label and use_markup=yes.
+=== enabled ===
 * '''w.enabled = value'''
 * '''boolean'''
 * '''set'''
 * all widgets
-==== tooltip ====
+=== tooltip ===
 * '''w.tooltip = value'''
 * '''string'''
 * '''set'''
 * all widgets
-==== visible ====
+=== visible ===
 * '''w.visible = value'''
 * '''string'''
 * '''set'''
 * all widgets
 The following visibility statuses are recognized:
 {| clasS="wikitable"
@@ Line 129: / Line 167: @@
 | invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
 |}
-==== type ====
+=== type ===
 * '''value = w.type'''
 * '''string'''
 * '''get'''
 * all widgets
-=== widget callbacks ===
-==== on_modified ====
+== widget callbacks ==
+=== on_modified ===
 * '''function w.on_modified() .... end
 * all widgets the allow the user to select a value of any type.
-==== on_left_click ====
+=== on_left_click ===
 * '''function w.on_left_click() .... end
 * all widgets
-==== on_button_click ====
+=== on_button_click ===
 * '''function w.on_button_click() .... end
 * button type widgets
-=== widget methods ===
+== widget methods ==
+=== focus ===
-==== focus ====
 * '''w.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 ====
+=== set_canvas ===
 * '''w.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 (empty path = window widget)
+<syntaxhighlight lang=lua>
- wesnoth.set_dialog_canvas(2, {
+-- draw two rectangles in the upper-left corner of the window (assume dialog is the window widget)
-     T.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
+dialog.set_canvas(2, {
-     T.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,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" }
+})
+</syntaxhighlight>
 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 ====
+=== add_item ===
 * '''w.add_item()'''
-add an item to a widget, for example a listbox, returns the created item as a widget userdata.
-==== add_item_of_type ====
+Add an item to a widget, for example a listbox. Returns the created item as a widget userdata.
+=== add_item_of_type ===
 * '''w.add_item_of_type("category")'''
-add an item to a widget which Is a  heterogeneous container of different types of widgets, in particular multi_pages and treeviews
-==== remove_items_at ====
+Add an item to a widget which is a  heterogeneous container of different types of widgets, in particular multi_pages and treeviews.
+=== remove_items_at ===
 * '''w.remove_items_at(2)'''
-removes the widget at the given index of a container type widget (like treeviews).
-==== find ====
+Removes the widget at the given index of a container type widget (like treeviews).
+=== find ===
 * '''dialog.find(unit_list, 2, preview_panel)'''
-Finds a child widget of the widget of the given path, for example here is 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'