Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Insality
Insality committed Oct 19, 2024
1 parent 0a5bb24 commit 8d409b8
Show file tree
Hide file tree
Showing 5 changed files with 153 additions and 109 deletions.
8 changes: 6 additions & 2 deletions .vscode/settings.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,10 @@
"Lua.runtime.version": "Lua 5.1",
"Lua.workspace.library": [
"~/Library/Application Support/Code/User/globalStorage/astronachos.defold",
"~/Library/Application Support/Code/User/workspaceStorage/72e25b7e0fdc873ee6f7baa61edbd6b1/astronachos.defold"
]
"~/Library/Application Support/Code/User/workspaceStorage/72e25b7e0fdc873ee6f7baa61edbd6b1/astronachos.defold",
"~/Library/Application Support/Code/User/workspaceStorage/1446075a23c89451a63f0e82b2291def/astronachos.defold"
],
"files.exclude": {
"**/*.gui": true
}
}
28 changes: 15 additions & 13 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,21 @@

**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.
## Druid Example

Check the [**HTML5 version**](https://insality.github.io/druid/druid/) of the **Druid** example app.

In this example you can inspect a variety of **Druid** components and see how they work. Each example page provides a direct link to the corresponding example code, making it easier for you to understand how to use **Druid**.

## Setup

### Dependency

To integrate the **Druid** extension into your own project, add this project as a [dependency](https://www.defold.com/manuals/libraries/) in your **Defold** game. Open your `game.project` file and add the following line to the dependencies field under the project section:

**Druid v0.12.0**
**Druid v1.0**

> [https://github.com/Insality/druid/archive/refs/tags/0.12.0.zip](https://github.com/Insality/druid/archive/refs/tags/0.12.0.zip)
> [https://github.com/Insality/druid/archive/refs/tags/1.0.zip](https://github.com/Insality/druid/archive/refs/tags/1.0.zip)
Here is a list of [all releases](https://github.com/Insality/druid/releases).

Expand All @@ -30,7 +34,7 @@ Here is a list of [all releases](https://github.com/Insality/druid/releases).
| Platform | Library Size |
| ---------------- | ------------- |
| HTML5 | **38.96 KB** |
| HTML5 | **38.00 KB** |
| Desktop / Mobile | **65.97 KB** |


Expand Down Expand Up @@ -118,10 +122,10 @@ Here is full **Druid** components list.
| **[Button](https://insality.github.io/druid/modules/Button.html)** | Logic over GUI Node. Handle the user click interactions: click, long click, double click, etc. | [Button Example](https://insality.github.io/druid/druid/?example=general_buttons) | <img src="media/preview/button.gif" width="200" height="100"> |
| **[Text](https://insality.github.io/druid/modules/Text.html)** | Logic over GUI Text. By default Text component fit the text inside text node size area with different adjust modes. | [Text Example](https://insality.github.io/druid/druid/?example=texts_general) | <img src="media/preview/text.gif" width="200" height="100"> |
| **[Scroll](https://insality.github.io/druid/modules/Scroll.html)** | Logic over two GUI Nodes: input and content. Provides basic behaviour for scrollable content. | [Scroll Example](https://insality.github.io/druid/druid/?example=general_scroll) | <img src="media/preview/scroll.gif" width="200" height="100"> |
| **[Blocker](https://insality.github.io/druid/modules/Blocker.html)** | Logic over GUI Node. Don't pass any user input below node area size. | ❌ | |
| **[Back Handler](https://insality.github.io/druid/modules/BackHandler.html)** | Call callback on user "Back" action. It's a Android back button or keyboard backspace key | ❌ | |
| **[Blocker](https://insality.github.io/druid/modules/Blocker.html)** | Logic over GUI Node. Don't pass any user input below node area size. | [Blocker Example](https://insality.github.io/druid/druid/?example=timer) | <img src="media/preview/blocker.gif" width="200" height="100"> |
| **[Back Handler](https://insality.github.io/druid/modules/BackHandler.html)** | Call callback on user "Back" action. It's a Android back button or keyboard backspace key | [Back Handler Example](https://insality.github.io/druid/druid/?example=timer) | <img src="media/preview/back_handler.gif" width="200" height="100"> |
| **[Static Grid](https://insality.github.io/druid/modules/StaticGrid.html)** | Logic over GUI Node. Component to manage node positions with all equal node sizes. | [Static Gid Example](https://insality.github.io/druid/druid/?example=general_grid) | <img src="media/preview/static_grid.gif" width="200" height="100"> |
| **[Hover](https://insality.github.io/druid/modules/Hover.html)** | Logic over GUI Node. Handle hover action over node. For both: mobile touch and mouse cursor. | ❌ | <img src="media/preview/hover.gif" width="200" height="100"> |
| **[Hover](https://insality.github.io/druid/modules/Hover.html)** | Logic over GUI Node. Handle hover action over node. For both: mobile touch and mouse cursor. | [Hover Example](https://insality.github.io/druid/druid/?example=timer) | <img src="media/preview/hover.gif" width="200" height="100"> |
| **[Swipe](https://insality.github.io/druid/modules/Swipe.html)** | Logic over GUI Node. Handle swipe gestures over node. | [Swipe Example](https://insality.github.io/druid/druid/?example=general_swipe) | <img src="media/preview/swipe.gif" width="200" height="100"> |
| **[Drag](https://insality.github.io/druid/modules/Drag.html)** | Logic over GUI Node. Handle drag input actions. Can be useful to make on screen controlls. | [Drag Example](https://insality.github.io/druid/druid/?example=general_drag) | <img src="media/preview/drag.gif" width="200" height="100"> |

Expand All @@ -137,18 +141,16 @@ druid.register("data_list", data_list)

| Name | Description | Example | <div style="width:200px">Preview</div> |
|------|-------------|---------|---------|
| **[Checkbox](https://insality.github.io/druid/modules/Checkbox.html)** | Switch node state on click event. | [Checkbox Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/checkbox.gif" width="200" height="100"> |
| **[Checkbox group](https://insality.github.io/druid/modules/CheckboxGroup.html)** | Group of checkbox components. | [Checkbox group Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/checkbox_group.gif" width="200" height="100"> |
| **[Radio group](https://insality.github.io/druid/modules/RadioGroup.html)** | Like checkbox group but with single choise only. | [Radio Group Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/radio_group.gif" width="200" height="100"> |
| **[Dynamic Grid](https://insality.github.io/druid/modules/DynamicGrid.html)** | Logic over GUI Node. Component to manage node positions with all different node sizes. Only one direction: horizontal or vertical. | [Dynamic Grid Example](https://insality.github.io/druid/druid/?example=general_grid) | <img src="media/preview/dynamic_grid.gif" width="200" height="100"> |
| **[Data List](https://insality.github.io/druid/modules/DataList.html)** | Logic over Scroll and Grid components. Create only visible GUI nodes or components to make "infinity" scroll befaviour | [Data List Example](https://insality.github.io/druid/druid/?example=general_data_list) | <img src="media/preview/data_list.gif" width="200" height="100"> |
| **[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) | <img src="media/preview/input.gif" width="200" height="100"> |
| **[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` | ❌ | <img src="media/preview/lang_text.gif" width="200" height="100"> |
| **[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` | [Lang Text Example](https://insality.github.io/druid/druid/?example=timer) | <img src="media/preview/lang_text.gif" width="200" height="100"> |
| **[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) | <img src="media/preview/progress.gif" width="200" height="100"> |
| **[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) | <img src="media/preview/slider.gif" width="200" height="100"> |
| **[Timer](https://insality.github.io/druid/modules/Timer.html)** | Logic over GUI Text. Handle basic timer functions. | ❌ | <img src="media/preview/timer.gif" width="200" height="100"> |
| **[Timer](https://insality.github.io/druid/modules/Timer.html)** | Logic over GUI Text. Handle basic timer functions. | [Timer Example](https://insality.github.io/druid/druid/?example=timer) | <img src="media/preview/timer.gif" width="200" height="100"> |
| **[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) | <img src="media/preview/hotkey.gif" width="200" height="100"> |
| **[Layout](https://insality.github.io/druid/modules/Layout.html)** | Logic over GUI Node. Arrange nodes inside layout node with margin/paddings settings. | [Layout Example](https://insality.github.io/druid/druid/?example=general_layout) | <img src="media/preview/layout.gif" width="200" height="100"> |
| **[Rich Input](https://insality.github.io/druid/modules/RichInput.html)** | Logic over GUI Node and GUI Text (or Text component). Provides rich text input with different styles and text formatting. | [Rich Input Example](https://insality.github.io/druid/druid/?example=general_rich_input) | <img src="media/preview/rich_input.gif" width="200" height="100"> |
| **[Rich Text](https://insality.github.io/druid/modules/RichText.html)** | Logic over GUI Text. Provides rich text formatting with different styles and text formatting. | [Rich Text Example](https://insality.github.io/druid/druid/?example=general_rich_text) | <img src="media/preview/rich_text.gif" width="200" height="100"> |

For a complete overview, see: **_[components.md](docs_md/01-components.md)_**.

Expand Down
61 changes: 8 additions & 53 deletions docs_md/01-components.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -192,49 +192,6 @@ Create input component with druid: `input = druid:new_input(button_node_name, te
- To make work different keyboard type, make sure value in game.project Android:InputMethod set to HidderInputField (https://defold.com/manuals/project-settings/#input-method)


## Checkbox
[Checkbox API here](https://insality.github.io/druid/modules/Checkbox.html)

### Overview
Basic Druid checkbox component.

### Setup
Create checkbox component with druid: `checkbox = druid:new_checkbox(node, callback)`

### Notes
- Checkbox uses button to handle click
- You can setup another node to handle input with click_node arg in component init: `druid:new_checkbox(node, callback, [click_node])`


## Checkbox group
[Checkbox group API here](https://insality.github.io/druid/modules/CheckboxGroup.html)

### Overview
Several checkboxes in one group

### Setup
Create checkbox_group component with druid: `group = druid:new_checkbox_group(nodes[], callback)`

### Notes
- Callback arguments: `function(self, checkbox_index)`. Index is equals in _nodes[]_ array in component constructor
- You can get/set checkbox_group state with `group:set_state()` and `group:get_state()`


## Radio group
[Radio group API here](https://insality.github.io/druid/modules/RadioGroup.html)

### Overview
Several checkboxes in one group with single choice

### Setup
Create radio_group component with druid: `group = druid:new_radio_group(nodes[], callback)`

### Notes
- Callback arguments: `function(self, checkbox_index)`. Index is equals in _nodes[]_ array in component constructor
- You can get/set radio_group state with `group:set_state()` and `group:get_state()`
- Only different from checkbox_group: on click another checkboxes in this group will be unchecked


## Timer
[Timer API here](https://insality.github.io/druid/modules/Timer.html)

Expand Down Expand Up @@ -419,7 +376,7 @@ Create hotkey component with druid: `hotkey = druid:new_hotkey(keys_array, callb
[Layout API here](https://insality.github.io/druid/modules/Layout.html)

### Overview
Component to handle node size depends on layout mode. Unlike from Defold Adjust modes, you able to select node stretch by one size or zoom by minimum or maximum side
Component to arrange nodes inside layout node with margin/paddings settings. Works with different node sizes and pivots. Works in the same way as Figma AutoLayout

### Setup
This is extended component. Before use it, you should register it:
Expand All @@ -428,17 +385,15 @@ local druid = require("druid.druid")
local layout = require("druid.extended.layout")
druid.register("layout", layout)
```
Create layout component with druid: `layout = druid:new_layout(node, layout_mode, on_size_change_callback)`
Create layout component with druid: `layout = druid:new_layout(node, layout_mode)`


### Notes
- Layout mode can be next:
- `const.LAYOUT_MODE.STRETCH_X` - Stretch node only by X
- `const.LAYOUT_MODE.STRETCH_Y` - Stretch node only by Y
- `const.LAYOUT_MODE.ZOOM_MIN` - Zoom node by minimal stretch multiplier
- `const.LAYOUT_MODE.ZOOM_MAX` - Zoom node by maximum stretch multiplier
- `const.LAYOUT_MODE.FIT` - Usual Defold Fit mode
- `const.LAYOUT_MODE.STRETCH` - Usual Defold Stretch Mode
- The Layout component will change the node size property. So it's able to increase size of 9patch nodes without scaling issue
- The Layout works even inside parent node with Fit adjust mode
- `horizontal` - arrange nodes in horizontal line
- `vertical` - arrange nodes in vertical line
- `horizontal_wrap` - arrange nodes in horizontal line with wrap to next line
- You can setup margin and padding for layout nodes
- You can set "justify" alignment to place nodes with the same margin between layout node borders
- You can set "hug" by content. This option will set layout node size by content size. Can be setup separately for width and height

58 changes: 39 additions & 19 deletions docs_md/02-creating_custom_components.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,18 +15,38 @@ A basic custom component template looks like this (you can copy it from `/druid/
local component = require("druid.component")

---@class component_name: druid.base_component
local Component = component.create("component_name")
local M = component.create("component_name")

function Component:init(template, nodes)
function M:init(template, nodes)
self.druid = self:get_druid(template, nodes)
self.root = self:get_node("root")

self.button = self.druid:new_button("button", function() end)
end

function Component:on_remove() end
function M:hello()
print("Hello from custom component")
end

return M
```

Then you can create your custom component with Druid:
```lua
local druid = require("druid.druid")

local my_component = require("my.amazing.component")

function init(self)
self.druid = druid.new(self)

-- We pass a GUI template "template_name" and skip nodes due it already on the scene
self.my_component = self.druid:new(my_component, "template_name")
self.my_component:hello() -- Hello from custom component


end

return Component
```

### Full Component Template
Expand All @@ -37,36 +57,36 @@ A full custom component template looks like this (you can copy it from `/druid/t
local component = require("druid.component")

---@class component_name: druid.base_component
local Component = component.create("component_name")
local M = component.create("component_name")

function Component:init(template, nodes)
function M:init(template, nodes)
self.druid = self:get_druid(template, nodes)
self.root = self:get_node("root")
end

function Component:update(dt) end
function M:update(dt) end

function Component:on_input(action_id, action) return false end
function M:on_input(action_id, action) return false end

function Component:on_style_change(style) end
function M:on_style_change(style) end

function Component:on_message(message_id, message, sender) end
function M:on_message(message_id, message, sender) end

function Component:on_language_change() end
function M:on_language_change() end

function Component:on_layout_change() end
function M:on_layout_change() end

function Component:on_window_resized() end
function M:on_window_resized() end

function Component:on_input_interrupt() end
function M:on_input_interrupt() end

function Component:on_focus_lost() end
function M:on_focus_lost() end

function Component:on_focus_gained() end
function M:on_focus_gained() end

function Component:on_remove() end
function M:on_remove() end

return Component
return M
```

### Spawning a Custom Component
Expand Down Expand Up @@ -117,7 +137,7 @@ Druid provides an editor script to assist you in creating Lua files for your GUI

The script analyzes the current GUI scene and generates a Lua file with stubs for all Druid components found. The output file is named after the current GUI scene and placed in the same directory. Note that the script does not override any existing *.lua files. If you want to regenerate a file, delete the previous version first.

The script requires `python3` with `deftree` installed. If `deftree` is not installed, the instructions will be displayed in the console.
The script requires `python` with `deftree` installed. If `deftree` is not installed, the instructions will be displayed in the console.

### Auto-Layout Components

Expand Down
Loading

0 comments on commit 8d409b8

Please sign in to comment.