LuaAPI/types/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 userdataq are different for each widgets. Indexing a widgets userdata can either be used to

• Access a child widget

Example code ``` 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

• 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

• 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
  *Item1
  *Item2
  *Item3
 +Subsection12
  *Item4
  *Item5
  *Item6
+Section2
 +Subsection21
  *Item7
  *Item8
  *Item9
 +Subsection22
  *Item10
  *Item11
  *Item12

Item 9 is selected the value will be {2,1,3}

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

• 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 (empty path = window widget)
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.

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