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:

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:

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 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. You can use the Druid's editor script to create a widget by right-clicking on the GUI file in the editor or in "Edit" menu panel, while GUI file is opened.

Define init function to initialize the widget.

Here's a basic widget example:

---@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:

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:

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:

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:

self.my_widget = self.druid:new_widget(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)