Введение основных объектов и функций

AnkuLua использует объектную структуру и функционал Sikuli, но не все объекты и функции поддерживаются.
Однако они совместимы для поддерживаемых объектов и методов / функций / API. Методы, функции и API одинаковы в AnkuLua.
Эти термины будут использоваться взаимозаменяемо. Ниже мы расскажем о том, что поддерживается.
Подробное описание можно получить на веб-странице Sikulix. Для каждого объекта и функции предусмотрены ссылки.

Начнем с Объектов.

---

Объекты

Строка с названием картинки ссылается на файл картинки для сопоставления.

Location:    Местоположение координат на экране. Поддерживаемые методы getX(), getY(), grow() и offset().

--пример кода
loc = Location(100,200)
print(loc:getX()) -- 100
print(loc:getY()) -- 200
loc2 = loc:offset(11, 22)
print(loc2) -- L(111, 222)

Функция, доступная только в AnkuLua:

    TypeOf() - возвращает строку "Location".

Pattern:    Используется как шаблон, для добавления к картинке дополнительных атрибутов, используемых в функциях поиска и при действии на искомый объект. Поддерживаемые функции - mask, similar, targetOffset и getTargetOffset.

-- изменим пример example1.lua для calculator plus
-- ========== Settings ================
Settings:setCompareDimension(true, 960)
Settings:setScriptDimension(true, 960)

-- ==========  main program ===========
click(Pattern("6.png"))
plus = Pattern("+.png"):similar(0.8) -- установим сходство для картинки "+.png"
click(plus)

nine = Pattern("6.png"):targetOffset(0, -67) -- кнопка 9 расположена выше кнопки 6 и это расстояние составляет 67 пикселей для экрана 960x540
click(nine)
print(nine:getTargetOffset()) -- L(0, -67)
click("-.png")
click("7.png")
click("=.png")

Функция, доступная только в AnkuLua:

    typeOf(): вернут "Pattern" в виде строки.
    getFileName(): вернут имя файла в виде строки


Region:    Это прямоугольная область на экране координаты которой определяются левым верхним углом на экране (x, y) и ее шириной и высотой (w, h) измеряемыми в пикселях.
    Создаем область с помощью Region(x, y, w, h)
    Поддерживаются такие функции как getCenter(), getTarget(), getLastMatch(), getX(), getY(), getW() and getH().
    Следующие функции принимают область как параметры: click(), find(), exists(), wait(), findAll(), waitVanish(), dragDrop() and type().
    Детальное описание click, find, exists, wait, findAll, waitVanish, dragDrop и type будет позже.

Функция, доступная только в AnkuLua:

    typeOf(): вернет "Region" в виде строки.


Match:    Объект класса Match это результат успешных методов поиска. Он имеет размер изображения, который использовался для поиска. В нем есть координаты левого верхнего угла экрана на котором он был найден.
    Поскольку класс Match расширяет класс Region, все методы класса Region могут использоваться с объектом match.
    Match в AnkuLua так же поддерживает функцию getScore().

Функция, доступная только в AnkuLua:

    typeOf(): вернет "Match" в виде строки.

---

Функции (совместимые с Sikuli)

Для каждой функции сопоставления используются основные аргументы объектов. Для каждого объекта используются следующие сокращения.
P: Pattern (Шаблон)
S: String (Строка)
M: Match (Соответствие)
R: Region (Область)
L: Location (Местоположение)

click(PSMRL):    Кликнуть по экрану.

-- модифицируем пример example1.lua для calculator plus
-- ========== Settings ================
Settings:setCompareDimension(true, 960)
Settings:setScriptDimension(true, 960)

-- ==========  main program ===========
click(Pattern("6.png"))
plus = Pattern("+.png"):similar(0.8) -- установим сходство для картинки "+.png"
click(plus)

