add new apis and samples

README.md

@@ -26,8 +26,8 @@ The type of script is determined by the line (meta tag) at the beginning of the
 * 4.4.2 - added `fmt` and `html` utility modules;
 * 4.4.4 - added `tasker` module;
 * 4.4.6 - added `csv` module;
-* 4.4.7 - added `intent` module and `system:send_message` function;
+* 4.4.7 - added `intent` module;
-* 4.5.0 - added `system:get_currency()` and `ui:show_list_dialog()`.
+* 4.5.0 - the `aio` module has been significantly expanded, also added `system:get_currency()` and `ui:show_list_dialog()`.
 
 # Widget scripts
 
@@ -190,13 +190,10 @@ When you click on any menu item, the collback `on_context_menu_click(idx)` will
 * `system:get_tz_offset()` - returns TimeZone offset in seconds;
 * `system:get_currency()` - returns default currency code based on locale;
 * `system:get_battery_info()` - returns table with battery info;
-* `system:get_system_info()` - returns table with system info;
+* `system:get_system_info()` - returns table with system info.
-* `system:send_message(value, [script_name])` - sends lua value to other script or scripts (_avaialble from: 4.4.7_).
 
 The result of executing a shell command is sent to the `on_shell_result(string)` callback.
 
-To accept a value sent by the `send_message` function, the receiving script must implement a callback `on_message(value)`.
-
 ## Intens
 
 * `intent:start_activity(table)` - starts activity with intent described in the table;
@@ -214,10 +211,42 @@ Intent table format (all fields are optional):
 
 ## Launcher control
 
