



Системные
    define            - безопасно объявить через cdef
    geterr            - получить последнюю ошибку
    indexof           - получить индекс элемента в массиве
    ispilot           - является ли среда пилотом
    lg                - вывести содержимое в лог (в т.ч. таблицы)
    registryread      - прочитать ключ реестра
    sleep             - пауза
    utf16_to_ascii    - преобразовать UTF-16 в ASCII
    utf16_to_file     - записать UTF-16 в файл
    utf8_to_ascii     - преобразовать UTF-8 в ASCII
    utf8_to_utf16     - преобразовать UTF-8 в UTF-16

Окна:
    exec              - запустить исполняемый файл
    execandwait       - запустить исполняемый файл и ждать выполнения
    exepath           - путь к исполняемому файлу
    findwindow        - найти окно
    getcontroltext    - получить текст контрола (кнопки)
    getfocus          - получить хэндл окна с фокусом клавиатуры
    getforeground     - получить активное окно
    getwindow         - получить окно относительно другого
    getwindowclass    - получить класс окна
    getwindowtext     - получить имя окна
    isvisible         - является ли окно невидимым
    postmessage       - отправить post сообщение окну
    sendmessage       - отправить send сообщение окну
    setaffinity       - назначить ядра процессу
    setcontroltext    - задать текст контрола (кнопки)
    setpriority       - установить приоритет процеса
    setwindowtext     - задать имя окна
    showwindow        - показать/свернуть/развернуть/скрыть окно
    terminate         - уничтожить окно
    tohandle          - преобразовать число в хэндл
    windowfromcursor  - хэндл окна под курсором
    windowfrompoint   - хэндл окна в точке
    windowinfo        - получить информацию об окне
    windowpid         - получить PID окна
    windowpos         - получить позицию окна
    workwindow        - назначить рабочим окном

Мышь:
    mousepos          - получить текущие координаты мыши

    Методы кликов мышкой:
    post
    send
    event
    inner

    Каждый из методов имеет следующие функции:

    move              - переместить мышь

    left              - кликнуть левой кнопкой
    left_double       - двойной клик левой кнопкой
    left_down         - нажать левую кнопку
    left_up           - отпустить левую кнопку

    right             - кликнуть левой кнопкой
    right_double      - двойной клик левой кнопкой
    right_down        - нажать левую кнопку
    right_up          - отпустить левую кнопку

    middle            - кликнуть левой кнопкой
    middle_double     - двойной клик левой кнопкой
    middle_down       - нажать левую кнопку
    middle_up         - отпустить левую кнопку

    m4                - кликнуть левой кнопкой
    m4_double         - двойной клик левой кнопкой
    m4_down           - нажать левую кнопку
    m4_up             - отпустить левую кнопку

    m5                - кликнуть левой кнопкой
    m5_double         - двойной клик левой кнопкой
    m5_down           - нажать левую кнопку
    m5_up             - отпустить левую кнопку

    wheel_down        - кликнуть левой кнопкой
    wheel_up          - двойной клик левой кнопкой
    wheel_left        - нажать левую кнопку
    wheel_right       - отпустить левую кнопку

    Методы имеют следующие опции:
    move_before_click - переместить мышь в точку клика
    move_after_click  - вернуть мышь после клика
    move_func         - функция перемещения мыши
    move_split        - разделять перемещение и клик (только input и event)
    timeout_inner     - задержка межу down и up
    timeout_outer     - задержка между up и down (не блокирующая)
    timeout_move      - задержка межу move и down
    mod_inner         - использовать флаг зажатия ctrl/shift вместо зажатия (только send и post)
    clock_up          - время последнего клика


Клавиатура
    getlayout         - получить текущую раскладку клавиатуры
    getlayoutlist     - получить список доступных раскладок
    keystate          - получить состояние клавиши
    keystateasync     - получить состояние клавиши асинхронно.
    setlayout         - установить раскладку клавиатуры

    Методы отправки нажатий клавиатуры:
    send
    post
    event
    input

    Каждый из методов имеет следующие функции:
    key  - нажать и отпустить клавишу
    text - отправить текст
    down - нажать клавишу
    up   - отпустить клавишу


Время.
    clock_hp            - таймер с высоким разрешением
    clock_hp_int64      - таймер с высоким разрешением результат в int64
    clock_hp_resolution - количество тиков таймера с высоким разрешением в секунду
    clock_hp_result[0]  - результат выполнения clock_hp_int64()
    day                 - текущий день
    hour                - текущий час
    min                 - текущая минута
    month               - текущий месяц
    sec                 - текущая секунда
    sleep               - приостановить программу
    sleep_hp            - приостановить программу с высокой точностью
    timestamp           - строковый таймштамп
    weekday             - текущий день недели
    year                - текущий год








SYSTEM



define
    define(str)
    Выполняет защищенный вызов
    ffi.cdef чтобы избежать
    redefine на струтурах.

    str - строка для define.




