From e29c27de444ab8628e9bc18642f22cc93af19b72 Mon Sep 17 00:00:00 2001 From: luk3yx Date: Fri, 24 Mar 2023 16:19:08 +1300 Subject: [PATCH] Update documentation --- README.md | 52 ++++++++++----------- elements.md | 115 +++++++---------------------------------------- generate_docs.py | 20 +++++++-- 3 files changed, 59 insertions(+), 128 deletions(-) diff --git a/README.md b/README.md index 882d6ba..4f81f6a 100644 --- a/README.md +++ b/README.md @@ -271,6 +271,26 @@ gui.Label{label="I am centered!", align_h = "centre"}, This applies to other elements as well, because using HBox and Spacer to centre elements creates unnecessary containers. +#### `gui.Stack` + +This container element places its children on top of each other. All child +elements are expanded in both directions. + +Note that some elements (such as centred labels) won't pass clicks through to +the element below them. + +Example: + +```lua +gui.Stack{ + min_w = 10, + gui.Button{label = "Hello world!"}, + gui.Image{w = 1, h = 1, texture_name = "air.png", padding = 0.2, align_h = "left"}, +} +``` + +![Screenshot](https://user-images.githubusercontent.com/3182651/215946217-3705dbd1-4ec8-4aed-a9eb-381fecb2d8f2.png) + ### Minetest formspec elements There is an auto-generated @@ -344,18 +364,18 @@ gui.Button{ }, ``` +## Hiding elements + +Elements inside boxes can have `visible = false` set to hide them from the +player. Elements hidden this way will still take up space like with +`visibility: hidden;` in CSS. + The style elements are invisible and won't affect padding. ## Experimental features These features might be broken in the future. -### Hiding elements - -Elements inside boxes can have `visible = false` set to hide them from the -player. Elements hidden this way will still take up space like with -`visibility: hidden;` in CSS. - ### `no_prepend[]` You can set `no_prepend = true` on the "root" element to disable formspec @@ -379,23 +399,3 @@ end) ``` ![Screenshot](https://user-images.githubusercontent.com/3182651/212222545-baee3669-15cd-410d-a638-c63b65a8811b.png) - -### `gui.Stack` - -This container element places its children on top of each other. All child -elements are expanded in both directions. - -Note that some elements (such as centred labels and `gui.Box`) won't pass -clicks through to the element below them. - -Example: - -```lua -gui.Stack{ - min_w = 10, - gui.Button{label = "Hello world!"}, - gui.Image{w = 1, h = 1, texture_name = "air.png", padding = 0.2, align_h = "left"}, -} -``` - -![Screenshot](https://user-images.githubusercontent.com/3182651/215946217-3705dbd1-4ec8-4aed-a9eb-381fecb2d8f2.png) diff --git a/elements.md b/elements.md index c83e036..fed7159 100644 --- a/elements.md +++ b/elements.md @@ -9,8 +9,8 @@ Equivalent to Minetest's `animated_image[]` element. **Example** ```lua gui.AnimatedImage { - w = 1, -- Optional - h = 2, -- Optional + w = 1, + h = 2, name = "my_animated_image", -- Optional texture_name = "Hello world!", frame_count = 3, @@ -23,38 +23,6 @@ gui.AnimatedImage { } ``` -### `gui.Background` - -Equivalent to Minetest's `background[]` element. - -**Example** -```lua -gui.Background { - w = 1, -- Optional - h = 2, -- Optional - texture_name = "Hello world!", - auto_clip = false, -- Optional -} -``` - -### `gui.Background9` - -Equivalent to Minetest's `background9[]` element. - -**Example** -```lua -gui.Background9 { - w = 1, -- Optional - h = 2, -- Optional - texture_name = "Hello world!", - auto_clip = false, - middle_x = 3, - middle_y = 4, -- Optional - middle_x2 = 5, -- Optional - middle_y2 = 6, -- Optional -} -``` - ### `gui.Box` Equivalent to Minetest's `box[]` element. @@ -147,8 +115,8 @@ Equivalent to Minetest's `hypertext[]` element. **Example** ```lua gui.Hypertext { - w = 1, -- Optional - h = 2, -- Optional + w = 1, + h = 2, name = "my_hypertext", -- Optional text = "Hello world!", } @@ -161,8 +129,8 @@ Equivalent to Minetest's `image[]` element. **Example** ```lua gui.Image { - w = 1, -- Optional - h = 2, -- Optional + w = 1, + h = 2, texture_name = "Hello world!", middle_x = 3, -- Optional middle_y = 4, -- Optional @@ -178,8 +146,8 @@ Equivalent to Minetest's `image_button[]` element. **Example** ```lua gui.ImageButton { - w = 1, -- Optional - h = 2, -- Optional + w = 1, + h = 2, texture_name = "Hello world!", name = "my_image_button", -- Optional label = "Hello world!", @@ -196,8 +164,8 @@ Equivalent to Minetest's `image_button_exit[]` element. **Example** ```lua gui.ImageButtonExit { - w = 1, -- Optional - h = 2, -- Optional + w = 1, + h = 2, texture_name = "Hello world!", name = "my_image_button_exit", -- Optional label = "Hello world!", @@ -214,8 +182,8 @@ Equivalent to Minetest's `item_image[]` element. **Example** ```lua gui.ItemImage { - w = 1, -- Optional - h = 2, -- Optional + w = 1, + h = 2, item_name = "Hello world!", } ``` @@ -227,8 +195,8 @@ Equivalent to Minetest's `item_image_button[]` element. **Example** ```lua gui.ItemImageButton { - w = 1, -- Optional - h = 2, -- Optional + w = 1, + h = 2, item_name = "Hello world!", name = "my_item_image_button", -- Optional label = "Hello world!", @@ -268,8 +236,8 @@ Equivalent to Minetest's `model[]` element. **Example** ```lua gui.Model { - w = 1, -- Optional - h = 2, -- Optional + w = 1, + h = 2, name = "my_model", -- Optional mesh = "Hello world!", textures = "Hello world!", @@ -297,53 +265,6 @@ gui.Pwdfield { } ``` -### `gui.ScrollContainer` - -Equivalent to Minetest's `scroll_container[]` element. - -**Example** -```lua -gui.ScrollContainer { - w = 1, -- Optional - h = 2, -- Optional - scrollbar_name = "Hello world!", - orientation = "vertical", - scroll_factor = 3, -- Optional -} -``` - -### `gui.Scrollbar` - -Equivalent to Minetest's `scrollbar[]` element. - -**Example** -```lua -gui.Scrollbar { - w = 1, -- Optional - h = 2, -- Optional - orientation = "vertical", - name = "my_scrollbar", -- Optional - value = 3, -} -``` - -### `gui.Tabheader` - -Equivalent to Minetest's `tabheader[]` element. - -**Example** -```lua -gui.Tabheader { - h = 1, -- Optional - name = "my_tabheader", -- Optional - captions = "Hello world!", - current_tab = "Hello world!", - transparent = false, -- Optional - draw_border = false, -- Optional - w = 2, -- Optional -} -``` - ### `gui.Table` Equivalent to Minetest's `table[]` element. @@ -397,12 +318,10 @@ Equivalent to Minetest's `tooltip[]` element. **Example** ```lua gui.Tooltip { - w = 1, -- Optional - h = 2, -- Optional tooltip_text = "Hello world!", bgcolor = "#FF0000", -- Optional fontcolor = "#FF0000", -- Optional - gui_element_name = "Hello world!", -- Optional + gui_element_name = "Hello world!", } ``` diff --git a/generate_docs.py b/generate_docs.py index 5842d06..eabc7df 100644 --- a/generate_docs.py +++ b/generate_docs.py @@ -3,6 +3,11 @@ import collections, re, requests yaml = YAML(typ='safe') +hide_elements = { + 'background', 'background9', 'scroll_container', 'scrollbar', 'tabheader' +} + + def fetch_elements(): res = requests.get('https://github.com/luk3yx/minetest-formspec_ast/raw/' 'master/elements.yaml') @@ -23,6 +28,12 @@ def search_for_fields(obj): yield from search_for_fields(e) +def optional(element_name, field_name): + if field_name in ('w', 'h'): + return (element_name not in ('list', 'hypertext', 'model') and + 'image' not in element_name) + return field_name == 'name' + def element_to_docs(element_name, variants): flow_name = re.sub(r'_(.)', lambda m: m.group(1).upper(), element_name.capitalize()) @@ -36,14 +47,15 @@ def element_to_docs(element_name, variants): ] fields = collections.Counter(search_for_fields(variants)) - if (('x', 'number') not in fields or + if (element_name in hide_elements or ('x', 'number') not in fields or all(field_name in ('x', 'y') for field_name, _ in fields)): return '' num = 1 for (field_name, field_type), count in fields.items(): - if field_name in ('x', 'y'): + if (field_name in ('x', 'y') or (element_name == 'tooltip' and + field_name in ('w', 'h'))): continue if field_type == 'number': @@ -66,8 +78,8 @@ def element_to_docs(element_name, variants): value = '' line = f' {field_name} = {value},' - if ((field_name in ('name', 'w', 'h') and element_name != 'list') or - count < len(variants)): + if ((count < len(variants) or optional(element_name, field_name)) and + field_name != 'gui_element_name'): line = line + ' -- Optional' res.append(line)