Difference between revisions of "LuaAPI/types/widget"

From The Battle for Wesnoth Wiki
< LuaAPI‎ | types
(selected)
(label)
 
(8 intermediate revisions by one other user not shown)
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 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.
+
<div class="tright"> __TOC__ </div>
 +
 
 +
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:
 
An example of accessing a child widget:
Line 6: Line 8:
 
function preshow(dialog)
 
function preshow(dialog)
 
   local okay_button = dialog.okay_button
 
   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
 
end
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 17: Line 19:
 
* Available on: '''[toggle_button]''', '''[toggle_panel]'''
 
* 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. There exist in particular 3-State [toggle_button]s (for example in listbox headers): For those selected_index must be used instead..
+
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 ===
 
=== selected_index ===
Line 24: Line 26:
 
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[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. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (0 or 1) instead of a boolean.
+
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.
  
 
=== text ===
 
=== text ===
Line 45: Line 47:
 
* Available on: '''[progress_bar]'''
 
* Available on: '''[progress_bar]'''
  
The current position of the progress bar, between 0 and 1.
+
The current position of the progress bar, between 0 and 100.
  
 
=== selected_item_path ===
 
=== selected_item_path ===
Line 97: Line 99:
  
 
* ''widget''.'''item_count''' &rarr; ''number of items''
 
* ''widget''.'''item_count''' &rarr; ''number of items''
* Available on: '''[multi_page]''', '''listbox'''
+
* Available on: '''[multi_page]''', '''[listbox]'''
  
 
The number of items in the container widget.
 
The number of items in the container widget.
Line 113: Line 115:
 
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''
 
* 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.
+
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 ===
 
=== marked_up_text ===
Line 159: Line 161:
 
=== on_modified ===
 
=== on_modified ===
  
* ''widget''.'''on_modified''' &larr; ''function''
+
* ''widget''.'''on_modified''' &larr; '''function'''()
 
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''
 
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''
  
Line 166: Line 168:
 
=== on_left_click ===
 
=== on_left_click ===
  
* ''widget''.'''on_left_click''' &larr; ''function''
+
* ''widget''.'''on_left_click''' &larr; '''function'''()
 
* Available on: All widgets
 
* Available on: All widgets
  
Line 173: Line 175:
 
=== on_button_click ===
 
=== on_button_click ===
  
* ''widget''.'''on_button_click''' &larr; ''function''
+
* ''widget''.'''on_button_click''' &larr; '''function'''()
 
* Available on: '''[button]''', '''[repeating_button]'''
 
* Available on: '''[button]''', '''[repeating_button]'''
  
Line 181: Line 183:
  
 
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''' befor calling the method.
 
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''' befor calling the method.
 +
 +
[[Category:Lua Reference]]

Latest revision as of 12:28, 23 November 2023

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.selectedboolean
  • 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_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 (1 for false or 2 for true) 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 100.

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

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

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 befor calling the method.

This page was last edited on 23 November 2023, at 12:28.