geterr
    err, verbose = geterr()
    Получение кода последней ошибки
    и его расшифровки.

    err     - код ошибки

    verbose - текстовая расшифровка ошибки




indexof
    index = indexof(tbl, val)
    Получает номер индекса в массиве
    по значению элемента.
    Возвращает первый совпавший индекс.

    index - найденный номер индекса.

    tbl   - таблица в которой происходит поиск.

    val   - значение, которое ищется в таблице.




ispilot
    ispilot
    Проверка в пилоте мы или нет.
    Это переменная, а не функция.




lg
    lg(obj_1, obj_2, ..., obj_n)
    Вывод содержимого таблицы в лог.
    Допускается вывод
    других типов данных.

    obj_* - данные для вывода в лог.




loadlines
    result = loadlines(<path>, [empty_lines, [empty_tail]])
    Загружает файл построчно в массив.

    path        - пусть к файлу.

    empty_lines - загружать пустые строки true/false.
                  По умолчанию true.
    erease_tail - срезать загрузку пустыъ строк в хвосте файла.
                  Нужно понимать, что при выключенном
                  empty_lines пустой хвост так же загружен не будет.
                  По умолчанию false.




registryread
    key_value, data_size, err, verbose = registryread(fullpath)
    Получает значение ключа реестра.

    key_value - значение ключа.
                Строки будут приведены к
                ascii, в том числе REG_LINK
                который хранится всегда в
                юникоде.

    data_size - размер полученных данных.
                Актуально для binary, none,
                string данных. При типе данных
                REG_LINK вернет размер юникод
                строки, но сама строка будет
                в ascii. Т.е. этот параметр
                не равен размеру возвращаемой
                строки.

    err       - код ошибки. 0 - успех.

    verbose   - текстовая расшифровка ошибки




utf16_to_ascii
    ascii_str, err, verbose = utf16_to_ascii(utf16str, [utf16len])
    преобразовывает строку utf-8 в ascii

    ascii_str - строка в ascii

    utf16str  - указатель на строку в utf-16 LE.

    utf16len  - размер utf-16 LE строки в wchar_t.
                Данный парметр является опциональным,
                если размер не указан, то он будет
                посчитан автоматически, однако
                прямое указание размера ускоряет работу.

    err     - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки




utf16_to_file
    success, err, verbose = utf16_to_file(uft16str, utf16len, file_path)
    Сохраняет uft-16 LE строку в файл.

    success   - флаг успеха выполнения. true/nil

    err     - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки

    utf16str  - указатель на строку в utf-16 LE.

    utf16len  - размер utf-16 LE строки в wchar_t.
                Данный парметр является опциональным,
                если размер не указан, то он будет
                посчитан автоматически, однако
                прямое указание размера ускоряет работу.




utf8_to_ascii
    utf16_str, err, verbose = utf8_to_ascii(utf8str)
    преобразовывает строку utf-8 в ascii

    utf16_str - строка в ascii

    err       - код ошибки. 0 - успех.

    verbose   - текстовая расшифровка ошибки

    utf8str   - строка в uft-8.




utf8_to_utf16
    utf16buf, utf16len, err, verbose = utf8_to_utf16(utf8str)
    преобразовывает строку utf-8 в utf-16 LE

    utf16buf - указатель на строку в utf-16 LE

    utf16len - размер utf-16 LE строки в wchar_t.
               Для преобразования размера в байты
               можете воспользоваться следующим способом:
               utf16len * ffi.sizeof("wchar_t")

    utf8str  - строка в utf-8.

    err     - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки




workdirectory
    result = workdirectory(dir)
    Получает текущую рабочую директорию

    result - рабочая директория.

    dir    - установить новую рабочую директорию.
             Если не задана, то просто вернет текущую.








TIME



clock_hp_resolution
    result = clock_hp_resolution()
    Получает количество тиков в секунду при
    использовании clock_hp() и clock_hp_s()

    result - количество тиков.




sleep
    sleep(time_to_sleep)
    приостановить работу.

    time_to_sleep - время приостановки в секундах.
                    Точность до 1/1000 секунды.




sleep_hp
    sleep_hp(time)
    Задержка с высокой точностью.

    time - время задержки в секундах.




timestamp
    result = timestamp([opt_1, [opt_2]])
    Возвращает форматированный таймштамп вида:
    2024.07.28 13-46-26
    2024.07.28 13-46-26.356 (если вызван с опцией "ms")

    opt_* - опции вывода таймштампа:

            ms     - выводить с тысячными долями секунды

            unique - таймштамп должен отличаться от
                     предыдущего вызова функции с
                     включенной опцией unique.
                     В случае, если время еще не изменилось
                     функция встанет на ожидание и будет
                     проверять время раз в миллисекунду.








WINDOW



GetForegroundWindow
    handle = GetForegroundWindow()
    Получает хэндл активного окна.

    handle - хэндл активного окна.




exec
    exec(str)
    Запуск процесса без ожидания завершения

    str - путь для запуска исполняемого файла.




