基本物件與函數

AnkuLua 使用Sikuli 的物件結構與函數，但不是所有物件和函數都支援。
但是，對於支持的物件和函數，他們是和Sikulix用法相容的。
在這裡，我們將介紹相容的物件和函數。
你也可以參考Sikulix網頁取得更多內容，每一物件和函數都附上連結。

物件

以下物件儲字串外，均帶有各種函數，要使用這些函數，請以冒號(":")帶出相關函數。例如

reg = Region (0, 0, 100, 200)
reg:existsClick("target.png")
match = reg:getLastMatch()
match:setTargetOffset(50, 100)

圖檔字串(String): 一個圖檔字串代表就是要拿來做圖形比對的圖檔名稱。

位置(Location):
位置表示螢幕上的座標
AnkuLua支持的位置函數有 getX, getY, grow 和 offset.

--sample code
loc = Location(100,200)
print(loc:getX()) -- 100
print(loc:getY()) -- 200
loc2 = loc:offset(11, 22)
print(loc2) -- L(111, 222)
注意: 座標均以左上角為原點(0,0)
AnkuLua 特有函數:
    typeOf(): 返回 "Location" 字串

樣式(Pattern):
樣式可以讓圖形可以帶上其他屬性，以供圖形比對或點擊使用。
AnkuLua支持的樣式函數有mask, similar, targetOffset, 和getTargetOffset.

-- modified from example1.lua of calculator plus
-- ========== Settings ================
Settings:setCompareDimension(true, 960)
Settings:setScriptDimension(true, 960)

-- ==========  main program ===========
click(Pattern("6.png"))
plus = Pattern("+.png"):similar(0.8) -- set the similarity on "+.png"
click(plus)

nine = Pattern("6.png"):targetOffset(0, -67) -- 9 is above 6 and the distance is 67 pixels in 960x540 screen
click(nine)
print(nine:getTargetOffset()) -- L(0, -67)
click("-.png")
click("7.png")
click("=.png")

AnkuLua 特有函數:
    typeOf(): 返回 "Pattern" 字串

    getFileName(): 返回Pattern 的圖形檔名

    color(): 強制使用彩色圖形比對
        注意: 如果使用前面截圖，前面截圖必須是彩色的，否則會有例外(Exception)產生


    isColor(): 返回是否pattern 是採用彩色圖形比對

pat = Pattern("target.png"):color()
existsClick(pat)
print(pat:isColor() and "color" or "gray")


區域(Region):
一個區域代表的是螢幕上一個方形地方，區域是以左上角座標(x, y) 以及 寬和高的點數(w, h)來表示。
支持的函數有 getCenter, getTarget, getLastMatch, click, find, exists, wait, findAll, waitVanish, dragDrop, type.
我們會在後面詳細介紹以下函數 click, find, exists, wait, findAll, waitVanish, dragDrop, type 和 save
Region 四個參數依序是

左上角 X 座標
左上角 Y 座標
區域寬度
區域高度

reg = Region(250, 260, 100, 200) -- 創立一個左上角座標在(250, 260) 寬度100，高度兩百的區域注意: 第三和第四的參數是區域的寬和高，不是右下角座標；不要搞錯了

AnkuLua 特有函數:
    typeOf(): 返回 "Region" 字串


匹配(Match):
當圖形比對成功時，得到的物件就是Match。它有圖形的寬和高點數，同時Match帶有圖形比對最佳相符結果的左上角座標。
因為Match是Region的延伸(extension)，所有Region 的函數Match 都支持。
Match 額外支持下列函數:
setTargetOffset(Location)
setTargetOffset(int x, int y)
getCenter() 傳回中央點的Location
getTarget() 傳回目標點的Location
Match 有另一參數是Region沒有的，相似度(similar)；相似度是一個0到1的數字，代表搜尋到的圖形相似度有多少。
getScore()這一函數可以取的相似度.

AnkuLua 特有函數:
    typeOf(): 返回 "Match" 字串


Region函數 (Sikuli 相容的)

對於每一比對或點擊函數，都能使用好幾種不同物件當參數。以下列出所有可能物件，前方字母是代表縮寫。
P: Pattern(樣式)
S: String(字串)
M: Match(匹配)
R: Region(區域)
L: Location(位置)

click(PSMRL):
參數是P或S時:搜尋圖形，如果有找到符合的，則點擊對應位置
MRL: 點擊對應位置

-- modified from example1.lua of calculator plus
-- ========== Settings ================
Settings:setCompareDimension(true, 960)
Settings:setScriptDimension(true, 960)

