diff --git a/README.md b/README.md index 0bf2aa6..0b8def0 100644 --- a/README.md +++ b/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.5.0 - added `system:get_currency()` and `ui:show_list_dialog()`. +* 4.4.7 - added `intent` module; +* 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:send_message(value, [script_name])` - sends lua value to other script or scripts (_avaialble from: 4.4.7_). +* `system:get_system_info()` - returns table with system info. 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:add_widget(string)` - adds an aio widget, script widget or clone of an existing widget to the screen; -* `aio:remove_widget(string)` - removes the widget from the screen (note: clones will also be removed); +* `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: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: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 diff --git a/samples/msg-sender.lua b/samples/msg-sender.lua index 820b73b..a318594 100644 --- a/samples/msg-sender.lua +++ b/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 diff --git a/samples/screen-state-widget.lua b/samples/screen-state-widget.lua new file mode 100644 index 0000000..5a3ec96 --- /dev/null +++ b/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 diff --git a/samples/widget_add_remove_sample.lua b/samples/widget_add_remove_sample.lua index e56921c..d22b200 100644 --- a/samples/widget_add_remove_sample.lua +++ b/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 diff --git a/samples/widgets-sample.lua b/samples/widgets-sample.lua new file mode 100644 index 0000000..a4b5e1e --- /dev/null +++ b/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 diff --git a/samples/widgets-sample2.lua b/samples/widgets-sample2.lua new file mode 100644 index 0000000..ad9182a --- /dev/null +++ b/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 +