From e05ea759d826e52606742d9c07580036897b39af Mon Sep 17 00:00:00 2001 From: Ivan Maslov Date: Thu, 16 Jun 2022 13:50:03 +0300 Subject: [PATCH] Wiki: UIDesktop done --- Sources/pyOpenRPA/Robot/UIDesktop.py | 259 +++++++++++++++++++++------ 1 file changed, 203 insertions(+), 56 deletions(-) diff --git a/Sources/pyOpenRPA/Robot/UIDesktop.py b/Sources/pyOpenRPA/Robot/UIDesktop.py index 9c9c9cf5..fa101c2b 100644 --- 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) #Определить разрядность процесса