diff --git a/README.md b/README.md index 23f3ed8..9c8e7a4 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,15 @@ + + [![](media/druid_logo.png)](https://insality.github.io/druid/) -[![GitHub release (latest by date)](https://img.shields.io/github/v/release/insality/druid)](https://github.com/Insality/druid/releases) - -**Druid** - powerful defold component UI library. Use basic druid components or make your own game-specific components to make amazing GUI in your games. +**Druid** - powerful defold component UI library. Use basic Druid components or make your own game-specific components to make amazing GUI in your games. ## Setup ### Dependency -You can use the druid extension in your own project by adding this project as a [Defold library dependency](https://www.defold.com/manuals/libraries/). Open your game.project file and in the dependencies field under project add: +You can use the **Druid** extension in your own project by adding this project as a [Defold library dependency](https://www.defold.com/manuals/libraries/). Open your game.project file and in the dependencies field under project add: > [https://github.com/Insality/druid/archive/master.zip](https://github.com/Insality/druid/archive/master.zip) @@ -18,24 +18,45 @@ Or point to the ZIP file of a [specific release](https://github.com/Insality/dr ### Code -Adjust druid settings, if needed: +Adjust **Druid** settings, if needed: ```lua local druid = require("druid.druid") -- Used for button component and custom components +-- Callback should play sound by name druid.set_sound_function(callback) -- Used for lang_text component +-- Callback should return localized string by locale id druid.set_text_function(callback) -- Used for change default druid style druid.set_default_style(your_style) ``` +### Input bindings + +For **Druid** to work requires next input bindings: + +- Mouse trigger - `mouse-button-1` -> `touch` _For basic input components_ +- Key trigger - `Backspace` -> `backspace` _For back_handler component_ +- Key trigger - `Back` -> `text` _For back_handler component, Android back button_ + +![](media/input_binding.png) + +### Input capturing + +By default, **Druid** will auto-capture input focus, if any input component will be created. So you don't need to call `msg.post(".", "acquire_input_focus)"` + +If you not need this behaviour, you can disable it by settings `druid.no_auto_input` field in _game.project_: +``` +[druid] +no_auto_input = 1 +``` ## Components -Druid provides next basic components: +**Druid** provides next basic components: - **Button** - Basic game button - **Text** - Wrap on text node with text size adjusting @@ -69,16 +90,24 @@ Druid provides next basic components: Full info see on _components.md_ -## Creating components +## Basic usage + +For using **Druid**, first you should create Druid instance to spawn components. Pass to new Druid instance main engine functions: *update*, *on_message* and *on_input* + +All **Druid** components as arguments can apply node name string, you can don't do `gui.get_node()` before + +All **Druid** and component methods calling with `:` like `self.druid:new_button()` -Any components creating via druid: ```lua local druid = require("druid.druid") +local function button_callback(self) + print("Button was clicked!") +end + local function init(self) self.druid = druid.new(self) - local button = self.druid:new_button(node_name, callback) - local text = self.druid:new_text(node_text_name) + self.druid:new_button("button_node_name", button_callback) end function update(self, dt) @@ -90,14 +119,14 @@ function on_message(self, message_id, message, sender) end function on_input(self, action_id, action) - self.druid:on_input(action_id, action) + return self.druid:on_input(action_id, action) end ``` ## Examples -See the [example folder](https://github.com/insality/druid/tree/develop/example/kenney) for examples of how to use Druid +See the [example folder](https://github.com/insality/druid/tree/develop/example/kenney) for examples of how to use **Druid** See the [druid-assets repository](https://github.com/insality/druid-assets) for examples of how to create custom components and styles @@ -106,13 +135,13 @@ Try the [HTML5 version](https://insality.github.io/druid/druid/) of the example ## Documentation -To learn druid better, read next documentation: -- Druid components -- Create custom components -- Druid asset store -- Druid Styles +To learn **Druid** better, read next documentation: +- [Druid components](https://insality.github.io/druid/topics/01-components.md.html) +- [Create custom components](https://insality.github.io/druid/topics/02-creating_custom_components.md.html) +- [Druid styles](https://insality.github.io/druid/topics/03-styles.md.html) +- [Druid asset store](https://insality.github.io/druid/topics/04-druid_assets.md.html) -Full druid documentation you can find here: +Full **Druid** documentation you can find here: https://insality.github.io/druid/ @@ -127,7 +156,7 @@ _Will fill later_ - Add on_layout_change support (to keep gui data between layout change) -- Add on_change_language support (call single function to update all druid instance) +- Add on_change_language support (call single function to update all Druid instance) - Better documentation and examples @@ -140,9 +169,11 @@ Original created by [AGulev](https://github.com/AGulev) Developed and supporting by [Insality](https://github.com/Insality) +Assets from [Kenney](http://www.kenney.nl/) + MIT License ## Issues and suggestions -If you have any issues, questions or suggestions please [create an issue](https://github.com/Insality/druid/issues) or contact me: [insality@gmail.com](mailto:insality@gmail.com) +If you have any issues, questions or suggestions please [create an issue](https://github.com/Insality/druid/issues) or contact me: [insality@gmail.com](mailto:insality@gmail.com) diff --git a/docs_md/02-creating_custom_components.md b/docs_md/02-creating_custom_components.md index 197a2f3..05d09fd 100644 --- a/docs_md/02-creating_custom_components.md +++ b/docs_md/02-creating_custom_components.md @@ -10,7 +10,7 @@ Basic custom component template looks like this: local const = require("druid.const") local component = require("druid.component") -local M = component.create("your_component") +local M = component.create("name_your_component") -- Component constructor function M.init(self, ...) @@ -67,7 +67,7 @@ There is next interests in druid: ## Best practice on custom components -On each component recomended describe component scheme in next way: +On each component recommended describe component scheme in next way: ```lua -- Component module @@ -76,9 +76,9 @@ local component = require("druid.component") local M = component.create("your_component") local SCHEME = { - ROOT = "/root", - ITEM = "/item", - TITLE = "/title" + ROOT = "root", + ITEM = "item", + TITLE = "title" } function M.init(self, template_name, node_table) diff --git a/media/input_binding.png b/media/input_binding.png new file mode 100644 index 0000000..f5b68d6 Binary files /dev/null and b/media/input_binding.png differ