nine = Pattern("6.png"):targetOffset(0, -67) -- кнопка 9 расположена выше кнопки 6 и это расстояние составляет 67 пикселей для экрана 960x540
match = find(nine)
click(match)
print(match:getScore())  -- значение сходства для кнопки "6.png"
print(match:getTarget()) -- координаты кнопки "9.png"
print(match:getCenter()) -- координаты центра кнопки "6.png"
print("match upper left coordinate = (" .. match:getX() .. "," .. match:getY() .. ")")
-- координата верхнего левого угла

click("-.png")
click("7.png")
click(Location(885, 515)) -- "="

Некоторых играх существуют проблемы с использованием стандартного клика.
Поэтому с версии 3.2.0 вводится альтернативный метод клика.
Если стандартный метод клика не работает в игре (или приложении), используйте следующую функцию, чтобы включить новый метод.
setAlternativeClick(enable)

find(PS):    Поиск конкретного элемента графического интерфейса, который рассматривается как данное изображение.

findAll(PS):    Поиск ВСЕХ экземпляров шаблона, пока не будет найдено ни одного совпадения.
    Примечание: findAll(PS) вернет таблицу с совпадениями, но region:findAll(PS) вернет объект Java List.
    Поэтому, чтобы получить таблицу с совпадениями из области findAll (PS), используйте одно из следующих действий:

    findAll() выдает ошибку, если искомое изображение не найдено.
    Если ошибка не нужна, используйте findAllNoFindException() вместо него.


test1 = findAll("target.png"))

for i, m in ipairs(test1) do
   click(m)
end

print (table.getn(test1)) -- записываем количество совпадений

reg = Region(10, 10, 300, 500)
test2 = listToTable(reg:findAll("target.png"))

for i, m in ipairs(test2) do
   click(m)
end

test3 = regionFindAll(reg, "target.png")

for i, m in ipairs(test3) do
   click(m)
end


wait([PS][, seconds]):    Ведет поиск по заданному шаблону, пока не появится изображение (будет найдено с помощью Region.find()) или пока не пройдет указанное время.

exists(PS[, seconds]):    Проверяет, виден ли на экране заданный шаблон.

waitVanish(PS[, seconds]):    Ведет поиск по заданному шаблону, пока изображение не исчезнет (не будет найдено с помощью Region.find()) или пока не пройдет указанное время.

dragDrop(PSMRL, PSMRL):    Выполняет перетаскивание от начальной точки до целевой точки, указанной двумя PSMRL соответственно.
    Настроить функцию перетаскивания можно следующими командами:
    setDragDropTiming(downMs, upMs)
    downMs: Перед перемещением нажать и удерживать позицию перетаскивания необходимое количество миллисекунд.
    upMs: После перемещения удерживать позицию перетаскивания необходимое количество миллисекунд.
    setDragDropStepCount(stepCount)
    stepCount: Количество шагов, необходимых для перетаскивания от начальной точки к целевой.
    setDragDropStepInterval(intervalMs)
    intervalMs: Интервал между шагами в миллисекундах.

Поведение dragDrop можно описать так:

Нажимаем и удерживаем начальную точку downMs миллисекунд
Перемещаемся к конечной точке stepCount шагов
с задержкой intervalMs между шагами
При достижении конечной точки, удерживаем upMs миллисекунд

type([PSMRL, ]text):    Вводит текст в текущее поле ввода или кликает нужную точку, указанную в PSMRL.

Все вышеуказанные функции можно вызвать напрямую или из объекта Region()
При прямом вызове, поиск указанного PS будет осуществляться на всем экране.
При вызове из объекта Region() поиск указанного PS будет осуществляться только в заданной области

---

Следующие функции можно вызывать только из объектов Region и Match.

highlight([text, ][seconds]):    Выделение области в течении нужного количества времени.
    Если параметр text отсутствует, выделение выполняется без текста. Стиль подсветки можно задать с помощью метода setHighlightStyle (color, fill). Формат цвета - ARGB. Параметр fill является логическим.
    Если параметр text указан, то внутри выделения будет отображен текст.

