Difference between revisions of "LuaAPI/types/widget"

From The Battle for Wesnoth Wiki
< LuaAPI‎ | types
(Apply the new style guide)
Line 14: Line 14:
 
=== selected ===
 
=== selected ===
  
* '''w.selected = value'''
+
* ''widget''.'''selected''' &harr; ''boolean''
* '''boolean'''
 
* '''get/set'''
 
 
* [toggle_button], [toggle_panel]
 
* [toggle_button], [toggle_panel]
  
Line 23: Line 21:
 
=== selected_index ===
 
=== selected_index ===
  
* '''w.selected_index = value'''
+
* ''widget''.'''selected_index''' &harr; ''index''
* '''number'''
 
* '''get/set'''
 
 
* [listbox], [multi_page], [stacked_widget], selectable_item ([menu_button], [toggle_button], [toggle_panel])
 
* [listbox], [multi_page], [stacked_widget], selectable_item ([menu_button], [toggle_button], [toggle_panel])
  
Line 32: Line 28:
 
=== text ===
 
=== text ===
  
* '''w.text = value'''
+
* ''widget''.'''text''' &harr; ''text''
* '''string'''
 
* '''get/set'''
 
 
* [text_box]
 
* [text_box]
  
Line 41: Line 35:
 
=== value ===
 
=== value ===
  
* '''w.value = value'''
+
* ''widget''.'''value''' &harr; ''position''
* '''number'''
 
* '''get/set'''
 
 
* [slider]
 
* [slider]
  
 
=== percentage ===
 
=== percentage ===
  
* '''w.percentage = value'''
+
* ''widget''.'''percentage''' &harr; ''position''
* '''number'''
 
* '''get/set'''
 
 
* [progress_bar]
 
* [progress_bar]
  
 
=== selected_item_path ===
 
=== selected_item_path ===
  
* '''value = w.selected_item_path'''
+
* ''widget''.'''selected_item_path''' &rarr; ''array of indices''
* '''array of integers'''
 
* '''get'''
 
 
* [slider]
 
* [slider]
  
Line 83: Line 71:
 
=== path ===
 
=== path ===
  
* '''value = w.path'''
+
* ''widget''.'''path''' &rarr; ''array of indices''
* '''array of integers'''
 
* '''get'''
 
 
* [tree_view_node]
 
* [tree_view_node]
  
Line 92: Line 78:
 
=== unfolded ===
 
=== unfolded ===
  
* '''w.unfolded = value'''
+
* ''widget''.'''unfolded''' &larr; ''boolean''
* '''boolean'''
 
* '''set'''
 
 
* [tree_view_node]
 
* [tree_view_node]
  
 
=== unit ===
 
=== unit ===
  
* '''w.unit = value'''
+
* ''widget''.'''unit''' &larr; ''unit or unit type''
* '''unit''' or '''unit type'''
 
* '''set'''
 
 
* [unit_preview_pane]
 
* [unit_preview_pane]
  
 
=== item_count ===
 
=== item_count ===
  
* '''value = w.item_count'''
+
* ''widget''.'''item_count''' &rarr; ''number of items''
* '''number'''
 
* '''get'''
 
 
* [multi_page], [listbox]
 
* [multi_page], [listbox]
  
 
=== use_markup ===
 
=== use_markup ===
  
* '''w.use_markup = value'''
+
* ''widget''.'''use_markup''' &rarr; ''boolean''
* '''boolean'''
 
* '''set'''
 
 
* most widgets, in particular [label], [button]
 
* most widgets, in particular [label], [button]
  
 
=== label ===
 
=== label ===
  
* '''w.label = value'''
+
* ''widget''.'''label''' &larr; ''text''
* '''string'''
 
* '''set'''
 
 
* most widgets, in particular [label], [button], [image]
 
* most widgets, in particular [label], [button], [image]
  
Line 129: Line 105:
 
=== marked_up_text ===
 
=== marked_up_text ===
  
* '''w.marked_up_text = value'''
+
* ''widget''.'''marked_up_text''' &larr; ''text''
* '''string'''
 
* '''set'''
 
 
* most widgets, in particular [label], [button]
 
* most widgets, in particular [label], [button]
  
Line 138: Line 112:
 
=== enabled ===
 
=== enabled ===
  
* '''w.enabled = value'''
+
* ''widget''.'''enabled''' &larr; ''boolean''
* '''boolean'''
 
* '''set'''
 
 
* all widgets
 