execandwait
    execandwait(str)
    Запуск процесса с ожиданием его завершения.

    str - путь для запуска исполняемого файла.




exepath
    path, err, verbose = exepath([handle|pid])
    Получает путь к исполняемому файлу.

    path          - массив с результатом
    path.exe      - имя файла
    path.path     - путь к каталогу с файлом
    path.fullpath - полный путь к exe
    Пример:
    path.exe      - cmd.exe
    path.path     - c:\windows\system32\
    path.fullpath - c:\windows\system32\cmd.exe

    err    - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки

    handle - handle процесса информацию о котором получаем
             Значение по умолчанию window.

    pid    - pid процесса информацию о котором получаем

    Внимание! Указывается либо pid либо handle.
    Тип данный pid - number, handle - HWND (void*).




findwindow
    result, err, verbose = findwindow(path, [name, [class, [pos, [pid]]]])
    Функция ищет окна по заданным параметрам.
    Каждый из параметров применяется, как фильтр.
    Любой из параметров можно задать равным
    nil для того, чтобы исключить из фильтрации.
    Например:
    result = findwindow(nil, name, class, nil, nil)
    будет осуществлять поиск только по имени окна и класса.

    result             - массив в котором содержатся результаты.
    result[1]          - первое найденное окно.
    result[2]          - второе найденное окно.
    result[...]        - ...... найденное окно.
    result[N]          -   N    найденное окно.
    result[N].handle   - хэндл окна
    result[N].name     - имя окна
    result[N].class    - имя класса окна
    result[N].x        - x координата левой границы окна
    result[N].y        - y координата верхней границы окна
    result[N].width    - ширина окна
    result[N].height   - высота окна
    result[N].pid      - pid окна
    result[N].tid      - tid окна
    result[N].exe      - имя файла
    result[N].path     - путь к каталогу с файлом
    result[N].fullpath - полный путь к exe

    err     - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки

    path    - путь к исполняемому файлу (exe).
              Задается, как паттерн для regexp.
              Проверка происходит в полном пути.

    name    - заголовок окна. Задается как паттерн
              для regexp.

    class   - имя класса окна. Задается как паттерн
              для regexp.

    pos            - таблица с положением и размером окна.
    pos.min_x      - начальная X координата области поиска
    pos.min_y      - начальная Y координата области поиска
    pos.min_width  - минимальная ширина окна
    pos.min_height - минимальная высота окна
    pos.max_x      - конечная  X координата области поиска
    pos.max_y      - конечная  Y координата области поиска
    pos.max_width  - максимальная ширина окна
    pos.max_height - максимальная высота окна

    pid     - pid процесса.

    Паттерны стандартные для match в lua.
    Используйте '^' для обозначения
    начала строки и '$' для конца строки.
    Например:
    "name"  - найдет все окна, где присутствует "name"
    "^name" - найдет все окна, начинающиеся с "name"
    "name$" - найдет все окна, заканчивающиеся на "name"
    "^name$" - найдет все окна, с точным именм "name"
    Так же допустимо использование ?, .*, [] и т.д.




getcontroltext
    text = getcontroltext(handle)
    Получает текст контрола:
    поля ввода, имена кнопок и т.д.

    text   - текст контрола

    handle - хэндл контрола текст
             которого необходимо получить




getfocus
    handle, err, verbose = getfocus()
    Получает хэндл окна в который
    осуществляется ввод с клавитуры.
    (в котором мигает каретка).

    handle  - хэндл окна с фокусуом клавиватуры.

    err     - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки.




getwindow
    new_handle, err = getwindow(direction, handle)
    Получает хэндл окна относительно
    handle в направлении direction.

    new_handle - хэндл новго окна. Если произошла
                 ошибка - вернет nil.

    err     - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки

    direction  - направление поиска окна.
                 допустимы следующие значения:
                 "first"
                 "last"
                 "next"
                 "prev"
                 "owner"
                 "child"
                 "popup"




getwindowclass
    text, err, verbose = getwindowclass([handle])
    Получает имя класса окна.

    text   - имя класса окна.
             Если ошибка - врент nil.

    err    - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки

    handle - хэндл окна. По умлчанию window.




getwindowtext
    text, err, verbose = getwindowtext([handle])
    Получает текст заголовка окна.

    text    - текст заголовка окна.
              Если ошибка - врент nil.

    err     - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки

    handle  - хэндл окна. По умлчанию window.




isvisible
    result = isvisible(handle)
    Проверяет является ли окно видимым.
    Проверяется именно флаг невидимости.
    Данная функция не предназачена для проверки
    окна на перекрытие другими окнами.

    result - Результат проверки. true - видимое, false - скрыто.

    handle - хэндл проверяемого окна.