Стиль текста можно установить с помощью setHighlightTextStyle (bgColor, textColor, textSize)
    bgColor - цвет фона (по умолчанию 0xf8666666).
    textColor - цвет текста (по умолчанию 0xf8ffffff).
    textSize - размер текста (по умолчанию 16).

Если параметр second отсутствует, то при первом вызове выделение будет включено, при втором выключено.


highlightOff():    Выключает выделение заданной области. Если состояние неизвестно (включено или выключено), то этот метод можно использовать, для определения состояния как выключено.

Settings:setScriptDimension(true, 960)
right = Region(400, 0, 560, 640)
left = Region(0,0, 400, 640)
-- ==========  main program ===========
left:highlight("Hello!") -- выделим определенную область и напишем "Hello!". Цвет фона серый. Цвет текста белый.
right:highlight()
click("6.png")
click("+.png")
click("9.png")
setHighlightStyle(0x8fffff00, true)
getLastMatch():highlight(3)
right:highlight()
left:highlightOff()

Результат выполнения приведенного выше кода:


Для этих функций, создающих исключения, некоторые изображения сохраняются в каталоге /sdcard/AnkuLua/captured_images для отладки.
    FindException.png, снимок экрана с измененным размером
    regionException.png, снимок области экрана с измененным размером, если использовать поиск в области.

---

Другие функции (не совместимые с Sikuli)

AnkuLua поддерживает следующие функции, которые не предусмотрены в Sikuli.

waitClick(PSMRL [, seconds]):    Продолжает поиск заданного шаблона на экране до тех пор, пока не появится изображение или не пройдет указанное время. Если шаблон найден, кликнет на него и будет возвращен объект Match,     содержащий наилучшее соответствие. В случае, если изображение не появится, будет ошибка.

existsClick(PSMRL [, seconds]):    Продолжает поиск заданного шаблона на экране до тех пор, пока не появится изображение или не пройдет указанное время. Если шаблон найден, кликнет на него и будет возвращен объект Match,     содержащий наилучшее соответствие. В случае, если изображение не появится, ошибки не будет, а вернувшееся значении метода будет false (При нахождении шаблона, значение true).

doubleClick(PSMRL):    Название функции говорит обо всем. Её можно вызвать напрямую или через объект Region().

findAllNoFindException(PS):    То же самое что findAll(), но с возвратом логического значения false или true.

regionFindAllNoFindException(region, PS):    То же самое что regionFindAll(), но с возвратом логического значения false или true.

keyevent(keycode):    Нажатие клавиш путем отправки их кода. Тут можно найти коды клавиш.

keyevent(4) -- кнопка назад
keyevent(3) -- кнопка "домой"
wait(2)
keyevent(187) -- кнопка переключения приложений
swipe(PSMRL, PSMRL [, swiping seconds]):    Выполняет перетаскивание от начальной точки до целевой точки, указанной двумя PSMRL соответственно.
    Действие схоже с dragDrop, но время не устанавливается.
    Некоторые устройства работаю некорректно с dragDrop. Если вам нужно просто провести по экрану, используйте этот метод.
    Если параметр "swiping seconds" определен, скрипт может контролировать скорость жеста.

touchDown(PSMRL [,seconds]), touchMove(PSMRL [,seconds]), touchUp(PSMRL [,seconds]):    Эти три функции позволяют делать самые базовые сенсорные возможности.

manualTouch(actionTable):    Поскольку каждый вызов команды низкого уровня будет замедлять работу скрипта.
    И если заранее известны все последующие нажатия, то можно использовать maningTouch(), чтобы значительно повысить скорость, поскольку     вызывается только одна команда низкого уровня.

    Единственный параметр actionTable это таблица с содержащимися в ней списком действий. Каждое действие это тоже таблица с action и target. Действия (action) могут быть следующие (и только одно): "touchDown", "touchMove",     "touchUp" и "wait". Действию "wait", параметр target указывается в секундах. Для других действий, это координаты на экране.
    Простой пример использования:

-- ========== Settings ================
Settings:setCompareDimension(true, 1280)
Settings:setScriptDimension(true, 1280)
-- ==========  main program ===========
p1 = Location(100, 300)
p2 = Location(400, 300)
p3 = Location(400, 600)
p31 = Location(401, 601)

