Initial commit

README_ru.md

@@ -0,0 +1,72 @@
+# Функции (колбеки) жизненного цикла
+
+* `onResume()` - вызывается при каждом возрате на рабочий стол;
+* `onAlarm()` - вывызвается при возврате на рабочий стол при условии, что с прошлого вызова прошло больше 30 минут;
+* `onTick()` - вызывается каждую секунду пока лаунчер находится на экране.
+
+Для большинства сетевых скриптов (загрузка и показ значений) следует использовать `onAlarm`. Использование других функций может привести к блокировке вашего IP.
+
+# Сетевые функции
+
+* `net:getText(url)` - функция для получения текстовых данных по сети (JSON, XML, plain text).
+
+Функция не возвращает никакого значения, а вместо этого вызывает колбек `onNetworkResult(string)`. В нем следует обрабатывать результат.
+
+# Функции показа данных
+
+* `aio:showText(string)` - выводит в виджет обычный текст; повторный вызов стирает предыдущий текст;
+* `aio:showLines(table)` - выводит список строк, в качестве аргумента принимает таблицу строк;
+* `aio:showLinesWithAuthors(table, table)` - выводит список строк с отправителем (на манер почтового виджета); первая таблица - сами строки, вторая - соответствующие им отправители; таблицы должны быть одинакового размера;
+* `aio:showProgressBar(text, currentValue, maxValue)` - показывает прогресс бар;
+* `aio:showToast(string)` - показывает информационное сообщение в стиле Android;
+* `aio:openBrowser(string)` - открывает указанный URL в бразуере или в приложении, умеющем обрабатывать данный тип URL.
+
+# Функции обработки данных
+
+* `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". В коде это будет выглядеть так:
+
+```
+local 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 находится массив.
+
+# Колбеки обработки нажатий
+
+* `onClick(number)` - этот колбек будет вызван когда пользователь нажмет на элемент виджета; number - это порядковый номер элемента.
+
+Допустим скрипт использует функцию `aio:showLines` чтобы показать несколько строк. При нажатии первой строки будет вызван `onClick` с аргументом 1, второй - с аргументом 2 и так далее. При использовании функции `aio:showText` колбек всегда будет вызываться с аргументом 1.