From 5ecd67d8efd602f8b351f75efe03d609f5efe7e7 Mon Sep 17 00:00:00 2001 From: Insality Date: Thu, 13 Jul 2023 21:32:04 +0300 Subject: [PATCH] Update docs --- README.md | 16 +++--- docs_md/components/manual_rich_text.md | 59 ------------------- druid/base/button.lua | 2 + druid/base/drag.lua | 2 + druid/base/scroll.lua | 2 + druid/base/static_grid.lua | 2 + druid/base/text.lua | 2 + druid/custom/rich_text/module/rt.lua | 6 +- druid/custom/rich_text/rich_text.lua | 79 +++++++++++++++++++++----- druid/extended/checkbox.lua | 2 + druid/extended/checkbox_group.lua | 2 + druid/extended/data_list.lua | 2 + druid/extended/dynamic_grid.lua | 2 + druid/extended/hotkey.lua | 2 + druid/extended/input.lua | 2 + druid/extended/lang_text.lua | 1 + druid/extended/layout.lua | 2 + druid/extended/progress.lua | 2 + druid/extended/radio_group.lua | 2 + druid/extended/slider.lua | 2 + druid/extended/swipe.lua | 2 + druid/helper.lua | 10 +++- druid/system/druid_instance.lua | 34 +++++------ example/example.gui_script | 2 +- 24 files changed, 137 insertions(+), 102 deletions(-) delete mode 100644 docs_md/components/manual_rich_text.md diff --git a/README.md b/README.md index 392496e..2c191ed 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ **Druid** - powerful **Defold** component UI framework that empowers developers to create stunning and customizable GUIs by leveraging a wide range of embedded components or effortlessly designing their own game-specific components. +Try the [**HTML5 version**](https://insality.github.io/druid/druid/) of the **Druid** example app. ## Setup @@ -88,9 +89,9 @@ Start reading the API documentation [here](https://insality.github.io/druid/modu [EmmyLua](https://emmylua.github.io/annotation.html) is a Lua annotation library. It is a useful tool for enabling Lua code autocompletion in editors such as [VSCode](https://github.com/EmmyLua/VSCode-EmmyLua) and [IntelliJ IDEA](https://github.com/EmmyLua/IntelliJ-EmmyLua). -Since dependencies cannot be processed by external editors, to use the generated EmmyLua annotations, you should copy the _druid/annotations.lua_ file to your project. +Since dependencies cannot be processed by external editors, to use the EmmyLua annotations, you should copy the _druid/annotations.lua_ file to your project. -For EmmyLua, this will be sufficient. Remember that you can restart the EmmyLua server to refresh the changes if something goes wrong. +Remember that you can restart the EmmyLua server to refresh the changes if something goes wrong. After the annotations are processed, you should specify the type of "Druid" in the "require" statement: @@ -146,9 +147,9 @@ Here is full **Druid** components list. | **[Input](https://insality.github.io/druid/modules/Input.html)** | Logic over GUI Node and GUI Text (or Text component). Provides basic user text input. | [Input Example](https://insality.github.io/druid/druid/?example=general_input) | | | **[Lang text](https://insality.github.io/druid/modules/LangText.html)** | Logic over Text component to handle localization. Can be translated in real-time with `druid.on_language_change` | ❌ | | | **[Progress](https://insality.github.io/druid/modules/Progress.html)** | Logic over GUI Node. Handle node size and scale to handle progress node size. | [Progress Example](https://insality.github.io/druid/druid/?example=general_progress_bar) | | -| **[Slider](https://insality.github.io/druid/modules/Slider.html)** | Logic over GUI Node. Handle draggable node with position restrictions. | [Slider Example]() | | +| **[Slider](https://insality.github.io/druid/modules/Slider.html)** | Logic over GUI Node. Handle draggable node with position restrictions. | [Slider Example](https://insality.github.io/druid/druid/?example=general_sliders) | | | **[Timer](https://insality.github.io/druid/modules/Timer.html)** | Logic over GUI Text. Handle basic timer functions. | ❌ | | -| **[Hotkey](https://insality.github.io/druid/modules/Hotkey.html)** | Allow to set callbacks for keyboard hotkeys with key modificators. | [Hotkey Example](https://insality.github.io/druid/druid/?example=general_hokey) | | +| **[Hotkey](https://insality.github.io/druid/modules/Hotkey.html)** | Allow to set callbacks for keyboard hotkeys with key modificators. | [Hotkey Example](https://insality.github.io/druid/druid/?example=general_hotkey) | | | **[Layout](https://insality.github.io/druid/modules/Layout.html)** | Logic over GUI Node. Handle node size depends on layout mode and screen aspect ratio. Contains helpers to build more complex UI layout. | [Layout Example](https://insality.github.io/druid/druid/?example=general_layout) | | For a complete overview, see: **_[components.md](docs_md/01-components.md)_**. @@ -192,16 +193,17 @@ Refer to the [**example folder**](https://github.com/Insality/druid/tree/develop ## Documentation To better understand **Druid**, read the following documentation: +- [How To GUI in Defold](https://forum.defold.com/t/how-to-gui-in-defold/73256) - [Druid components](docs_md/01-components.md) - [Create custom components](docs_md/02-creating_custom_components.md) - [See FAQ article](docs_md/FAQ.md) - [Druid styles](docs_md/03-styles.md) -You can fund the full **Druid** documentation here: -https://insality.github.io/druid/ +You can find the full **Druid** documentation here: +https://insality.github.io/druid/modules/Druid.html -## License +## Licenses - Developed and supported by [Insality](https://github.com/Insality) - Original idea by [AGulev](https://github.com/AGulev) diff --git a/docs_md/components/manual_rich_text.md b/docs_md/components/manual_rich_text.md deleted file mode 100644 index aa4ffef..0000000 --- a/docs_md/components/manual_rich_text.md +++ /dev/null @@ -1,59 +0,0 @@ -# Druid Rich Text - -## Links -[Rich Text API here](https://insality.github.io/druid/modules/RichText.html) - -## Overview - - -## Setup - -Rich Text requires the next GUI Node scheme: -```bash - root - ├── text_prefab - └── node_prefab -``` -or make the copy of `/druid/custom/rich_text/rich_text.gui` and adjust your default settings - -Create Rich Text: -```lua -local RichText = require("druid.custom.rich_text.rich_text") - -function init(self) - self.druid = druid.new(self) - self.rich_text = self.druid:new(RichText, "template_name") - self.rich_text:set_text("Insert your text here") -end -``` - -## Usage - -| Tag | Description | Example | -|---------|------------------------------------------------|---------------------------------------------| -| a | Create a "hyperlink" that generates a message | `Foobar` | -| | when clicked (see `richtext.on_click`) | | -| br | Insert a line break (see notes on linebreak) | `
` | -| color | Change text color | `Foobar` | -| | | `Foobar` | -| | | `Foobar` | -| | | `Foobar` | -| shadow | Change text shadow | `Foobar` | -| | | `Foobar` | -| | | `Foobar` | -| | | `Foobar` | -| outline | Change text shadow | `Foobar` | -| | | `Foobar` | -| | | `Foobar` | -| | | `Foobar` | -| font | Change font | `Foobar` | -| img | Display image | `` | -| | Display image in fixed square | `` | -| | Display image in fixed rectangle | `` | -| nobr | Prevent the text from breaking | `Words inside tag won't break` | -| size | Change text size, relative to default size | `Twice as large` | - - -## Usecases - -## Notes diff --git a/druid/base/button.lua b/druid/base/button.lua index f21da7f..628b58e 100755 --- a/druid/base/button.lua +++ b/druid/base/button.lua @@ -19,6 +19,8 @@ -- -- • To animate a small icon on a big button panel, you can use an animation node. -- The trigger node name should be set as "big panel," and the animation node should be set as "small icon." +-- +-- Example Link -- @usage -- local function on_button_click(self, args, button) -- print("Button has clicked with params: " .. args) diff --git a/druid/base/drag.lua b/druid/base/drag.lua index 2667ca4..5c420db 100644 --- a/druid/base/drag.lua +++ b/druid/base/drag.lua @@ -4,6 +4,8 @@ -- Drag have correct handling for multitouch and swap -- touched while dragging. Drag will be processed even -- the cursor is outside of node, if drag is already started +-- +-- Example Link -- @module Drag -- @within BaseComponent -- @alias druid.drag diff --git a/druid/base/scroll.lua b/druid/base/scroll.lua index 294fd05..a7b510a 100755 --- a/druid/base/scroll.lua +++ b/druid/base/scroll.lua @@ -31,6 +31,8 @@ -- -- • Multitouch is required for scrolling. The scroll component correctly handles -- touch ID swaps while dragging the scroll. +-- +-- Example Link -- @module Scroll -- @within BaseComponent -- @alias druid.scroll diff --git a/druid/base/static_grid.lua b/druid/base/static_grid.lua index 54554cc..1274a87 100644 --- a/druid/base/static_grid.lua +++ b/druid/base/static_grid.lua @@ -29,6 +29,8 @@ -- -- • You can specify a position_function for animations using the -- _static_grid:set_position_function(node, pos) callback. The default position function is gui.set_position(). +-- +-- Example Link -- @module StaticGrid -- @within BaseComponent -- @alias druid.static_grid diff --git a/druid/base/text.lua b/druid/base/text.lua index 6372a79..1735311 100755 --- a/druid/base/text.lua +++ b/druid/base/text.lua @@ -29,6 +29,8 @@ -- For better effect, use with a stencil node. -- -- - const.TEXT_ADJUST.SCALE_THEN_SCROLL: Combines two modes: limited downscale first, then scroll. +-- +-- Example Link -- @module Text -- @within BaseComponent -- @alias druid.text diff --git a/druid/custom/rich_text/module/rt.lua b/druid/custom/rich_text/module/rt.lua index fa48fec..5b82a09 100755 --- a/druid/custom/rich_text/module/rt.lua +++ b/druid/custom/rich_text/module/rt.lua @@ -449,9 +449,9 @@ function M.set_text_scale(words, settings, scale) end ----@param words rich_text.word[] ----@param settings rich_text.settings ----@param lines_metrics rich_text.lines_metrics +---@param words druid.rich_text.word[] +---@param settings druid.rich_text.settings +---@param lines_metrics druid.rich_text.lines_metrics function M.adjust_to_area(words, settings, lines_metrics) local last_line_metrics = lines_metrics diff --git a/druid/custom/rich_text/rich_text.lua b/druid/custom/rich_text/rich_text.lua index d6a7078..30a6948 100644 --- a/druid/custom/rich_text/rich_text.lua +++ b/druid/custom/rich_text/rich_text.lua @@ -1,40 +1,89 @@ -- Copyright (c) 2022 Maksim Tuprikov . This code is licensed under MIT license ---- Druid Rich Text custom component. +--- Druid Rich Text Custom Component. -- # Overview # -- --- Heavily inspired by https://github.com/britzl/defold-richtext. +-- This custom component is inspired by defold-richtext by britzl. +-- It uses a similar syntax for tags but currently supports fewer tags. -- --- Uses the same syntax for tags, but currently have less tags support. +-- All parameters for the Rich Text component are adjusted in the GUI scene. -- --- All Rich Text params are adjusted in GUI scene +-- This component uses GUI component template. (/druid/custom/rich_text/rich_text.gui). -- --- The Rich Text template should have next scheme: +-- You able to customize it or make your own with the next node scructure: -- -- root -- --- - text_prefab +-- - text_prefab -- --- - icon_prefab +-- - icon_prefab -- -- # Rich Text Setup # --- • Root node size - maximum width and height of the text --- • Root anchor - Aligment of the Rich Text inside root node size area --- • Text prefab - all text params for the text node --- • Text prefab anchor - Anchor for each text node (you should adjust this only if animate text) --- • Icon prefab - all node params for the icon node --- • Icon prefab anchor - Anchor for each icon node (you should adjust this only if animate icon) +-- +-- • Root node size: Set the maximum width and height of the text. +-- +-- • Root anchor: Define the alignment of the Rich Text inside the root node size area. +-- +-- • Text prefab: Configure all default text parameters for the text node. +-- +-- • Text prefab anchor: Set the anchor for each text node (adjust this only if animating text). +-- +-- • Icon prefab: Configure all default node parameters for the icon node. +-- +-- • Icon prefab anchor: Set the anchor for each icon node (adjust this only if animating the icon). -- -- # Notes # -- -- • Nested tags are supported -- +-- Example Link -- @usage -- local RichText = require("druid.custom.rich_text.rich_text") -- ... -- self.rich_text = self.druid:new(RichText, "rich_text") -- self.rich_text:set_text("Hello, Druid Rich Text!") +-- @usage +-- type druid.rich_text.word = { +-- node: Node, +-- relative_scale: number, +-- color: vector4, +-- position: vector3, +-- offset: vector3, +-- scale: vector3, +-- size: vector3, +-- metrics: druid.rich_text.metrics, +-- pivot: Pivot, +-- text: string, +-- shadow: vector4, +-- outline: vector4, +-- font: string, +-- image: druid.rich_text.image, +-- default_animation: string, +-- anchor: number, +-- br: boolean, +-- nobr: boolean, +-- } -- +-- type druid.rich_text.word.image = { +-- texture: string, +-- anim: string, +-- width: number, +-- height: number, +-- } +-- +-- type druid.rich_text.lines_metrics = { +-- text_width: number, +-- text_height: number, +-- lines: table, +-- } +-- +-- type druid.rich_text.metrics = { +-- width: number, +-- height: number, +-- offset_x: number|nil, +-- offset_y: number|nil, +-- node_size: vector3|nil @For images only, +-- } -- @module RichText -- @within BaseComponent -- @alias druid.rich_text @@ -79,8 +128,8 @@ end --- Set text for Rich Text -- @tparam RichText self @{RichText} -- @tparam string text The text to set --- @treturn table words --- @treturn table line_metrics +-- @treturn druid.rich_text.word[] words +-- @treturn druid.rich_text.lines_metrics line_metrics -- @usage -- • color: Change text color -- diff --git a/druid/extended/checkbox.lua b/druid/extended/checkbox.lua index ef1b295..f3ee5fa 100755 --- a/druid/extended/checkbox.lua +++ b/druid/extended/checkbox.lua @@ -1,6 +1,8 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license --- Druid checkbox component +-- +-- Example Link -- @module Checkbox -- @within BaseComponent -- @alias druid.checkbox diff --git a/druid/extended/checkbox_group.lua b/druid/extended/checkbox_group.lua index 2ca9561..046bbfa 100644 --- a/druid/extended/checkbox_group.lua +++ b/druid/extended/checkbox_group.lua @@ -1,6 +1,8 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license --- Checkbox group module +-- +-- Example Link -- @module CheckboxGroup -- @within BaseComponent -- @alias druid.checkbox_group diff --git a/druid/extended/data_list.lua b/druid/extended/data_list.lua index 2c1b011..f7187b7 100644 --- a/druid/extended/data_list.lua +++ b/druid/extended/data_list.lua @@ -2,6 +2,8 @@ --- Component to manage data for huge dataset in scroll. -- It requires Druid Scroll and Druid Grid (Static or Dynamic) components +-- +-- Example Link -- @module DataList -- @within BaseComponent -- @alias druid.data_list diff --git a/druid/extended/dynamic_grid.lua b/druid/extended/dynamic_grid.lua index 5e8dbc6..1fec83f 100644 --- a/druid/extended/dynamic_grid.lua +++ b/druid/extended/dynamic_grid.lua @@ -1,6 +1,8 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license --- Component to handle placing components in row +-- +-- Example Link -- @module DynamicGrid -- @within BaseComponent -- @alias druid.dynamic_grid diff --git a/druid/extended/hotkey.lua b/druid/extended/hotkey.lua index 23ecd49..6985f15 100644 --- a/druid/extended/hotkey.lua +++ b/druid/extended/hotkey.lua @@ -1,6 +1,8 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license --- Druid hotkey component +-- +-- Example Link -- @module Hotkey -- @within BaseComponent -- @alias druid.hotkey diff --git a/druid/extended/input.lua b/druid/extended/input.lua index da1b220..3cb2bca 100755 --- a/druid/extended/input.lua +++ b/druid/extended/input.lua @@ -2,6 +2,8 @@ --- Druid input text component. -- Carry on user text input +-- +-- Example Link -- @author Part of code from Britzl gooey input component -- @module Input -- @within BaseComponent diff --git a/druid/extended/lang_text.lua b/druid/extended/lang_text.lua index af36877..6b066c5 100755 --- a/druid/extended/lang_text.lua +++ b/druid/extended/lang_text.lua @@ -12,6 +12,7 @@ -- -- # Notes # -- +-- Example Link -- @module LangText -- @within BaseComponent -- @alias druid.lang_text diff --git a/druid/extended/layout.lua b/druid/extended/layout.lua index 6e8db43..7bcd8f0 100644 --- a/druid/extended/layout.lua +++ b/druid/extended/layout.lua @@ -1,6 +1,8 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license --- Layout management on node +-- +-- Example Link -- @module Layout -- @within BaseComponent -- @alias druid.layout diff --git a/druid/extended/progress.lua b/druid/extended/progress.lua index ddd2081..ac24bba 100644 --- a/druid/extended/progress.lua +++ b/druid/extended/progress.lua @@ -13,6 +13,8 @@ -- -- • If you have glitchy or dark texture bug with progress bar, try to disable mipmaps in your texture profiles -- +-- +-- Example Link -- @module Progress -- @within BaseComponent -- @alias druid.progress diff --git a/druid/extended/radio_group.lua b/druid/extended/radio_group.lua index fef1d00..96aa334 100644 --- a/druid/extended/radio_group.lua +++ b/druid/extended/radio_group.lua @@ -1,6 +1,8 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license --- Radio group module +-- +-- Example Link -- @module RadioGroup -- @within BaseComponent -- @alias druid.radio_group diff --git a/druid/extended/slider.lua b/druid/extended/slider.lua index 4f48e8d..8907a8b 100644 --- a/druid/extended/slider.lua +++ b/druid/extended/slider.lua @@ -1,6 +1,8 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license --- Druid slider component +-- +-- Example Link -- @module Slider -- @within BaseComponent -- @alias druid.slider diff --git a/druid/extended/swipe.lua b/druid/extended/swipe.lua index d4ecc27..d263686 100644 --- a/druid/extended/swipe.lua +++ b/druid/extended/swipe.lua @@ -3,6 +3,8 @@ --- Component to handle swipe gestures on node. -- Swipe will be triggered, if swipe was started and -- ended on one node +-- +-- Example Link -- @module Swipe -- @within BaseComponent -- @alias druid.swipe diff --git a/druid/helper.lua b/druid/helper.lua index e79fd40..d59880a 100644 --- a/druid/helper.lua +++ b/druid/helper.lua @@ -10,6 +10,7 @@ local const = require("druid.const") local M = {} +M._some = { pepepe = true } local function get_text_width(text_node) @@ -393,7 +394,14 @@ end --- Get text metric from GUI node. -- @function helper.get_text_metrics_from_node -- @tparam Node text_node --- @treturn GUITextMetrics Fields: width, height, max_ascent, max_descent +-- @treturn pepepe +-- @usage +-- type GUITextMetrics = { +-- width: number, +-- height: number, +-- max_ascent: number, +-- max_descent: number +-- } function M.get_text_metrics_from_node(text_node) local font_resource = gui.get_font_resource(gui.get_font(text_node)) local options = { diff --git a/druid/system/druid_instance.lua b/druid/system/druid_instance.lua index 862586e..0bb1f8e 100755 --- a/druid/system/druid_instance.lua +++ b/druid/system/druid_instance.lua @@ -43,27 +43,29 @@ -- -- @module DruidInstance -- @alias druid_instance --- @see Button --- @see Blocker -- @see BackHandler --- @see Input --- @see Text --- @see LangText --- @see Timer --- @see Progress --- @see StaticGrid --- @see DynamicGrid --- @see Scroll --- @see Slider +-- @see Blocker +-- @see Button -- @see Checkbox -- @see CheckboxGroup --- @see RadioGroup --- @see Swipe --- @see Drag -- @see DataList --- @see Hover --- @see Layout +-- @see Drag +-- @see DynamicGrid -- @see Hotkey +-- @see Hover +-- @see Input +-- @see LangText +-- @see Layout +-- @see Progress +-- @see RadioGroup +-- @see RichInput +-- @see RichText +-- @see Scroll +-- @see Slider +-- @see StaticGrid +-- @see Swipe +-- @see Text +-- @see Timer local helper = require("druid.helper") local class = require("druid.system.middleclass") diff --git a/example/example.gui_script b/example/example.gui_script index 5e786c8..7ff6864 100644 --- a/example/example.gui_script +++ b/example/example.gui_script @@ -85,7 +85,7 @@ local function init_top_panel(self) gui.set_enabled(self.button_menu.node, false) self.button_api = self.druid:new_button("button_api/button", function() - sys.open_url("https://insality.github.io/druid/") + sys.open_url("https://insality.github.io/druid/modules/Druid.html") end) self.button_code = self.druid:new_button("button_code/button", function()