Wiki: UIDesktop done

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
+    Для backend = win32:
-    :return:
+    
+    - 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
-####################################################################################################
+#old: - GUISearchElementByRootXY
-#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
 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
 
-###################################################################################################
+#old: - ElementGetChildElementList
-#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
 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
+    .. code-block:: python
-    :param inBackend: "win32" or "uia"
-    :return:
-    """
 
+        # 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
 
-####################################################################################################
+#old1: - ElementSpecificationArraySearchPrepare
-#Подготовить массив для обращшения к поиску элемементов
+#old2: - ElementSpecificationListNormalize
-#inControlSpecificationArray - UIOSelector (can be dirty)
-#old name 1 - ElementSpecificationArraySearchPrepare
-#old name 2 - 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)
+#old: - ElementInfoExportObject
-#inElementInfo - UIOEI
-#old name - ElementInfoExportObject
 def UIOEI_Convert_UIOInfo(inElementInfo):
     """
     Техническая функция: Дообогащение словаря с параметрами UIO объекта по заданному UIO.element_info
@@ -1543,10 +1629,21 @@ def UIOEI_Convert_UIOInfo(inElementInfo):
     #Вернуть результат
     return lResult
 
-###################################################################################################
+#old: - GetRootElementList
-#Get list of top level
-#old name - 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
 
-###################################################################################################
+#old: - ElementDrawOutlineNew
-#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
 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
+    .. code-block:: python
-    :return:
+
+        # 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
-
+#old: - ElementDrawOutlineNewFocus
-###################################################################################################
-#inSpecificationArray - UIOSelector
-#!!!!!Safe call is included (you can set activity and UIDesktop will choose the bitness and return the result)!!!!!
-#old name - 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
+        # UIDesktop: Взаимодействие с UI объектами приложений
-    :return:
+        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: - draw_outline_new
-#old name - 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: - draw_outline_new_focus
-#Аналог подсвечивания + установка фокуса
-#old name - 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)
 
 #Определить разрядность процесса