LuaGuiElement.add docs for optional parameters?

[sparr]

http://lua-api.factorio.com/latest/LuaG ... lement.add

Code: Select all

game.player.gui.top.add{ name = "test", type = "button", caption = "caption", value = 0.5, text = "text", state = true, tooltip = "tooltip", horizontal_scroll_policy = "auto", vertical_scroll_policy = "auto", selected_index = 1, number = 1, show_percent_for_small_numbers = true, surface_index = 1, zoom = 1, minimap_player_index = 1, selectable = true, word_wrap = true, read_only = true, enabled = true, ignored_by_interaction = true, locked = true, draw_vertical_lines = true, draw_horizontal_lines = true, draw_horizontal_line_after_headers = true, slider_value = 0.5 }

It seems that every read/write attribute of LuaGuiElement is also a valid named parameter to LuaGuiElement.add, and will be applied if the element is the appropriate type. This doesn't seem to be documented anywhere. A sentence or two somewhere on that doc page would be helpful.

[Bilka]

What the hell is that code line meant to mean, just about nothing there even has an effect on buttons.

[Klonan]

http://lua-api.factorio.com/latest/LuaG ... lement.add

Code: Select all

game.player.gui.top.add{ name = "test", type = "button", caption = "caption", value = 0.5, text = "text", state = true, tooltip = "tooltip", horizontal_scroll_policy = "auto", vertical_scroll_policy = "auto", selected_index = 1, number = 1, show_percent_for_small_numbers = true, surface_index = 1, zoom = 1, minimap_player_index = 1, selectable = true, word_wrap = true, read_only = true, enabled = true, ignored_by_interaction = true, locked = true, draw_vertical_lines = true, draw_horizontal_lines = true, draw_horizontal_line_after_headers = true, slider_value = 0.5 }

It seems that every read/write attribute of LuaGuiElement is also a valid named parameter to LuaGuiElement.add, and will be applied if the element is the appropriate type. This doesn't seem to be documented anywhere. A sentence or two somewhere on that doc page would be helpful.

Its not that they are valid parameters, but that the game only looks for what it wants,
You can pass a whole lot of junk data in the array to .add(), but internally the game does something like this:

Code: Select all

this->singleLine = input.getDefault("single_line", true)
this->locked = input.getDefault("locked", false)

So it looks if there is the value, if not it sets a default

[sparr]

What the hell is that code line meant to mean, just about nothing there even has an effect on buttons.

"just about nothing" is the key. Nowhere do the docs specify which add parameters work for a button. there are two categories of problem here:

1) In some places, the LuaGuiElement docs tell us that a particular attribute exists on a particular element, such as http://lua-api.factorio.com/latest/LuaG ... nt.caption which says that frames and labels and buttons have a caption. However, nowhere do the docs say that every applicable attribute of the object is also accepted as a parameter to LuaGuiElement.add for that element type. The solution to this is adding

2) In other cases, the docs don't even tell us which element types have a particular attribute, or the information seems incomplete. As mentioned above, for caption it says "For other elements, like buttons or labels, this is the content." but that doesn't sound like an exhaustive list. For http://lua-api.factorio.com/latest/LuaG ... nt.tooltip there's no list at all; does every element support it?

Most of a solution here would be to add a sentence to the description of the add() method, saying it will take any read/write attributes for the type in question. If it will take some read-only attributes, that's more than I've been able to suss out experimentally.

[Bilka]

What the hell is that code line meant to mean, just about nothing there even has an effect on buttons.

"just about nothing" is the key. Nowhere do the docs specify which add parameters work for a button. there are two categories of problem here:

1) In some places, the LuaGuiElement docs tell us that a particular attribute exists on a particular element, such as http://lua-api.factorio.com/latest/LuaG ... nt.caption which says that frames and labels and buttons have a caption. However, nowhere do the docs say that every applicable attribute of the object is also accepted as a parameter to LuaGuiElement.add for that element type.

Except it's not. It just seemed like that for you for the reasons Klonan explained. Not all parameters have an effect in LuaGuiElement::add().

2) In other cases, the docs don't even tell us which element types have a particular attribute, or the information seems incomplete. As mentioned above, for caption it says "For other elements, like buttons or labels, this is the content." but that doesn't sound like an exhaustive list. For http://lua-api.factorio.com/latest/LuaG ... nt.tooltip there's no list at all; does every element support it?

Yes.

Most of a solution here would be to add a sentence to the description of the add() method, saying it will take any read/write attributes for the type in question. If it will take some read-only attributes, that's more than I've been able to suss out experimentally.

The second things is the case, and the list has been updated for the next version.