diff --git a/druid/druid.lua b/druid/druid.lua index 31ac629..0003720 100644 --- a/druid/druid.lua +++ b/druid/druid.lua @@ -1,7 +1,12 @@ --- Druid UI Library. --- Component based UI library to make your life easier. --- Contains a lot of base components and give API --- to create your own rich components. +-- Powerful Defold component based UI library. Use standart +-- components or make your own game-specific to make amazing +-- GUI in your games. +-- +-- Contains the several basic components and examples +-- to how to do your custom complex components to +-- separate UI game logic to small files +-- -- @module druid local const = require("druid.const") @@ -13,47 +18,12 @@ local M = {} local log = settings.log ---- Basic components -M.components = { - button = require("druid.base.button"), - blocker = require("druid.base.blocker"), - back_handler = require("druid.base.back_handler"), - text = require("druid.base.text"), - locale = require("druid.base.locale"), - timer = require("druid.base.timer"), - progress = require("druid.base.progress"), - grid = require("druid.base.grid"), - scroll = require("druid.base.scroll"), - slider = require("druid.base.slider"), - checkbox = require("druid.base.checkbox"), - checkbox_group = require("druid.base.checkbox_group"), - radio_group = require("druid.base.radio_group"), - - -- TODO: - -- input - text input - -- infinity_scroll -- to handle big data scroll - - progress_rich = require("druid.rich.progress_rich"), - - -- TODO: Examples: - -- Slider menu like clash royale -} - - -local function register_basic_components() - for k, v in pairs(M.components) do - if not druid_instance["new_" .. k] then - M.register(k, v) - else - log("Basic component", k, "already registered") - end - end -end - - ---- Register external module +--- Register external druid component. +-- After register you can create the component with +-- druid_instance:new_{name}. For example `druid:new_button(...)` +-- @function druid:register -- @tparam string name module name --- @tparam table module lua table with module +-- @tparam table module lua table with component function M.register(name, module) -- TODO: Find better solution to creating elements? -- Possibly: druid.new(druid.BUTTON, etc?) @@ -66,23 +36,30 @@ function M.register(name, module) end ---- Create Druid instance for creating components --- @return instance with all ui components +--- Create Druid instance. +-- @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 function M.new(context, style) - if register_basic_components then - register_basic_components() - register_basic_components = false - end - return druid_instance(context, style) end +-- Set new default style. +-- @function druid.set_default_style +-- @tparam table style Druid style module function M.set_default_style(style) settings.default_style = style end +-- Set text function. +-- 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(callback) +-- @tparam function callback Get localized text function function M.set_text_function(callback) settings.get_text = callback or const.EMPTY_FUNCTION -- TODO: Update all localized text @@ -90,6 +67,11 @@ function M.set_text_function(callback) end +-- Set sound function. +-- Component will call this function to +-- play sound by sound_id +-- @function druid.set_sound_function +-- @tparam function callback Sound play callback function M.set_sound_function(callback) settings.play_sound = callback or const.EMPTY_FUNCTION end diff --git a/druid/system/druid_instance.lua b/druid/system/druid_instance.lua index e174852..b76b652 100644 --- a/druid/system/druid_instance.lua +++ b/druid/system/druid_instance.lua @@ -1,8 +1,43 @@ +--- Druid main class. Create instance of this +-- to start creating components +-- @module druid_instance +-- @see druid.button +-- @see druid.blocker +-- @see druid.back_handler +-- @see druid.text +-- @see druid.locale +-- @see druid.timer +-- @see druid.progress +-- @see druid.grid +-- @see druid.scroll +-- @see druid.slider +-- @see druid.checkbox +-- @see druid.checkbox_group +-- @see druid.radio_group + local const = require("druid.const") local druid_input = require("druid.helper.druid_input") local settings = require("druid.system.settings") local class = require("druid.system.middleclass") +local button = require("druid.base.button") +local blocker = require("druid.base.blocker") +local back_handler = require("druid.base.back_handler") +local text = require("druid.base.text") +local locale = require("druid.base.locale") +local timer = require("druid.base.timer") +local progress = require("druid.base.progress") +local grid = require("druid.base.grid") +local scroll = require("druid.base.scroll") +local slider = require("druid.base.slider") +local checkbox = require("druid.base.checkbox") +local checkbox_group = require("druid.base.checkbox_group") +local radio_group = require("druid.base.radio_group") +-- local input - require("druid.base.input") +-- local infinity_scroll = require("druid.base.infinity_scroll") +local progress_rich = require("druid.rich.progress_rich") + +-- @classmod Druid local Druid = class("druid.druid_instance") @@ -19,12 +54,9 @@ local function input_init(self) end --- Create the component +-- Create the component itself local function create(self, instance_class) - ---@class component local instance = instance_class() - - -- Component context, self from component creation instance:setup_component(self._context, self._style) self.components[const.ALL] = self.components[const.ALL] or {} @@ -75,7 +107,10 @@ local function match_event(action_id, events) end ---- Druid constructor +--- Druid class constructor +-- @function druid:initialize +-- @tparam context table Druid context. Usually it is self of script +-- @tparam style table Druid style module function Druid.initialize(self, context, style) self._context = context self._style = style or settings.default_style @@ -83,9 +118,12 @@ function Druid.initialize(self, context, style) end ---- Create new component inside druid instance -function Druid.create(self, instance_class, ...) - local instance = create(self, instance_class) +--- Create new druid component +-- @function druid:create +-- @tparam Component component Component module +-- @tparam args ... Other component params to pass it to component:init function +function Druid.create(self, component, ...) + local instance = create(self, component) if instance.init then instance:init(...) @@ -95,8 +133,10 @@ function Druid.create(self, instance_class, ...) end ---- Remove component from druid instance --- It will call on_remove on component, if exist +--- Remove component from druid instance. +-- Component `on_remove` function will be invoked, if exist. +-- @function druid:remove +-- @tparam Component component Component instance function Druid.remove(self, component) local all_components = self.components[const.ALL] for i = #all_components, 1, -1 do @@ -123,8 +163,9 @@ function Druid.remove(self, component) end ---- Druid instance update function --- @function druid:update(dt) +--- Druid update function +-- @function druid:update +-- @tparam number dt Delta time function Druid.update(self, dt) local components = self.components[const.ON_UPDATE] if components then @@ -135,8 +176,10 @@ function Druid.update(self, dt) end ---- Druid instance on_input function --- @function druid:on_input(action_id, action) +--- Druid on_input function +-- @function druid:on_input +-- @tparam hash action_id Action_id from on_input +-- @tparam table action Action from on_input function Druid.on_input(self, action_id, action) -- TODO: расписать отличия ON_SWIPE и ON_INPUT -- Почему-то некоторые используют ON_SWIPE, а логичнее ON_INPUT? (blocker, slider) @@ -168,8 +211,11 @@ function Druid.on_input(self, action_id, action) end ---- Druid instance on_message function --- @function druid:on_message(message_id, message, sender) +--- Druid on_message function +-- @function druid:on_message +-- @tparam hash message_id Message_id from on_message +-- @tparam table message Message from on_message +-- @tparam hash sender Sender from on_message function Druid.on_message(self, message_id, message, sender) local specific_ui_message = const.SPECIFIC_UI_MESSAGES[message_id] if specific_ui_message then @@ -189,4 +235,132 @@ function Druid.on_message(self, message_id, message, sender) end +--- Create button basic component +-- @function druid:new_button +-- @tparam args ... button init args +-- @treturn Component button component +function Druid.new_button(self, ...) + return Druid.create(self, button, ...) +end + + +--- Create blocker basic component +-- @function druid:new_blocker +-- @tparam args ... blocker init args +-- @treturn Component blocker component +function Druid.new_blocker(self, ...) + return Druid.create(self, blocker, ...) +end + + +--- Create back_handler basic component +-- @function druid:new_back_handler +-- @tparam args ... back_handler init args +-- @treturn Component back_handler component +function Druid.new_back_handler(self, ...) + return Druid.create(self, back_handler, ...) +end + + +--- Create text basic component +-- @function druid:new_text +-- @tparam args ... text init args +-- @treturn Component text component +function Druid.new_text(self, ...) + return Druid.create(self, text, ...) +end + + +--- Create locale basic component +-- @function druid:new_locale +-- @tparam args ... locale init args +-- @treturn Component locale component +function Druid.new_locale(self, ...) + return Druid.create(self, locale, ...) +end + + +--- Create timer basic component +-- @function druid:new_timer +-- @tparam args ... timer init args +-- @treturn Component timer component +function Druid.new_timer(self, ...) + return Druid.create(self, timer, ...) +end + + +--- Create progress basic component +-- @function druid:new_progress +-- @tparam args ... progress init args +-- @treturn Component progress component +function Druid.new_progress(self, ...) + return Druid.create(self, progress, ...) +end + + +--- Create grid basic component +-- @function druid:new_grid +-- @tparam args ... grid init args +-- @treturn Component grid component +function Druid.new_grid(self, ...) + return Druid.create(self, grid, ...) +end + + +--- Create scroll basic component +-- @function druid:new_scroll +-- @tparam args ... scroll init args +-- @treturn Component scroll component +function Druid.new_scroll(self, ...) + return Druid.create(self, scroll, ...) +end + + +--- Create slider basic component +-- @function druid:new_slider +-- @tparam args ... slider init args +-- @treturn Component slider component +function Druid.new_slider(self, ...) + return Druid.create(self, slider, ...) +end + + +--- Create checkbox basic component +-- @function druid:new_checkbox +-- @tparam args ... checkbox init args +-- @treturn Component checkbox component +function Druid.new_checkbox(self, ...) + return Druid.create(self, checkbox, ...) +end + + +--- Create checkbox_group basic component +-- @function druid:new_checkbox_group +-- @tparam args ... checkbox_group init args +-- @treturn Component checkbox_group component +function Druid.new_checkbox_group(self, ...) + return Druid.create(self, checkbox_group, ...) +end + + +--- Create radio_group basic component +-- @function druid:new_radio_group +-- @tparam args ... radio_group init args +-- @treturn Component radio_group component +function Druid.new_radio_group(self, ...) + return Druid.create(self, radio_group, ...) +end + + +--- Create progress_rich basic component +-- @function druid:new_progress_rich +-- @tparam args ... progress_rich init args +-- @treturn Component progress_rich component +function Druid.new_progress_rich(self, ...) + return Druid.create(self, progress_rich, ...) +end + + + + return Druid diff --git a/druid/system/settings.lua b/druid/system/settings.lua index 1ca7dbe..d7bdfcd 100644 --- a/druid/system/settings.lua +++ b/druid/system/settings.lua @@ -1,5 +1,6 @@ --- Druid settings file -- @module settings +-- @local local M = {}