Difference between revisions of "LuaAPI/gui/widget"
(→remove_items_at: Fix missing argument) |
(Add clear()) |
||
| (7 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
| − | 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. | + | The '''gui.widget''' module contains functions for managing widgets in custom GUI2 dialogs. Since these functions take a [[LuaAPI/types/widget|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. |
'''Note:''' The '''gui.widget.set_callback''' is a compatibility wrapper and is unsupported. It may be removed without warning. Callbacks should be bound by assigning the appropriate callback key on the widget. | '''Note:''' The '''gui.widget.set_callback''' is a compatibility wrapper and is unsupported. It may be removed without warning. Callbacks should be bound by assigning the appropriate callback key on the widget. | ||
| Line 18: | Line 18: | ||
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 depends on which shape is used: | 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 depends on which shape is used: | ||
| − | * [ | + | * [[GUICanvasWML#Circle|Circle]] |
| − | * [ | + | * [[GUICanvasWML#Image|Image]] |
| − | * [ | + | * [[GUICanvasWML#Line|Line]] |
| − | * [ | + | * [[GUICanvasWML#Bounded_Shape|common attributes of rectangles, round rectangles and text]] |
| − | * [ | + | * [[GUICanvasWML#Rectangle|Rectangle]] |
| − | * [ | + | * [[GUICanvasWML#Rounded_Rectangle|Rounded Rectangle]] |
| − | * [ | + | * [[GUICanvasWML#Text|Text]] |
<syntaxhighlight lang=lua> | <syntaxhighlight lang=lua> | ||
| Line 41: | Line 41: | ||
* ''widget'':'''add_item'''([''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 | + | Add an item to a container widget, for example a listbox. Returns the created item as a [[LuaAPI/types/widget|widget userdata]]. |
=== add_item_of_type === | === add_item_of_type === | ||
| Line 48: | Line 48: | ||
* ''widget'':'''add_item_of_type'''(''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 | + | 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 === | === remove_items_at === | ||
| Line 56: | Line 56: | ||
Removes one or more elements of a container type widget (like treeviews), starting at the given index. If 0 is passed as the count, all elements from that point to the end are removed. Otherwise, the specified number of elements are removed. | Removes one or more elements of a container type widget (like treeviews), starting at the given index. If 0 is passed as the count, all elements from that point to the end are removed. Otherwise, the specified number of elements are removed. | ||
| + | |||
| + | === clear === | ||
| + | {{DevFeature1.19|5}} | ||
| + | |||
| + | * '''gui.widget.clear'''(''widget'') | ||
| + | * ''widget'':'''clear'''() | ||
| + | |||
| + | Removes all elements of a container type widget. | ||
=== find === | === find === | ||
| Line 66: | Line 74: | ||
<syntaxhighlight lang=lua> | <syntaxhighlight lang=lua> | ||
dialog:find('unit_list', 2, 'preview_panel') | dialog:find('unit_list', 2, 'preview_panel') | ||
| + | </syntaxhighlight> | ||
| + | |||
| + | This is more or less equivalent to the following: | ||
| + | |||
| + | <syntaxhighlight lang=lua> | ||
| + | dialog.unit_list[2].preview_panel | ||
| + | </syntaxhighlight> | ||
| + | |||
| + | However, if the path comes from a variable, the functional form may be more convenient: | ||
| + | |||
| + | <syntaxhighlight lang=lua> | ||
| + | dialog:find(table.unpack(path)) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Latest revision as of 21:04, 21 October 2024
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.
Note: The gui.widget.set_callback is a compatibility wrapper and is unsupported. It may be removed without warning. Callbacks should be bound by assigning the appropriate callback key on the widget.
Contents
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 depends on which shape is used:
- Circle
- Image
- Line
- common attributes of rectangles, round rectangles and text
- Rectangle
- Rounded Rectangle
- Text
-- 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.
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.
remove_items_at
- gui.widget.remove_items_at(widget, position, count)
- widget:remove_items_at(position, count)
Removes one or more elements of a container type widget (like treeviews), starting at the given index. If 0 is passed as the count, all elements from that point to the end are removed. Otherwise, the specified number of elements are removed.
clear
(Version 1.19.5 and later only)
- gui.widget.clear(widget)
- widget:clear()
Removes all elements of a container type widget.
find
- gui.widget.find(root widget, ...)
- widget:find(...)
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')
This is more or less equivalent to the following:
dialog.unit_list[2].preview_panel
However, if the path comes from a variable, the functional form may be more convenient:
dialog:find(table.unpack(path))
close
- gui.widget.close(dialog)
- widget:close()
Closes the dialog.