[docs] GUI API documented.

2020-03-12 23:38:34 +01:00 · 2020-03-12 23:38:34 +01:00 · 3ad14ad3f3
parent e658c478a1
commit 3ad14ad3f3
10 changed files with 592 additions and 56 deletions
--- a/README.md
+++ b/README.md
@ -37,6 +37,12 @@ The long-term goal of this project is to provide a viable alternative to Minecra
        - [Biome](https://openminer.readthedocs.io/en/latest/lua-api-biome/)
        - [Dimension](https://openminer.readthedocs.io/en/latest/lua-api-dimension/)
    - [GUI API](https://openminer.readthedocs.io/en/latest/lua-api-gui/)
+        - [Crafting widget](https://openminer.readthedocs.io/en/latest/lua-api-gui-crafting/)
+        - [Image](https://openminer.readthedocs.io/en/latest/lua-api-gui-image/)
+        - [Inventory data](https://openminer.readthedocs.io/en/latest/lua-api-gui-inventory-data/)
+        - [Inventory widget](https://openminer.readthedocs.io/en/latest/lua-api-gui-inventory/)
+        - [Progress bar](https://openminer.readthedocs.io/en/latest/lua-api-gui-progress-bar/)
+        - [Scroll bar](https://openminer.readthedocs.io/en/latest/lua-api-gui-scroll-bar/)
    - [C++ classes in Lua](https://openminer.readthedocs.io/en/latest/lua-api-cpp/)
 - [Network Protocol](https://github.com/Unarelith/OpenMiner/wiki/Network-Protocol)

--- a/docs/index.md
+++ b/docs/index.md
@ -21,6 +21,12 @@
        - [Biome](lua-api-biome.md)
        - [Dimension](lua-api-dimension.md)
    - [GUI API](lua-api-gui.md)
+        - [Crafting widget](lua-api-gui-crafting.md)
+        - [Image](lua-api-gui-image.md)
+        - [Inventory data](lua-api-gui-inventory-data.md)
+        - [Inventory widget](lua-api-gui-inventory.md)
+        - [Progress bar](lua-api-gui-progress-bar.md)
+        - [Scroll bar](lua-api-gui-scroll-bar.md)
    - [C++ classes in Lua](lua-api-cpp.md)
 - [Network Protocol](https://github.com/Unarelith/OpenMiner/wiki/Network-Protocol)

--- a/docs/lua-api-gui-crafting.md
+++ b/docs/lua-api-gui-crafting.md
@ -0,0 +1,105 @@
+# Lua API: Crafting Widget
+
+## Example
+
+```lua
+gui:crafting {
+	name = "inv_crafting",
+	pos = {x = 29, y = 16},
+	result_pos = {x = 123, y = 34},
+
+	inventory = "block",
+	block = {x = pos.x, y = pos.y, z = pos.z},
+
+	shift_destination = "inv_main,inv_hotbar",
+}
+```
+
+## Attributes
+
+### `block`
+
+Specify the block to use with `block` inventory source.
+
+```lua
+block = {
+	x = 0,
+	y = 0,
+	z = 0
+}
+```
+
+### `inventory`
+
+Source of the inventory displayed.
+
+Example:
+```lua
+inventory = "block"
+```
+
+Possible values:
+
+- `block`: Set a specific block as the source
+- `temp`: Set a temporary inventory as the source
+
+### `name`
+
+Name of the widget. **Mandatory field.**
+
+Example:
+```lua
+name = "inv_crafting"
+```
+
+### `offset`
+
+Offset of the subset of the source inventory. Only used with `inventory = "block"`.
+
+Example:
+```lua
+offset = 0
+```
+
+### `pos`
+
+Position of the widget. **Mandatory field.**
+
+Example:
+```lua
+pos = {
+	x = 0,
+	y = 0
+}
+```
+
+### `result_pos`
+
+Position of the result slot of the crafting table.
+
+Example:
+```lua
+result_pos = {
+	x = 0,
+	y = 0
+}
+```
+
+### `shift_destination`
+
+Names of the inventories used for the Shift+Click action, separated by `,`
+
+Example:
+```lua
+shift_destination = "inv_hotbar,inv_main"
+```
+
+### `size`
+
+Size of the crafting table.
+
+Example:
+```lua
+size = 3, -- default value, 3x3 crafting table
+```
+
--- a/docs/lua-api-gui-image.md
+++ b/docs/lua-api-gui-image.md
@ -0,0 +1,60 @@
+# Lua API: Image
+
+## Example
+
+```lua
+gui:image {
+	name = "img_background", -- mandatory
+	pos = {x = 0, y = 0},    -- mandatory
+
+	texture = "mods/default/textures/gui/workbench.png",
+	clip = {x = 0, y = 0, width = 176, height = 166},
+}
+```
+
+## Attributes
+
+### `clip`
+
+Clip rect of the texture.
+
+Example:
+```lua
+clip = {
+	x = 0,
+	y = 0,
+	width = 176,
+	height = 166
+}
+```
+
+### `name`
+
+Name of the widget. **Mandatory field.**
+
+Example:
+```lua
+name = "img_background"
+```
+
+### `pos`
+
+Position of the widget. **Mandatory field.**
+
+Example:
+```lua
+pos = {
+	x = 0,
+	y = 0
+}
+```
+
+### `texture`
+
+Full path of the texture. Relative to the repo root.
+
+Example:
+```lua
+texture = "mods/default/textures/gui/workbench.png"
+```
+
--- a/docs/lua-api-gui-inventory-data.md
+++ b/docs/lua-api-gui-inventory-data.md
@ -0,0 +1,70 @@
+# Lua API: Inventory data
+
+## Example
+
+```lua
+gui:inventory_data {
+	name = "inv_data",
+
+	width = 9,
+	height = 1,
+
+	items = {
+		{"default:cobblestone", 10},
+		{"default:stick", 64}
+	},
+
+	is_unlimited = true,
+}
+```
+
+## Attributes
+
+### `height`
+
+Height of the inventory.
+
+Example:
+```lua
+height = 1
+```
+
+### `is_unlimited`
+
+Defines if the inventory is an infinite source of items or not.
+
+Example:
+```lua
+is_unlimited = false -- this is the default value
+```
+
+### `items`
+
+Table containing item stacks. Format of the stack table is `{id, amount}`.
+
+Example:
+```lua
+items = {
+	{"default:cobblestone", 10},
+	{"default:stick", 64}
+}
+```
+
+### `name`
+
+Name of the widget. **Mandatory field.**
+
+Example:
+```lua
+name = "inv_data"
+```
+
+### `width`
+
+Width of the inventory.
+
+Example:
+```lua
+width = 9
+```
+
--- a/docs/lua-api-gui-inventory.md
+++ b/docs/lua-api-gui-inventory.md
@ -0,0 +1,127 @@
+# Lua API: Inventory Widget
+
+## Example
+
+```lua
+gui:inventory {
+	name = "inv_main",     -- mandatory field
+	pos = {x = 7, y = 83}, -- mandatory field
+
+	inventory = "player",
+	player = "player",
+	inventory_name = "main",
+	size = {x = 9, y = 3},
+	offset = 9,
+	count = 9 * 3,
+
+	shift_destination = "inv_hotbar,inv_main",
+}
+```
+
+## Attributes
+
+### `block`
+
+Specify the block to use with `block` inventory source.
+
+```lua
+block = {
+	x = 0,
+	y = 0,
+	z = 0
+}
+```
+
+### `count`
+
+Size of the subset of the source inventory.
+
+Example:
+```lua
+count = 27
+```
+
+### `inventory`
+
+Source of the inventory displayed.
+
+Example:
+```lua
+inventory = "player"
+```
+
+Possible values:
+
+- `player`: Set a specific player as the source
+- `block`: Set a specific block as the source
+- `temp`: Set a temporary inventory as the source
+
+### `inventory_name`
+
+Specify the inventory to use. Used with `player` and `temp` inventory sources.
+
+Example:
+```lua
+inventory_name = "main"
+```
+
+### `name`
+
+Name of the widget. **Mandatory field.**
+
+Example:
+```lua
+name = "inv_main"
+```
+
+### `offset`
+
+Offset of the subset of the target inventory.
+
+Example:
+```lua
+offset = 0
+```
+
+### `player`
+
+**Note:** Placeholder. Currently unused.
+
+Example:
+```lua
+player = "player"
+```
+
+### `pos`
+
+Position of the widget. **Mandatory field.**
+
+Example:
+```lua
+pos = {
+	x = 0,
+	y = 0
+}
+```
+
+### `shift_destination`
+
+Names of the inventories used for the Shift+Click action, separated by `,`
+
+Example:
+```lua
+shift_destination = "inv_hotbar,inv_main"
+```
+
+### `size`
+
+Size of the inventory (in slots).
+
+Example:
+```lua
+size = {
+	x = 9,
+	y = 3
+}
+```
+
--- a/docs/lua-api-gui-progress-bar.md
+++ b/docs/lua-api-gui-progress-bar.md
@ -0,0 +1,120 @@
+# Lua API: Progress bar
+
+## Example
+
+```lua
+gui:progress_bar {
+	name = "bar_process",
+	pos = {x = 80, y = 35},
+
+	type = "item_process",
+
+	block = {x = pos.x, y = pos.y, z = pos.z},
+
+	meta = "item_progress",
+	max_value = 200,
+
+	texture = "mods/default/textures/gui/furnace.png",
+	clip = {x = 176, y = 14, width = 24, height = 17},
+}
+```
+
+## Attributes
+
+### `block`
+
+Specify the block to use for metadata.
+
+```lua
+block = {
+	x = 0,
+	y = 0,
+	z = 0
+}
+```
+
+### `clip`
+
+Clip rect of the texture.
+
+Example:
+```lua
+clip = {
+	x = 0,
+	y = 0,
+	width = 176,
+	height = 166
+}
+```
+
+### `max_meta`
+
+Name of the metadata value storing the max value of the bar in the `block`.
+
+Example:
+```lua
+max_meta = "current_burn_time"
+```
+
+### `max_value`
+
+Max value of the progress bar. Used with `type = "item_process"`.
+
+Example:
+```lua
+max_value = 200,
+```
+
+### `meta`
+
+Name of the metadata value storing the progress of the bar in the `block`.
+
+Example:
+```lua
+meta = "ticks_remaining"
+```
+
+### `name`
+
+Name of the widget. **Mandatory field.**
+
+Example:
+```lua
+name = "bar_burn"
+```
+
+### `pos`
+
+Position of the widget. **Mandatory field.**
+
+Example:
+```lua
+pos = {
+	x = 0,
+	y = 0
+}
+```
+
+### `texture`
+
+Full path of the texture. Relative to the repo root.
+
+Example:
+```lua
+texture = "mods/default/textures/gui/furnace.png"
+```
+
+### `type`
+
+Type of the progress bar.
+
+Example:
+```lua
+type = "item_process"
+```
+
+Possible values:
+
+- `item_process`: Goes from left to right depending on `meta` and `max_value`.
+- `burn_process`: Goes from down to up depending on `meta` and `max_meta`.
+
--- a/docs/lua-api-gui-scroll-bar.md
+++ b/docs/lua-api-gui-scroll-bar.md
@ -0,0 +1,92 @@
+# Lua API: Scroll bar
+
+## Example
+
+```lua
+gui:scroll_bar {
+	name = "scroll_bar",
+	pos = {x = 175, y = 18},
+
+	texture = "mods/default/textures/gui/tabs.png",
+	clip = {x = 232, y = 0, width = 12, height = 15},
+
+	widget = "inv_creative_items",
+
+	min_y = 0,
+	max_y = 110 - 15,
+}
+```
+
+## Attributes
+
+### `clip`
+
+Clip rect of the texture.
+
+Example:
+```lua
+clip = {
+	x = 0,
+	y = 0,
+	width = 176,
+	height = 166
+}
+```
+
+### `max_y`
+
+Maximum Y position for the bar.
+
+Example:
+```lua
+max_y = 95
+```
+
+### `min_y`
+
+Minimum Y position for the bar.
+
+Example:
+```lua
+min_y = 0
+```
+
+### `name`
+
+Name of the widget. **Mandatory field.**
+
+Example:
+```lua
+name = "scroll_bar"
+```
+
+### `pos`
+
+Position of the widget. **Mandatory field.**
+
+Example:
+```lua
+pos = {
+	x = 0,
+	y = 0
+}
+```
+
+### `texture`
+
+Full path of the texture. Relative to the repo root.
+
+Example:
+```lua
+texture = "mods/default/textures/gui/tabs.png"
+```
+
+### `widget`
+
+Name of the inventory widget which will be affected by the scroll bar.
+
+Example:
+```lua
+widget = "inv_items"
+```
+
--- a/docs/lua-api-gui.md
+++ b/docs/lua-api-gui.md
@ -1,7 +1,5 @@
 # Lua API: GUI API Overview

-**Note:** This page is possibly outdated for the moment.
-
 You can create a new GUI with:
 ```lua
 local gui = LuaGUI.new()
@ -12,57 +10,3 @@ To show the custom GUI use:
 gui:show(client)
 ```

-## Button
-
-```lua
-gui:button {
-	name = "btn_test",
-	pos = {x = 0, y = 0},
-
-	text = "Test button",
-	on_click = function(self)
-		print("Test button pressed")
-	end,
-}
-```
-
-## Inventory
-
-```lua
-gui:inventory {
-	name = "inv_main",
-	pos = {x = gui_pos.x + 7, y = gui_pos.y + 83},
-
-	player = "player",
-	inventory = "main",
-	size = {x = 9, y = 3},
-	offset = 9,
-	count = 9 * 3,
-}
-```
-
-## Crafting table
-
-```lua
-gui:crafting {
-	name = "inv_crafting",
-	pos = {x = gui_pos.x, y = gui_pos.y},
-
-	block = {x = pos.x, y = pos.y, z = pos.z},
-
-	offset = 0,
-}
-```
-
-## Image
-
-```lua
-gui:image {
-	name = "img_background",
-	pos = gui_pos,
-
-	texture = "texture-workbench",
-	clip = {x = 0, y = 0, width = 176, height = 166},
-}
-```
-
--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -16,6 +16,12 @@ nav:
        - 'Tree': 'lua-api-tree.md'
    - 'Lua: GUI API':
        - 'Overview': 'lua-api-gui.md'
+        - 'Crafting widget': 'lua-api-gui-crafting.md'
+        - 'Image': 'lua-api-gui-image.md'
+        - 'Inventory data': 'lua-api-gui-inventory-data.md'
+        - 'Inventory widget': 'lua-api-gui-inventory.md'
+        - 'Progress bar': 'lua-api-gui-progress-bar.md'
+        - 'Scroll bar': 'lua-api-gui-scroll-bar.md'

 theme:
    name: readthedocs