docs: improve docs ui

examples/asteroids/game.lua

@@ -243,7 +243,7 @@ local function loop(std, game)
                 game.graphics_fastest = std.math.clamp(game.graphics_fastest + keyh, 0, 1)
                 game.fps_max = 100
             elseif game.menu == 7 then
-                std.i18n.next_language()
+                std.i18n.next()
             elseif game.menu == 8 then
                 game.state = 2
             elseif game.menu == 9 then

examples/fellow7/game.lua

@@ -0,0 +1,45 @@
+local App = {
+    title = 'Grid System',
+    author = '',
+    version = '1.0.0',
+    require = 'math',
+    assets = {
+        './assets/icon80x80.png:icon80x80.png'
+    }
+}
+
+local Widget = {
+    draw = function(std, data)
+        std.draw.image('icon80x80.png')
+    end
+}
+
+function App.key(std, data)
+    data.slider:next(std.key.axis.x):apply()
+end
+
+function App.load(std, data)
+    std.ui.style('selected')
+        :pos_y(function(std, node)
+            return node.config.offset_y - 100
+        end)
+
+    std.ui.style('home')
+        :height(200)
+        :pos_y(function(std, node, parent)
+            return parent.data.height - node.data.height
+        end)
+
+    data.slider = std.ui.slide('6x1')
+        :style_item_select('selected')
+        :style('home')
+        :add(Widget)
+        :add(Widget)
+        :add(Widget)
+        :add(Widget)
+        :add(Widget)
+        :add(Widget)
+        :apply()
+end
+
+return App

src/lib/engine/api/i18n.lua

@@ -100,38 +100,39 @@ local function set_language(l)
     end
 end
 
+--! @renamefunc next
+--! @hideparam to
 --! @par Example
 --! @code
---! if game.state == game.menu_lang and std.key.press.left then
---!     std.i18n.back_language()
+--! if game.state == game.menu_lang then
+--!     std.i18n.next(std.key.axis.y)
 --! end
 --! @endcode
-local function back_language()
+local function next_language(to)
     local index = language_inverse_list[language]
+    local incr = to or 1
     if index then
-        if index <= 1 then
-            index = #language_list + 1
+        index = index + incr
+        if index > #language_list then
+            index = 1
+        end
+        if index <= 0 then
+            index = #language_list
         end
-        index = index - 1
+        index = index == 0 and 1 or index
         set_language(language_list[index])
     end
 end
 
+--! @renamefunc back
 --! @par Example
 --! @code
---! if game.state == game.menu_lang and std.key.press.right then
---!     std.i18n.next_language()
+--! if game.state == game.menu_lang and std.key.press.left then
+--!     std.i18n.back()
 --! end
 --! @endcode
-local function next_language()
-    local index = language_inverse_list[language]
-    if index then
-        if index >= #language_list then
-            index = 0
-        end
-        index = index + 1
-        set_language(language_list[index])
-    end
+local function back_language()
+    next_language(-1)
 end
 
 --! @}

src/lib/engine/draw/ui/common.lua

@@ -46,7 +46,8 @@ local function get_item(self, id)
     return self.items_node[id]
 end
 
---! @renamefunc style
+--! @hideparam classkey
+--! @hideparam self
 local function style(classkey, self, classlist)
     self[classkey] = classlist
     return self

src/lib/engine/draw/ui/grid.lua

@@ -46,6 +46,7 @@ local util_decorator = require('src/lib/util/decorator')
 --!     :add(btn1)
 --!     :add(btn2)
 --!     :add(btn3)
+--!     :apply()
 --! @endcode
 --!
 --! @par Columns
@@ -93,6 +94,7 @@ local util_decorator = require('src/lib/util/decorator')
 --!      :add(std.ui.grid('1x1')
 --!         :add(btn)
 --!      )
+--!     :apply()
 --! @endcode
 --! @}
 --! @}

src/lib/engine/draw/ui/slide.lua

@@ -1,6 +1,30 @@
 local ui_common = require('src/lib/engine/draw/ui/common')
 local util_decorator = require('src/lib/util/decorator')
 
+--! @defgroup std
+--! @{
+--! @defgroup ui
+--! @{
+--!
+--! @page ui_slide Slide System
+--! @details
+--! also known as carousel, it has similar behavior to grid but with visual selection of items.
+--! but it only accepts one-dimensional grids such as @c 1x1 @c 2x1 or @c 1x2 .
+--! @par Example
+--! @code{.java}
+--! std.ui.slide('6x1')
+--!     :add_items(my_items)
+--!     :apply()
+--! @endcode
+
+--! @renamefunc next
+--! @hideparam self
+--! @hideparam to
+--! @pre avaliable only in the @c std.ui.slide
+--! @par Example
+--! @code{.java}
+--! std.ui.slide('6x1'):add_items(items):next(2):apply()
+--! @endcode
 local function slider_next(self, to)
     local incr = to or 1
     self.index = self.index + incr
@@ -13,10 +37,20 @@ local function slider_next(self, to)
     return self
 end
 
+--! @renamefunc back
+--! @hideparam self
+--! @pre avaliable only in the @c std.ui.slide
+--! @par Example
+--! @code{.java}
+--! std.ui.slide('1x6'):add_items(items):back():apply()
+--! @endcode
 local function slider_back(self)
     return slider_next(self, -1)
 end
 
+--! @}
+--! @}
+
 --! @hideparam std
 --! @hideparam engine
 local function apply(std, engine, self)

src/lib/engine/draw/ui/style.lua

@@ -3,6 +3,48 @@ local style = {
     dict = {}
 }
 
+--! @defgroup std
+--! @{
+--! @defgroup ui
+--! @{
+--!
+--! @page ui_style Style
+--! @details
+--! there is a css style componetization style,
+--! you define the name of a class and define fixed attributes or you can pass functions.
+--!
+--! @par Attributes
+--!
+--! @li @b pos_x
+--! @li @b pos_y
+--! @li @b width
+--! @li @b height
+--!
+--! @par Example
+--! @code{.java}
+--! std.ui.style('home')
+--!     :height(300)
+--!     :pos_y(function(std, node, parent)
+--!         return parent.data.height - 300
+--!     end)
+--! @endcode
+--! @code{.java}
+--! std.ui.style('center')
+--!     :pos_x(function(std, node, parent)
+--!         return parent.data.width/2 - node.data.width/2
+--!     end)
+--! @endcode
+--! @code{.java}
+--! std.ui.grid('3x1')
+--!     :style('center home')
+--!     :add(item1)
+--!     :add({})
+--!     :add(item2)
+--! @endcode
+--!
+--! @}
+--! @}
+
 local function decorate_style(namespace, attribute)
     return function(self, value)
         self.pipeline[#self.pipeline + 1] = function(std, node, parent, root)