-- ==========  main program ===========
click(Pattern("6.png"))
plus = Pattern("+.png"):similar(0.8) -- set the similarity on "+.png"
click(plus)

nine = Pattern("6.png"):targetOffset(0, -67) -- 9 is above 6 and the distance is 67 pixels in 960x540 screen
match = find(nine)
click(match)
print(match:getScore())  -- the similarity value of "6.png"
print(match:getTarget()) -- the coordinates of "9.png"
print(match:getCenter()) -- the center of "6.png"
print("match upper left coordinate = (" .. match:getX() .. "," .. match:getY() .. ")")
-- upperleft corner coordinate

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


find(PS):
找尋一個圖形，如果找到則回傳最佳匹配(Match)物件

findAll(PS):
找尋螢幕上所有符合條件的圖形，回傳包含所有符合匹配(Match)的陣列
注意: findAll(PS) 返回值是包含Match 的表格(table with matches), 但 region:findAll(PS) 則是返回Java List 物件.
Therefore, to get table with matches from region:findAll(PS), use one of the followings
因此，要從region:findAll(PS)獲得包含Match 的表格，請使用下列程式之一



test1 = findAll("target.png"))

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

print (table.getn(test1)) -- print the number of matches

-- 方法一
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]):
在幾(seconds)秒內，等待所指定圖形出現；如果在時限內出現，則回傳最佳匹配物件。
如果過了時限依然無法找到所需圖形，例外(exception)將被舉發。
注意: AnkuLua 裡所有的秒數都是實數，可以有小數點。例如 wait(0.5) 代表等待 0.5 秒；wait(1.3) 代表等待 1.3 秒

exists(PS[, seconds]):
檢查在時限內圖形是否存在如果在時限內出現，則回傳最佳匹配物件
如果過了時限依然無法找到所需圖形，則傳回nil

waitVanish(PS[, seconds]):
在時限內等待物件消失
如果消失沒回傳是(true)，否則回傳否(false)

dragDrop(PSMRL, PSMRL):
搜尋第一個和第二個圖形，如果都能找到，則抓取第一個物件指定位置到第二個物件指定位置。
如果找不到，例外(exception)將被舉發。
dragDrop 的行為可以由下列函數設定各種參數
setDragDropTiming(downMs, upMs)
downMs: 開始移動前壓不住不動幾毫秒
upMs: 最後放開前停住幾毫秒
setDragDropStepCount(stepCount)
stepCount: 從啟始點到目的地分幾步移動完
setDragDropStepInterval(intervalMs)
intervalMs: 每次移動間停留幾毫秒

因此，dragDrop 的行為是

壓住啟始目標 downMs 毫秒
分stepCount 步網目的地移動， 每次移動間停留幾毫秒
在目的地持續壓住 upMs 毫秒，然後舉起手指

type([PSMRL, ]text):
如果不帶PSMRL 參數，則直接送出文字(text)
如果帶有PSMRL參數，則做需要的搜尋(PS)，點擊指定位置，然後送出文字
如果找不到，例外(exception)將被舉發。

getLastMatch():
回傳最後搜尋到的匹配(Match)

對於會產生例外(Exception)的函數，當例外發生時，有些幫助除蟲的影像檔會儲存在/sdcard/AnkuLua/captured_images

findException.png: 依照CompareDimension縮放過的截圖

regionException.png: 如果有用到區域函數，則會同時儲存縮放過的區域截圖



所有以上函數都可以直接被Region 物件呼叫
如果直接呼叫(不經由Region)，則整個螢幕都會被搜尋
如果由Region或Match呼叫這些函數，則只有指定區域會被搜尋


highlight([text][,seconds]): 強調指定區域一段時間
如果沒給文字參數，將只顯示框框
強調的方式可以用setHighlightStyle (color, fill)設定。 這裡 color 是ARGB格式的整數(預設值是0xffff0000)。 fill 代表是否要填滿該區域。

如果有給文字參數，則將在框內顯示文字
此時強調的方式可以用setHighlightTextStyle (bgColor, textColor, textSize)設定。
bgColor(預設值0xf8666666)為背景顏色，textColor為文字顏色(預設值0xf8ffffff)，textSize為文字大小(預設值16)。

如果不給秒數，就是一個開關
第一次呼叫給出框框，第二次呼叫將框框取消

highlightOff(): 關掉指定區域強調
如果您不知指定區域強調現在是開還是關，可以用此函數直接關掉指定區域強調

