ORPA-pyOpenRPA/Sources/GuideSphinx/Robot/02_uidesktop.rst

.. _module.robot.uidesktop:

####################################
2. Функции UIDesktop
####################################


************************
Общее
************************
Здесь представлено описание всех функций, которые используются для взаимодействия с UI интерфейсами локальных приложений.

**Функции в модуле UIDesktop именуются по следующему принципу:**
<Входящий аргумент>_<действие>_<исходящий аргумент - если присутствует>

**Термины и определения:**

- **UIO:** Объект пользовательского интерфейса
- **UIOSelector:** Селектор (адрес) одного и/или более UIO объектов. Селектор представлен в формате списка (list) словарей (dict) атрибутивных критериев.

**************************************************
Описание функций
**************************************************


.. automodule:: pyOpenRPA.Robot.UIDesktop
    :members:
    :autosummary:

************************
Селектор UIO
************************

Селектор UIO - адрес одного и/или более UIO объектов. Селектор представлен в формате списка (list) словарей (dict) атрибутивных критериев. Поддерживает формат JSON, что позволяет обеспечить удобство форматирования и передачи через web интерфейс студии / оркестратора.

UIO селектор — это список характеристических словарей (спецификаций UIO). Данные спецификации UIO содержат условия, с помощью которых библиотека pyOpenRPA определит UIO, удовлетворяющий условиям, заданным в спецификации UIO. Индекс спецификации UIO в списке UIO селектора харакетризует уровень вложенности целевого UIO. Говоря другим языком, UIO селектор — это перечень условий, под которые может попасть 0, 1 или n UIO.

Ниже приведен перечень атрибутов — условий, которые можно использовать в спецификациях UIO:

**Формат селектора:**

[
    {
        
        "depth_start" :: [int, начинается с 1] :: глубина, с которой начинается поиск (по умолчанию 1),
        
        "depth_end" :: [int, начинается с 1] :: глубина, до которой ведется поиск (по умолчанию 1),
        
        "ctrl_index" || "index" :: [int, начинается с 0] :: индекс UIO в списке у родительского UIO,
        
        "title" :: [str] :: идентичное наименование атрибута *title* искомого объекта UIO,
        
        "title_re" :: [str] :: регулярное выражение (python диалект) для отбора UIO, у которого атрибут *title* должен удовлетворять условию данного регулярного выражения,
        
        "rich_text" :: [str] :: идентичное наименование атрибута *rich_text* искомого объекта UIO,
        
        "rich_text_re" :: [str] :: регулярное выражение (python диалект) для отбора UIO, у которого атрибут *rich_text* должен удовлетворять условию данного регулярного выражения,
        
        "class_name" :: [str] :: идентичное наименование атрибута *class_name* искомого объекта UIO,
        
        "class_name_re" :: [str] :: регулярное выражение (python диалект) для отбора UIO, у которого атрибут *class_name* должен удовлетворять условию данного регулярного выражения,
        
        "friendly_class_name" :: [str] :: идентичное наименование атрибута *friendly_class_name* искомого объекта UIO,
        
        "friendly_class_name_re" :: [str] :: регулярное выражение (python диалект) для отбора UIO, у которого атрибут *friendly_class_name* должен удовлетворять условию данного регулярного выражения,
        
        "control_type" :: [str] :: идентичное наименование атрибута *control_type* искомого объекта UIO,
        
        "control_type_re" :: [str] :: регулярное выражение (python диалект) для отбора UIO, у которого атрибут *control_type* должен удовлетворять условию данного регулярного выражения,
        
        "is_enabled" :: [bool] :: признак, что UIO доступен для выполнения действий,
        
        "is_visible" :: [bool] :: признак, что UIO отображается на экране,
        
        "backend" :: [str, "win32" || "uia"] :: вид способа адресации к UIO (по умолчанию "win32"). Внимание! Данный атрибут может быть указан только для первого элемента списка UIO селектора. Для остальных элементов списка данный атрибут будет проигнорирован.
    
    },
    { ... спецификация UIO следующего уровня иерархии }
]

**Пример UIO селектора:**
[
    {"class_name":"CalcFrame", "backend":"win32"}, # Спецификация UIO 1-го уровня вложенности
    {"title":"Hex", "depth_start":3, "depth_end": 3} # Спецификация UIO 1+3-го уровня вложенности (так как установлены атрибуты depth_start|depth_stop, определяющие глубину поиска UIO)
]


**UIO объект - свойства и методы (общие)**

