Difference between revisions of "LuaAPI/gui/widget"

From The Battle for Wesnoth Wiki
< LuaAPI‎ | gui
(Document the gui.widget module (content moved from LuaAPI/types/widget))
 
(find)
Line 57: Line 57:
 
dialog:find(unit_list, 2, preview_panel)
 
dialog:find(unit_list, 2, preview_panel)
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
=== close ===
 +
 +
* '''gui.widget.close'''(''dialog'')
 +
* ''widget'':'''close'''()
 +
* Not Yet Implemented
 +
 +
Closes the dialog.

Revision as of 22:59, 27 September 2020

The gui.widget module contains functions for managing widgets in custom GUI2 dialogs. Since these functions take a widget userdata as the first parameter, they can only be used in the preshow or postshow of a GUI2 dialog (directly or indirectly). However, the table is available at all times, and additional methods can be installed here for unusual needs.

focus

  • gui.widget.focus(widget)
  • 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

  • gui.widget.set_canvas(widget, 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.

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

  • gui.widget.add_item(widget[, position]) → the new item, position
  • widget:add_item([position]) → the new item, position

Add an item to a container widget, for example a listbox. Returns the created item as a widget userdata. You can pass a negative position to count from the end of the container, but the returned position is always positive.

add_item_of_type

  • gui.widget.add_item_of_type(widget, category[, position]) → the new item, position
  • widget:add_item_of_type(category[, position]) → the new item, position

Add an item to a widget which is a heterogeneous container of different types of widgets, in particular multi_pages and treeviews. You can pass a negative position to count from the end of the container, but the returned position is always positive.

remove_items_at

  • gui.widget.remove_items_at(widget, position)
  • widget:remove_items_at(position)

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

find

  • gui.widget.find(root widget, path, to, widget)
  • 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':

dialog:find(unit_list, 2, preview_panel)

close

  • gui.widget.close(dialog)
  • widget:close()
  • Not Yet Implemented

Closes the dialog.