# Функции (колбеки) жизненного цикла

* `onResume()` - вызывается при каждом возврате на рабочий стол;
* `onAlarm()` - вызывается при возврате на рабочий стол при условии, что с прошлого вызова прошло больше 30 минут;
* `onTick()` - вызывается каждую секунду пока лаунчер находится на экране.

Для большинства сетевых скриптов (загрузка и показ значений) следует использовать `onAlarm`. Использование других функций может привести к блокировке вашего IP.

# Функции показа данных

* `ui:showText(string)` - выводит в виджет обычный текст; повторный вызов стирает предыдущий текст;
* `ui:showLines(table)` - выводит список строк, в качестве аргумента принимает таблицу строк;
* `ui:showLinesWithAuthors(table, table)` - выводит список строк с отправителем (на манер почтового виджета); первая таблица - сами строки, вторая - соответствующие им отправители; таблицы должны быть одинакового размера;
* `ui:showButtons(table)` - выводит список кнопок; аргумент - таблица строк;
* `ui:showProgressBar(text, currentValue, maxValue)` - показывает прогресс бар;
* `ui:showToast(string)` - показывает информационное сообщение в стиле Android;
* `ui:showDialog(string, string, [string], [string])` - показать диалог; первый аргумент - заголовок, второй - текст, третий (опциональный) - имя первой кнопки, четвертый (опциональный) - имя второй кнопки;

При нажатии на любой элемент интерфейса будет выполнен колбек `onClick(number)`, где number - это порядковый номер элемента. Например, если вы используете `ui:showButtons` для показа трех кнопок, то при нажатии первой кнопки будет вызван `onClick` с аргументом 1, второй - с аргументов 2, и так далее. Если элемент на экране всего один - аргумент всегда будет равен единице и его можно будет опустить.

Нажатия на кнопки диалога должны обрабатываться в колбеке `onDialogClick(number)`, где 1 - это первая кнопка, 2 - вторая, а -1 - нажатие кнопки "закрыть", если никакие кнопки не были указаны.

Функции `ui:showText(string)` и `ui:showLines(string)` поддерживают многие теги HTML. Например:

```
First line<br/>Second line
<b>Bold Line</b><br/><i>Oblique Line</i>
<font color="red">Red text</font>
<span style="background-color: #00FF00">Text on green background</span>
```

# Системные функции

* `system:openApp(string)` - открывает приложение, имя пакета которого указано в аргументе;
* `system:openBrowser(string)` - открывает указанный URL в браузере или в приложении, умеющем обрабатывать данный тип URL;
* `system:exec(string)` - выполняет shell-команду;
* `system:su(string)` - выполняет shell-команду от имени root;
* `system:getLocation()` - возвращает местоположение в таблице с двумя значениями (запрос местоположения НЕ выполняется, используется значение, сохраненное системой ранее).

# Функции управления лаунчером

* `aio:doAction(string)` - выполняет действие AIO ([подробнее](https://aiolauncher.app/api.html));
* `aio:addWidget(string)` - добавляет на экран встроенный виджет или виджет-скрипт;
* `aio:removeWidget(string)` - удаляет с экрана встроенный виджет или виджет-скрипт (внимание: доп. виджеты тоже будут удалены);
* `aio:isWidgetAdded(string)` - проверяет, добавлен ли виджет на экран;

# Сетевые функции

* `net:getText(url)` - функция для получения текстовых данных по сети (JSON, XML, plain text).

Функция не возвращает никакого значения, а вместо этого вызывает колбек `onNetworkResult(string)`. В нем следует обрабатывать результат.

# Функции обработки данных

* `json:getValue(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 = json:getValue(result, "object object:value string:joke")
```

При этом полный текст скрипта может выглядеть так:

```
function onAlarm()
    net:getText("http://api.icndb.com/jokes/random")
end

function onNetworkResult(result)
    local joke = json:getValue(result, "object object:value string:joke")
    aio:showText(joke)
end
```

Обратите внимание, что последним элементом строки всегда должна идти инструкция для извлечения примитивных типов данных:

* `string:имя`
* `int:имя`
* `double:имя`

Также вместо `object` можно использовать `array` если в JSON находится массив.

# Метаданные

Чтобы AIO Launcher смог корректно показать информацию о скрипте в каталоге скриптов и корректно вывести заголовок, вы должны добавить в начало скрипта метаданные. Например:

```
-- name = "Covid info"
-- description = "Cases of illness and death from covid (covid19api.com)"
-- type = "widget"
-- author = "Evgeny Zobnin (zobnin@gmail.com)"
-- version = "1.0"
```