* all widgets
  
 
=== tooltip ===
 
=== tooltip ===
  
* '''w.tooltip = value'''
+
* ''widget''.'''tooltip''' &larr; ''text''
* '''string'''
 
* '''set'''
 
 
* all widgets
 
* all widgets
  
 
=== visible ===
 
=== visible ===
  
* '''w.visible = value'''
+
* ''widget''.'''visible''' &larr; ''visibility string''
* '''string'''
 
* '''set'''
 
 
* all widgets
 
* all widgets
  
Line 170: Line 138:
 
=== type ===
 
=== type ===
  
* '''value = w.type'''
+
* ''widget''.'''type''' &rarr; ''string''
* '''string'''
 
* '''get'''
 
 
* all widgets
 
* all widgets
  
Line 178: Line 144:
 
=== on_modified ===
 
=== on_modified ===
  
* '''function w.on_modified() .... end
+
* ''widget''.'''on_modified''' &larr; ''function''
 
* all widgets the allow the user to select a value of any type.
 
* 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
+
* ''widget''.'''on_left_click''' &larr; ''function''
 
* all widgets
 
* all widgets
  
 
=== on_button_click ===
 
=== on_button_click ===
  
* '''function w.on_button_click() .... end
+
* ''widget''.'''on_button_click''' &larr; ''function''
 
* button type widgets
 
* button type widgets
  
Line 195: Line 161:
 
=== focus ===
 
=== focus ===
  
* '''w: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.
 
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.
Line 201: Line 167:
 
=== set_canvas ===
 
=== set_canvas ===
  
* '''w:set_canvas(layer index, content)'''
+
* ''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]].
 
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]].
Line 217: Line 183:
 
=== add_item ===
 
=== add_item ===
  
* '''w:add_item()'''
+
* ''widget'':'''add_item'''() &rarr; ''the new item''
  
 
Add an item to a widget, for example a listbox. Returns the created item as a widget userdata.
 
Add an item to a widget, for example a listbox. Returns the created item as a widget userdata.
Line 223: Line 189:
 
=== add_item_of_type ===
 
=== add_item_of_type ===
  
* '''w:add_item_of_type("category")'''
+
* '''widget'':'''add_item_of_type'''(''category'') &rarr; ''the new item''
  
 
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.
Line 229: Line 195:
 
=== remove_items_at ===
 
=== remove_items_at ===
  
* '''w:remove_items_at(2)'''
+
* ''widget'':'''remove_items_at''(''position'')
  
 
Removes the widget at the given index of a container type widget (like treeviews).
 
Removes the widget at the given index of a container type widget (like treeviews).
Line 235: Line 201:
 
=== find ===
 
=== find ===
  
* '''dialog:find(unit_list, 2, preview_panel)'''
+
* ''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'

Revision as of 22:34, 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
  • [toggle_button], [toggle_panel]

Whether the item is selected or not.

selected_index

  • widget.selected_indexindex
  • [listbox], [multi_page], [stacked_widget], selectable_item ([menu_button], [toggle_button], [toggle_panel])

The selected index of the item.

text

  • widget.texttext
  • [text_box]

The text of the textbox.

value

  • widget.valueposition
  • [slider]

percentage

  • widget.percentageposition
  • [progress_bar]

selected_item_path

  • widget.selected_item_patharray of indices
  • [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

  • widget.patharray of indices
  • [tree_view_node]

See selected_item_path for the syntax.

unfolded

  • widget.unfoldedboolean
  • [tree_view_node]

unit

  • widget.unitunit or unit type
  • [unit_preview_pane]

item_count

  • widget.item_countnumber of items
  • [multi_page], [listbox]

use_markup

  • widget.use_markupboolean
  • most widgets, in particular [label], [button]

label

  • widget.labeltext
  • 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

  • widget.marked_up_texttext
  • most widgets, in particular [label], [button]

Shortcut for setting label and use_markup=yes.

enabled

  • widget.enabledboolean
  • all widgets

tooltip

  • widget.tooltiptext
  • all widgets

visible

  • widget.visiblevisibility string
  • 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

  • widget.typestring
  • all widgets

widget callbacks

on_modified

  • widget.on_modifiedfunction
  • all widgets the allow the user to select a value of any type.

on_left_click

  • widget.on_left_clickfunction
  • all widgets

on_button_click

  • widget.on_button_clickfunction
  • button type widgets

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() → the new item

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

add_item_of_type

  • widget:'add_item_of_type(category) → the new item

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

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