postmessage
    result = postmessage([message, [wparam, [lparam, [handle]]]])
    Отсылка сообщений в окна.

    result  - код результата. Индивидуален для message.

    message - сообщение. По умолчанию 0.

    wparam  - wparam параметр сообщения. По умолчанию 0.

    lparam  - lparam параметр сообщения. По умолчанию 0.

    handle  - хэндл окна. Если не указать - работает с window.

    Все параметры опциональные.
    За что именно отвечают wparam и lparam индивидуально
    для каждого сообщения.




sendmessage
    result = sendmessage([message, [wparam, [lparam, [handle]]]])
    Отсылка сообщений в окна.

    result  - код результата. Индивидуален для message.

    message - сообщение. По умолчанию 0.

    wparam  - wparam параметр сообщения. По умолчанию 0.

    lparam  - lparam параметр сообщения. По умолчанию 0.

    handle  - хэндл окна. Если не указать - работает с window.

    Все параметры опциональные.
    За что именно отвечают wparam и lparam индивидуально
    для каждого сообщения.




setaffinity
    result, err, verbose = setaffinity(mask, [handle|pid])
    Устанавливает приоритет для цли.

    result - успех выполнения true/false.

    err    - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки

    mask   - битовая маска соответствия с процессорами.
             Может быть задана числом в виде
             number или ULONG_PTR.
             Внимание number может корректно хранить
             только 52 бита, т.е. 52 процессора.
             Альтернативный способ задать маску
             строка с символами "Y", где
             позиция = номер процессора.
             Прочие символы игнорируются.
             Пример:
             "01YY456Y" - задаст соответствие
             2, 3, 7 процессорам (отсчет с нуля).
             Цифры используются только для удобства
             в качестве разделителя.

    handle - хэндл процесса HWND (void*)
             По умолчанию window.

    pid    - pid процесса (number).




setcontroltext
    lenght = setcontroltext(text, handle)
    Получает текст контрола:
    поля ввода, имена кнопок и т.д.

    lenght - длина установленного заголовка.

    text   - текст контрола.

    handle - хэндл контрола текст
             которого необходимо получить.




setpriority
    result, err, verbose = setpriority(prio, [handle|pid])
    Устанавливает приоритет для цли.

    result - успех выполнения true/false.

    err    - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки

    prio   - желаемый приоритет. Возможные варианты:
             "real"   - реального времени
             "high"   - высокий
             "above"  - выше среднего
             "normal" - средний
             "below"  - ниже среднего
             "idle"   - низкий

    handle - хэндл процесса HWND (void*)
             По умолчанию window.

    pid    - pid процесса (number).




setwindowtext
    err, verbose = setwindowtext([text, [handle]])
    Установит новый заголовок для окна handle.

    err     - вернет nil, если ошибка, true - успех.

    verbose - текстовая расшифровка ошибки

    text    - текст новго заголовка. Может быть nil.

    handle  - хэндл окна имя которого будет изменяться.
              По умолчанию window.




showwindow
    result = showwindow([state, [handle]])
    Изменяет состояние окна handle на состояние state

    result - Если окно ранее было видимым, возвращаемое значение равно true.
             Если окно ранее было скрыто , возвращаемое значение равно false.

    handle - хэндл окна с которым производится действие. По умолчанию window.
    state - состояние окна. По умолчанию na.
    Допустимые значения кратко:
    "na"            - вытащить на передний план.
    "top"           - псевдоним для na.
    "hide"          - скрыть
    "maximize"      - развернуть на весь экран
    "show"          - сделать видимым (анти-hide)
    "minimize"      - свернуть
    "restore"       - отменить сворачивание, отменить на весь экран

    Полный набор флагов state и полная расшифровка:
    "hide"          - Скрывает окно и активирует другое окно.
    "normal"        - Активирует и отображает окно. Если окно свернуто,
                      развернуто или упорядочено, система восстанавливает
                      его исходный размер и положение. Приложение должно
                      указать этот флаг при первом отображении окна.
    "minimized"     - Активирует окно и отображает его как свернутое окно.
    "maximize"      - Активирует окно и отображает его в виде развернутого окна.
    "noactivate"    - Отображает окно с последним размером и положением.
                      Это значение похоже на SW_SHOWNORMAL, за исключением
                      того, что окно не активировано.
    "show"          - Активирует окно и отображает его
                      в текущем размере и положении.
    "minimize"      - Свертывание указанного окна и активация следующего
                      окна верхнего уровня в порядке Z.
    "minnoactive"   - Отображает окно в виде свернутого окна.
                      Это значение похоже на SW_SHOWMINIMIZED,
                      за исключением того, что окно не активировано.
    "na"            - Отображает окно в его текущем размере и положении.
                      Это значение похоже на SW_SHOW, за исключением того,
                      что окно не активировано.
    "top"           - псевдоним для na.
    "restore"       - Активирует и отображает окно. Если окно свернуто,
                      развернуто или упорядочено, система восстанавливает
                      его исходный размер и положение. Приложение должно
                      указать этот флаг при восстановлении свернутого окна.
    "default"       - Задает состояние отображения на основе значения SW_ ,
                      указанного в структуре STARTUPINFO , переданной
                      в функцию CreateProcess программой,
                      которая запустила приложение.
    "forceminimize" - Свертывание окна, даже если поток, которому
                      принадлежит окно, не отвечает. Этот флаг следует
                      использовать только при минимизации окон
                      из другого потока.