- process_id(): Возвращает идентификатор процесса, которому принадлежит это окно
- window_text(): Текст окна элемента. Довольно много элементов управления имеют другой текст, который виден, например, элементы управления редактированием обычно имеют пустую строку для window_text, но все равно имеют текст, отображаемый в окне редактирования.
- rectangle(): Возвращает прямоугольник элемента: {"сверху", "слева", "справа", "снизу"} Прямоугольник() - это прямоугольник элемента на экране. Координаты указаны в левом верхнем углу экрана. Этот метод возвращает прямоугольную структуру, которая имеет атрибуты - top, left, right, bottom. и имеет методы width() и height(). См. раздел win32structures.Прямую кишку для получения дополнительной информации.
- right_click_input(coords=(None, None)): Щелкните правой кнопкой мыши на указанных координатах
- click_input(button='left', coords=(None, None), button_down=True, button_up=True, double=False, wheel_dist=0, use_log=True, pressed='', absolute=False, key_down=True, key_up=True): Щелкните по указанным координатам кнопкой мыши, чтобы щелкнуть. Один из "влево", "вправо", "посередине" или "x" (по умолчанию: "влево", "переместить" - это особый случай) определяет координаты, по которым нужно щелкнуть.(По умолчанию: центр элемента управления) дважды Укажите, следует ли выполнять двойной щелчок или нет (по умолчанию: False) wheel_dist Расстояние для перемещения колеса мыши (по умолчанию: 0) Внимание: Этот метод отличается от метода щелчка тем, что он требует, чтобы элемент управления был виден на экране, но выполняет более реалистичную симуляцию щелчка. Этот метод также уязвим, если пользователь перемещает мышь, поскольку это может легко переместить мышь с элемента управления до завершения click_input.
- double_click_input(button='left', coords=(None, None)): Дважды щелкните по указанным координатам
- press_mouse_input(button='left', coords=(None, None), pressed='', absolute=True, key_down=True, key_up=True): Нажмите кнопку мыши с помощью SendInput
- drag_mouse_input(dst=(0, 0), src=None, button='left', pressed='', absolute=True): Нажмите на src, перетащите его и перетащите на dst dst - это объект-оболочка назначения или просто координаты. src - это исходный объект-оболочка или координаты. Если src равен None, self используется в качестве исходного объекта. кнопка - это кнопка мыши, которую нужно удерживать во время перетаскивания. Это может быть “влево”, “вправо”, “посередине” или “x”. Нажата клавиша на клавиатуре, которую нужно нажимать во время перетаскивания. абсолютные указывает, следует ли использовать абсолютные координаты для расположения указателя мыши
- wheel_mouse_input(coords=(None, None), wheel_dist=1, pressed=''): Прокрутить колесо мыши
- draw_outline(colour='green', thickness=2, fill=<MagicMock name='mock.win32defines.BS_NULL' id='140124673757368'>, rect=None): Нарисуйте контур вокруг окна. цвет может быть либо целым числом, либо одним из "красного", "зеленого", "синего" (по умолчанию "зеленый") толщина толщина прямоугольника (по умолчанию 2) заливка как заполнить прямоугольник (по умолчанию BS_NULL) укажите координаты прямоугольника для рисования (по умолчанию используется прямоугольник элемента управления)
- element_info: Свойство, доступное только для чтения, для получения объекта ElementInfo
- from_point(x, y): Получить объект-оболочку для элемента в заданных координатах экрана (x, y)
- get_properties(): Возвращает свойства элемента управления в виде словаря.
- is_child(parent): Возвращает значение True, если этот элемент является дочерним элементом ‘parent’. Элемент является дочерним элементом другого элемента, когда он является прямым элементом другого элемента. Элемент является прямым потомком данного элемента, если родительский элемент является цепочкой родительских элементов для дочернего элемента.
- is_dialog(): Возвращает значение True, если элемент управления является окном верхнего уровня
- is_enabled(): Независимо от того, включен элемент или нет. Проверяет, что как родительский элемент верхнего уровня (возможно, диалоговое окно), которому принадлежит этот элемент, так и сам элемент включены.Если вы хотите дождаться, пока элемент станет включенным (или дождаться, пока он станет отключенным), используйте Application.wait('visible') или Application.wait_not('visible').Если вы хотите немедленно вызвать исключение, если элемент не включен, вы можете использовать BaseWrapper.verify_enabled(). Функция BaseWrapper.Verify Ready() вызывается, если окно одновременно не видно и не включено.
- is_visible(): Является ли элемент видимым или нет. Проверяет, видны ли как родительский элемент верхнего уровня (возможно, диалоговое окно), которому принадлежит этот элемент, так и сам элемент. Если вы хотите дождаться, пока элемент станет видимым (или дождаться, пока он станет скрытым), используйте Application.wait('visible') или Application.wait_not('visible'). Если вы хотите немедленно вызвать исключение, если элемент не виден, вы можете использовать BaseWrapper.verify_visible(). Базовая оболочка.verify_actible() вызывается, если элемент одновременно не виден и не включен.
- parent(): Возвращает родительский элемент этого элемента Обратите внимание, что родительским элементом элемента управления не обязательно является диалоговое окно или другое главное окно. Например, поле группы может быть родительским для некоторых переключателей. Чтобы получить главное (или окно верхнего уровня), затем используйте BaseWrapper.top_level_parent().
- root(): Возвращаемая оболочка для корневого элемента (рабочий стол)
- set_focus(): Установить фокус на этот элемент
- texts(): Возвращает текст для каждого элемента этого элемента управления Это список строк для элемента управления. Часто переопределяется извлечение всех строк из элемента управления с несколькими элементами. Это всегда список с одной или несколькими строками: Первый элемент - это текст окна элемента управления Последующие элементы содержат текст любых элементов элемента управления (например, элементы в listbox/combobox, вкладки в tabcontrol)
- type_keys(keys, pause=None, with_spaces=False, with_tabs=False, with_newlines=False, turn_off_numlock=True, set_foreground=True, vk_packet=True): Введите ключи для элемента с помощью клавиатуры.send_keys. Ограниченная функциональность. Для более полной функциональности рекомендуем ознакомится с pyOpenPRA.Robot.Keyboard
- was_maximized(): Проверить, было ли окно развернуто перед сворачиванием или нет

