===========
自定義函式
===========
以內建或特殊形式的函式取代某些函式呼叫，可協助您的應用程式執行速度更快。尋著本章節函數介紹，您將更快上手Blackey Script之使用。

  .. _CustomFunction_page: 

特色函數 
---------- 

 ==========================================  ====================================================
 函數                                                   功能
 ==========================================  ====================================================
 :ref:`find(path)<find>`                      給予一個圖像的路徑，尋找目前的畫面中是否存在該圖像。
 :ref:`click(position,interval)<click>`       給予一個圖像的路徑，單擊/雙擊該圖的座標點及點擊間距時間。
 :ref:`dclick(path)<dclick>`                  就算畫面上不存在此圖像時，仍會點擊擷取圖像時的座標。
 :ref:`press(position)<press>`                按下某個座標點
 :ref:`move(position)<move>`                  移動到某個座標點
 :ref:`release(position)<release>`            離開某個座標點
 :ref:`wheel(direction, position)<wheel>`     在某個座標點模擬滾輪事件
                                              direction = 0 時表示向上滾動；
                                              direction = 1 時表示向下滾動。
 :ref:`keycode(value)<keycode>`                發送Android KeyEvent
 :ref:`input(string)<input>`                  發送對應的字串給設備。
 :ref:`print(expression1, …)<print>`           列印參數到日誌視窗
 :ref:`random(value)<random>`                 回傳 0 ~ (value-1) 之間的隨機數
 :ref:`msleep(value)<msleep>`                 睡眠 value 毫秒
 ==========================================  ====================================================

.. _find:

find(path)
+++++++++++
圖像的相對路徑參數可透過 :ref:`圖形辨識<Script_img>` 或是 :ref:`操作錄製<Script_rec>` 取得， 
再添加判斷式 if / else 語法，即可製作具判斷式之腳本

    .. code-block :: 

        if (find(“res/20190809-131033.png”)) {

            print(“Yes, we find it!”);

        } else {

            print(“No, we could not find it!”);

        }
      
.. _click:

click(position,interval)
+++++++++++++++++++++++++++++++
圖像的相對路徑參數可透過 :ref:`圖形辨識<Script_img>` 或是 :ref:`操作錄製<Script_rec>` 取得位置（position），即使當前畫面不存在該圖，腳本仍會點擊該圖像紀錄的座標位置;interval時間預設為100(ms) ,使用者若想增減點擊時間可調整參數。

 .. tip::
    點擊間距預設時間單位100毫秒(ms)，期望點擊速度加快請填入<100之數字，如：50（不須填入單位）。

    .. code-block :: 

        if (find(“res/20190809-131033.png”)) {    

            click(“res/20190809-131033.png”);

        } else {

            print(“No, we could not find it!”);

        }

.. _dclick:

dclick(path)
+++++++++++++++++++++++++++
功能與click相同，使用此API來觸發雙擊。


.. _press:

press(position)
+++++++++++++++++++++++++++
Android的觸摸事件是由 *按下->移動-> 離開* 這三種事件組合而成的。
操作滑動的時候，移動的成份會佔很大，距離也相對較長；
如果是點擊/長按的時候，通常移動的比例就大幅下降了。



.. _move:

move(position)
+++++++++++++++++++++++++++
此指令與press 以及 release 有相當大的關聯性，針對移動座標進行紀錄



.. _release:

release(position)
+++++++++++++++++++++++++++
此指令與press 以及 move 有相當大的關聯性，在鬆開按壓鍵實惠進行座標紀錄點

.. _wheel:

wheel(position) 
+++++++++++++++++++++++++++
滾輪事件一樣可以錄製下來使用，
使用錄製的好處是可以精準定位到你想要滾動的地方。
往上滾動的時候，direction會記為0；反之則記為1。
下面是滑鼠滾動事件的錄製範例


 .. code-block :: 

        click("res/20211105-150410.png");
        msleep(80);
        msleep(1418);
        wheel(1, pos(0.454268, 0.404372));
        msleep(28);
        wheel(1, pos(0.454268, 0.404372));
        msleep(7);
        wheel(1, pos(0.454268, 0.404372));
        wheel(1, pos(0.454268, 0.404372));
        wheel(1, pos(0.454268, 0.404372));
        ...

 .. figure:: Images/scripts/11wheel.gif
    :width: 500
    :alt: mouse wheel
    :align: center  

    腳本將自動偵測滑鼠滑動座標，並紀錄於編輯區塊中

.. _keycode:

keycode(value) 
+++++++++++++++++++++++++++
keycode函數是用來發送Android KeyEvent給設備時使用。
按鍵事件跟觸摸事件很類似，由一個或多個ACTION_DOWN與一個ACTION_UP的事件串接而成。

在目前的Blackey Script中，我們簡化了這個按壓方式，
在腳本運行到keycode(value)時，會自動送出ACTION_DOWN與ACTION_UP事件，
不過也因此目前Blackey Script並不支援長按硬體鍵的功能。

keycode的使用方法可由錄製時系統自動填入，或是編輯調用keycode並填入對應的鍵值即可。

 ===========  =======================
 Keycode       Action
 ===========  =======================
 102            Power
 172            Home
 5000           Rotate
 ===========  =======================

 .. figure:: Images/scripts/13keycode.gif
    :width: 500
    :alt: key code(102)
    :align: center  

    腳本自動偵測操作並填入相對應之keycode


.. _input:

input(string)
+++++++++++++++++++++++++++
input函數是用來發送字串給設備時使用。
設備需要先點開可輸入的地方，此時input函數才會有作用。
使用的方式可以為

    .. code-block :: 

        // Input the string directly
            input(“Hello World!”);

        // Input string according to the variable
            myString = “Hello Blackey”;
            input(myString);

.. hint::
    使用input功能時，需要開啟 :ref:`BlacKeyBoard <BlacKeyBoard>`

.. _print:

print (expression1, …)
+++++++++++++++++++++++++++
print函數可用於debug，你可以使用print函數列印數個不同的表達式，print函數會印出每個表達式計算得到的原型。 請參考 :ref:`陳述式範例<Statements>` ，
並檢視Console 區域 即可得到print結果

.. _random:

random (value)
+++++++++++++++++++++++++++
隨機函數random，隨機的決定腳本行為時就可以派上用場
調用的方法只要填入預期的範圍即可
回傳的值會是從 0 到 (輸入值-1) 之間的一個隨機數。
例如要獲取 1~10 隨機數的話，可以這樣子寫：

``randomValue = 1 + random(10);``

    .. code-block :: 

        x = 0;
        while (x < 10) {

            print(x, random(10));
            x = x+1;

        }

.. _msleep:

msleep (value)
+++++++++++++++++++++++++++
使用的時機是需要延後執行下一個表達式時使用，
在腳本錄製模式下，也會自動判斷你動作之間的間隔來填入msleep。
可參考 :ref:`操作錄製<Script_rec>` 中自動偵測msleep秒數，或是 :ref:`圖形辨識<Script_img>` 自行填入msleep（）秒數之範例

 .. tip::
    msleep的單位是毫秒(1/1000 sec)



:ref:`進入腳本編撰<腳本編撰>` or
:ref:`回到頂部<內建函式>`