terminate
    result, err, verbose = terminate(victim, name, class, pos, pid)
    Форсированно завершает процесс.

    result  - успех выполнения true/nil.

    err     - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки

    вариант 1
    victim  - можеть быть задан хэндлом тип HWND (cdata void*)
              name, class, pos, pid - игнорируются.

    вариант 2
              Любой из параметров может быть nil,
              для исключения его из фильтрации.

    victim  - путь к исполняемому файлу (exe).
              Задается, как паттерн для regexp.
              Проверка происходит в полном пути.

    name    - заголовок окна. Задается как паттерн
              для regexp.

    class   - имя класса окна. Задается как паттерн
              для regexp.

    pos            - таблица с положением и размером окна.
    pos.min_x      - начальная X координата области поиска
    pos.min_y      - начальная Y координата области поиска
    pos.min_width  - минимальная ширина окна
    pos.min_height - минимальная высота окна
    pos.max_x      - конечная  X координата области поиска
    pos.max_y      - конечная  Y координата области поиска
    pos.max_width  - максимальная ширина окна
    pos.max_height - максимальная высота окна

    pid     - pid процесса.




tohandle
    HWND = tohandle()
    Переобразут хэндл заданный number,
    в HWND (он же void*).

    HWND - number преобразованный в HWND.




windowfromcursor
    handle, err, verbose = windowfromcursor(x, y)
    Возвращает окно под координатами x, y.

    handle  - хэндл найденного окна.
              Если ошибка - вернет nil.

    err     - код ошибки на этапе получения
              координат мышки. 0 - успех.

    verbose - текстовая расшифровка ошибки

    x       - x координата поиска.

    y       - y координата поиска.




windowfrompoint
    handle = windowfrompoint(x, y)
    Возвращает окно под координатами x, y.

    handle - хэндл найденного окна.
             Если ошибка - вернет nil.

    x      - x координата поиска.

    y      - y координата поиска.




windowpid
    pid, tid, err, verbose = windowpid([handle])
    Вернет pid и tid процесса и потока.

    pid     - pid процесса которому принадлежит окно.

    tid     - tid потока который создал окно.

    err     - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки

    handle  - хэндл окна данные которого запрашиваются.
              По умолчанию window.




windowpos
    result, err, verbose = windowpos([pos], [handle])
    Функция перемещает окно в заданный pos,
    если pos не задан просто вернет текущее положение.

    result  - таблица с итоговым положением окна:
              result.x - начальная X координата
              result.y - начальная Y координата
              result.width  - ширина окна
              result.height - высота окна
              если произошла ошибка, то вместо
              таблицы вернет nil.

    err     - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки

    pos     - таблица с желаемым положением
              и размером окна.
              Структура аналогична result.
              result.x - начальная X координата
              result.y - начальная Y координата
              result.width  - ширина окна
              result.height - высота окна
              любое из полей может отсутствовать (nil).
              Если какое либо поле отсутствует,
              оно будет оставлено без изменений.

    handle  - хэндл окна с которым будет
              работать функция.
              Тип данных - HWND (он же void *).
              Для преобразования числа в HWND
              используйте функцию tohandle(number).
              Если handle не задан - будет работать
              с глобальной переменной window,
              которая так же должна быть HWND.
              window = tohandle(number)




workwindow
    prev_handle, err, verbose = workwindow(path, name, class, pos, pid)
    prev_handle, err, verbose = workwindow(handle)
    Устанавливает рабочее окно
    (глобальная переменная window),
    если переданы параметры нового
    рабочего окна.
    Возвращает текущее рабочее окно.

    prev_handle - предыдущий хэндл рабочего окна

    err     - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки

    вариант 1
    handle - можеть быть задан хэндлом (cdata void*)
             либо числом равным хэндлом (number),
             name, class, pos, pid - игнорируются.

    вариант 2
    path  - путь к исполняемому файлу (exe).
            Задается, как паттерн для regexp.
            Проверка происходит в полном пути.

    name  - заголовок окна. Задается как паттерн
            для regexp.

    class - имя класса окна. Задается как паттерн
            для regexp.

    pid   - pid процесса.

    Паттерны стандартные для match в lua.
    Используйте '^' для обозначения
    начала строки и '$' для конца строки.
    Например:
    "name"  - найдет все окна, где присутствует "name"
    "^name" - найдет все окна, начинающиеся с "name"
    "name$" - найдет все окна, заканчивающиеся на "name"
    "^name$" - найдет все окна, с точным именм "name"
    Так же допустимо использование ?, .*, [] и т.д.

    Внимание!
    В случае 3 варианта синтаксиса рабочим окном
    будет сделано первое найденное.
    Самое близкое к поверхности рабочего стола
    (последнее активное).
    Любой из параметров может быть nil для
    исключения фильтрации по этому параметру.




