Docs: UIDesktop

2 years ago · 66992ebab8
parent 349687fe45
commit 66992ebab8
1 changed files with 120 additions and 34 deletions
--- a/Sources/pyOpenRPA/Robot/UIDesktop.py
+++ b/Sources/pyOpenRPA/Robot/UIDesktop.py
@ -558,14 +558,23 @@ def Get_OSBitnessInt ():
    if pywinauto.sysinfo.is_x64_OS():
        lResult=64
    return lResult
-#################################################################################################
+#old: -
 def UIOSelector_SafeOtherGet_Process(inUIOSelector):
-    '''
-    Safe get other process or None if destination app is the other/same bitness
+    """
+    Получить процесс робота другой разрядности (если приложение UIO объекта выполняется в другой разрядности). Функция возвращает None, если разрядность робота совпадает с разрядностью приложения UIO объекта, либо если при инициализации робота не устанавливался интерпретатор другой разрядности.

-    :param inUIOSelector: UIO Selector of the UI object
-    :return: None or process (of the other bitness)
-    '''
+    .. code-block:: python
+
+        # UIDesktop: Взаимодействие с UI объектами приложений
+        from pyOpenRPA.Robot import UIDesktop
+        # 1С: UIO Селектор выбора базы
+        lDemoBaseUIOSelector = [{"title":"Запуск 1С:Предприятия","class_name":"V8TopLevelFrameTaxiStarter","backend":"uia"},{"title":"DEMO", "depth_start": 5, "depth_end": 5}]		
+        lOtherBitnessProcess = UIDesktop.UIOSelector_SafeOtherGet_Process(lDemoBaseUIOSelector) # Вернуть процесс робота, схожей разрядности
+
+    :param inUIOSelector: UIO селектор, который определяет критерии поиска UIO объекта
+    :type inUIOSelector: list, обязательный
+    :return: Процесс робота схожей разрядности
+    """
    #Default value
    lResult = None
    #Go check bitness if selector exists
@ -575,15 +584,44 @@ def UIOSelector_SafeOtherGet_Process(inUIOSelector):
        if lUIOSelectorAppBitness and Utils.ProcessBitness.mSettingsDict["BitnessProcessCurrent"] != lUIOSelectorAppBitness:
            lResult = Utils.ProcessBitness.OtherProcessGet()
    return lResult
-##################################################################################################
+#old: GetControl
 def PWASpecification_Get_UIO(inControlSpecificationArray):
-    '''
-    #Backend def selection - attribute "backend" ("win32" || "uia") in 1-st list element
-    #old name - GetControl
+    """
+    Получить UIO объект по PWA (pywinauto) селектору. (https://pywinauto.readthedocs.io/en/latest/code/pywinauto.findwindows.html). Мы рекомендуем использовать метод UIOSelector_UIO_Get, так как UIO селектор обладает большей функциональностью.

-    :param inControlSpecificationArray: List of dict, dict in pywinauto.find_windows notation
-    :return: list of UIO object
-    '''
+    .. code-block:: python
+
+        # UIDesktop: Взаимодействие с UI объектами приложений
+        from pyOpenRPA.Robot import UIDesktop
+        # 1С: UIO Селектор выбора базы
+        lDemoBaseUIOSelector = [{"title":"Запуск 1С:Предприятия","class_name":"V8TopLevelFrameTaxiStarter","backend":"uia"}]		
+        lUIOObject = UIDesktop.PWASpecification_Get_UIO(lDemoBaseUIOSelector) # Получить UIO объект по PWA селектору
+
+    :param inControlSpecificationArray: PWA селектор, который определяет критерии поиска UIO объекта
+        Допустимые ключи PWA селектора:
+
+        - class_name содержимое атрибута class UIO объекта
+        - class_name_re содержимое атрибута class UIO объекта, которое удовлетворяет установленному рег. выражению
+        - process идентификатор процесса, в котором находится UIO объект
+        - title содержимое атрибута title UIO объекта
+        - title_re содержимое атрибута title UIO объекта, которое удовлетворяет установленному рег. выражению
+        - top_level_only признак поиска только на верхнем уровне приложения. По умолчанию True
+        - visible_only признак поиска только среди видимых UIO объектов. По умолчанию True
+        - enabled_only признак поиска только среди разблокированных UIO объектов. По умолчанию False
+        - best_match содержимое атрибута title UIO объекта максимально приближено к заданному
+        - handle идентификатор handle искомого UIO объекта 
+        - ctrl_index индекс UIO объекта среди всех дочерних объектов в списке родительского
+        - found_index индекс UIO объекта среди всех обнаруженных
+        - predicate_func пользовательская функция проверки соответсвия UIO элемента
+        - active_only признак поиска только среди активных UIO объектов. По умолчанию False
+        - control_id идентификатор control_id искомого UIO объекта 
+        - control_type тип элемента (применимо, если backend == "uia")
+        - auto_id идентификатор auto_id искомого UIO объекта (применимо, если backend == "uia")
+        - framework_id идентификатор framework_id искомого UIO объекта (применимо, если backend == "uia")
+        - backend вид технологии подключения к поиску UIO объекта ("uia" или "win32")
+    :type inControlSpecificationArray: list, обязательный
+    :return: UIO объект
+    """
    #Определение backend
    lBackend=mDefaultPywinautoBackend
    if "backend" in inControlSpecificationArray[0]:
@ -629,14 +667,44 @@ def PWASpecification_Get_UIO(inControlSpecificationArray):
                #Добавить объект в результирующий массив
                lResultList.append(lTempObject)
    return lResultList
-##################################################################################################
+
 def PWASpecification_Get_PWAApplication(inControlSpecificationArray):
-    '''
-    #Backend selection - attribute "backend" ("win32" || "uia") in 1-st list element
+    """
+    Получить значение атрибута backend по PWA (pywinauto) селектору. Мы рекомендуем использовать метод UIOSelector_UIO_Get, так как UIO селектор обладает большей функциональностью.

-    :param inControlSpecificationArray: List of dict, dict in pywinauto.find_windows notation
-    :return: process application object
-    '''
+    .. code-block:: python
+
+        # UIDesktop: Взаимодействие с UI объектами приложений
+        from pyOpenRPA.Robot import UIDesktop
+        # 1С: UIO Селектор выбора базы
+        lDemoBaseUIOSelector = [{"title":"Запуск 1С:Предприятия","class_name":"V8TopLevelFrameTaxiStarter","backend":"uia"}]		
+        lBackendStr = UIDesktop.PWASpecification_Get_PWAApplication(lDemoBaseUIOSelector) # Получить backend по PWA селектору
+
+    :param inControlSpecificationArray: PWA селектор, который определяет критерии поиска UIO объекта
+        Допустимые ключи PWA селектора:
+
+        - class_name содержимое атрибута class UIO объекта
+        - class_name_re содержимое атрибута class UIO объекта, которое удовлетворяет установленному рег. выражению
+        - process идентификатор процесса, в котором находится UIO объект
+        - title содержимое атрибута title UIO объекта
+        - title_re содержимое атрибута title UIO объекта, которое удовлетворяет установленному рег. выражению
+        - top_level_only признак поиска только на верхнем уровне приложения. По умолчанию True
+        - visible_only признак поиска только среди видимых UIO объектов. По умолчанию True
+        - enabled_only признак поиска только среди разблокированных UIO объектов. По умолчанию False
+        - best_match содержимое атрибута title UIO объекта максимально приближено к заданному
+        - handle идентификатор handle искомого UIO объекта 
+        - ctrl_index индекс UIO объекта среди всех дочерних объектов в списке родительского
+        - found_index индекс UIO объекта среди всех обнаруженных
+        - predicate_func пользовательская функция проверки соответсвия UIO элемента
+        - active_only признак поиска только среди активных UIO объектов. По умолчанию False
+        - control_id идентификатор control_id искомого UIO объекта 
+        - control_type тип элемента (применимо, если backend == "uia")
+        - auto_id идентификатор auto_id искомого UIO объекта (применимо, если backend == "uia")
+        - framework_id идентификатор framework_id искомого UIO объекта (применимо, если backend == "uia")
+        - backend вид технологии подключения к поиску UIO объекта ("uia" или "win32")
+    :type inControlSpecificationArray: list, обязательный
+    :return: "win32" или "uia"
+    """
    inControlSpecificationArray=copy.deepcopy(inControlSpecificationArray)
    #Определение backend
    lBackend=mDefaultPywinautoBackend
@ -666,16 +734,23 @@ def PWASpecification_Get_PWAApplication(inControlSpecificationArray):
            #Скорректировано из-за недопонимания структуры
            lTempObject=lRPAApplication
    return lTempObject
-
-###########################################################################################################
+#old: AutomationSearchMouseElement
 def UIOSelector_SearchChildByMouse_UIO(inElementSpecification):
-    '''
-    UIOSelector (see description on the top of the document)
-    #old name - AutomationSearchMouseElement
+    """
+    Инициировать визуальный поиск UIO объекта с помощью указателя мыши. При наведении указателя мыши UIO объект выделяется зеленой рамкой. Остановить режим поиска можно с помощью зажима клавиши ctrl left на протяжении нескольких секунд. После этого в веб окне студии будет отображено дерево расположения искомого UIO объекта.

-    :param inElementSpecification: UIOSelector of the UI Object
-    :return: pywinauto element wrapper instance or None
-    '''
+    .. code-block:: python
+
+        # UIDesktop: Взаимодействие с UI объектами приложений
+        from pyOpenRPA.Robot import UIDesktop
+        # 1С: UIO Селектор выбора базы
+        lDemoBaseUIOSelector = [{"title":"Запуск 1С:Предприятия","class_name":"V8TopLevelFrameTaxiStarter","backend":"uia"}]		
+        lUIO = UIDesktop.UIOSelector_SearchChildByMouse_UIO(lDemoBaseUIOSelector) # Инициировать поиск дочернего UIO объекта, который расположен внутри lDemoBaseUIOSelector.
+
+    :param inElementSpecification: UIO селектор, который определяет критерии поиска родительского UIO объекта, в котором будет производиться поиск дочернего UIO объекта
+    :type inElementSpecification: list, обязательный
+    :return: UIO объект или None (если UIO не был обнаружен)
+    """
    lGUISearchElementSelected=None
    #Настройка - частота обновления подсвечивания
    lTimeSleepSeconds=0.4
@ -713,15 +788,26 @@ def UIOSelector_SearchChildByMouse_UIO(inElementSpecification):
    #Вернуть результат поиска
    return lElementFoundedList

-####################################################################################################
-#old name - AutomationSearchMouseElementHierarchy
+#old: - AutomationSearchMouseElementHierarchy
 def UIOSelector_SearchChildByMouse_UIOTree(inUIOSelector):
-    '''
-    !!!!Safe call is included (you can set activity and UIDesktop will choose the bitness and return the result)!!!!!
+    """
+    Получить список уровней UIO объекта с указнием всех имеющихся атрибутов по входящему UIO селектору.
+
+    !ВНИМАНИЕ! ДАННАЯ ФУНКЦИОНАЛЬНОСТЬ В АВТОМАТИЧЕСКОМ РЕЖИМЕ ПОДДЕРЖИВАЕТ ВСЕ РАЗРЯДНОСТИ ПРИЛОЖЕНИЙ (32|64), КОТОРЫЕ ЗАПУЩЕНЫ В СЕСИИ. PYTHON x64 ИМЕЕТ ВОЗМОЖНОСТЬ ВЗЗАИМОДЕЙСТВИЯ С x32 UIO ОБЪЕКТАМИ, НО МЫ РЕКОМЕНДУЕМ ДОПОЛНИТЕЛЬНО ИСПОЛЬЗОВАТЬ ИНТЕРПРЕТАТОР PYTHON x32 (ПОДРОБНЕЕ СМ. ФУНКЦИЮ Configure())
+
+    .. code-block:: python
+
+        # UIDesktop: Взаимодействие с UI объектами приложений
+        from pyOpenRPA.Robot import UIDesktop
+        # 1С: UIO Селектор выбора базы
+        lDemoBaseUIOSelector = [{"title":"Запуск 1С:Предприятия","class_name":"V8TopLevelFrameTaxiStarter","backend":"uia"}]		
+        lBackendStr = UIDesktop.UIOSelector_SearchChildByMouse_UIOTree(lDemoBaseUIOSelector) # Получить список атрибутов всех родительских элементов lDemoBaseUIOSelector.
+
+    :param inUIOSelector: UIO селектор, который определяет UIO объект, для которого будет произведено извлечение всех атрибутов на всех уровнях.
+    :type inUIOSelector: list, обязательный
+    :return: list, список атрибутов на каждом уровне UIO объекта
+    """

-    :param inUIOSelector: UIOSelector of the UI Object
-    :return: ?
-    '''
    lItemInfo = []
    #Check the bitness
    lSafeOtherProcess = UIOSelector_SafeOtherGet_Process(inUIOSelector)