diff --git a/README_ru.md b/README_ru.md deleted file mode 100644 index 3fbec41..0000000 --- a/README_ru.md +++ /dev/null @@ -1,341 +0,0 @@ -# Введение - -Начиная с версии 4.0, AIO Launcher поддерживает скрипты, а точнее специальные виджеты, написанные на скриптовом языке [Lua](https://en.wikipedia.org/wiki/Lua_(programming_language)). Такие виджеты следует размещать в каталоге `/sdcard/Android/data/ru.execbit.aiolauncher/files/`. Затем их можно добавить на экран используя раздел настроек "Скрипты" или с помощью бокового меню. - -С помощью скриптов можно практически безгранично расширять функциональность приложения (смотрите примеры в этом репозитории). - -# Изменения - -* 4.0.0 - первая версия с поддержкой скриптов; -* 4.1.0 - добавлены модули `weather` и `cloud`; -* 4.1.3 - добавлены модули `notify`, `files` и `utils`. - -# Функции (колбеки) жизненного цикла - -Работа любого скрипта-виджета начинается с одной из трех описанных функций. Именно внутри них следует выполнять основную работу и выводить на экран данные. - -* `on_resume()` - вызывается при каждом возврате на рабочий стол; -* `on_alarm()` - вызывается при возврате на рабочий стол при условии, что с прошлого вызова прошло больше 30 минут; -* `on_tick()` - вызывается каждую секунду пока лаунчер находится на экране. - -Для большинства сетевых скриптов (загрузка и показ значений) следует использовать `on_alarm()`. Использование других функций может привести к блокировке вашего IP. - -# Функции показа данных - -* `ui:show_text(string, [no_html])` - выводит в виджет обычный текст, повторный вызов стирает предыдущий текст, если второй аргумент true форматирование HTML будет отключено; -* `ui:show_lines(table, [table])` - выводит список строк с отправителем (на манер почтового виджета), второй аргумент (необязательный) - соответствующие им отправители (форматирование в стиле почтового виджета); -* `ui:show_table(table, [main_column], [centering], [folded_string])` - выводит таблицу, первый аргумент: таблица таблиц, второй аргумент - основная колонка, она будет растягиваться, занимая основное пространство таблицы (если аргумент равен нулю или не указан будут равномерно растягиваться все элементы таблицы), третий - булево значение, указывающее, нужно ли центрировать ячейки таблицы, четвертый - строка, которая будет показана в свернутом режиме; -* `ui:show_buttons(names, [colors])` - выводит список кнопок, первый аргумент - таблица строк, второй опциональный аргумент, таблица цветов в формате #XXXXXX; -* `ui:show_progress_bar(text, current_value, max_value, [color])` - показывает прогресс бар; -* `ui:show_chart(points, [format], [title], [show_grid], [folded_string], [copyright])` - показывает график, points - таблица таблиц координат, format - формат данных (см. ниже), title - название графика, show\_grid - флага показа сетки, folded\_string - строка для свернутого состояния (иначе будет показано название), copyright - строка, отображаемая в правом нижнем углу; -* `ui:show_toast(string)` - показывает информационное сообщение в стиле Android; -* `ui:get_default_title()` - возвращает стандартный заголовок виджета (задается в метаданных `name`); -* `ui:set_title()` - изменяет заголовок виджета, функцию следует вызывать до функции отображения данных (пустая строка - сброс до стандартного заголовка); -* `ui:set_folding_flag(boolean)` - устанавливает или снимает флаг свернутого режима виджета, функцию следует вызывать до функций отображения данных; -* `ui:get_folding_flag()` - возвращает флаг свернутого режима -* `ui:get_colors()` - возвращает таблицу текущих цветов темы; - -При нажатии на любой элемент интерфейса будет выполнен колбек `on_click(number)`, где number - это порядковый номер элемента. Долгое нажатие вызывает `on_long_click(number)`. Например, если вы используете `ui:show_buttons` для показа трех кнопок, то при нажатии первой кнопки будет вызван `on_click` с аргументом 1, второй - с аргументов 2, и так далее. Если элемент на экране всего один - аргумент всегда будет равен единице и его можно будет опустить. - -Функция `ui:show_chart()` в качестве третьего аргумента принимает строку, задающую форматирование значений x и y на экране. Например, строка `x:date y:number` означает, что значения по оси X необходимо отформатировать как даты, а значения по оси Y - как обычное число. Всего существует четыре формата: - -* `number` - обычное число с разделением групп; -* `float` - то же самое, но с двумя знаками после запятой; -* `date` - дата в формате день.месяц; -* `time` - время в формате часы:минуты. - -Функции `ui:show_text()` и `ui:show_lines()` поддерживают многие теги HTML. Например: - -``` -First line
Second line -Bold Line
Oblique Line -Red text -Text on green background -``` - -Функция `ui:show_buttons()` поддерживает иконки Fontawesome. Просто укажите в качестве имени кнопки `fa:имя_иконки`, например: `fa:play`. - -# Диалоги - -* `ui:show_dialog(title, text, [button1_text], [button2_text])` - показать диалог; первый аргумент - заголовок, второй - текст, button1\_text - имя первой кнопки, button2\_text - имя второй кнопки; -* `ui:show_edit_dialog(title, [text], [default_value])` - показать диалог с полем ввода: title - заголовок, text - подпись, default\_value - стандартное значения поля ввода; -* `ui:show_radio_dialog(title, lines, [index])` - показать диалог с выбором: title - заголовок, lines - таблица строк, index - индекс дефолтового значения; -* `ui:show_checkbox_dialog(title, lines, [table])` - показать диалог с выбором нескольких элементов: title - заголовок, lines - таблица строк, table - таблица дефолтовых значений. - -Нажатия на кнопки диалога должны обрабатываться в колбеке `on_dialog_action(number)`, где 1 - это первая кнопка, 2 - вторая, а -1 - нажатие кнопки "закрыть" или "назад". `ui:show_radio_dialog()` возвращает индекс выбранного элемента или -1 в случае нажатия кнопки "Отмена". `ui:show_checkbox_dialog()` возвращает таблицу индексов или -1. `ui:show_edit_dialog()` возвращает текст. - -Если первый аргумент диалога содержит две строки, разделенных знаком `\n`, вторая строка станет подзаголовком. - -# Контекстное меню - -* `ui:show_context_menu(table)` - функция показывает контекстное меню. В качестве аргумента функция принимает таблицу таблиц с иконками и названиями элементов меню. Например, следующий код подготовит контекстное меню из трех элементов: - -``` -ui:show_context_menu({ - { "share", "Menu item 1" }, - { "copy", "Menu item 2" }, - { "trash", "Menu item 3" }, -}) -``` - -Здесь `share`, `copy` и `trash` - это названия иконок, которое можно узнать на сайте [Fontawesome](https://fontawesome.com/). - -При нажатии на любой элемент меню будет вызван колбек `on_context_menu_click(item_idx)`, где `item_idx` - это индекс элемента меню. - -# Системные функции - -* `system:open_browser(url)` - открывает указанный URL в браузере или в приложении, умеющем обрабатывать данный тип URL; -* `system:exec(string)` - выполняет shell-команду; -* `system:su(string)` - выполняет shell-команду от имени root; -* `system:get_location()` - возвращает местоположение в таблице с двумя значениями (запрос местоположения НЕ выполняется, используется значение, сохраненное системой ранее); -* `system:copy_to_clipboard(string)` - копирует строку в буфер обмена; -* `system:get_from_clipboard()` - возвращает строку из буфера обмена: -* `system:share_text(string)` - открывает системный диалог "Поделиться"; -* `system:vibrate(milliseconds)` - вибрация; -* `system:alarm_sound(seconds)` - издать звук будильника; -* `system:get_lang()` - возвращает выбранный в системе язык; -* `system:get_tz_offset()` - возвращает time zone offset в секундах. -* `system:get_battery_info()` - возвращает таблицу с информацией о состоянии батареи; -* `system:get_system_info()` - возвращает таблицу с различной системной информацией. - -Результат выполнения shell-команды приходит в колбек `on_shell_result(string)`. - -# Управление лаунчером - -* `aio:do_action(string)` - выполняет действие AIO ([подробнее](https://aiolauncher.app/api.html)); -* `aio:add_widget(string)` - добавляет на экран встроенный виджет, виджет-скрипт или клон существующего виджета; -* `aio:remove_widget(string)` - удаляет с экрана встроенный виджет или виджет-скрипт (внимание: доп. виджеты тоже будут удалены); -* `aio:is_widget_added(string)` - проверяет, добавлен ли виджет на экран; - -# Управление приложениями - -* `apps:get_list([sort_by], [no_hidden])` - возвращает таблицу пакетов всех установленных приложений, `sort_by` - вариант сортировки (см. ниже), `no_hidden` - true, если скрытые приложения не нужны; -* `apps:get_name(package)` - возвращает имя приложения; -* `apps:get_color(package)` - возвращает цвет приложения в формате #XXXXXX; -* `apps:launch(package)` - запускает приложение; -* `apps:show_edit_dialog(package)` - показывает диалог редактирования приложения. - -Варианты сортировки: - -* `abc` - по алфавиту (по умолчанию); -* `launch_count` - по количеству запусков; -* `launch_time` - по времени запуска; -* `install_time` - по времени установки. - -При любых событиях, связанных с приложениями (установка, удаление, изменение имени и т.д.), будет вызван колбек `on_apps_changed()`. - -# Сетевые функции - -* `http:get(url, [id])` - выполняет запрос HTTP GET, id - строка-идентификатор запрос (см. ниже); -* `http:post(url, body, media_type, [id])` - выполняет запрос HTTP POST; -* `http:put(url, body, media_type, [id])` - выполняет запрос HTTP; -* `http:delete(url, [id])` - выполняет запрос HTTP DELETE; -* `http:set_headers(table)` - устанавливает заголовки для **всех** последующих сетевых запросов; аргумент - таблица со строками типа "Cache-Control: no-cache". - -Эти функции не возвращают никакого значения, а вместо этого вызывают колбек `on_network_result(string, [code])`. Первый аргумент: тело ответа, второй (опциональный) - код (200, 404 и т.д.). - -Если в запросе был указан `id`, то функция вместо описанного выше колбека вызовет `on_network_result_$id(string, [code])`. То есть если id равен "server1", то колбек будет иметь вид `on_network_result_server1(string, [code])`. - -# Календарь - -* `calendar:get_events([start_date], [end_date], [cal_table])` - возвращает таблицу табдлиц событий всех календарей, start\_date - дата начала событий, end\_date - дата окончания событий, cal\_table - таблица идентификаторов календарей; -* `calendar:get_calendars()` - возвращет таблицу таблиц календарей; -* `calendar:show_event_dialog(id)` - открывает событие в системном календаре. - -Формат таблицы события: - -* `id` - идентификатор события; -* `calendar_id` - идентификатор календаря; -* `title` - заголовок события; -* `description` - описание события; -* `location` - адрес события строкой; -* `begin` - время начала события (в секундах); -* `end` - время конца события (в секундах); -* `all_day` - булево значение, означающее, что событие длится весь день. - -Формат таблицы календаря: - -* `id` - идентификатор календаря; -* `name` - название календаря; -* `color` - цвет календаря в фолрмате #XXXXXX. - -# Телефон - -* `phone:get_contacts()` - возвращает таблицу телефонных контактов; -* `phone:make_call(number)` - набрать номер в диалере; -* `phone:send_sms(number, [text])` - открыть приложение СМС и ввети номер, опционально ввести текст; -* `phone:show_contact_dialog(id)` - показать диалог контакта; - -Формат таблицы контактов: - -* `id` - ID контакта; -* `lookup_key` - уникальный идентификтор контакта; -* `name` - имя контакта; -* `number` - номер контакта. - -# Погода - -* `weather:get_by_hour()` - выполняет запрос почасовой погоды. - -Функция возвращает данные о погоде в колбеке `on_weather_result(result)`, где `result` - это таблица таблиц со следующими полями: - -* `time` - время в секундах; -* `temp` - температура; -* `icon_code` - код иконки погоды; -* `humidity` - влажность; -* `wind_speed` - скорость ветра; -* `wind_direction` - направление ветра. - -# Облако - -* `cloud:get_metadata(path)` - возвращает таблицу с метаданными файла; -* `cloud:get_file(path)` - возвращает содержимое файла; -* `cloud:put_file(sting, path)` - записывает строку в файл; -* `cloud:remove_file(path)` - удаляет файл; -* `cloud:list_dir(path)` - возвращает таблицу таблиц метаданных всех файлов и подкаталогов; -* `cloud:create_dir(path)` - создает каталог; - -Все данные возвращаются в `on_cloud_result(meta, content)`. Первый аргумент - это метаданные, либо таблица метаданных (в случае с `list_dir()`), либо строка с сообщением об ошибке. Второй аргумент - содержимое файла (в случае `get_file()`). - -# Уведомления - -* `notify:get_current()` - запрашивает у лаунчера текущие уведомления; -* `notify:open(key)` - открывает уведомление с указанным key; -* `notify:close(key)` - смахивает уведомление с указанным key; - -Функция `notify:get_current()` запрашивает все текущие уведомления. Лаунчер возвращает их поочередно в колбек `on_notify_posted(table)`, где table - это таблица, олицетворяющая уведомление. Тот же колбек будет вызван когда появится новое уведомление. При закрытии уведомления будет вызван колбек `on_notify_removed(table)`. - -Формат таблицы-уведомления: - -* `key` - уникальный ключ, однозначно идентифицирующий уведомление; -* `time` - время публикации уведомления в секундах; -* `package` - имя пакета приложения, отправившего уведомление; -* `number` - цифра на бейдже уведомления, если есть; -* `importance` - уровень важности уведомления: от 1 (низкий) до 4 (высокий), 3 - стандартный; -* `category` - категория уведомления, например `email`; -* `title` - заголовок уведомления; -* `text` - текст уведомления; -* `sub_text` - дополнительный текст уведомления; -* `big_text` - текст развернутого уведомления; -* `is_clearable` - true, если уведомление смахиваемое; -* `group_id` - ID группы уведомлений. - -Имейте ввиду, что стандартный виджет уведомлений AIO также делает вызов `get_current()` при каждом возврате на рабочий стол, а это значит, что при наличии виджета уведомлений все скрипты также будут получать информацию об уведомлениях в колбек `on_notify_posted()` при каждом возврате на рабочий стол. - -# Файлы - -* `files:read(file)` - возвращает содержимое файла или `nil` если файла не существует; -* `files:write(file, string)` - записывает строку `string` в файл (создает файл если его не существует); -* `files:delete(file)` - удаляет файл; - -Обратите внимание, что лаунчер не позволяет читать и писать любые файлы. Вместо этого все файлы создаются в подкаталоге `/sdcard/Android/data/ru.execbit.aiolauncher/files/scripts` без возможности создавать подкаталоги. - -# Настройки - -* `settings:get()` - возвращает таблицу настроек в формате массива слов; -* `settings:set(table)` - сохраняет таблицу настроек в форме массива слов; -* `settings:get_kv()` - возвращает таблицу настроек в формате `ключ=значение`; -* `settings:set_kv(table)` - сохраняет таблицу настроек в формате `ключ=значение`; -* `settings:show_dialog()` - показать диалог изменения настроек. - -Пользователь может изменять настройки через диалог, доступный по нажатию на "шестеренку" в меню редактирования виджета. Если в метаданных виджета есть поле `arguments_help`, его значение будет выведено в диалоге редактирования. Если есть поле `arguments_default` - оно будет использовано для получения дефолтовых аргументов. - -Стандартный диалог редактирования можно заменить на свой если реализовать функцию `on_settings()`. - -# Подсобные функции - -* `utils:md5(string)` - возвращает md5-хэш строки (массива байт); -* `utils:sha256(string)` - возвращает sha256-хэш строки (массива байт); -* `utils:base64encode(string)` - возвращает base64-представление строки (массива байт); -* `utils:base64decode(string)` - декодирует base64-строку; - -# Функции обработки данных - -* `ajson:get_value(string, string)` - получает указанное значение из JSON; первый аргумент - JSON-строка, второй - инструкция для получения значения. - -В отличие от классических парзеров JSON, эта функция предназначена не для парзинга, а именно для извлечения одиночных значений. Например, есть следующий JSON: - -``` -{ - "type": "success", - "value": { - "id": 344, - "joke": "Aliens DO indeed exist. They just know better than to visit a planet that Chuck Norris is on.", - "categories": [] - } -} -``` - -Необходимо извлечь из него строку "joke". По тексту JSON видно, что эта строка содержится внутри объекта "value", а сам этот объект находится внутри основного объекта JSON. Другими словами чтобы извлечь нужную строку необходимо "открыть" основной объект JSON, затем "открыть" объект "value" и найти в нем строку "joke". В коде это будет выглядеть так: - -``` -joke = ajson:get_value(result, "object object:value string:joke") -``` - -При этом полный текст скрипта может выглядеть так: - -``` -function on_alarm() - net:get_text("http://api.icndb.com/jokes/random") -end - -function on_network_result(result) - local joke = ajson:get_value(result, "object object:value string:joke") - aio:show_text(joke) -end -``` - -Обратите внимание, что последним элементом строки всегда должна идти инструкция для извлечения примитивных типов данных: - -* `string:имя` -* `int:имя` -* `double:имя` -* `boolean:имя` - -Также вместо `object` можно использовать `array` если в JSON находится массив. - -Подводя итог: ajson хорошо (и очень быстро) работает тогда, когда вам необходимо извлечь одно-два значения. Если же необходимо получить большое количество данных (или все данные) из JSON, то лучше использовать библиотеку json.lua (см. ниже). Она превращает JSON в набор удобных для работы вложенных таблиц Lua. - -# Другие функции - -AIO Launcher включает в себя интерпретатор LuaJ 3.0.1 (совместимый с Lua 5.2) со стандартным набором модулей: `bit32`, `coroutine`, `math`, `os`, `string`, `table`. - -Модули `io` и `package` в целях безопасности исключены из поставки, модуль `os` урезан в функциональности. Доступны только следующие функции: `os.clock()`, `os.date()`, `os.difftime()` и `os.time()`. - -Стандартный API Lua расширен следующими функциями: - -* `string:split(delimeter)` - разделяет строку с помощью указанного разделителя и возвращает таблицу; -* `string:replace(regexp, string)` - заменяет текст, найденный регулярным выражением, на другой текст; -* `slice(table, start, end)` - возвращает часть таблицы, начиная с индекса `start` и заканчивая `end`; -* `get_index(table, value)` - возвращает индекс элемента таблицы; -* `get_key(table, value)` - возвращает ключ элемента таблицы; -* `round(x, n)` - округляет число; - -В комплект также входят: - -* `md_colors` - модуль-таблица цветов Material Design (исходник есть в этом репозитории, [справка](https://materialui.co/colors)); -* `url` - модуль с функциями для кодирования/декодирования строки в URL из библиотеки Lua Penlight; -* [utf8](https://gist.github.com/Stepets/3b4dbaf5e6e6a60f3862) - аналог одноименного модуля из Lua 5.3; -* [luaDate](https://github.com/Tieske/date) - функции для работы со временем; -* [LuaFun](https://github.com/luafun/luafun) - библиотека функционального программирования; -* [json.lua](https://github.com/rxi/json.lua) - парзер JSON; -* [Lua-Simple-XML-Parser](https://github.com/Cluain/Lua-Simple-XML-Parser) - парзер XML (см. пример `xml-test.lua`). - -# Метаданные - -Чтобы AIO Launcher смог корректно показать информацию о скрипте в каталоге скриптов и корректно вывести заголовок, вы должны добавить в начало скрипта метаданные. Например: - -``` --- name = "Covid info" --- description = "Cases of illness and death from covid" --- data_source = "https://covid19api.com" --- arguments_help = "Specify the country code" --- arguments_default = "RU" --- type = "widget" --- author = "Evgeny Zobnin (zobnin@gmail.com)" --- version = "1.0" -``` - -# Contribution - -Если вы хотите, что ваши скрипты были включены в репозитрий и официальную поставку AIO Launcher - создайте pull request или напишите мне письмо: zobnin@gmail.com. Также я всегда готов ответить на ваши вопросы и обсудить расширение текущего API.