Получаем
    Получаем информацию об окне по его хэндлу.
    info, err, verbose = windowinfo(handle)

    info - массив с информацией об окне.

    info.handle   - хэндл окна
    info.name     - имя окна
    info.class    - имя класса окна
    info.x        - x координата левой границы окна
    info.y        - y координата верхней границы окна
    info.width    - ширина окна
    info.height   - высота окна
    info.pid      - pid окна
    info.tid      - tid окна
    info.exe      - имя файла
    info.path     - путь к каталогу с файлом
    info.fullpath - полный путь к exe

    err  - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки








KEYBOARD



getlayout
    layout = getlayout([handle])
    получает активную раскладку клавиатуры

    layout - раскладка клавиатуры

    handle - хэндл окна.
             По умолчанию window.




getlayoutlist
    layout, err, verbose = getlayoutlist()
    Получает список всех раскладок
    клавиатуры в системе.

    layout  - таблица с хэндлами раскладок

    err     - код ошибки. 0 - успех.

    verbose - текстовая расшифровка ошибки




keystate
    state, toggle = keystate(button)
    Получает состояние нажата ли клавиша

    state  - true - нажата, false - нет.

    toggle - горит ли лампочка кнопки
             актуально только для
             num_lock, caps_lock, scroll_lock,
             для других клавиш при каждом нажатии
             меняет свое состояние
             если было true, то на false,
             если было false, то на true.

    button - клавиша для проверки.
             Может быть задана строкой или числом.
             Строка указывает на имя клавиши,
             например, "ctrl", "a", "1".
             Если строка задана числом,
             то вернет состояние виртуальной
             клавиши с данным номером.
             Внимание!
             keystate(1) - задано числом, вернет
             состояние клавиши с кодом 1
             (левая кнопка мыши)
             keystate("1") - вернет состояние
             клавиши 1 на клавиатуре.
             Подробнее ознакомиться со списком
             клавиш можно в файле key_code.lua.




keystateasync
    state, toggle = keystateasync(button)
    Получает состояние нажата ли клавиша

    state  - true - нажата, false - нет.

    toggle - было ли нажатие клавиши с момента
             прошлого вызова keystateasync.

    button - клавиша для проверки.
             Может быть задана строкой или числом.
             Строка указывает на имя клавиши,
             например, "ctrl", "a", "1".
             Если строка задана числом,
             то вернет состояние виртуальной
             клавиши с данным номером.
             Внимание!
             keystate(1) - задано числом, вернет
             состояние клавиши с кодом 1
             (левая кнопка мыши)
             keystate("1") - вернет состояние
             клавиши 1 на клавиатуре.
             Подробнее ознакомиться со списком
             клавиш можно в файле key_code.lua.




setlayout
    setlayout(new_layout)
    Меняет активную раскладку.

    new_layout - новая раскладка. Может быть
                 задана хэндлом либо числом.

    Примечание:
    Ошибки нормально не выбрасывает,
    можно вытащить результат
    через DefWindowProc, смысла
    реализовывать на данный момент не вижу.