highlightUpdate(text): 更新強調內的文字

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()

上方腳本執行結果如下 



其他函數 (Sikuli沒有的)

AnkuLua 額外提供下列函數以供方便使用

waitClick(PSMRL [, seconds]):
waitClick 執行以下代碼

wait(PSMRL [,seconds])
click(getLastMatch())
existsClick(PSMRL [, seconds]): 
existsClick 執行以下代碼

if exists(PSMRL [,seconds]) then click(getLastMatch()) end


findAllNoFindException(PS)
與findAll 相同，只是不會發出例外(Exception)

regionFindAllNoFindException(region, PS)
與regionFindAll 相同，只是不會發出例外

doubleClick(PSMRL)
雙擊目標. 這個函數可以直接呼叫或從Region物件中呼叫

keyevent(keycode)
送出特別的按鍵，例如桌面、返回
參考Android的所有按件對應碼

keyevent(4) -- back
keyevent(3) -- home
wait(2)
keyevent(187) -- app_switch

swipe(PSMRL, PSMRL)
搜尋第一個和第二個圖形，如果都能找到，則從第一個物件指定位置滑到第二個物件指定位置。
如果找不到，例外(exception)將被舉發。
swipe 的行為和dragDrop 類似，但無法控制細部時間
有些機器使用dragDrop 會有問題，如果只需滑動畫面，可以使用swipe


touchDown(PSMRL [,seconds]), touchMove(PSMRL [,seconds]), touchUp(PSMRL [,seconds])

這三個函數提供最基本的三個動作

manualTouch(actionTable)

touchDown(), touchMove() 和touchUp() 因為每一次都要呼叫底層命令，因此可能執行速度較慢。
如果已經事先知道所有點擊移動路徑，可以使用manualTouch()，只呼叫一次底層命令，執行速度會快很多。

唯一的參數actionTable是一個帶有很多動作的表格，每一個動作以action 代表要執行動作("touchDown", "touchMove", "touchUp", "wait")，以target 代表目標(除"wait" 是秒數外，其他都是Location)。
直接看範例比較清楚

-- ========== 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 = p3} }

manualTouch(actionList)


setManualTouchParameter(int maxDistance, int insertWaitTimeMs)

設定manualTouch()中touchMove 相關參數，因為如果一次移動太遠，可能造成遊戲行為不對
maxDistance: 每次移動最遠距離，如果移動距離超過，會插入每次多個距離為maxDistance的移動點，初始值為5
insertWaitTimeMs: 如果需要插入移動點，會再前面同時插入等待insertWaitTime毫秒(millisecond)，初始值為1
調整適當的參數，可以在速度與正確性取得平衡

一般函數 (與搜尋或點擊無關)

save(fileName)
saveColor(fileName)
save()和saveColor() 函數必須由Region或Match物件呼叫
save()和saveColor() 無返回值
會將區域內圖形儲存到 imagePath 的下的fileName
save() 儲存的檔案為灰階
saveColor() 則為彩色

以calculator plus 為例
match = waitClick("6.png",2)
match:save("save6.png") -- save the region to save6.png
print(getLastMatch())
click("+.png")
click("9.png")
click("-.png")
click("7.png")
click("save6.png") -- We can now click the saved image
click("=.png")

scriptPath()
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版本字串

getAndroidVersion()
返回Android API 版本數字

getDeviceID(), getIMEI(), getSIMSerial(), getIMSI(), getWiFiMAC(), getMacAddr()

這些函數會返回對應的ID 字串
他們可以被用來發展可以出售的腳本
注意: 因為WiFiMAC 在Android 6.0 後固定回 02:00:00:00:00:00，可以用getMacAddr()來取代，但兩者在6.0 以前版本返回值並不同

getUserID()
這個函數會返回Pro2使用者帳號的email
如果是試用版，則返回 nil

typeOf()
原本lua 提供type() 供判斷變數類別。但是，Sikuli 已經使用type() 來代表輸入文字。
因此，在AnkuLua 裡，請使用typeOf() 來判斷變數類別。

如果您一定要用type() 判斷變數類別，您可以
inputText = type
type = typeOf

setClipboard(String string)
更改剪貼簿裡的文字
在root或daemon的情形下，如果Android版本是7.0或以上，可以搭配keyevent(279) 輸入中文
setClipboard("中文\nEngligh")
keyevent(279)
在協助工具模式下，可以直接用type()輸入中文


[下一頁]: 使用者介面函數
[上一頁]: 腳本開發快速入門
[首頁]: AnkuLua介紹