GUI: definitions

[white_haired_uncle]

I kept running across examples with objects with entries like 'definition = "default"'. At some point I ran into something in the docs that confirmed my suspicion about what these were, but it was short on details and I don't remember where it was. Eventually I discovered I could set definition = "tree_view_node" on a button and its appearance would change from a checkbox to a triangle. Which leads to the obvious questions, is there a list of valid definitions for each widget, and if not how (besides hunting for examples, hopefully) can I find them?

For example, right now I'm learning about text boxes. I swear I've seen a "text box" that only took integers (UMC: Trader - Strange Legacy), but I can't find an example. I can't find an "integer box" or similar, could this be a text_box with definition = xxx ?

P.S. This probably doesn't belong in 'lua labs', but I didn't see a better place.

[Celtic_Minstrel]

I don't think there exists a text box that only takes integers. The add-on you remember probably added additional logic to a regular text box to forbid you from entering non-numerical values.

Each of the definitions is defined in WML with a [xxx_definition] tag, where xxx is the type of widget. You can find them by searching through the gui folder in the game data directory. Most widgets define a macro that sketches out the general form of the definition, and then instantiate that macro several times with different parameters to create multiple definitions. Generally, each widget has at least one corresponding file that contains the definitions. In some cases, particularly when there are definitions that are drastically different, there may be multiple files for the same widget, each containing at least one definition.

You can also add new definitions at runtime using the Lua function, add_widget_definition.

[white_haired_uncle]

Okay, so when I was working with a toggle_button in a tree_view_node, I could have looked at .../data/gui/widget/toggle_button_tree_view_node.cfg, which includes:

Code: Select all

#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###

[toggle_button_definition]
        id = "tree_view_node"
        description = "Fold/unfold status indicator of a tree view node."
...

This tells me that if I like what I find in that [toggle_button_definition], I can use it by setting the definition of my button:

Code: Select all

wml.tag.toggle_button {
               id = "my_button",
               definition = "tree_view_node"   -- matches "id = ..." in [toggle_button_definition] above
}

I'd seen those files, but never made any sense of them. Now I think I see what they do.