Клавиши
    Клавиши эмуляция.

    key(button, [mod_1, [mod_2, ...]], [handle])
        Нажимает клавишу button, с возможностью
        зажатых модификаторов.

        button - клавиша которая должна быть нажата.

        mod_*  - модификатор который должен быть
                 зажат во время нажатия button.
                 Предполагается возможное зажатие
                 "shift", "ctrl", "alt", но
                 не ограничиваясь ими.
                 Количество не ограничено.
                 Подробнее ознакомиться со списком
                 клавиш можно в файле key_code.lua.

        handle - хэндл окна в котрое посылать нажатие.
                 Только для send и post.


    down(button, system, [handle])
        Зажать клавишу button.

        button - клавиша которая должна быть зажата.

        system - только для send и post.
                 флаг того, что клавиша должна
                 быть зажата системно с использованием
                 WM_SYSKEYDOWN.
                 Возможные значения: nil/true/false.
                 По умолчанию nil.

        handle - хэндл окна в котрое посылать нажатие.
                 Только для send и post.


    up(button, system, [handle])
        Отжать клавишу button.

        button - клавиша которая должна быть отжата.

        system - только для send и post.
                 флаг того, что клавиша должна
                 быть отжата системно с использованием
                 WM_SYSKEYUP.
                 Возможные значения: nil/true/false.
                 По умолчанию nil.

        handle - хэндл окна в котрое посылать нажатие.
                 Только для send и post.


    text(text, [handle])
        Написать текст text.

        text   - текст для ввода.
                 Если среда выполнения не является
                 редактором uopilot версии 2.42 и ниже,
                 то текст должен быть в utf8.

        handle - хэндл окна в котрое посылать нажатие.
                 Только для send и post.


    Примечания.
    send, post методы могут отправлять сочетания
    клавиш не зажимая alt, ctrl, shift для всей
    системы. При этом может наблюдаться отсутствие
    эффекта при комбинировании с реальной клавитурой.
    Т.е. если программно зажать alt через send или post,
    а затем нажать F4 на реально клавиатуре - блокнот
    не закроется. При этом полностю программная эмуляция
    post("F4", "alt") прекрасно работает.
    keystate("alt") так же будет говорить что alt не нажат.

    При использвании down и up в send и post
    они будут пытаться автоматически определить
    необходимость эмулировать системное нажатие
    из-за использованя alt и F10.
    Тем не менее настоятельно рекомендуются использовать
    их симметрично. Т.е. если вы нажимали что-то
    через down, то эта кнопка должна быть отжата
    через up, а не другим методом или физической
    клавиатурой. Аналогично не стоит пытаться
    отжать с помощью up клавиши которые вы не нажимали
    с помощью down.
    В противном случае может возникнуть путаница
    с флагами системного нажатия.
    Если все-таки очень хочется, то:
    1) выше описанные проблемы касаются исключительно
    сочетаний клавиш с ctrl, alt и F10. Перепутанный флаг
    ctrl может повлиять только на alt. Если alt не используете,
    то последствий быть не должно.
    2) при работе с alt и F10 прямо задавайте флаг
    системного нажатия либо обычного.
    Логика работы винды при обработке системных клавиш:
    if keydown then
        if key == alt
            if ctrl_pressed then
                msg = 0x100
            else
                msg = 0x104
            end
        elseif key == f10 then
            msg = 0x104
        else
            if alt_pressed then
                msg = 0x104
            else
                msg = 0x100
            end
        end
    end
    if keyup then
        if key == alt then
            -- none_nonsys_was_unpressed
            -- именно было ли ли отжатие
            -- какой-либо не системной клавиши
            -- после нажатия альта.
            -- Это НЕ текущее состояние каких-либо клавиш.
            if ctrl_was_pressed_before_alt then
                msg = 0x101
            else
                if none_nonsys_was_unpressed or ctrl_pressed then
                    msg = 0x105
                else
                    msg = 0x101
                end
            end
        else
            if alt_pressed or key == F10 then
                msg = 0x105
            else
                msg = 0x101
            end
        end
    end








MOUSE



mousepos
    x, y = mousepos(abs_flag)
    Получение текущих координат курсора.

    x - x координата курсора

    y - y координата курсора

    abs - флаг того, что координаты
          нужны абсолютные




