Wiki: UIDesktop done

2 years ago · e05ea759d8
parent 7d76920a36
commit e05ea759d8
1 changed files with 203 additions and 56 deletions
--- a/Sources/pyOpenRPA/Robot/UIDesktop.py
+++ b/Sources/pyOpenRPA/Robot/UIDesktop.py
@ -1110,16 +1110,57 @@ def UIOSelectorUIOActivity_Run_Dict(inUIOSelector, inActionName, inArgumentList=
            lResult = lPIPEResponseDict["Result"]
    return lResult

-####################################################################################################
-#Get the UIO dict of the attributes
-#!!!!!Safe call is included (you can set activity and UIDesktop will choose the bitness and return the result)!!!!!
 #old name - ElementGetInfo
 def UIOSelector_Get_UIOInfo(inUIOSelector):
    """
-    Get the UIO dict of the attributes
+    Получить свойства UIO объекта (element_info), по заданному UIO селектору. Ниже представлен перечень возвращаемых свойств.

-    :param inUIOSelector: UIOSelector - List of items, which contains condition attributes
-    :return:
+    Для backend = win32:
+    
+    - automation_id (int)
+    - class_name (str)
+    - control_id (int)
+    - control_type (str)
+    - full_control_type (str)
+    - enabled (bool)
+    - handle (int)
+    - name (str)
+    - parent (object/UIO)
+    - process_id (int)
+    - rectangle (object/rect)
+    - rich_text (str)
+    - visible (bool)
+
+    Для backend = uia:
+
+    - automation_id (int)
+    - class_name (str)
+    - control_id (int)
+    - control_type (str)
+    - enabled (bool)
+    - framework_id (int)
+    - handle (int)
+    - name (str)
+    - parent (object/UIO)
+    - process_id (int)
+    - rectangle (object/rect)
+    - rich_text (str)
+    - runtime_id (int)
+    - visible (bool)
+
+    !ВНИМАНИЕ! ДАННАЯ ФУНКЦИОНАЛЬНОСТЬ В АВТОМАТИЧЕСКОМ РЕЖИМЕ ПОДДЕРЖИВАЕТ ВСЕ РАЗРЯДНОСТИ ПРИЛОЖЕНИЙ (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"}]		
+        lUIOElementInfoDict = UIDesktop.UIOSelector_Get_UIOInfo(lDemoBaseUIOSelector) #Получить свойства над UIO объектом с помощью UIO селектора.
+
+    :param inUIOSelector: UIO селектор, который определяет UIO объект, для которого будет представлен перечень доступных активностей.
+    :type inUIOSelector: list, обязательный
+    :return: словарь свойств element_info: Пример {"control_id": ..., "process_id": ...}
    """
    #Check the bitness
    lSafeOtherProcess = UIOSelector_SafeOtherGet_Process(inUIOSelector)
@ -1150,12 +1191,28 @@ def UIOSelector_Get_UIOInfo(inUIOSelector):
        else:
            lResultList = lPIPEResponseDict["Result"]
    return lResultList
-####################################################################################################
-#Search child UIO by the: Parent UIO, X, Y
-#inHierarchyList: [{"index":<>,"element":<>}] - technical argument for internal purpose
-#result -List of dict [{"index":<>,"element":<>}] -- list of element hierarchy specifications
-#old name - GUISearchElementByRootXY
+#old: - GUISearchElementByRootXY
 def UIOXY_SearchChild_ListDict(inRootElement,inX,inY,inHierarchyList=None):
+    """
+    Техническая функция: Получить иерархию вложенности UIO объекта по заданным корневому UIO объекту, координатам X и Y.
+
+    .. code-block:: python
+
+        # UIDesktop: Взаимодействие с UI объектами приложений
+        from pyOpenRPA.Robot import UIDesktop
+        # 1С: UIO Селектор выбора базы
+        lDemoBaseUIOSelector = [{"title":"Запуск 1С:Предприятия","class_name":"V8TopLevelFrameTaxiStarter","backend":"uia"}]		
+        lUIO = UIDesktop.UIOSelector_Get_UIO(lDemoBaseUIOSelector) # Получить UIO объект с помощью UIO селектора
+        lUIOHierarchyList = UIDesktop.UIOXY_SearchChild_ListDict(lUIO, 100, 200) # Получить UIO объект с помощью UIO селектора родительского элемента и координат X / Y
+
+    :param inRootElement: родительский UIO объект, полученный ранее с помощью UIO селектора.
+    :type inRootElement: object UIO, обязательный
+    :param inX: родительский UIO объект, полученный ранее с помощью UIO селектора.
+    :type inX: int, обязательный
+    :param inY: родительский UIO объект, полученный ранее с помощью UIO селектора.
+    :type inY: int, обязательный
+    :return: Список словарей - уровней UIO объектов
+    """
    if inHierarchyList is None: inHierarchyList = []
    #Инициализация результирующего значения
    lResultElement = None
@ -1240,21 +1297,27 @@ def UIOXY_SearchChild_ListDict(inRootElement,inX,inY,inHierarchyList=None):
        False == False
    return lResultHierarchyList

-###################################################################################################
-#Get list of child UIO's by Parent UIOSelector
-#!!!!!Safe call is included (you can set activity and UIDesktop will choose the bitness and return the result)!!!!!
-#inControlSpecificationArray- UIOSelector
-#old name - ElementGetChildElementList
+#old: - ElementGetChildElementList
 def UIOSelector_GetChildList_UIOList(inUIOSelector=None, inBackend=mDefaultPywinautoBackend):
    """
-    Get list of child UIO's by the parent UIOSelector
+    Получить список дочерних UIO объектов по входящему UIO селектору inUIOSelector.
+    
+    !ВНИМАНИЕ! ДАННАЯ ФУНКЦИОНАЛЬНОСТЬ В АВТОМАТИЧЕСКОМ РЕЖИМЕ ПОДДЕРЖИВАЕТ ВСЕ РАЗРЯДНОСТИ ПРИЛОЖЕНИЙ (32|64), КОТОРЫЕ ЗАПУЩЕНЫ В СЕСИИ. PYTHON x64 ИМЕЕТ ВОЗМОЖНОСТЬ ВЗЗАИМОДЕЙСТВИЯ С x32 UIO ОБЪЕКТАМИ, НО МЫ РЕКОМЕНДУЕМ ДОПОЛНИТЕЛЬНО ИСПОЛЬЗОВАТЬ ИНТЕРПРЕТАТОР PYTHON x32 (ПОДРОБНЕЕ СМ. ФУНКЦИЮ Configure())

-    :param inUIOSelector: UIOSelector - List of items, which contains condition attributes
-    :param inBackend: "win32" or "uia"
-    :return:
-    """
+    .. code-block:: python

+        # UIDesktop: Взаимодействие с UI объектами приложений
+        from pyOpenRPA.Robot import UIDesktop
+        # 1С: UIO Селектор выбора базы
+        lDemoBaseUIOSelector = [{"title":"Запуск 1С:Предприятия","class_name":"V8TopLevelFrameTaxiStarter","backend":"uia"}]		
+        lUIOList = UIDesktop.UIOSelector_GetChildList_UIOList(lDemoBaseUIOSelector) # Получить список дочерних UIO объектов с помощью UIO селектора

+    :param inUIOSelector: родительский UIO объект, полученный ранее с помощью UIO селектора.
+    :type inUIOSelector: list, обязательный
+    :param inBackend: вид backend "win32" или "uia". По умолчанию mDefaultPywinautoBackend ("win32")
+    :type inBackend: str, необязательный
+    :return: список дочерних UIO объектов
+    """
    if inUIOSelector is None: inUIOSelector = []
    #mRobotLogger.info(f"File!!!!")
    #mRobotLogger.info(f"inSelector:{str(inUIOSelector)}, inBackend:{str(inBackend)}")
@ -1304,12 +1367,24 @@ def UIOSelector_GetChildList_UIOList(inUIOSelector=None, inBackend=mDefaultPywin
            lResultList = lPIPEResponseDict["Result"]
    return lResultList

-####################################################################################################
-#Подготовить массив для обращшения к поиску элемементов
-#inControlSpecificationArray - UIOSelector (can be dirty)
-#old name 1 - ElementSpecificationArraySearchPrepare
-#old name 2 - ElementSpecificationListNormalize
+#old1: - ElementSpecificationArraySearchPrepare
+#old2: - ElementSpecificationListNormalize
 def UIOSelector_SearchUIONormalize_UIOSelector (inControlSpecificationArray):
+    """
+    Нормализовать UIO селектор для дальнейшего использования в функциях поиск UIO объекта. Если недопустимых атрибутов не присутствует, то оставить как есть.
+
+    .. code-block:: python
+
+        # UIDesktop: Взаимодействие с UI объектами приложений
+        from pyOpenRPA.Robot import UIDesktop
+        # 1С: UIO Селектор выбора базы
+        lDemoBaseUIOSelectorDitry = [{"title":"Запуск 1С:Предприятия","class_name":"V8TopLevelFrameTaxiStarter","backend":"uia"}]		
+        lDemoBaseUIOSelectorClean = UIDesktop.UIOSelector_SearchUIONormalize_UIOSelector(lDemoBaseUIOSelectorDitry) # Очистить UIO селектор от недопустимых ключей для дальнейшего использования
+
+    :param inControlSpecificationArray: UIO селектор, который определяет UIO объект, для которого будет представлен перечень доступных активностей.
+    :type inControlSpecificationArray: list, обязательный
+    :return: нормализованный UIO селектор
+    """
    lResult=[]
    #Циклический обход
    for lSpecificationItem in inControlSpecificationArray:
@ -1377,12 +1452,25 @@ def UIOSelector_SearchUIONormalize_UIOSelector (inControlSpecificationArray):
        lResult.append(lSpecificationItemNew)
    #Вернуть результат
    return lResult
-####################################################################################################
-#Подготовить массив для обращшения к поиску процесса (отличается от поиска элемента, тк данная функция нужна для нормализации спецификации для подключения к процессу с окнами)
-#inControlSpecificationArray - UIOSelector (can be dirty)
+
 #old name 1 - ElementSpecificationArraySearchPrepare
 #old name 2 - ElementSpecificationListNormalize
 def UIOSelector_SearchProcessNormalize_UIOSelector (inControlSpecificationArray):
+    """
+    Нормализовать UIO селектор для дальнейшего использования в функциях поиска процесса, в котором находится искомый UIO объект. Если недопустимых атрибутов не присутствует, то оставить как есть.
+
+    .. code-block:: python
+
+        # UIDesktop: Взаимодействие с UI объектами приложений
+        from pyOpenRPA.Robot import UIDesktop
+        # 1С: UIO Селектор выбора базы
+        lDemoBaseUIOSelectorDitry = [{"title":"Запуск 1С:Предприятия","class_name":"V8TopLevelFrameTaxiStarter","backend":"uia"}]		
+        lDemoBaseUIOSelectorClean = UIDesktop.UIOSelector_SearchProcessNormalize_UIOSelector(lDemoBaseUIOSelectorDitry) # Очистить UIO селектор от недопустимых ключей для дальнейшего использования
+
+    :param inControlSpecificationArray: UIO селектор, который определяет UIO объект, для которого будет представлен перечень доступных активностей.
+    :type inControlSpecificationArray: list, обязательный
+    :return: нормализованный UIO селектор
+    """
    lResult=[]
    #Циклический обход
    for lSpecificationItem in inControlSpecificationArray:
@ -1455,10 +1543,8 @@ def UIOSelector_SearchProcessNormalize_UIOSelector (inControlSpecificationArray)
        lResult.append(lSpecificationItemNew)
    #Вернуть результат
    return lResult
-####################################################################################################
-#Transfer UI object element info (pywinauto) to UIOInfo (dict of attributes)
-#inElementInfo - UIOEI
-#old name - ElementInfoExportObject
+
+#old: - ElementInfoExportObject
 def UIOEI_Convert_UIOInfo(inElementInfo):
    """
    Техническая функция: Дообогащение словаря с параметрами UIO объекта по заданному UIO.element_info
@ -1543,10 +1629,21 @@ def UIOEI_Convert_UIOInfo(inElementInfo):
    #Вернуть результат
    return lResult

-###################################################################################################
-#Get list of top level
-#old name - GetRootElementList
+#old: - GetRootElementList
 def BackendStr_GetTopLevelList_UIOInfo(inBackend=mDefaultPywinautoBackend):
+    """
+    Получить список UIOInfo словарей - процессы, которые запущены в рабочей сессии и готовы для взаимодействия с роботом через backend inBackend
+
+    .. code-block:: python
+
+        # UIDesktop: Взаимодействие с UI объектами приложений
+        from pyOpenRPA.Robot import UIDesktop
+        lAppList = UIDesktop.BackendStr_GetTopLevelList_UIOInfo() # Очистить UIO селектор от недопустимых ключей для дальнейшего использования
+
+    :param inBackend: вид backend, который планируется использовать для взаимодействия с UIO объектами
+    :type inBackend: list, обязательный
+    :return: список UIOInfo словарей
+    """
    #Получить список объектов
    lResultList=pywinauto.findwindows.find_elements(top_level_only=True,backend=inBackend)    
    lResultList2=[]
@ -1555,16 +1652,23 @@ def BackendStr_GetTopLevelList_UIOInfo(inBackend=mDefaultPywinautoBackend):
        lResultList2.append(UIOEI_Convert_UIOInfo(lI))
    return lResultList2

-###################################################################################################
-#Highlight the UI object
-#!!!!!Safe call is included (you can set activity and UIDesktop will choose the bitness and return the result)!!!!!
-#old name - ElementDrawOutlineNew
+#old: - ElementDrawOutlineNew
 def UIOSelector_Highlight(inUIOSelector):
    """
-    Highlight (draw outline) the element (in app) by the UIO selector.
+    Подсветить на несколько секунд на экране зеленой рамкой UIO объект, который соответствует входящему UIO селектору inUIOSelector
+
+    !ВНИМАНИЕ! ДАННАЯ ФУНКЦИОНАЛЬНОСТЬ В АВТОМАТИЧЕСКОМ РЕЖИМЕ ПОДДЕРЖИВАЕТ ВСЕ РАЗРЯДНОСТИ ПРИЛОЖЕНИЙ (32|64), КОТОРЫЕ ЗАПУЩЕНЫ В СЕСИИ. PYTHON x64 ИМЕЕТ ВОЗМОЖНОСТЬ ВЗЗАИМОДЕЙСТВИЯ С x32 UIO ОБЪЕКТАМИ, НО МЫ РЕКОМЕНДУЕМ ДОПОЛНИТЕЛЬНО ИСПОЛЬЗОВАТЬ ИНТЕРПРЕТАТОР PYTHON x32 (ПОДРОБНЕЕ СМ. ФУНКЦИЮ Configure())

-    :param inUIOSelector: UIOSelector - List of items, which contains condition attributes
-    :return:
+    .. code-block:: python
+
+        # UIDesktop: Взаимодействие с UI объектами приложений
+        from pyOpenRPA.Robot import UIDesktop
+        # 1С: UIO Селектор выбора базы
+        lDemoBaseUIOSelector = [{"title":"Запуск 1С:Предприятия","class_name":"V8TopLevelFrameTaxiStarter","backend":"uia"}]		
+        UIDesktop.UIOSelector_Highlight(lDemoBaseUIOSelector) # Подсветить UIO объект по UIO селектору
+
+    :param inUIOSelector: UIO селектор, который определяет UIO объект, для которого будет представлен перечень доступных активностей.
+    :type inUIOSelector: list, обязательный
    """
    #Check the bitness
    lSafeOtherProcess = UIOSelector_SafeOtherGet_Process(inUIOSelector)
@ -1585,17 +1689,23 @@ def UIOSelector_Highlight(inUIOSelector):
        else:
            return lPIPEResponseDict["Result"]
    return True
-
-###################################################################################################
-#inSpecificationArray - UIOSelector
-#!!!!!Safe call is included (you can set activity and UIDesktop will choose the bitness and return the result)!!!!!
-#old name - ElementDrawOutlineNewFocus
+#old: - ElementDrawOutlineNewFocus
 def UIOSelector_FocusHighlight(inUIOSelector):
    """
-    Set focus and highlight (draw outline) the element (in app) by the UIO selector.
+    Установить фокус и подсветить на несколько секунд на экране зеленой рамкой UIO объект, который соответствует входящему UIO селектору inUIOSelector
+
+    !ВНИМАНИЕ! ДАННАЯ ФУНКЦИОНАЛЬНОСТЬ В АВТОМАТИЧЕСКОМ РЕЖИМЕ ПОДДЕРЖИВАЕТ ВСЕ РАЗРЯДНОСТИ ПРИЛОЖЕНИЙ (32|64), КОТОРЫЕ ЗАПУЩЕНЫ В СЕСИИ. PYTHON x64 ИМЕЕТ ВОЗМОЖНОСТЬ ВЗЗАИМОДЕЙСТВИЯ С x32 UIO ОБЪЕКТАМИ, НО МЫ РЕКОМЕНДУЕМ ДОПОЛНИТЕЛЬНО ИСПОЛЬЗОВАТЬ ИНТЕРПРЕТАТОР PYTHON x32 (ПОДРОБНЕЕ СМ. ФУНКЦИЮ Configure())
+
+    .. code-block:: python

-    :param inUIOSelector: UIOSelector - List of items, which contains condition attributes
-    :return:
+        # UIDesktop: Взаимодействие с UI объектами приложений
+        from pyOpenRPA.Robot import UIDesktop
+        # 1С: UIO Селектор выбора базы
+        lDemoBaseUIOSelector = [{"title":"Запуск 1С:Предприятия","class_name":"V8TopLevelFrameTaxiStarter","backend":"uia"}]		
+        UIDesktop.UIOSelector_FocusHighlight(lDemoBaseUIOSelector) # Установить фокус и подсветить UIO объект по UIO селектору
+
+    :param inUIOSelector: UIO селектор, который определяет UIO объект, для которого будет представлен перечень доступных активностей.
+    :type inUIOSelector: list, обязательный
    """

    #Check the bitness
@ -1618,9 +1728,29 @@ def UIOSelector_FocusHighlight(inUIOSelector):
            return lPIPEResponseDict["Result"]
    return True

-###################################################################################################
-#old name - draw_outline_new
+#old: - draw_outline_new
 def UIO_Highlight(lWrapperObject,colour='green',thickness=2,fill=win32defines.BS_NULL,rect=None,inFlagSetFocus=False):
+    """
+    Выполнить подсветку UIO объекта на экране
+
+    .. code-block:: python
+
+        # UIDesktop: Взаимодействие с UI объектами приложений
+        from pyOpenRPA.Robot import UIDesktop
+        # 1С: UIO Селектор выбора базы
+        lDemoBaseUIOSelector = [{"title":"Запуск 1С:Предприятия","class_name":"V8TopLevelFrameTaxiStarter","backend":"uia"}]		
+        lUIO = UIDesktop.UIOSelector_Get_UIO(lDemoBaseUIOSelector) # Получить UIO объект по UIO селектору
+        UIDesktop.UIO_Highlight(lUIO) # Подсветить UIO объект по UIO селектору зеленым цветом с толщиной подсветки 2 px.
+
+    :param lWrapperObject: UIO объект, который будет подсвечен
+    :type lWrapperObject: object UIO, обязательный
+    :param colour: цвет подсветки UIO объекта. Варианты: 'red', 'green', 'blue'. По умолчанию 'green'
+    :type colour: str, необязательный
+    :param thickness: толщина подсветки UIO объекта. По умолчанию 2
+    :type thickness: int, необязательный
+    :param inFlagSetFocus: признак установки фокуса на UIO объект перед подсветкой. По умолчанию False
+    :type inFlagSetFocus: bool, необязательный
+    """
    if lWrapperObject is not None:
        """
        Draw an outline around the window.
@ -1670,10 +1800,27 @@ def UIO_Highlight(lWrapperObject,colour='green',thickness=2,fill=win32defines.BS
        # delete the Display context that we created
        win32functions.DeleteDC(dc)

-###################################################################################################
-#Аналог подсвечивания + установка фокуса
-#old name - draw_outline_new_focus
+#old: - draw_outline_new_focus
 def UIO_FocusHighlight(lWrapperObject,colour='green',thickness=2,fill=win32defines.BS_NULL,rect=None):
+    """
+    Установить фокус и выполнить подсветку UIO объекта на экране
+
+    .. code-block:: python
+
+        # UIDesktop: Взаимодействие с UI объектами приложений
+        from pyOpenRPA.Robot import UIDesktop
+        # 1С: UIO Селектор выбора базы
+        lDemoBaseUIOSelector = [{"title":"Запуск 1С:Предприятия","class_name":"V8TopLevelFrameTaxiStarter","backend":"uia"}]		
+        lUIO = UIDesktop.UIOSelector_Get_UIO(lDemoBaseUIOSelector) # Получить UIO объект по UIO селектору
+        UIDesktop.UIO_FocusHighlight(lUIO) # Установить фокус и подсветить UIO объект по UIO селектору зеленым цветом с толщиной подсветки 2 px.
+
+    :param lWrapperObject: UIO объект, который будет подсвечен
+    :type lWrapperObject: object UIO, обязательный
+    :param colour: цвет подсветки UIO объекта. Варианты: 'red', 'green', 'blue'. По умолчанию 'green'
+    :type colour: str, необязательный
+    :param thickness: толщина подсветки UIO объекта. По умолчанию 2
+    :type thickness: int, необязательный
+    """
    UIO_Highlight(lWrapperObject,'green',2,win32defines.BS_NULL,None,True)

 #Определить разрядность процесса