**UIO свойства и методы (дополнение к базовым методам для win32 элементов)**

**Кнопка (Button || CheckBox || RadioButton || GroupBox)**

- check(): Установить флажок
- uncheck(): Снять флажок
- get_check_state(): Вернуть состояние проверки флажка. Состояние проверки представлено целым числом 0 - непроверено 1 - проверено 2 - неопределенно. Следующие константы определены в модуле win32defines BST_UNCHECKED = 0 BST_CHECKED = 1 BST_INDETERMINATE = 2
- click(button='left', pressed='', coords=(0, 0), double=False, absolute=False): Клик на кнопку управления
- is_checked(): Возвращает True, если флажок установлен, False, если флажок не установлен, None, если значение не определено
- is_dialog(): Кнопки никогда не являются диалоговыми окнами, поэтому возвращайте значение False
- set_check_indeterminate(): Установить флажок в положение неопределенный
- friendly_class_name(): Возвращает имя класса кнопки. Они могут выглядеть следующим образом: Кнопки, этот метод возвращает “Button”; Флажки, этот метод возвращает “флажок”; RadioButtons, этот метод возвращает “RadioButton”; GroupBoxes, этот метод возвращает “GroupBox”

**Поле выбора нескольких значений из списка (ComboBox)**

- friendlyclassname = 'ComboBox'
- windowclasses = ['ComboBox', 'WindowsForms\\d*\\.COMBOBOX\\..*', '.*ComboBox']
- dropped_rect(): Получить выпадающий прямоугольник в поле со списком
- get_properties(): Возвращает свойства элемента управления в виде словаря
- item_count(): Возвращает количество элементов в поле со списком
- item_data(item): Возвращает данные элемента, связанные с элементом, если таковые имеются
- item_texts(): Возвращает текст элементов выпадающего списка
- select(item): Выбрать элемент со списком элемент может быть либо индексом элемента для выбора на основе 0, либо строкой, которую вы хотите выбрать
- selected_index(): Возвращает выбранный индекс
- selected_text():Возвращает выделенный текст
- texts(): Возвращает текст элементов в выпадающем списке

**Поле ввода (Edit)**

