Druid-Extension/wiki/basic_usage.md

# Basic Usage

This guide will help you get started with **Druid** UI framework. We'll cover the basic setup and usage patterns.

## Initial Setup

To use **Druid**, you need to create a **Druid** instance in your GUI script. This instance will handle all component management and core functionality.

Create a new `*.gui_script` file with the following template:

```lua
local druid = require("druid.druid")

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

function final(self)
    self.druid:final()
end

function update(self, dt)
    self.druid:update(dt)
end

function on_message(self, message_id, message, sender)
    self.druid:on_message(message_id, message, sender)
end

function on_input(self, action_id, action)
    return self.druid:on_input(action_id, action)
end
```

Add this script to your GUI scene. Now you can start creating **Druid** components.

> **Note:** When passing nodes to components, you can use node name strings instead of `gui.get_node()` function.

## Basic Components Example

Here's a simple example showing how to create and use basic **Druid** components:

```lua
local druid = require("druid.druid")

-- All component callbacks pass "self" as first argument
-- This "self" is a context data passed in `druid.new(context)`
local function on_button_callback(self)
    self.text:set_text("The button clicked!")
end

function init(self)
    self.druid = druid.new(self)
    -- We can use the node_id instead of gui.get_node():
    self.button = self.druid:new_button("button_node_id", on_button_callback)
    self.text = self.druid:new_text("text_node_id", "Hello, Druid!")
end

function final(self)
    self.druid:final()
end

function update(self, dt)
    self.druid:update(dt)
end

function on_message(self, message_id, message, sender)
    self.druid:on_message(message_id, message, sender)
end

function on_input(self, action_id, action)
    return self.druid:on_input(action_id, action)
end
```

## Widgets

Widgets are reusable UI components that encapsulate multiple **Druid** components. Read more in the [Widgets](wiki/widgets.md) documentation.

### Creating a Widget

Create a new Lua file for your widget class. This file better to be placed near the corresponding GUI file with the same name.

Define `init` function to initialize the widget.

Here's a basic widget example:

```lua
---@class best_widget_in_the_world: druid.widget
local M = {}

function M:init()
    self.root = self:get_node("root")

    -- Create a button and a text components inside your widget
    self.button = self.druid:new_button("button_node_id", self.on_click)
    self.text = self.druid:new_text("text_node_id", "Hello, Druid!")

    -- They are now accessible by self.button and self.text outside
end

---The "self" will be invoked correctly inside Druid's callbacks
function M:on_click()
    self.text:set_text("The button clicked!")
end


---Add your own functions to the widget
function M:say_hello()
    self.text:set_text("Hello, Druid!")
end


return M
```

### Using Widgets

You can create widgets in your GUI script:

```lua
local druid = require("druid.druid")
local best_widget_in_the_world = require("widgets.best_widget_in_the_world")

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

    local my_widget_template_id_on_gui_scene = "best_widget_in_the_world"
    self.my_widget = self.druid:new_widget(best_widget_in_the_world, my_widget_template_id_on_gui_scene)

    -- Now you can use the widget functions
    self.my_widget:say_hello()
end

function final(self)
    self.druid:final()
end

function update(self, dt)
    self.druid:update(dt)
end

function on_message(self, message_id, message, sender)
    self.druid:on_message(message_id, message, sender)
end

function on_input(self, action_id, action)
    return self.druid:on_input(action_id, action)
end
```

## Widget Templates

Widgets can use templates defined in your GUI scene. Templates are collections of nodes that define the widget's structure.

### Using Templates

If you have a GUI template with ID `best_widget_in_the_world` containing `button_node_id` and `text_node_id` nodes, you can use it like this:

```lua
function init(self)
    self.druid = druid.new(self)
    self.my_widget = self.druid:new_widget(best_widget_in_the_world, "best_widget_in_the_world")

    self.my_widget.button.on_click:subscribe(function()
        print("my custom callback")
    end)
    self.my_widget.text:set_text("Hello, Widgets!")
end
```

### Dynamic Templates

For dynamically created GUI templates (from prefabs), you can pass nodes directly to the widget:

```lua
function init(self)
    self.druid = druid.new(self)
    self.prefab = gui.get_node("best_widget_in_the_world/root")
    local nodes = gui.clone_tree(self.prefab)
    self.my_widget = self.druid:new_widget(best_widget_in_the_world, "best_widget_in_the_world", nodes)
end
```

You can also use the root node ID or node directly, it will be cloned and used as a template:

```lua
self.my_widget = self.druid:new_widget(best_widget_in_the_world, "best_widget_in_the_world", "best_widget_in_the_world/root")
-- or
self.my_widget = self.druid:new_widget(best_widget_in_the_world, "best_widget_in_the_world", self.prefab)
```