:mod:`wl.ui` ============= .. module:: wl.ui :synopsis: Provides access on user interface. Mainly for tutorials and debugging. .. moduleauthor:: The Widelands development team .. currentmodule:: wl.ui .. Note:: The objects inside this module can not be persisted. That is if the player tries to save the game while any of these objects are assigned to variables, the game will crash. So when using these, make sure that you only create objects for a short amount of time where the user can't take control to do something else. Module Classes ^^^^^^^^^^^^^^^^ Panel ----- .. graphviz:: :alt: Dependency graph for class: Panel graph Panel { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Panel [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, ] "Button" [href="../autogen_wl_ui/index.html#button", target="_parent", label="Button", tooltip="Button"] "Panel" -- "Button" "MultilineTextarea" [href="../autogen_wl_ui/index.html#multilinetextarea", target="_parent", label="Multiline-\nTextarea", tooltip="MultilineTextarea"] "Panel" -- "MultilineTextarea" "Textarea" [href="../autogen_wl_ui/index.html#textarea", target="_parent", label="Textarea", tooltip="Textarea"] "Panel" -- "Textarea" "Checkbox" [href="../autogen_wl_ui/index.html#checkbox", target="_parent", label="Checkbox", tooltip="Checkbox"] "Panel" -- "Checkbox" "RadioButton" [href="../autogen_wl_ui/index.html#radiobutton", target="_parent", label="Radio-\nButton", tooltip="RadioButton"] "Panel" -- "RadioButton" "ProgressBar" [href="../autogen_wl_ui/index.html#progressbar", target="_parent", label="Progress-\nBar", tooltip="ProgressBar"] "Panel" -- "ProgressBar" "SpinBox" [href="../autogen_wl_ui/index.html#spinbox", target="_parent", label="Spin-\nBox", tooltip="SpinBox"] "Panel" -- "SpinBox" "Slider" [href="../autogen_wl_ui/index.html#slider", target="_parent", label="Slider", tooltip="Slider"] "Panel" -- "Slider" "TextInputPanel" [href="../autogen_wl_ui/index.html#textinputpanel", target="_parent", label="Text-\nInput-\nPanel", tooltip="TextInputPanel"] "Panel" -- "TextInputPanel" "Dropdown" [href="../autogen_wl_ui/index.html#dropdown", target="_parent", label="Dropdown", tooltip="Dropdown"] "Panel" -- "Dropdown" "Listselect" [href="../autogen_wl_ui/index.html#listselect", target="_parent", label="Listselect", tooltip="Listselect"] "Panel" -- "Listselect" "Table" [href="../autogen_wl_ui/index.html#table", target="_parent", label="Table", tooltip="Table"] "Panel" -- "Table" "TabPanel" [href="../autogen_wl_ui/index.html#tabpanel", target="_parent", label="Tab-\nPanel", tooltip="TabPanel"] "Panel" -- "TabPanel" "Tab" [href="../autogen_wl_ui/index.html#tab", target="_parent", label="Tab", tooltip="Tab"] "Panel" -- "Tab" "Window" [href="../autogen_wl_ui/index.html#window", target="_parent", label="Window", tooltip="Window"] "Panel" -- "Window" "MapView" [href="../autogen_wl_ui/index.html#mapview", target="_parent", label="Map-\nView", tooltip="MapView"] "Panel" -- "MapView" } .. class:: Panel The Panel is the most basic ui class. Each UI element is a panel. .. attribute:: name .. versionadded:: 1.2 (RO) The name of this panel. .. attribute:: children .. versionadded:: 1.2 (RO) An :class:`array` of all direct children of this panel. The array also contains invisible children. It does not contain indirect descendants. .. attribute:: buttons (RO) An :class:`array` of all visible buttons inside this Panel. .. attribute:: dropdowns (RO) An :class:`array` of all visible dropdowns inside this Panel. .. attribute:: tabs (RO) An :class:`array` of all visible tabs inside this Panel. .. attribute:: windows (RO) A :class:`array` of all currently open windows that are children of this Panel. .. attribute:: width, height (RW) The dimensions of this panel in pixels .. attribute:: position_x, position_y (RO) The top left pixel of the our inner canvas relative to the parent's element inner canvas. .. attribute:: visible .. versionadded:: 1.2 (RW) Whether this panel is visible to the user. .. method:: get_descendant_position(child) Get the child position relative to the inner canvas of this Panel in pixels. Throws an error if child is not really a child. :arg child: children to get position for :type child: :class:`Panel` :returns: x, y :rtype: both are :class:`integers` .. method:: die() .. versionadded:: 1.2 Delete this panel in the next frame. .. method:: force_redraw() .. versionadded:: 1.2 Force the screen to redraw immediately. .. warning:: Only call this during a blocking operation from a plugin, otherwise it will interfere with the regular redrawing and may result in glitches or crashes. .. method:: get_child(name[, recursive=true]) .. versionadded:: 1.2 Get a panel by name that is a descendant of this panel. If the optional parameter is ``false``, only direct children of this panel are considered. :arg name: Name of the descendant to look for. :type child: :class:`string` :arg recursive: Also consider non-direct descendants. :type child: :class:`boolean` :returns: The child upcasted to the correct class, or ``nil`` if the child does not exist. .. method:: create_child(table) .. versionadded:: 1.2 Create a UI widget as a child of this panel as specified by the provided table. A UI descriptor table contains multiple keys of type :class:`string`. Common properties are: * ``"widget"``: **Mandatory**. The type of widget to create. See below for allowed values. * ``"name"``: **Mandatory**. The internal name of the panel. * ``"x"``: **Optional**. The horizontal offset inside the parent from the left. Default: 0. * ``"y"``: **Optional**. The vertical offset inside the parent from the top. Default: 0. * ``"w"``: **Optional**. The widget's width. Default: automatic. * ``"h"``: **Optional**. The widget's height. Default: automatic. * ``"tooltip"``: **Optional**. The widget's tooltip. .. _resizing_strategies: * ``"resizing"``: **Optional**. If the parent component is a Box, the Resizing strategy to use for layouting. Valid values are: * ``"align"``: Use the widget's desired size. This is the default. * ``"fullsize"``: Use the widget's desired depth and the full available breadth. * ``"fillspace"``: Use the widget's desired breadth and the full available depth. * ``"expandboth"``: Use the full available space. A box's depth is its primary layout direction, and the breadth is the direction orthogonal to it. See: :ref:`Box widgets ` * ``"align"``: **Optional**. If the parent component is a Box, the Alignment strategy to use for layouting. Valid values are ``"center"`` (the default,) ``"left"``/``"top"``, and ``"right"``/``"bottom"``. * ``"on_panel_clicked"``: **Optional**. Callback code to run when the user clicks anywhere inside the widget. * ``"on_position_changed"``: **Optional**. Callback code to run when the widget's position changes. * ``"children"``: **Optional**. An array of widget descriptor tables. Keys that are not supported by the widget type are silently ignored. Currently supported types of widgets are: * ``"window"``: A window. Windows can only be added to the top-level :class:`~wl.ui.MapView`. Properties: * ``"title"``: **Mandatory**. The title bar text. * ``"content"``: **Optional**. The main panel descriptor table. The window will resize itself to accommodate this widget perfectly. * ``"unique_window"``: A window of which only one instance can exist. If a unique window with the same registry as the provided one is already open, this function does nothing. Unique windows have all attributes of non-unique windows and the following additional property: * ``"registry"``: **Mandatory**. The window's unique registry identifier. .. _box_description: * ``"box"``: A wrapper around other components with intelligent layouting. It is strongly recommended to layout all your components exclusively with Boxes. Properties: * ``"orientation"``: **Mandatory**. The box's layouting direction: ``"vertical"`` or ``"horizontal"``. The shorthands ``"vert"``, ``"v"``, ``"horz"``, and ``"h"`` may be used. The size of a child component along this direction is called its *depth*, and the size of a child component along the direction orthogonal to it is called its *breadth*. See also: The :ref:`"resizing" ` property * ``"max_x"``: **Optional**. The maximum horizontal size. Default: unlimited. * ``"max_y"``: **Optional**. The maximum vertical size. Default: unlimited. * ``"spacing"``: **Optional**. The inner spacing between items. Default: 0. * ``"scrolling"``: **Optional**. Whether the box may scroll if its content is too large. Default: false. * ``"inf_space"``: Only valid as the direct child of a Box. A flexible spacer. Takes no properties. * ``"space"``: Only valid as the direct child of a Box. A fixed-size spacer. Only accepted property: * ``"value"``: **Mandatory**. The size of the space. * ``"panel"``: A plain panel that can act as a spacer or as a container for other widgets. * ``"textarea"``: A static text area with a single line of text. Properties: * ``"text"``: **Mandatory**. The text to display. * ``"font"``: **Mandatory**. The font style to use. See :ref:`theme_fonts` * ``"text_align"``: **Optional**. The alignment of the text. Valid values are ``"center"`` (the default), ``"left"``, and ``"right"``. * ``"fixed_width"``: **Optional**. If set, the text area's width is fixed instead of resizing to accomodate the text or the parent. Default: not set. * ``"multilinetextarea"``: A static text area displaying multiple lines of text. Properties: * ``"text"``: **Mandatory**. The text to display. The text can be formatted with richtext (see :ref:`richtext.lua`), in which case the ``font`` attribute will have no effect. * ``"scroll_mode"``: **Mandatory**. The text area's scrolling behaviour. One of: * ``"none"``: The text area expands to accommodate its content instead of scrolling. * ``"normal"``: Explicit scrolling only. * ``"normal_force"``: Explicit and forced scrolling. * ``"log"``: Follow the bottom of the log. * ``"log_force"``: Follow the bottom of the log with forced scrolling. * ``"font"``: **Optional**. The font style to use. See :ref:`theme_fonts` * ``"text_align"``: **Optional**. The alignment of the text. Valid values are ``"center"`` (the default), ``"left"``, and ``"right"``. .. _button_description: * ``"button"``: A clickable button. A button must have either a title or an icon, but not both. Properties: * ``"title"``: **Optional**. The text on the button. * ``"icon"``: **Optional**. The file path of the button's icon. * ``"style"``: **Optional**. The button's style. One of: * ``"primary"`` * ``"secondary"`` (default) * ``"menu"`` * ``"visual"``: **Optional**. The button's appearance. One of: * ``"raised"`` (default) * ``"permpressed"`` * ``"flat"`` * ``"repeating"``: **Optional**. Whether pressing and holding the button generates repeated events. Default: false. * ``"on_click"``: **Optional**. Callback code to run when the button is clicked. To associate actions with a button press, prefer this over the ``on_panel_clicked`` event. * ``"checkbox"``: A toggleable checkbox. A checkbox must have either a title or an icon, but not both. Properties: * ``"title"``: **Optional**. The text on the button. * ``"icon"``: **Optional**. The file path of the button's icon. * ``"state"``: **Optional**. Whether the checkbox is initially checked. * ``"on_changed"``: **Optional**. Callback code to run when the checkbox's state changes. * ``"radiogroup"``: A group of pictorial buttons of which at most one can be selected at the same time. Properties: * ``"buttons"``: **Mandatory**. An array of tables, each of which defines a radiobutton with the following properties: * ``"name"``: **Mandatory**. The internal name of the button. * ``"icon"``: **Mandatory**. The file path of the radiobutton's icon. * ``"tooltip"``: **Optional**. The radiobutton's tooltip. * ``"x"``: **Optional**. The radiobutton's x position. * ``"y"``: **Optional**. The radiobutton's y position. * ``"state"``: **Optional**. The ID of the initially active radiobutton (0-based; -1 for none). * ``"on_changed"``: **Optional**. Callback code to run when the radiogroup's active button changes. This widget does not use the sizing and positioning properties and has no tooltip. * ``"progressbar"``: A partially filled bar that indicates the progress of an operation. Properties: * ``"orientation"``: **Mandatory**. The progress bar's direction: ``"vertical"`` or ``"horizontal"``. The shorthands ``"vert"``, ``"v"``, ``"horz"``, and ``"h"`` may be used. * ``"total"``: **Mandatory**. The progress bar's maximum value. * ``"state"``: **Mandatory**. The progress bar's initial value. * ``"percent"``: **Optional**. Whether to show a percentage instead of absolute values. Default: :const:`true`. * ``"spinbox"``: A box with buttons to increase or decrease a numerical value. There are two kinds of spinboxes by their value ranges: normal spinboxes that can have any integer value within a range, and spinboxes that can only use values from a value list. Some properties are only used by one kind of spinbox and forbidden for the other kind. * Common Properties: * ``"unit_w"``: **Mandatory**. The total width of the buttons and value display. * ``"value"``: **Mandatory**. The spinbox's initial value. When ``"values"`` is used, this is a 0 based index within the value list. * ``"label"``: **Optional**. Text to display next to the spinbox. * ``"units"``: **Optional**. The unit for the spinbox's value. One of: * ``"none"`` (default) * ``"pixels"`` * ``"percent"`` * ``"fields"`` * ``"minutes"`` * ``"weeks"`` * ``"replacements"``: **Optional**. An array of tables with keys ``"value"`` and ``"replacement"``. When the spinbox's value is equal to any replaced value, the replacement string is displayed instead of the value. * ``"on_changed"``: **Optional**. Callback code to run when the spinbox's value changes. * Properties for normal spinboxes: * ``"min"``: **Mandatory** for normal spinboxes. The spinbox's minimum value. * ``"max"``: **Mandatory** for normal spinboxes. The spinbox's maximum value. * ``"step_size_small"``: **Optional**. The amount by which the value changes on each button click. * ``"step_size_big"``: **Optional**. If set, the spinbox additionally shows buttons to change the value by this larger amount. * Properties for value list spinboxes: * ``"values"``: **Mandatory** to set the type to value list. An array of integers. The spinbox can only switch between the values in this array. The properties for normal spinboxes above cannot be used when ``"values"`` is used. This widget can not have a custom tooltip. * ``"slider"``: A button that can be slid along a line to change a value. Properties: * ``"orientation"``: **Mandatory**. The slider's direction: ``"vertical"`` or ``"horizontal"``. The shorthands ``"vert"``, ``"v"``, ``"horz"``, and ``"h"`` may be used. * ``"value"``: **Mandatory**. The slider's initial value. * ``"min"``: **Mandatory**. The slider's minimum value. * ``"max"``: **Mandatory**. The slider's maximum value. * ``"cursor_size"``: **Optional**. The size of the slider button in pixels (default 20). * ``"dark"``: **Optional**. Draw the slider darker instead of lighter. * ``"on_changed"``: **Optional**. Callback code to run when the slider's value changes. * ``"discrete_slider"``: A button that can be slid along a horizontal line to change a value between several predefined points. Properties: * ``"labels"``: **Mandatory**. Array of strings. Each string defines one slider point. * ``"value"``: **Mandatory**. The initially selected value. * ``"cursor_size"``: **Optional**. The size of the slider button in pixels (default 20). * ``"dark"``: **Optional**. Draw the slider darker instead of lighter. * ``"on_changed"``: **Optional**. Callback code to run when the slider's value changes. * ``"multilineeditbox"``: A multi-line field where the user can enter text. Properties: * ``"text"``: **Optional**. The initial text in the field. * ``"password"``: **Optional**. Whether the editbox's content will be hidden. * ``"warning"``: **Optional**. Whether the editbox will be highlighted as having errors. * ``"on_changed"``: **Optional**. Callback code to run whenever the content changes. * ``"on_cancel"``: **Optional**. Callback code to run whenever the user presses Escape. * ``"editbox"``: A single-line field where the user can enter text. Has all the properties of multilineeditbox and the following additional property: * ``"on_ok"``: **Optional**. Callback code to run whenever the user presses Return. * ``"dropdown"``: A dropdown that allows the user to select an entry from a popup list. Properties: * ``"label"``: **Mandatory**. The text on the dropdown. * ``"max_list_items"``: **Mandatory**. Maximum number of items to show in the list. * ``"button_dimension"``: **Mandatory**. Size of the button in pixels. * ``"button_style"``: **Mandatory**. The style for the button. See: :ref:`Button widgets `. * ``"type"``: **Mandatory**. The behaviour of the dropdown. One of: * ``"textual"``: Shows the name of the selected entry and a push button. * ``"textual_narrow"``: Only shows the name of the selected entry. * ``"pictorial"``: Only shows the icon of the selected entry. * ``"pictorial_menu"``: The shown icon remains always unchanged. * ``"textual_menu"``: The shown text remains always unchanged. * ``"datatype"``: **Mandatory**. The data type of the dropdown's entries. Currently only ``"string"`` is supported. * ``"icon"``: **Optional**. The icon filepath for the dropdown's button, if any. If an icon is set, the label or selected value are not displayed on the button and only shown as a tooltip. * ``"entries"``: **Optional**. The entries in the dropdown. An array of tables with the following keys: * ``"label"``: **Mandatory**. The text for this entry. * ``"value"``: **Mandatory**. The internal value of this entry. * ``"icon"``: **Mandatory** for dropdowns of type ``"pictorial"``, **optional** for other types. The icon filepath for the entry. * ``"tooltip"``: **Optional**. The entry's tooltip. * ``"select"``: **Optional**. Whether to select this entry (default :const:`false`). * ``"on_selected"``: **Optional**. Callback code to run when the user selects an entry. * ``"listselect"``: A list of entries from which the user may choose. Properties: * ``"type"``: **Optional**. The highlighting mode for the selected entry. One of: * ``"plain"``: Highlight the selection's background (default). * ``"check"``: Draw a check mark before the selected item. * ``"dropdown"``: Select entries as soon as the mouse hovers over them. * ``"datatype"``: **Mandatory**. The data type of the listselect's entries. Currently only ``"string"`` is supported. * ``"entries"``: **Optional**. The entries in the listselect. An array of tables with the following keys: * ``"label"``: **Mandatory**. The text for this entry. * ``"value"``: **Mandatory**. The internal value of this entry. * ``"icon"``: **Optional**. The icon filepath for the entry. * ``"tooltip"``: **Optional**. The entry's tooltip. * ``"select"``: **Optional**. Whether to select this entry (default :const:`false`). * ``"indent"``: **Optional**. How many levels to indent the item (default 0). * ``"on_selected"``: **Optional**. Callback code to run when the user selects an entry. * ``"on_double_clicked"``: **Optional**. Callback code to run when the user double-clicks on an entry. This widget can not have a custom tooltip. * ``"table"``: A table with multiple rows and columns. Properties: * ``"datatype"``: **Mandatory**. The data type of the table's entries. Currently only ``"int"`` is supported. * ``"multiselect"``: **Optional**. Whether the user can select multiple rows (default :const:`false`). * ``"sort_column"``: **Optional**. The index of the column by which the table is sorted (default 0). * ``"sort_descending"``: **Optional**. Whether the sorting order is inverted (default :const:`false`). * ``"columns"``: **Optional**. The columns in the table. An array of tables with the following keys: * ``"w"``: **Mandatory**. The width of the column in pixels. * ``"title"``: **Mandatory**. The title of the column. * ``"tooltip"``: **Optional**. The tooltip in pixels. * ``"flexible"``: **Optional**. Whether the column width adapts automatically (default :const:`false`). A table must not have multiple flexible columns. * ``"align"``: **Optional**. The alignment of the column content. Valid values are ``"center"`` (the default), ``"left"``, and ``"right"``. * ``"rows"``: **Optional**. The rows in the table. An array of tables with the following keys: * ``"value"``: **Mandatory**. The internal value associated with the row. * ``"select"``: **Optional**. Whether to select this row (default :const:`false`). * ``"disable"``: **Optional**. Whether to disable this row (default :const:`false`). * For each column ``i`` (indices are zero-based): * ``"text_"``: **Optional**. The text to show in the cell. * ``"icon_"``: **Optional**. The icon filepath in the cell. * ``"on_cancel"``: **Optional**. Callback code to run when the user presses Escape. * ``"on_selected"``: **Optional**. Callback code to run when the user selects a row. * ``"on_double_clicked"``: **Optional**. Callback code to run when the user double-clicks on an entry. This widget can not have a custom tooltip. * ``"tabpanel"``: A panel that allows switching between multiple tabs. * ``"dark"``: **Optional**. Whether to use dark appearance (default :const:`false`). * ``"active"``: **Optional**. The name or index of the initially active tab. * ``"tabs"``: **Optional**. The tabs in the tab panel. An array of tables with the following keys: * ``"name"``: **Mandatory**. The name of the tab. * ``"panel"``: **Mandatory**. The descriptor table for the panel wrapped in this tab. * ``"title"``: **Optional**. The title of the tab. If set, ``"icon"`` must be ``nil``. * ``"icon"``: **Optional**. The icon filepath for the tab. If set, ``"title"`` must be ``nil``. * ``"tooltip"``: **Optional**. The tooltip for the tab. * ``"on_clicked"``: **Optional**. Callback code to run when the user selects a tab. It is strongly recommended to use box layouting for all widgets. All widgets that are the child of a Box widget are layouted automatically by the Box. Their x and y positions will be ignored, and their width and/or height may be changed in accordance with their resizing strategy in order to optimally layout all components. If a widget appears to be missing, usually its width and/or height has been determined as zero. In this case, setting a minimum width and height or using a more dynamic resizing strategy will fix the widget's layout. Note that event callbacks functions must be provided as raw code in string form. During the lifetime of a *toolbar* widget, the Lua Interface used by the game may be reset. Therefore, any callbacks attached to such widgets must not use any functions or variables defined at an arbitrary earlier time by your script - they may have been deleted by the time the callback is invoked. Example: .. code-block:: lua push_textdomain("yes_no.wad", true) local mv = wl.ui.MapView() -- Create a toolbar button mv.toolbar:create_child({ widget = "button", name = "yes_no_toolbar_button", w = styles.get_size("toolbar_button_size"), h = styles.get_size("toolbar_button_size"), tooltip = _("Yes or No"), icon = "images/ui_basic/different.png", -- Callback code to run when the user presses the button on_click = [[ push_textdomain("yes_no.wad", true) -- Open a new window wl.ui.MapView():create_child({ widget = "window", name = "yes_or_no_window", title = _("Yes or No"), x = wl.ui.MapView().width // 2, y = wl.ui.MapView().height // 2, -- The window's content content = { -- The window's central panel: A box with three children widget = "box", orientation = "vert", name = "main_box", children = { { widget = "textarea", font = "wui_info_panel_paragraph", text = _("Click Yes or No"), name = "label_yes_no", }, { -- Space between the text and the buttons is also created like a widget widget = "space", value = 10, }, { -- Place the buttons side by side in a horizontal box widget = "box", orientation = "horz", name = "buttons_box", children = { { widget = "button", name = "no", title = _("No"), on_click = [=[ wl.ui.show_messagebox(_("Hello"), _("You clicked no!"), false) ]=], }, { widget = "space", value = 10, }, { widget = "button", name = "yes", title = _("Yes"), on_click = [=[ wl.ui.show_messagebox(_("Hello"), _("You clicked yes!")) ]=], }, }, }, } } }) pop_textdomain() ]] }) mv:update_toolbar() pop_textdomain() Button ------ .. graphviz:: :alt: Dependency graph for class: Button graph Button { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Button [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- Button } .. class:: Button Child of: :class:`Panel` This represents a simple push button. .. attribute:: title .. versionadded:: 1.2 (RW) The text shown on the button. .. attribute:: enabled .. versionadded:: 1.2 (RW) Whether the user may interact with the button. .. method:: press() Press and hold this button. This is mainly to visualize a pressing event in tutorials. Holding a button does not generate a Clicked event. Use :meth:`click` to release the button. .. method:: click() Click this button just as if the user would have moused over and clicked it. .. method:: set_repeating(b) .. versionadded:: 1.2 Set whether holding the button will generate repeated clicked events. :arg b: :const:`true` or :const:`false` :type b: :class:`boolean` .. method:: set_perm_pressed(b) .. versionadded:: 1.2 Set whether the button will be styled as if permanently pressed. :arg b: :const:`true` or :const:`false` :type b: :class:`boolean` .. method:: toggle() .. versionadded:: 1.2 Toggle whether the button will be styled as if permanently pressed. Checkbox -------- .. graphviz:: :alt: Dependency graph for class: Checkbox graph Checkbox { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Checkbox [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- Checkbox } .. class:: Checkbox Child of: :class:`Panel` .. versionadded:: 1.2 A tick box that can be toggled on or off by the user. .. attribute:: state (RW) Whether the checkbox is currently checked. .. function:: set_enabled(b) Set whether the user can change the state of this checkbox. :arg b: :const:`true` or :const:`false` :type b: :class:`boolean` RadioButton ----------- .. graphviz:: :alt: Dependency graph for class: RadioButton graph RadioButton { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] RadioButton [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- RadioButton } .. class:: RadioButton Child of: :class:`Panel` .. versionadded:: 1.2 One of the buttons in a radio group. In each radio group, at most one button can be active at the same time. Note that each button in the group also acts as a representation of the group itself. .. attribute:: state (RW) The index of the radio group's currently active button (0-based; -1 for none). .. function:: set_enabled(b) Set whether the user can change the state of the radio group. :arg b: :const:`true` or :const:`false` :type b: :class:`boolean` ProgressBar ----------- .. graphviz:: :alt: Dependency graph for class: ProgressBar graph ProgressBar { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] ProgressBar [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- ProgressBar } .. class:: ProgressBar Child of: :class:`Panel` .. versionadded:: 1.2 A partially filled bar that indicates the progress of an operation. .. attribute:: state (RW) The current progress value. .. Note:: When using a progress bar to visualize the progress of a blocking script, you may need to call :meth:`~Panel.force_redraw` after changing this property to ensure the change becomes visible to the user immediately. .. attribute:: total (RW) The maximum progress value. .. attribute:: show_percent (RW) Whether the progress bar label displays the absolute progress or the percentage completed. SpinBox ------- .. graphviz:: :alt: Dependency graph for class: SpinBox graph SpinBox { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] SpinBox [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- SpinBox } .. class:: SpinBox Child of: :class:`Panel` .. versionadded:: 1.2 A box with buttons to increase or decrease a numerical value. .. attribute:: value (RW) The currently selected value. .. function:: set_unit_width(w) Set the width of the spinbox's buttons and content. :arg w: Width in pixels. :type min: :class:`int` .. function:: set_interval(min, max) Set the minimum and maximum value of the spinbox. :arg min: Minimum value. :type min: :class:`int` :arg max: Maximum value. :type max: :class:`int` .. function:: add_replacement(value, label) Replacement string to display instead of a specific value when that value is selected. :arg value: Value to replace. :type value: :class:`int` :arg label: Replacement text. :type label: :class:`string` Slider ------ .. graphviz:: :alt: Dependency graph for class: Slider graph Slider { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Slider [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- Slider } .. class:: Slider Child of: :class:`Panel` .. versionadded:: 1.2 A button that can be slid along a line to change a value. .. attribute:: value (RW) The currently selected value. .. attribute:: min_value (RW) The lowest selectable value. .. attribute:: max_value (RW) The highest selectable value. .. function:: set_enabled(b) Set whether the user can move this slider. :arg b: :const:`true` or :const:`false` :type b: :class:`boolean` .. function:: set_cursor_fixed_height(h) Set the slider cursor's height. :arg h: Height in pixels. :type h: :class:`int` MultilineTextarea ----------------- .. graphviz:: :alt: Dependency graph for class: MultilineTextarea graph MultilineTextarea { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] MultilineTextarea [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- MultilineTextarea } .. class:: MultilineTextarea Child of: :class:`Panel` .. versionadded:: 1.2 A static text area with multiple lines that can not be modified by the user. .. attribute:: text (RW) The text currently shown by this area. Textarea -------- .. graphviz:: :alt: Dependency graph for class: Textarea graph Textarea { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Textarea [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- Textarea } .. class:: Textarea Child of: :class:`Panel` .. versionadded:: 1.2 A static text area with a single line of text that can not be modified by the user. .. attribute:: text (RW) The text currently shown by this area. TextInputPanel -------------- .. graphviz:: :alt: Dependency graph for class: TextInputPanel graph TextInputPanel { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] TextInputPanel [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- TextInputPanel } .. class:: TextInputPanel Child of: :class:`Panel` .. versionadded:: 1.2 This represents a box containing arbitrary text that can be edited by the user. .. attribute:: text (RW) The text currently held in this box. .. attribute:: selected_text (RO) The text currently selected by the user (may be empty). .. attribute:: password (RW) Whether the actual text is displayed with asterisks for password boxes. .. attribute:: warning (RW) Whether the box is highlighted to indicate an error. .. attribute:: caret_pos (RW) The position of the caret in the text. .. attribute:: multiline (RO) Whether this editbox has multiple lines or just one line. Dropdown -------- .. graphviz:: :alt: Dependency graph for class: Dropdown graph Dropdown { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Dropdown [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- Dropdown } .. class:: Dropdown Child of: :class:`Panel` This represents a dropdown menu. Some attributes and functions are available only for dropdowns with a data type supported by the Lua interface. See :attr:`datatype`. .. attribute:: datatype .. versionadded:: 1.2 (RO) The dropdown's datatype as :class:`string` if supported, or ``nil`` for dropdowns with unsupported datatype. Currently only ``"string"`` is supported. .. attribute:: expanded (RO) True if the dropdown's list is currently expanded. .. attribute:: no_of_items (RO) The number of items this dropdown has. .. attribute:: selection .. versionadded:: 1.2 (RO) The currently selected entry or ``nil`` if none is selected. For dropdowns with unsupported datatype, this is always ``nil``. .. method:: open Open this dropdown menu. .. method:: highlight_item(index) :arg index: the index of the item to highlight, starting from ``1`` :type index: :class:`integer` Highlights an item in this dropdown without triggering a selection. .. method:: select() Selects the currently highlighted item in this dropdown. .. method:: add(label, value[, icon = nil, tooltip = "", select = false]) .. versionadded:: 1.2 Add an entry to the dropdown. Only allowed for dropdowns with supported datatypes. :arg label: The label to display for the entry. :type label: :class:`string` :arg value: The internal value of the entry. :type value: This dropdown's :attr:`datatype` :arg icon: The icon filepath for the entry (``nil`` for no icon). :type icon: :class:`string` :arg tooltip: The entry's tooltip text. :type tooltip: :class:`string` :arg select: Whether to select this entry. :type select: :class:`boolean` Listselect ---------- .. graphviz:: :alt: Dependency graph for class: Listselect graph Listselect { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Listselect [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- Listselect } .. class:: Listselect Child of: :class:`Panel` .. versionadded:: 1.2 This represents a selection list. Some attributes and functions are available only for listselects with a data type supported by the Lua interface. See :attr:`datatype`. .. attribute:: datatype (RO) The listselect's datatype as :class:`string` if supported, or ``nil`` for listselects with unsupported datatype. Currently only ``"string"`` is supported. .. attribute:: no_of_items (RO) The number of items this listselect has. .. attribute:: selection (RO) The currently selected entry or ``nil`` if none is selected. For listselects with unsupported datatype, this is always ``nil``. .. method:: add(label, value[, icon = nil, tooltip = "", select = false, indent = 0]) Add an entry to the list. Only allowed for lists with supported datatypes. :arg label: The label to display for the entry. :type label: :class:`string` :arg value: The internal value of the entry. :type value: This list's :attr:`datatype` :arg icon: The icon filepath for the entry (``nil`` for no icon). :type icon: :class:`string` :arg tooltip: The entry's tooltip text. :type tooltip: :class:`string` :arg select: Whether to select this entry. :type select: :class:`boolean` :arg indent: By how many levels to indent this entry. :type indent: :class:`int` Table ----- .. graphviz:: :alt: Dependency graph for class: Table graph Table { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Table [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- Table } .. class:: Table Child of: :class:`Panel` .. versionadded:: 1.2 This represents a table. Some attributes and functions are available only for tables with a data type supported by the Lua interface. See :attr:`datatype`. .. attribute:: datatype (RO) The table's datatype as :class:`string` if supported, or ``nil`` for tables with unsupported datatype. Currently only ``"int"`` is supported. .. attribute:: no_of_rows (RO) The number of rows this table has. .. attribute:: selection_index (RW) The index of the currently selected row or ``nil`` if none is selected. Setting this to ``nil`` clears the selection. .. attribute:: selections (RO) An :class:`array` with all currently selected row indices (may be empty). .. attribute:: sort_column (RW) The index of the column by which the table is sorted. .. attribute:: sort_descending (RW) Whether the table is sorted in reverse order. .. method:: get(row) Lookup the internal value associated with a given row index. Only allowed for tables with supported datatypes. :arg row: The row index to look up. :type row: :class:`int` :returns: The row's internal value. :rtype: :class:`int` .. method:: add(value, select, disable, columns) Add a row to the table. Only allowed for tables with supported datatypes. The named arguments are followed by an array of as many entries as the table has columns. Each array entry is a :class:`table` describing the content of one table cell. Valid keys are: * ``"text"``: **Optional**. The text to show in the cell. * ``"icon"``: **Optional**. The icon filepath in the cell. :arg value: The internal value of the entry. :type value: This table's :attr:`datatype` :arg select: Whether to select this entry. :type select: :class:`boolean` :arg disable: Whether to disable this row. :type disable: :class:`boolean` :arg columns: The cell descriptors. :type columns: :class:`array` of :class:`table` .. method:: remove_row(row) Delete the row at the specified index from the table. :arg row: The row index to delete. :type row: :class:`int` .. method:: remove_entry(entry) Delete the row with the specified internal value from the table. Only allowed for tables with supported datatypes. :arg entry: The entry value to delete. :type entry: :class:`int` TabPanel -------- .. graphviz:: :alt: Dependency graph for class: TabPanel graph TabPanel { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] TabPanel [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- TabPanel } .. class:: TabPanel Child of: :class:`Panel` .. versionadded:: 1.2 This represents a panel that allows switching between multiple tabs. .. attribute:: no_of_tabs (RO) The number of tabs this tab panel has. .. attribute:: active (RW) The index of the currently active tab. When assigning this property, it is also allowed to activate a tab by name instead of index. .. method:: remove_last_tab(name) Remove the **last** tab in the panel. As a precaution against accidental removal of tabs, the name of the tab that will be removed has to be specified. :arg name: The name of the last tab. :type name: :class:`string` :returns: Whether the tab was removed. :rtype: :class:`boolean` Tab ------ .. graphviz:: :alt: Dependency graph for class: Tab graph Tab { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Tab [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- Tab } .. class:: Tab Child of: :class:`Panel` A tab button. .. attribute:: active (RO) Is this the currently active tab in this window? .. method:: click Click this tab making it the active one. Window ------ .. graphviz:: :alt: Dependency graph for class: Window graph Window { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Window [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- Window } .. class:: Window Child of: :class:`Panel` This represents a Window. .. attribute:: title .. versionadded:: 1.2 (RW) The title shown in the window's title bar. .. attribute:: pinned .. versionadded:: 1.2 (RW) Whether the window is pinned so it can't be closed accidentally. .. attribute:: minimal .. versionadded:: 1.2 (RW) Whether the window is minimized and only the title bar visible. .. method:: close Closes this window. This invalidates this Object, do not use it any longer. MapView ------- .. graphviz:: :alt: Dependency graph for class: MapView graph MapView { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] MapView [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] Panel [shape=house, href="../autogen_wl_ui/index.html#panel", target="_parent"] Panel -- MapView } .. class:: MapView Child of: :class:`Panel` The map view is the main widget and the root of all panels. It is the big view of the map that is visible at all times while playing. .. attribute:: toolbar .. versionadded:: 1.2 (RO) The main toolbar. .. attribute:: average_fps (RO) The average frames per second that the user interface is being drawn at. .. attribute:: center_map_pixel (RO) The map position (in pixels) that the center pixel of this map view currently sees. This is a table containing 'x', 'y'. .. attribute:: buildhelp (RW) True if the buildhelp is show, false otherwise. .. attribute:: census (RW) True if the census strings are shown on buildings, false otherwise .. attribute:: statistics (RW) True if the statistics strings are shown on buildings, false otherwise .. attribute:: is_building_road (RO) Is the player currently in road/waterway building mode? .. attribute:: auto_roadbuild_mode (RO) Is the player using automatic road building mode? .. attribute:: is_animating (RO) True if this MapView is currently panning or zooming. .. method:: click(field) Jumps the mouse onto a field and clicks it just like the user would have. :arg field: the field to click on :type field: :class:`wl.map.Field` .. method:: start_road_building(flag[, waterway = false]) Enters the road building mode as if the player has clicked the flag and chosen build road. It will also warp the mouse to the given starting node. Throws an error if we are already in road building mode. :arg flag: :class:`wl.map.Flag` object to start building from. :arg waterway: if `true`, start building a waterway rather than a road .. method:: abort_road_building If the player is currently in road building mode, this will cancel it. If he wasn't, this will do nothing. .. method:: close Closes the MapView. Note that this is the equivalent as clicking on the exit button in the game; that is the game will be exited. This is especially useful for automated testing of features and is for example used in the widelands Lua test suite. .. method:: scroll_to_map_pixel(x, y) Starts an animation to center the view on top of the pixel (x, y) in map pixel space. Use `is_animating` to check if the animation is still going on. :arg x: x coordinate of the pixel :type x: number :arg y: y coordinate of the pixel :type y: number .. method:: scroll_to_field(field) Starts an animation to center the view on top of the 'field'. Use `is_animating` to check if the animation is still going on. :arg field: the field to center on :type field: :class:`wl.map.Field` .. method:: is_visible(field) Returns `true` if `field` is currently visible in the map view. :arg field: the field :type field: :class:`wl.map.Field` .. method:: mouse_to_pixel(x, y) Starts an animation to move the mouse onto the pixel (x, y) of this panel. Use `is_animating` to check if the animation is still going on. :arg x: x coordinate of the pixel :type x: number :arg y: y coordinate of the pixel :type y: number .. method:: mouse_to_field(field) Starts an animation to move the mouse onto the 'field'. If 'field' is not visible on the screen currently, does nothing. Use `is_animating` to check if the animation is still going on. :arg field: the field :type field: :class:`wl.map.Field` .. method:: update_toolbar() .. versionadded:: 1.2 Recompute the size and position of the toolbar. Call this after you have modified the toolbar in any way. .. method:: add_toolbar_plugin(action, icon, name[, tooltip = ""]) .. versionadded:: 1.2 Add an entry to the main toolbar's Plugin dropdown. This makes the plugin dropdown visible if it was hidden. :arg action: The Lua code to run when the user selects the entry. :type action: :class:`string` :arg icon: Icon filepath for the entry. :type icon: :class:`string` :arg name: Label for the entry. :type name: :class:`string` :arg tooltip: Tooltip for the entry. :type tooltip: :class:`string` .. method:: add_plugin_timer(action, interval[, failsafe=true]) .. versionadded:: 1.2 Register a piece of code that will be run periodically as long as the game/editor is running. :arg action: The Lua code to run. :type action: :class:`string` :arg interval: The interval in milliseconds realtime in which the code will be invoked. :type interval: :class:`int` :arg failsafe: In event of an error, an error message is shown and the timer is removed. If this is set to :const:`false`, the game will be aborted with no error handling instead. :type failsafe: :class:`boolean` .. function:: set_user_input_allowed(b) Allow or disallow user input. Be warned, setting this will make that mouse movements and keyboard presses are completely ignored. Only scripted stuff will still happen. :arg b: :const:`true` or :const:`false` :type b: :class:`boolean` .. method:: get_user_input_allowed Return the current state of this flag. :returns: :const:`true` or :const:`false` :rtype: :class:`boolean` .. method:: get_shortcut(name) Returns the keyboard shortcut with the given name. :returns: The human-readable and localized shortcut. :rtype: :class:`string` .. method:: get_ingame_shortcut_help() .. versionadded:: 1.2 Returns the list of current in-game keyboard shortcuts formatted as richtext. :returns: The richtext formatted list of shortcuts :rtype: :class:`string` .. method:: get_fastplace_help() .. versionadded:: 1.2 Returns the list of current fastplace shortcuts for the current player formatted as richtext. :returns: The richtext formatted list of shortcuts :rtype: :class:`string` .. method:: get_editor_shortcut_help() .. versionadded:: 1.2 Returns the list of current map editor keyboard shortcuts formatted as richtext. :returns: The richtext formatted list of shortcuts :rtype: :class:`string` .. method:: show_messagebox(title, text[, cancel_button = true]) .. versionadded:: 1.2 Show the user a modal message box with an OK button and optionally a cancel button. You can use :ref:`richtext ` to style the text. Don't forget to wrap it in an :ref:`rt tag ` in this case. :arg title: The caption of the window :type title: :class:`string` :arg text: The message to show :type text: :class:`string` :arg cancel_button: Whether to include a Cancel button :type cancel_button: :class:`boolean` :returns: Whether the user clicked OK. :rtype: :class:`boolean`