- friendlyclassname = 'Edit'
- windowclasses = ['Edit', '.*Edit', 'TMemo', 'WindowsForms\\d*\\.EDIT\\..*', 'ThunderTextBox', 'ThunderRT6TextBox']
- get_line(line_index): Возвращает указанную строку
- line_count(): Возвращает, сколько строк есть в редактировании
- line_length(line_index): Возвращает количество символов в строке
- select(start=0, end=None): Установите выбор редактирования элемента управления редактированием
- selection_indices(): Начальный и конечный индексы текущего выбора
- set_edit_text(text, pos_start=None, pos_end=None): Задать текст элемента управления редактированием
- set_text(text, pos_start=None, pos_end=None): Задать текст элемента управления редактированием
- set_window_text(text, append=False): Переопределите set_window_text для элементов управления редактированием, поскольку он не должен использоваться для элементов управления редактированием. Элементы управления редактированием должны использовать либо set_edit_text(), либо type_keys() для изменения содержимого элемента управления редактированием.
- text_block(): Получить текст элемента управления редактированием
- texts(): Получить текст элемента управления редактированием

**Поле выбора 1-го значения из списка (ListBox)**

- friendlyclassname = 'ListBox'
- windowclasses = ['ListBox', 'WindowsForms\\d*\\.LISTBOX\\..*', '.*ListBox']
- get_item_focus(): Возвращает индекс текущего выбора в списке
- is_single_selection(): Проверить, имеет ли поле списка режим одиночного выбора
- item_count(): Возвращает количество элементов в списке
- item_data(i): Возвращает item_data, если таковые имеются, связанные с элементом
- item_texts(): Возвращает текст элементов списка
- select(item, select=True): Выбрать элемент списка элемент может быть либо индексом элемента для выбора на основе 0, либо строкой, которую вы хотите выбрать
- selected_indices(): Выбранные в данный момент индексы списка
- set_item_focus(item): Установить фокус по элементу
- texts(): Получить текст элемента управления редактированием

**Выпадающее меню (PopupMenu)**

- friendlyclassname = 'PopupMenu'
- windowclasses = ['#32768']
- is_dialog(): Возвращает, является ли это диалогом

**Текст (Static)**

- friendlyclassname= 'Static'
- windowclasses= ['Static', 'WindowsForms\\d*\\.STATIC\\..*', 'TPanel', '.*StaticText']


**Инициализация 2-х разрядностей для UIO**

pyOpenRPA позволяет обеспечить максимальную совместимость со всеми приложениями, которые выполняются на компьютере. Мы рекомендуем разрабатывать робота под интерпретатором Python x64. В дополнение к нему Вы можете подключить Python x32 (см. ниже пример подключения). Если планируемый робот не будет взаимодействовать через pyOpenRPA.Robot.UIDesktop с другой разрядность, то эту настройку можно не применять.

.. code-block:: python

    from pyOpenRPA.Robot import UIDesktop
    # В нашем случае процесс робота будет исполняться на Python x64. Дополнительно подключим Python x32 (делать это только, если вы планируете работать в другой разрядностью в рамках робота)
    lPyOpenRPA_SettingsDict = {
            "Python32FullPath": "..\\Resources\\WPy32-3720\\python-3.7.2\\python.exe",# Путь к интерпретатору Python.exe x32
            "Python64FullPath": "..\\Resources\\WPy64-3720\\python-3.7.2.amd64\\python.exe", # Путь к интерпретатору Python.exe x64
            "Python32ProcessName": "pyOpenRPA_UIDesktopX32.exe", # Наименование процесса робота x32 в диспетчере задач. Установите свое наименование
            "Python64ProcessName": "pyOpenRPA_UIDesktopX64.exe" # Наименование процесса робота x64 в диспетчере задач. Установите свое наименование
    }
    # Инициализировать 2-й разрядность.
    UIDesktop.Utils.ProcessBitness.SettingsInit(lPyOpenRPA_SettingsDict)
    # Теперь при вызове функций pyOpenRPA.Robot.UIDesktop платформа pyOpenRPA будет отслеживать разрядность приложения и отправлять соответсвующий вызов на идентичную разрядность.


******************************
Быстрая навигация
******************************

- `Сообщество pyOpenRPA (telegram) <https://t.me/pyOpenRPA>`_
- `Сообщество pyOpenRPA (tenchat) <https://tenchat.ru/iMaslov?utm_source=19f2a84f-3268-437f-950c-d987ae42af24>`_
- `Сообщество pyOpenRPA (вконтакте) <https://vk.com/pyopenrpa>`_
- `Презентация pyOpenRPA <https://pyopenrpa.ru/Index/pyOpenRPA_product_service.pdf>`_
- `Портал pyOpenRPA <https://pyopenrpa.ru>`_
- `Репозиторий pyOpenRPA <https://gitlab.com/UnicodeLabs/OpenRPA>`_