From e14f68bc90fa82231bb2443e5a514978528cb591 Mon Sep 17 00:00:00 2001 From: Insality Date: Wed, 7 Jun 2023 00:41:05 +0300 Subject: [PATCH] Move swipe to extended, update docs --- README.md | 4 + druid/druid.lua | 127 +++++++++++++----- druid/{base => extended}/swipe.lua | 0 druid/system/druid_instance.lua | 50 ++++--- .../examples/general/swipe/swipe.gui_script | 4 +- 5 files changed, 135 insertions(+), 50 deletions(-) rename druid/{base => extended}/swipe.lua (100%) diff --git a/README.md b/README.md index ec35463..3471660 100644 --- a/README.md +++ b/README.md @@ -181,6 +181,10 @@ 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 diff --git a/druid/druid.lua b/druid/druid.lua index 44f13c6..3970fa5 100644 --- a/druid/druid.lua +++ b/druid/druid.lua @@ -1,20 +1,49 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license ---- Druid UI Library. --- Powerful Defold component based UI library. Use standart --- components or make your own game-specific components to --- make amazing GUI in your games. +--- Druid UI Component Framework. +-- # Overview # -- --- Contains the several basic components and examples --- to how to do your custom complex components to --- separate UI game logic to small files +-- Druid - powerful Defold component UI library. Use basic and extended +-- Druid components or make your own game-specific components to make +-- amazing GUI in your games. -- --- require("druid.druid") --- function init(self) --- self.druid = druid.new(self) --- end +-- To start use Druid, check the Basic Usage below. -- --- @module druid +-- # Tech Info # +-- +-- - Each Druid keeps the self context from constructor to pass it into each Druid callback +-- +-- See next: @{DruidInstance} +-- +-- @usage +-- local druid = require("druid.druid") +-- +-- local function button_callback(self) +-- print("Button was clicked!") +-- end +-- +-- function init(self) +-- self.druid = druid.new(self) +-- self.druid:new_button("button_node_name", button_callback) +-- 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 +-- +-- @module Druid local const = require("druid.const") local base_component = require("druid.component") @@ -38,12 +67,19 @@ local function get_druid_instances() end ---- Register external druid component. --- After register you can create the component with --- druid_instance:new_{name}. For example `druid:new_button(...)` --- @function druid:register +--- Register new external Druid component. +-- +-- You can register your own components to create it with druid:new_{name} function +-- For example, you can register your own component "my_component" and create it with druid:new_my_component(...) +-- @function druid.register -- @tparam string name module name -- @tparam table module lua table with component +-- @usage +-- local my_component = require("path.to.my.component") +-- druid.register("my_component", my_component) +-- ... +-- local druid = druid.new(self) +-- local component_instance = self.druid:new_my_component(...) function M.register(name, module) -- TODO: Find better solution to creating elements? -- Current way is very implicit @@ -53,11 +89,17 @@ function M.register(name, module) end ---- Create Druid instance. +--- Create new Druid instance to create GUI components. -- @function druid.new --- @tparam table context Druid context. Usually it is self of script --- @tparam[opt] table style Druid style module --- @treturn druid_instance Druid instance +-- @tparam table context Druid context. Usually it is *self* of *gui_script. It passes into all Druid callbacks +-- @tparam[opt] table style Druid style table to override style params for this Druid instance +-- @treturn druid_instance Druid instance @{DruidInstance} +-- @usage +-- local druid = require("druid.druid") +-- +-- function init(self) +-- self.druid = druid.new(self) +-- end function M.new(context, style) if settings.default_style == nil then M.set_default_style(default_style) @@ -69,40 +111,60 @@ function M.new(context, style) end ---- Set new default style. +--- Set your own default style for all Druid instances. +-- +-- To create your own style file, copy the default style file and change it. +-- Register new style before your Druid instances creation. -- @function druid.set_default_style -- @tparam table style Druid style module +-- @usage +-- local my_style = require("path.to.my.style") +-- druid.set_default_style(my_style) function M.set_default_style(style) settings.default_style = style or {} end ---- Set text function --- Druid locale component will call this function --- to get translated text. After set_text_funtion +--- Set text function for LangText component. +-- +-- Druid locale component will call this function to get translated text. After set_text_funtion -- all existing locale component will be updated -- @function druid.set_text_function -- @tparam function callback Get localized text function +-- @usage +-- druid.set_text_function(function(text_id) +-- return lang_data[text_id] -- Replace with your real function +-- end) function M.set_text_function(callback) settings.get_text = callback or const.EMPTY_FUNCTION M.on_language_change() end ---- Set sound function. --- Component will call this function to --- play sound by sound_id +--- Set Druid sound function to play UI sounds if used. +-- +-- Set function to play sound by sound_id. It used in Button click and play "click" sound. +-- Also can be used by play sound in your custom components (see default Druid style file for example) -- @function druid.set_sound_function -- @tparam function callback Sound play callback +-- @usage +-- druid.set_sound_function(function(sound_id) +-- sound.play(sound_id) -- Replace with your real function +-- end) function M.set_sound_function(callback) settings.play_sound = callback or const.EMPTY_FUNCTION end ---- Callback on global window event. --- Used to trigger on_focus_lost and on_focus_gain +--- Set window callback to enable *on_focus_gain* and *on_focus_lost* functions. +-- +-- Used to trigger on_focus_lost and on_focus_gain in Druid components -- @function druid.on_window_callback -- @tparam string event Event param from window listener +-- @usage +-- window.set_listener(function(_, event) +-- druid.on_window_callback(event) +-- end) function M.on_window_callback(event) local instances = get_druid_instances() @@ -126,9 +188,12 @@ function M.on_window_callback(event) end ---- Callback on global language change event. --- Use to update all lang texts +--- Call this on game language change. +-- +-- This function will update all LangText components -- @function druid.on_language_change +-- @usage +-- druid.on_language_change() function M.on_language_change() local instances = get_druid_instances() diff --git a/druid/base/swipe.lua b/druid/extended/swipe.lua similarity index 100% rename from druid/base/swipe.lua rename to druid/extended/swipe.lua diff --git a/druid/system/druid_instance.lua b/druid/system/druid_instance.lua index a4004d4..be43e0d 100755 --- a/druid/system/druid_instance.lua +++ b/druid/system/druid_instance.lua @@ -1,14 +1,28 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license ---- Instance of Druid. Make one instance per gui_script with next code: +--- Druid Instance which you use for component creation. -- --- local druid = require("druid.druid") --- function init(self) --- self.druid = druid.new(self) --- local button = self.druid:new_button(...) --- end +-- # Component List # +-- +-- See all component list in "See Also" section. +-- @usage +-- local druid = require("druid.druid") +-- +-- local function close_window(self) +-- print("WOW, you closed the game!") +-- end +-- +-- function init(self) +-- self.druid = druid.new(self) +-- +-- -- Call all druid instance function with ":" syntax: +-- local text = self.druid:new_text("text_header", "Hello Druid!") +-- local button = self.druid:new_button("button_close", close_window) +-- +-- -- You not need to save component reference if not need it +-- self.druid:new_back_handler(close_window) +-- end -- --- Learn Druid instance function here -- @module DruidInstance -- @alias druid_instance -- @see Button @@ -46,7 +60,6 @@ local drag = require("druid.base.drag") local hover = require("druid.base.hover") local scroll = require("druid.base.scroll") local static_grid = require("druid.base.static_grid") -local swipe = require("druid.base.swipe") local text = require("druid.base.text") -- To use this components, you should register them first @@ -60,6 +73,7 @@ local text = require("druid.base.text") -- local slider = require("druid.extended.slider") -- local timer_component = require("druid.extended.timer") -- local data_list = require("druid.extended.data_list") +-- local swipe = require("druid.extended.swipe") local DruidInstance = class("druid.druid_instance") @@ -621,16 +635,6 @@ function DruidInstance.new_scroll(self, view_node, content_node) end ---- Create swipe basic component --- @tparam DruidInstance self --- @tparam node node Gui node --- @tparam function on_swipe_callback Swipe callback for on_swipe_end event --- @treturn Swipe swipe component -function DruidInstance.new_swipe(self, node, on_swipe_callback) - return DruidInstance.new(self, swipe, node, on_swipe_callback) -end - - --- Create drag basic component -- @tparam DruidInstance self -- @tparam node node GUI node to detect dragging @@ -641,6 +645,16 @@ function DruidInstance.new_drag(self, node, on_drag_callback) end +--- Create swipe basic component +-- @tparam DruidInstance self +-- @tparam node node Gui node +-- @tparam function on_swipe_callback Swipe callback for on_swipe_end event +-- @treturn Swipe swipe component +function DruidInstance.new_swipe(self, node, on_swipe_callback) + return helper.extended_component("swipe") +end + + --- Create dynamic grid component -- @tparam DruidInstance self -- @tparam node parent The gui node parent, where items will be placed diff --git a/example/examples/general/swipe/swipe.gui_script b/example/examples/general/swipe/swipe.gui_script index 074d80d..508bafc 100644 --- a/example/examples/general/swipe/swipe.gui_script +++ b/example/examples/general/swipe/swipe.gui_script @@ -1,5 +1,7 @@ local druid = require("druid.druid") +local Swipe = require("druid.extended.swipe") + local function on_swipe_callback(self, direction, distance, swipe_time) self.text:set_to(direction) @@ -11,7 +13,7 @@ function init(self) self.druid = druid.new(self) self.text = self.druid:new_text("text_value") - self.swipe = self.druid:new_swipe("swipe_node", on_swipe_callback) + self.swipe = self.druid:new(Swipe, "swipe_node", on_swipe_callback) end