-* `aio:do_action(string)` - performs an AIO action ([more](https://aiolauncher.app/api.html));
+* `aio:get_available_widgets()` - returns a table with the metadata of all widgets, scripts and plugins available for adding to the screen (_available from: 4.5.0_);
-* `aio:add_widget(string)` - adds an aio widget, script widget or clone of an existing widget to the screen;
+* `aio:get_active_widgets()` - returns a table with the metadata of all widgets, scripts, and plugins already added to the screen (_available from: 4.5.0_);
-* `aio:remove_widget(string)` - removes the widget from the screen (note: clones will also be removed);
+* `aio:add_widget(string, [position])` - adds a builtin widget, script widget or clone of an existing widget to the screen;
+* `aio:remove_widget(string)` - removes the widget from the screen (instead of the name you can also pass the widget number or do not pass anything - then the current widget will be deleted);
+* `aio:move_widget(string, position)` - moves the widget to a new position (you can also use the widget position instead of the name) (_available from: 4.5.0_);
+* `aio:fold_widget(string, [boolean])` - fold/unfold widget (if you do not specify the second argument the state will be switched) (_available from: 4.5.0_);
 * `aio:is_widget_added(string)` - checks if the widget is added to the screen;
+* `aio:get_self_name()` - returns current script file name (_available from: 4.5.0_);
+* `aio:do_action(string)` - performs an AIO action ([more](https://aiolauncher.app/api.html));
+* `aio:send_message(value, [script_name])` - sends lua value to other script or scripts (_avaialble from: 4.5.0_).
+
+Format of table elements returned by `aio:get_available_widgets()`:
+
+* `name` - internal name of the widget;
+* `type` - widget type: `builtin`, `script` or `plugin`;
+* `description` - widget description (usually empty for non-script widgets);
+* `clonable` - true if the widget can have clones (examples: "My apps", "Contacts", "Mailbox" widgets);
+* `enabled` - true if the widget is placed on the screen.
+
+Format of table elements returned by `aio:get_active_widgets()`:
+
+* `name` - internal name of the widget;
+* `position` - position on the screen;
+* `folded` - true if widget is folded.
+
+To accept a value sent by the `send_message` function, the receiving script must implement a callback `on_message(value)`.
+
+The script can track screen operations such as adding, removing or moving a widget with the `on_widget_action()` callback. For example:
+
+```
+function on_widget_action(action, name)
+    ui:show_toast(name..." action)
+end
+```
+
+This function will be called on add, remove or move any widget.
 
 ## Application management
 

samples/msg-sender.lua

@@ -8,10 +8,10 @@ end
 
 function on_click(idx)
     if idx == 1 then
-        system:send_message("text", "msg-receiver.lua")
+        aio:send_message("text", "msg-receiver.lua")
     elseif idx == 2 then
-        system:send_message(1)
+        aio:send_message(1)
     else
-        system:send_message{ "one", "two", "three" }
+        aio:send_message{ "one", "two", "three" }
     end
 end

samples/screen-state-widget.lua

@@ -0,0 +1,48 @@
+-- name = "Screen state"
+
+local json = require "json"
+
+function on_resume()
+    ui:show_buttons{
+        "Save screen",
+        "Restore screen",
+    }
+end
+
+function on_click(idx)
+    if idx == 1 then
+        save_state()
+    else
+        restore_state()
+    end
+end
+
+function save_state()
+    local state = aio:get_active_widgets()
+    local json_str = json.encode(state)
+
+    files:write("screen-state", json_str)
+    ui:show_toast("Screen state saved!")
+end
+
+function restore_state()
+    local json_str = files:read("screen-state")
+    local state = json.decode(json_str)
+
+    remove_all_widgets()
+
+    for k,v in pairs(state) do
+        aio:add_widget(v.name, v.position)
+    end
+
+    ui:show_toast("Screen state restored!")
+end
+
+function remove_all_widgets()
+    local curr_state = aio:get_active_widgets()
+    for k,v in pairs(curr_state) do
+        if (v.name ~= "screen-state-widget.lua") then
+            aio:remove_widget(v.position)
+        end
+    end
+end

samples/widget_add_remove_sample.lua

@@ -1,11 +1,26 @@
 function on_resume()
-    ui:show_buttons({ "Add clock widget", "Remove clock widget" })
+    ui:show_lines{
+        "Add clock widget",
+        "Add clock widget (position 1)",
+        "Add clock widget (position 5)",
+        "Remove clock widget",
+        "Swap first and third widgets",
+        "Swap back",
+    }
 end
 
 function on_click(idx)
     if idx == 1 then
         aio:add_widget("clock")
-    else
+    elseif idx == 2 then
+        aio:add_widget("clock", 1)
+    elseif idx == 3 then
+        aio:add_widget("clock", 5)
+    elseif idx == 4 then
         aio:remove_widget("clock")
+    elseif idx == 5 then
+        aio:move_widget(1, 3)
+    elseif idx == 6 then
+        aio:move_widget(3, 1)
     end
 end

samples/widgets-sample.lua

@@ -0,0 +1,28 @@
+local fmt = require "fmt"
+
+function on_resume()
+    local widgets = aio:get_active_widgets()
+    local tab = {}
+
+    for k,v in pairs(widgets) do
+        table.insert(tab, { fmt.bold(v.name), "(un)fold", "remove" })
+    end
+
+    ui:show_table(tab)
+end
+
+function on_click(idx)
+    local widget_num = math.ceil(idx / 3)
+    local action = idx % 3
+
+    if action == 0 then
+        aio:remove_widget(widget_num)
+    elseif action == 2 then
+        aio:fold_widget(widget_num)
+    end
+end
+
+function on_widget_action(action, name)
+    ui:show_toast(name.." "..action)
+    on_resume()
+end

samples/widgets-sample2.lua

@@ -0,0 +1,13 @@
+local fmt = require "fmt"
+
+function on_resume()
+    local widgets = aio:get_available_widgets()
+    local tab = {}
+
+    for k,v in pairs(widgets) do
+        table.insert(tab, { fmt.bold(v.name), v.type })
+    end
+
+    ui:show_table(tab)
+end
+