Difference between revisions of "LuaAPI/types/widget"

Latest revision as of 16:24, 5 November 2024

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 or write-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 widget's child with the id 'okay_button' 
end

Widget Attributes

selected

widget.selected ↔ boolean
Available on: [toggle_button], [toggle_panel]

Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.

selected_index

widget.selected_index ↔ index
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 (1 for false or 2 for true) instead of a boolean.

For a [listbox]with has_maximum=false and more than one item selected, reading selected_index will return the first selected index.

For a [stacked_widget], only the layer specified by selected_index will be displayed and receive events (callbacks will only be triggered on the selected layer). A selected_index of 0 represents all layers being selected, with events only being received by the layer with the highest index. Note that term selected for the layer of a stacked_widget is not the same as the selected widget attribute.

text

widget.text ↔ text
Available on: [text_box]

The text of the textbox.

value

widget.value ↔ position
Available on: [slider]

The current position of the slider.

percentage

widget.percentage ↔ position
Available on: [progress_bar]

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

selected_item_path

widget.selected_item_path → array of indices
Available on: [tree_view]

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.path → array 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.unfolded ← boolean
Available on: [tree_view_node]

Control whether a tree node is currently expanded or not.

unit

widget.unit ← unit or unit type
Available on: [unit_preview_pane]

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

item_count

widget.item_count → number of items
Available on: [multi_page], [listbox]

The number of items in the container widget.

use_markup

widget.use_markup → boolean
Available on: Most widgets, in particular [label], [button]

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

label

widget.label ← text
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. For [text_box], use text for initial values.

marked_up_text

widget.marked_up_text ← text
Available on: Most widgets, in particular [label], [button]

Shortcut for setting label and use_markup=yes.

enabled

widget.enabled ← boolean
Available on: Most widgets

tooltip

widget.tooltip ← text
Available on: Most widgets

visible

widget.visible ← visibility string
Available on: Most 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.type → string
Available on: All widgets

Returns a string specifying the type of the widget.

Widget callbacks

on_modified

widget.on_modified ← function()
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_click ← function()
Available on: All widgets

Triggers when the user clicks on the widget.

on_button_click

widget.on_button_click ← function()
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

Any function defined in the gui.widget module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check widget.type before calling the method.