setManualTouchParameter(5, 1) -- пояснение ниже

actionList = { {action = "touchDown", target = p1},
   {action = "wait", target = 0.2},
   {action = "touchMove", target = p2},
   {action = "touchMove", target = p3},
   {action = "touchUp", target = p31} }

manualTouch(actionList)


setManualTouchParameter(int maxDistance, int insertWaitTimeMs):    Если действия перемещения совершаются на большие расстояния, то в игре могут быть сбои. Можно использовать setManualTouchParameter() чтобы настроить     touchMove в manualTouch().
    maxDistance: Максимальное расстояние перемещения. Если расстояние touchMove больше, чем это значение, то несколько движущихся точек с расстоянием maxDistance будут вставлены автоматически.
    Значение по умолчанию равно 5.
    insertWaitTimeMs: При необходимости вставки дополнительных точек перед перемещением, вставляется так же одна миллисекунда задержки WaitTime. Значение по умолчанию равно 1.
    С настройкой параметров можно достичь баланса между скоростью и корректностью отображения.

---

Общие функции (не связанные с поиском и нажатиями)

save(fileName):    Функция вызывается из объектов Region или Match. Возвращаемое значение отсутствует.
    При этом изображение будет сохранено с именем fileName в каталог imagePath.
    Простой пример с "calculator plus"
match = waitClick("6.png",2)
match:save("save6.png") -- сохраняем область с именем "save6.png"
print(getLastMatch())
click("+.png")
click("9.png")
click("-.png")
click("7.png")
click("save6.png") -- можно нажать на сохраненное изображение
click("=.png")

scriptPath():    Возвращает путь к скрипту. Пользователи могут использовать этот в путь в dofile или require.

local dir = scriptPath()
print (dir)
package.path = package.path .. ";" .. dir .. '?.lua'
print(package.path)
require(somelib)
dofile(dir .. "script.lua")

getLanguage():    Возвращает языковую настройку для системы Android. Можно использовать для многоязычных скриптов.

function fileExists(name)
   local f=io.open(name,"r")
   if f~=nil then io.close(f) return true else return false end
end

function loadStrings(path)
   local language = getLanguage()
   local file = path.."strings."..getLanguage()..".lua";
   if (fileExists(file)) then
       dofile(file)
   else
       if (fileExists(path.."strings.lua")) then
           dofile(path.."strings.lua")
       end
   end
end


getCountry():    Возвращает настройку страны для системы Android.

getVersion():    Возвращает в виде строки версию AnkuLua.

getDeviceID(), getIMEI(), getSIMSerial(), getIMSI(), getWiFiMAC(), getMacAddr():    Все эти функции возвращают соответствующие идентификаторы. Можно использовать для платных сценариев.
    Примечание: поскольку WiFiMAC всегда возвращает 02:00:00:00:00:00 выше версии Android 6.0. Вместо него можно использовать getMacAddr(). Но возвращаемые значения для этих двух методов будут разными.

getUserID():    Возвращает аккаунт пользователя электронной почты в Pro2 версии. При использовании пробной версии, значение будет nil.

setClipboard(String string):    Изменяет строку, содержащуюся в буфере обмена
    При использовании root-прав или daemon в Android 7.0 или выше, можно ввести строку UTF с помощью setClipboard() и keyevent (279).
setClipboard("Olá Mundo\nEngligh")
keyevent(279)
    В режиме специальных возможностей, type() поддерживает UTF.

typeOf():    Для определения типа переменной Lua использует метод "type()". Однако Sikuli также использует "type()" для ввода текста.
    Поэтому, чтобы узнать тип переменной, используйте, typeOf().
    Можно вернуть оригинальный type() используемый Lua:
inputText = type
type = typeOf

[Вперед]: Первый пример: использование AnkuLua в реальном приложении
[Назад]: Установка Daemon
[Главная]: AnkuLua. Введение