Клик
    Клик мышью.
    Функции и параметры методов соответственно
    содержатся подмассивах методов:
    send
    post
    event
    input
    Функции кликов:
    move              (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    left              (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    left_down         (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    left_up           (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    left_double       (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    right             (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    right_down        (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    right_up          (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    right_double      (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    middle            (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    middle_down       (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    middle_up         (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    middle_double     (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    m4                (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    m4_down           (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    m4_up             (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    m4_double         (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    m5                (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    m5_down           (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    m5_up             (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    m5_double         (<x, y>|<crds_table>, ["abs"], [modifer], [handle])
    wheel_up          (<x, y>|<crds_table>, ["abs"], [count], [modifer], [handle])
    wheel_down        (<x, y>|<crds_table>, ["abs"], [count], [modifer], [handle])
    wheel_left        (<x, y>|<crds_table>, ["abs"], [count], [modifer], [handle])
    wheel_right       (<x, y>|<crds_table>, ["abs"], [count], [modifer], [handle])

    Координаты могут быть заданы напрямую двумя числами x и y,
    либо таблицей (для прямой совместимости с результатми findimage и findcolor)
    x                 - x координата клика

    y                 - y координата клика

    crds_table        - таблица в которой содержатся x и y координаты.
                        Таблица анализируется согласно типам данных,
                        координатами признаются в порядке убывания
                        приоритета:
                        crds_table.x         crds_table.y
                        crds_table[1]        crds_table[2]
                        crds_table[1].x      crds_table[1].y
                        crds_table[1][1]     crds_table[1][2]

    "abs"             - флаг того, что координаты абсолютные.
                        Т.е. x=0, y=0 - верхний левый угол экрана,
                        а не окна.

    count             - количество прокруток колесом
                        (только для wheel_* функций)

    modifer           - массив с модификаторами
                        указывающий какие клавиши
                        зажаты при клике.
                        Допустимые значения:
                        "shift"
                        "ctrl"
                        "alt"
                        "move"        (только для event и input)
                        "left_down"
                        "left_up"     (только для event и input)
                        "right_down"
                        "right_up"    (только для event и input)
                        "middle_down"
                        "middle_up"   (только для event и input)
                        только один из группы одновременно:
                        "m4_down"
                        "m4_up"       (только для event и input)
                        "m5_down"
                        "m5_up"       (только для event и input)
                        "wheel_down"  (только для event и input)
                        "wheel_up"    (только для event и input)
                        "wheel_right" (только для event и input)
                        "wheel_left"  (только для event и input)

    handle            - хэндл окна. По умолчанию window.
                        Если указан "abs",
                        то handle игнорируется.


    Каждый метод имеет свои внутренние
    таймауты в комбинированных кликах (down+up)
    (left, right, middle, mouse4, mouse5).

    timeout_move      - явная пауза между move в точку
                        клика и событием down.
                        Имеет смысл только при
                        По умолчанию 0.

    timeout_inner     - явная пауза между down и up.
                        По умолчанию 10.

    timeout_outer     - пауза между up и down.
                        Фактически это пауза между
                        двумя вызовами, например, парой left
                        или между left и right.
                        Данная пауза является не блокирующей,
                        т.е. если вы совершили некторый клик,
                        и выполняете иные действия в коде
                        не связанные с кликами, то таймер все
                        равно продолжает исчислятся,
                        вплоть до нуля, что привидет к тому,
                        что следующий клик будет совершен без
                        каких либо дополнительных задержек.
                        По умолчанию 10.

    clock_up          - время прошлого события up в
                        комбинированных кликах. Используется
                        для рассчета таймера на следующий клик.
                        При комбинированных кликах обновляется
                        автоматически.
                        Можно использовать для неблокирующей
                        дополнительной задержки пред
                        следующим кликом. Например:
                        clock_up = os.clock() + 2
                        укажет, что следующий клик должен
                        произойти не ранее чем через
                        2 секунды + timeout_outer
                        с текущего момента.

    Опции методов:

    move_split        - Перемещение и клик могут быть
                        объедены либо разделены в один
                        вызов WinAPI функции
                        (работает только для event и input).
                        При выключенном разделении
                        timeout_move будет проигнорирован.
                        true - разделить, false - объеденить.
                        По умолчанию false.

    move_before_click - Включить перемещение мыши
                        перед кликом.
                        event и input методы фактически
                        кликают только в текущую позицию
                        курсора, move необходим им
                        для корректной работы.
                        По умолчанию для event и input true,
                        для остальных методов - false.

    move_after_click  - Возвращать мышь после клика
                        на исходную позицию.
                        По умолчанию false.

    move_func         - функция для перемещения мыши, которая
                        будет использована при
                        move_before_click и move_after_click.
                        Наиболее актуально для send и post
                        методов, т.к. встроенный move очень
                        специфичный и может не работать с
                        некоторыми приложениями.
                        По умолчанию функция из того же метода,
                        что и клик (send.move для send.left и т.д.).

    mod_func          - массив с функциями которые будут
                        использованы для зажатия модификаторов
                        shift, ctrl, alt.
                        Внимание! Это именно массив, а не функция.
                        Массив должен содержать функции down и up.
                        По умолчанию:
                        send  -> kbd.send
                        post  -> kbd.send (!)
                        event -> kbd.event
                        input -> kbd.input

    mod_inner         - send и post имеют встроенный функционал
                        для передачи клика с флагом shift, ctrl,
                        но не alt. Если эта опция включена -
                        send и post будут использовать именно
                        внутренние флаги для shift и ctrl, для
                        alt будет использована mod_func.
                        Если выключено, то для всех модификаторов
                        клавиатуры будет использован mod_func.
                        Возможные значения: true/false.
                        Значение по умолчанию false.

    Пример вызова:
    left_down (100, 200, "abs")
    left_up   (100, 200, {"ctrl", "shift"})
    left      (100, 200, "abs", {"ctrl", "shift"})
    wheel_down(100, 200,     2, {"ctrl", "shift"})


    Примечание.
    Все нижеследующие ограничения обусловлены
    реализацией WinAPI, а не текущим модулем.


    Для SEND и POST:
    Все действия производятся с окном напрямую
    не затрагивая реальный курсор и клавиатуру
    (за исключением модификатора "alt").

    Модификатор "alt" в явном виде не поддерживается.
    Для его зажатия используется эмуляция клавиатуры.
    Т.е. клавиша будет зажата для всей системы.
    Время изменения состояния минимизировано,
    но это может создавать помехи при работе в других
    приложениях, а ручное нажатие/отжатие alt с
    некоторой будет вероятностью сбивать клик.

    Данная функция не поддерживает abs.
    Клик в абсолютные координаты эмулируется
    вызовом windowfrompoint, windowpos,
    рассчетом смещения и явной передачей хэндла.

    Количество прокруток за один вызов
    не должно привышать 273.


    Для EVENT, INPUT:

    Все действия влияют на реальный курсор мыши.

    Данная функция не поддерживает handle.
    Клик в относительыне координаты является
    вызовом windowpos, рассчетом смещения.

    Модификаторы "shift", "ctrl", "alt"
    в явном виде не поддерживаются.
    Для их зажатия используется эмуляция клавиатуры.
    Т.е. клавиши будет зажаты для всей системы.