@@ 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
+<div class="tright"> __TOC__ </div>
-* Access a child widget
+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 or write-only; the properties depend on the type of the widget.
-Example code
-```
+An example of accessing a child widget:
+<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'
+   -- okay_button is now a handle to the the widget's 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''.'''selected''' &harr; ''boolean''
+* Available on: '''[toggle_button]''', '''[toggle_panel]'''
+Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.
+=== selected_index ===
+* ''widget''.'''selected_index''' &harr; ''index''
+* 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 (1 for false or 2 for true) instead of a boolean.
+For a  '''[listbox]'''with '''has_maximum=false''' and more than one item selected, reading '''selected_index''' will return the first selected index.
+For a '''[stacked_widget]''', only the layer specified by '''selected_index''' will be displayed and receive events (callbacks will only be triggered on the selected layer).
+A '''selected_index''' of 0 represents all layers being selected, with events only being received by the layer with the highest index.  Note that term ''selected'' for the ''layer'' of a stacked_widget is not the same as the '''selected''' ''widget'' attribute.
+=== text ===
+* ''widget''.'''text''' &harr; ''text''
+* Available on: '''[text_box]'''
+The text of the textbox.
+=== value ===
+* ''widget''.'''value''' &harr; ''position''
+* Available on: '''[slider]'''
+The current position of the slider.
+=== percentage ===
+* ''widget''.'''percentage''' &harr; ''position''
+* Available on: '''[progress_bar]'''
+The current position of the progress bar, between 0 and 100.
+=== selected_item_path ===
+* ''widget''.'''selected_item_path''' &rarr; ''array of indices''
+* Available on: '''[tree_view]'''
+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}.
-=== 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 descibing the currently selected node. If for example in this treeview
   +Section1
    +Subsection11
@@ Line 65: / Line 79: @@
     *Item11
     *Item12
-Item 9 is selected the value will be {2,1,3}
-==== path ====
+=== path ===
-* '''value = w.path'''
-* '''array of integers'''
+* ''widget''.'''path''' &rarr; ''array of indices''
-* '''get'''
+* Available on: '''[tree_view_node]'''
-* [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 ====
-* '''w.unfolded = value'''
+=== unfolded ===
-* '''boolean'''
-* '''set'''
+* ''widget''.'''unfolded''' &larr; ''boolean''
-* [tree_view_node]
+* Available on: '''[tree_view_node]'''
-==== unit ====
-* '''w.unit = value'''
+Control whether a tree node is currently expanded or not.
-* '''unit''' or '''unit type'''
-* '''set'''
+=== unit ===
-* [unit_preview_pane]
-==== item_count ====
+* ''widget''.'''unit''' &larr; ''unit or unit type''
-* '''value = w.item_count'''
+* Available on: '''[unit_preview_pane]'''
-* '''number'''
-* '''get'''
+Change the displayed unit or unit type in the preview pane.
-* [multi_page], [listbox]
-==== use_markup ====
+=== item_count ===
-* '''w.use_markup = value'''
-* '''boolean'''
+* ''widget''.'''item_count''' &rarr; ''number of items''
-* '''set'''
+* Available on: '''[multi_page]''', '''[listbox]'''
-* most widgets, in particular [label], [button]
-==== label ====
+The number of items in the container widget.
-* '''w.label = value'''
-* '''string'''
+=== use_markup ===
-* '''set'''
-* most widgets, in particular [label], [button], [image]
+* ''widget''.'''use_markup''' &rarr; ''boolean''
-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
+* Available on: Most widgets, in particular '''[label]''', '''[button]'''
-==== marked_up_text ====
-* '''w.marked_up_text = value'''
+Sets whether the widget's label will parse [[Pango formatting]].
-* '''string'''
-* '''set'''
+=== label ===
-* most widgets, in particular [label], [button]
-shortcut for setting label and use_markup=yes
+* ''widget''.'''label''' &larr; ''text''
-==== enabled ====
+* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''
-* '''w.enabled = value'''
-* '''boolean'''
+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.  For '''[text_box]''', use '''text''' for initial values.
-* '''set'''
-* all widgets
+=== marked_up_text ===
-==== tooltip ====
-* '''w.tooltip = value'''
+* ''widget''.'''marked_up_text''' &larr; ''text''
-* '''string'''
+* Available on: Most widgets, in particular '''[label]''', '''[button]'''
-* '''set'''
-* all widgets
+Shortcut for setting label and use_markup=yes.
-==== visible ====
-* '''w.visible = value'''
+=== enabled ===
-* '''string'''
-* '''set'''
+* ''widget''.'''enabled''' &larr; ''boolean''
-* all widgets
+* Available on: Most widgets
-The following visibility statuses are recognized:
+=== tooltip ===
+* ''widget''.'''tooltip''' &larr; ''text''
+* Available on: Most widgets
+=== visible ===
+* ''widget''.'''visible''' &larr; ''visibility string''
+* Available on: Most widgets
+Determines whether the widget is visible onscreen. The following visibility statuses are recognized:
 {| clasS="wikitable"
 ! String value !! Boolean shorthand !! Meaning
@@ Line 129: / Line 154: @@
 | 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 ===
+=== type ===
+* ''widget''.'''type''' &rarr; ''string''
+* Available on: All widgets
+Returns a string specifying the type of the widget.
+== Widget callbacks ==
+=== on_modified ===
+* ''widget''.'''on_modified''' &larr; '''function'''()
+* 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_click''' &larr; '''function'''()
+* Available on: All widgets
+Triggers when the user clicks on the widget.
+=== on_button_click ===
+* ''widget''.'''on_button_click''' &larr; '''function'''()
+* 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.
-==== focus ====
+== Widget methods ==
-* '''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 (empty path = window widget)
+Any function defined in the [[LuaAPI/gui/widget|gui.widget]] module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check '''widget.type''' before calling the method.
- wesnoth.set_dialog_canvas(2, {
-     T.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
-     T.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.
+[[Category:Lua Reference]]
-==== 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 is searches for the widget with the id 'preview_panel' of the second item of the widget with the id 'unit_list'