Módulo desktop_utils (desktop_utils.py)

---

Para realizar automações em aplicações desktop, de interface gráfica, utilize este módulo. Abaixo, detalhamento das funções suas utilizações:

Estrutura de hierarquia de um elemento:

Para a interação com uma janela ou elemento dentro da aplicação, é necessário informar a árvore de elementos até o elemento alvo em formato dict, conforme apresentado abaixo:

 {
     'window': {
         'title': 'nome do elemento',
         'session': 'nome da sessão',
         'child_window': {
             'title': 'nome do elemento filho',
             'control_type': 'tipo de elemento',
             'auto_id': 'identificador do elemento',
             'child_window': {
                 'best_match': 'Outro identificador único',
             }
         }
     }
 }

Onde:

• 'window': É a marcação que define os parâmetros da janela;

• 'child_window': É a marcação que define os parâmetros dos elementos filhos e filhos de filhos;

• 'session': é o nome da sessão;

• 'title': é o título da janela ou do elemento;

• 'control_type': é o tipo de elemento desktop;

• 'auto_id': é o identificador do elemento dentro da aplicação desktop.

• 'best_match': é um identificador único, como a classe do elemento dentro da aplicação desktop.

Ativando foco em uma janela

Para colocar a janela em evidência, utilize a função ativar_foco. Nela, passe como parâmetro o nome de uma janela que já está em manipulação pela aplicação. Isso significa que o nome precisa ser válido dentre as opções dos nomes de janelas que já são manipuláveis.

A função retorna booleano. Caso o foco dê certo, True. Caso o foco dê errado, False.

função ativar_foco

Ativa a janela de um objeto do tipo Application deixando-a com foco.

Parameters:

Name	Type	Description	Default
nome_janela	str	O nome de uma janela já manipulável.	required

Returns:

Type	Description
bool	Retorna booleano, True caso o foco tenha sucesso, False caso o foco não tenha sucesso.

Examples:

>>> ativar_foco(nome_janela='Untitled - Notepad')
True

>>> ativar_foco(nome_janela='aaaaa')
False

Source code in py_rpautom\desktop_utils.py

def ativar_foco(nome_janela: str) -> bool:
    """Ativa a janela de um objeto do tipo `Application` deixando-a com foco.

    Parameters:
        nome_janela: O nome de uma janela já manipulável.

    Returns:
        Retorna booleano, `True` caso o foco tenha sucesso, \
        `False` caso o foco não tenha sucesso.

    Raises:
        ...

    Examples:
        >>> ativar_foco(nome_janela='Untitled - Notepad')
        True

        >>> ativar_foco(nome_janela='aaaaa')
        False
    """

    # importa app para o escopo da função
    global APP

    try:
        # inicializa APP para uma variável interna
        app_interno = APP

        # ativa a janela informada
        app_interno.window(title=nome_janela).set_focus()

        # retorna verdadeiro confirmando a execução da ação
        return True
    except:
        return False

---

Verificando se um botão de seleção está marcado

Para verificar se um botão de seleção do tipo checkbox está marcado, utilize a função botao_esta_marcado. Esta função verifica se o botão está selecionado, retornando um valor booleano. True caso o botão estiver selecionado, False caso o botão não estiver selecionado. Para utilizá-la, basta no momento da chamada, informar os seguintes dados:

caminho até o elemento em formato dict (caminho_campo) :

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

opcao de verificacao (opcao_verificacao) :

Existem 3 tipos de verificações:

• 'IS_CHECKED': É a verificação pura se está selecionado.
• 'GET_CHECK_STATE': Coleta o estado do elemento (se selecionado ou não).
• 'GET_SHOW_STATE': Coleta a exibição gráfica do estado do elemento (se selecionado ou não).

A escolha entre cada uma delas vai depender do tipo de elemento que está sendo manipulado. Como cada aplicação tem um jeito diferente de expor os elementos e seus estados, recomendamos testar cada opção e verificar o que melhor se encaixa ao momento.

função botao_esta_marcado

Verifica se o estado de um botão está como marcado ou não.

Parameters:

Name	Type	Description	Default
caminho_campo	dict	Caminho do elemento. Precisa ser do tipo dict.	required
opcao_verificacao	str	O nome do estado do elemento que se quer verificar. Aceita as opções IS_CHECKED, GET_CHECK_STATE e GET_SHOW_STATE em tipo string.	'IS_CHECKED'

Returns:

Type	Description
bool	Retorna booleano, True caso o botão estiver marcado, False caso o botão não estiver marcado.

Raises:

Type	Description
ValueError	caminho_campo precisa ser do tipo dict.
ValueError	opcao_verificacao precisa ser do tipo str.
ValueError	Valores permitidos para opcao_verificacao: get_check_state, GET_SHOW_STATE, is_checked.

Source code in py_rpautom\desktop_utils.py

def botao_esta_marcado(
    caminho_campo: dict,
    opcao_verificacao: str = 'IS_CHECKED',
) -> bool:
    """Verifica se o estado de um botão está como marcado ou não.

    Parameters:
        caminho_campo: Caminho do elemento. Precisa ser do tipo dict.
        opcao_verificacao: O nome do estado do elemento que se quer \
            verificar. Aceita as opções IS_CHECKED, GET_CHECK_STATE \
            e GET_SHOW_STATE em tipo string.

    Returns:
        Retorna booleano, `True` caso o botão estiver marcado, \
        `False` caso o botão não estiver marcado.

    Raises:
        ValueError: `caminho_campo` precisa ser do tipo dict.

        ValueError: `opcao_verificacao` precisa ser do tipo str.

        ValueError: \
            Valores permitidos para `opcao_verificacao`: \
            get_check_state, GET_SHOW_STATE, is_checked.

    """

    if isinstance(caminho_campo, dict) is False:
        raise ValueError('`caminho_campo` precisa ser do tipo dict.')

    if isinstance(opcao_verificacao, str) is False:
        raise ValueError('`opcao_verificacao` precisa ser do tipo str.')

    # localiza o elemento até o final da árvore de parantesco do app
    app_interno = _localizar_elemento(caminho_campo)
    app_interno.exists()

    marcado = True
    if opcao_verificacao.upper() == 'IS_CHECKED':
        return app_interno.is_checked() == marcado
    elif opcao_verificacao.upper() == 'GET_CHECK_STATE':
        return app_interno.get_check_state() == marcado
    elif opcao_verificacao.upper() == 'GET_SHOW_STATE':
        return app_interno.get_show_state() == marcado
    else:
        raise ValueError(
            'Valores permitidos para `opcao_verificacao`: '
            'get_check_state, GET_SHOW_STATE, is_checked.'
        )

---

Capturando imagem de um elemento

Existe um recurso para tirar uma imagem do elemento no estado atual da execução. Para isso, utilize a função capturar_imagem.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função capturar_imagem

Captura uma imagem do estado atual do elemento informado e retorna a imagem em bytes.

Parameters:

Name	Type	Description	Default
caminho_campo	dict	Caminho do elemento na estrutura da aplicação sendo manipulada.	required
coordenadas	tuple	fixar valor da posição do elemento. Aceita as posições na seguinte ordem: esquerda, cima, direita, baixo.	None

Returns:

Type	Description
bytes	Retorna o valor da imagem em tipo bytes.

Raises:

Type	Description
ValueError	caminho_campo precisa ser do tipo dict.
ValueError	coordenadas precisa ser do tipo tuple.
ValueError	coordenadas precisa conter 4 posições.

Examples:

>>> capturar_imagem(
        caminho_campo=arvore_do_elemento,
        coordenadas=(
            posicao_esquerda,
            posicao_cima,
            posicao_direita,
            posicao_baixo
        )
    )
b'%%&%%&%%&%%&%%&%%&%%&%%&%%&%Jq\xa1\xbc\xcc\xc7\xad\x81K%&%%
&%%&%%&%%&%%&%%&%%&%%&%%&%%&%:a\x7f\x8'

Source code in py_rpautom\desktop_utils.py

def capturar_imagem(caminho_campo: dict, coordenadas: tuple = None) -> bytes:
    r"""
    Captura uma imagem do estado atual do elemento
    informado e retorna a imagem em bytes.

    Parameters:
        caminho_campo: Caminho do elemento na estrutura da aplicação
            sendo manipulada.
        coordenadas: fixar valor da posição do elemento. Aceita as
            posições na seguinte ordem: esquerda, cima, direita, baixo.

    Returns:
        Retorna o valor da imagem em tipo bytes.

    Raises:
        ValueError: `caminho_campo` precisa ser do tipo dict.

        ValueError: `coordenadas` precisa ser do tipo tuple.

        ValueError: `coordenadas` precisa conter 4 posições.

    Examples:
        >>> capturar_imagem(
                caminho_campo=arvore_do_elemento,
                coordenadas=(
                    posicao_esquerda,
                    posicao_cima,
                    posicao_direita,
                    posicao_baixo
                )
            )
        b'%%&%%&%%&%%&%%&%%&%%&%%&%%&%Jq\xa1\xbc\xcc\xc7\xad\x81K%&%%
        &%%&%%&%%&%%&%%&%%&%%&%%&%%&%:a\x7f\x8'
    """

    # Validar o tipo da varivavel
    if isinstance(caminho_campo, dict) is False:
        raise ValueError('`caminho_campo` precisa ser do tipo dict.')

    # Validar o tipo da varivavel
    if (isinstance(coordenadas, tuple) is False) and (coordenadas is not None):
        raise ValueError('`coordenadas` precisa ser do tipo tuple.')

    # Capturar o caminho do campo
    app_interno = _localizar_elemento(caminho_campo=caminho_campo)

    if coordenadas is not None:
        # Validar a quantidade de dados
        if not len(coordenadas) == 4:
            raise ValueError('`coordenadas` precisa conter 4 posições.')

        (
            posicao_esquerda,
            posicao_cima,
            posicao_direita,
            posicao_baixo,
        ) = coordenadas

        posicao_total = capturar_propriedade_elemento(
            caminho_campo=caminho_campo
        )['rectangle']

        posicao_total.left = posicao_esquerda
        posicao_total.right = posicao_direita
        posicao_total.top = posicao_cima
        posicao_total.bottom = posicao_baixo

        # Salvar imagem no caminho solicitado
        imagem_bytes: bytes = app_interno.capture_as_image(
            rect=posicao_total
        ).tobytes()
    else:
        # Salvar imagem no caminho solicitado
        imagem_bytes: bytes = app_interno.capture_as_image().tobytes()

    return imagem_bytes

---

Coletando propriedades de um elemento

Algumas vezes serão necessárias algumas informações, como a posição do elemento na aplicação, se o elemento está em unicode ou mesmo nome da classe ou control_id. Para coletar estas e outras informações de um elemento, utilize a função capturar_propriedade_elemento.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função capturar_propriedade_elemento

Captura as propriedades do elemento informado.

Parameters:

Name	Type	Description	Default
caminho_campo	dict	Caminho do elemento na estrutura da aplicação sendo manipulada.	required

Returns:

Type	Description
dict[str, Union[str, int, bool, list]]	Retorna um dicionário contendo string na chave, e um dos valores a seguir como valor: str, int, bool ou list.

Raises:

Type	Description
ValueError	caminho_campo precisa ser do tipo dict.

Examples:

>>> capturar_propriedade_elemento(
...     caminho_campo={
...         'window': {
...             'title': 'Untitled - Notepad',
...             'child_window': {
...                 'title': 'DesktopWindowXamlSource',
...                 'best_match': 'Windows.UI.Composition.DesktopWindowContentBridge2',
...                 'child_window': {
...                     'best_match': 'Windows.UI.Input.InputSite.WindowClass2',
...                 }
...             }
...         }
...     }
... )
{'class_name': 'Windows.UI.Input.InputSite.WindowClass', 'friendly_class_name': 'Windows.UI.Input.InputSite.WindowClass', 'texts': [''], 'control_id': 0, 'rectangle': <RECT L961, T562, R961, B562>, 'is_visible': True, 'is_enabled': True, 'control_count': 0, 'style': 1342177280, 'exstyle': 0, 'user_data': 0, 'context_help_id': 0, 'fonts': [<LOGFONTW 'MS Shell Dlg' -13>], 'client_rects': [<RECT L0, T0, R0, B0>], 'is_unicode': True, 'menu_items': [], 'automation_id': ''}

Source code in py_rpautom\desktop_utils.py

def capturar_propriedade_elemento(
    caminho_campo: dict,
) -> dict[str, Union[str, int, bool, list]]:
    """Captura as propriedades do elemento informado.

    Parameters:
        caminho_campo: Caminho do elemento na estrutura da aplicação \
            sendo manipulada.

    Returns:
        Retorna um dicionário contendo string na chave, e um dos valores \
            a seguir como valor: str, int, bool ou list.

    Raises:
        ValueError: `caminho_campo` precisa ser do tipo dict.

    Examples:
        >>> capturar_propriedade_elemento(
        ...     caminho_campo={
        ...         'window': {
        ...             'title': 'Untitled - Notepad',
        ...             'child_window': {
        ...                 'title': 'DesktopWindowXamlSource',
        ...                 'best_match': 'Windows.UI.Composition.DesktopWindowContentBridge2',
        ...                 'child_window': {
        ...                     'best_match': 'Windows.UI.Input.InputSite.WindowClass2',
        ...                 }
        ...             }
        ...         }
        ...     }
        ... )
        {'class_name': 'Windows.UI.Input.InputSite.WindowClass', 'friendly_class_name': 'Windows.UI.Input.InputSite.WindowClass', 'texts': [''], 'control_id': 0, 'rectangle': <RECT L961, T562, R961, B562>, 'is_visible': True, 'is_enabled': True, 'control_count': 0, 'style': 1342177280, 'exstyle': 0, 'user_data': 0, 'context_help_id': 0, 'fonts': [<LOGFONTW 'MS Shell Dlg' -13>], 'client_rects': [<RECT L0, T0, R0, B0>], 'is_unicode': True, 'menu_items': [], 'automation_id': ''}
    """

    # Validar o tipo da varivavel
    if isinstance(caminho_campo, dict) is False:
        raise ValueError('`caminho_campo` precisa ser do tipo dict.')

    # Capturar o caminho do campo
    app_interno = _localizar_elemento(caminho_campo=caminho_campo)

    # Capturar propriedade do campo
    dado = app_interno.get_properties()

    return dado

---

Coletando o texto de um elemento

Um recurso muito comum é a captura de texto de um elemento. Para este feito, utilize a função capturar_texto.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função capturar_texto

Captura o texto de um elemento dentro de um objeto do tipo Application.

Parameters:

Name	Type	Description	Default
caminho_campo	dict	Caminho do elemento na estrutura da aplicação sendo manipulada.	required

Returns:

Type	Description
list[str]	Retorna uma lista de strings, sendo o valor capturado do elemento informado.

Raises:

Type	Description
ValueError	caminho_campo precisa ser do tipo dict.

Examples:

>>> capturar_texto(
...     caminho_campo={
...         'window': {
...             'title': 'Windows Powershell Main Window',
...             'child_window': {
...                 'title': 'Windows Powershell Main Menu',
...                 'child_window': {
...                     'title': 'File',
...                 }
...             }
...         }
...     },
... )
['File']

Source code in py_rpautom\desktop_utils.py

def capturar_texto(caminho_campo: dict) -> list[str]:
    """Captura o texto de um elemento dentro de um objeto do tipo Application.

    Parameters:
        caminho_campo: Caminho do elemento na estrutura da aplicação \
            sendo manipulada.

    Returns:
        Retorna uma lista de strings, sendo o valor capturado do elemento \
            informado.

    Raises:
        ValueError: `caminho_campo` precisa ser do tipo dict.


    Examples:
        >>> capturar_texto(
        ...     caminho_campo={
        ...         'window': {
        ...             'title': 'Windows Powershell Main Window',
        ...             'child_window': {
        ...                 'title': 'Windows Powershell Main Menu',
        ...                 'child_window': {
        ...                     'title': 'File',
        ...                 }
        ...             }
        ...         }
        ...     },
        ... )
        ['File']
    """

    if isinstance(caminho_campo, dict) is False:
        raise ValueError('`caminho_campo` precisa ser do tipo dict.')

    # localiza o elemento até o final da árvore de parantesco do app
    app_interno = _localizar_elemento(caminho_campo)
    app_interno.exists()

    # captura o texto do campo localizado
    valor_capturado: list = app_interno.texts()

    # retorna o valor capturado
    return valor_capturado

---

Clicando em um elemento

Para realizar o clique em um elemento dentro da aplicação, utilize a função clicar.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função clicar

Clica em um elemento dentro de um objeto do tipo Application.

Parameters:

Name	Type	Description	Default
caminho_campo	dict	Caminho do elemento na estrutura da aplicação sendo manipulada.	required
performar	bool	Ativa clique físico direto no elemento informado.	False

Returns:

Type	Description
bool	Retorna True caso chegue ao final do clique.

Raises:

Type	Description
ValueError	caminho_campo precisa ser do tipo dict.
ValueError	performar precisa ser do tipo boleano.'
ValueError	indice precisa ser do tipo int.

Examples:

>>> clicar(
...     caminho_campo={
...         'window': {
...             'title': 'Windows Powershell Main Window',
...             'child_window': {
...                 'title': 'Windows Powershell Main Menu',
...                 'child_window': {
...                     'title': 'File',
...                 }
...             }
...         }
...     },
...     indice=0,
...     performar=True,
... )
True

Source code in py_rpautom\desktop_utils.py

def clicar(
    caminho_campo: dict,
    performar: bool = False,
    indice: int = None,
) -> bool:
    """Clica em um elemento dentro de um objeto do tipo Application.

    Parameters:
        caminho_campo: Caminho do elemento na estrutura da aplicação \
            sendo manipulada.
        performar: Ativa clique físico direto no elemento informado.

    Returns:
        Retorna `True` caso chegue ao final do clique.

    Raises:
        ValueError: `caminho_campo` precisa ser do tipo dict.
        ValueError: `performar` precisa ser do tipo boleano.'
        ValueError: `indice` precisa ser do tipo int.


    Examples:
        >>> clicar(
        ...     caminho_campo={
        ...         'window': {
        ...             'title': 'Windows Powershell Main Window',
        ...             'child_window': {
        ...                 'title': 'Windows Powershell Main Menu',
        ...                 'child_window': {
        ...                     'title': 'File',
        ...                 }
        ...             }
        ...         }
        ...     },
        ...     indice=0,
        ...     performar=True,
        ... )
        True
    """

    # localiza o elemento até o final da árvore de parantesco do app
    if isinstance(caminho_campo, dict) is False:
        raise ValueError('`caminho_campo` precisa ser do tipo dict.')

    if isinstance(performar, bool) is False:
        raise ValueError('`performar` precisa ser do tipo boleano.')

    if isinstance(indice, int) is False and indice is not None:
        raise ValueError('`indice` precisa ser do tipo int.')

    app_interno = _localizar_elemento(caminho_campo)
    app_interno.exists()

    if indice is not None:
        app_interno = app_interno.children()[indice]

    # digita o valor no campo localizado
    if performar is True:
        app_interno.click_input()
    else:
        app_interno.click()

    # retorna o valor capturado e tratado
    return True

---

Coletando a árvore de elementos de uma janela ou elemento

Utilizando a função coletar_arvore_elementos, é possível verificar quais elementos compõem uma janela ou um elemento específico. A abordagem é única para ambos os casos.

Uma árvore de elementos é a estrutura hierárquica dos elementos em uma aplicação. Dentro de uma janela há elementos. Esses elementos podem ou não conter elementos dentro de si. Isso vai compondo uma hierarquização de elementos, um dentro de outro, ao lado de outro e assim por diante.

Assim, para visualizar a estrutura de um elemento ou de uma janela, recorra à função coletar_arvore_elementos. Ela retorna, em string, os elementos dentro do que foi solicitado. Caso, por exemplo, seja informado no parâmetro caminho_elemento uma janela, será retornado todos os elementos visíveis dessa janela no momento da execução do comando. O mesmo acontece caso seja passado um elemento.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função coletar_arvore_elementos

Lista um elemento dentro de um objeto do tipo Application e retorna o valor coletado.

Parameters:

Name	Type	Description	Default
caminho_elemento	dict	Caminho do elemento na estrutura da aplicação sendo manipulada.	required

Returns:

Type	Description
list[str]	Retorna uma lista de strings, sendo o valor capturado do elemento informado.

Raises:

Type	Description
ValueError	caminho_elemento precisa ser do tipo dict.

Examples:

>>> coletar_arvore_elementos(
...     caminho_elemento={
...         'window': {
...             'title': 'Untitled - Notepad',
...             'child_window': {
...                 'title': 'DesktopWindowXamlSource',
...                 'best_match': 'Windows.UI.Composition.DesktopWindowContentBridge2',
...                 'child_window': {
...                     'best_match': 'Windows.UI.Input.InputSite.WindowClass2',
...                 }
...             }
...         }
...     }
... )
['Control Identifiers:', '', "Windows.UI.Input.InputSite.WindowClass - ''    (L1898, T603, R1898, B603)", "['Windows.UI.Input.InputSite.WindowClass']", 'child_window(class_name="Windows.UI.Input.InputSite.WindowClass")', '']

Source code in py_rpautom\desktop_utils.py

def coletar_arvore_elementos(caminho_elemento: dict) -> list[str]:
    """Lista um elemento dentro de um objeto do tipo Application e retorna \
        o valor coletado.

    Parameters:
        caminho_elemento: Caminho do elemento na estrutura da aplicação \
            sendo manipulada.

    Returns:
        Retorna uma lista de strings, sendo o valor capturado do elemento \
            informado.

    Raises:
        ValueError: `caminho_elemento` precisa ser do tipo dict.

    Examples:
        >>> coletar_arvore_elementos(
        ...     caminho_elemento={
        ...         'window': {
        ...             'title': 'Untitled - Notepad',
        ...             'child_window': {
        ...                 'title': 'DesktopWindowXamlSource',
        ...                 'best_match': 'Windows.UI.Composition.DesktopWindowContentBridge2',
        ...                 'child_window': {
        ...                     'best_match': 'Windows.UI.Input.InputSite.WindowClass2',
        ...                 }
        ...             }
        ...         }
        ...     }
        ... )
        ['Control Identifiers:', '', "Windows.UI.Input.InputSite.WindowClass - ''    (L1898, T603, R1898, B603)", "['Windows.UI.Input.InputSite.WindowClass']", 'child_window(class_name="Windows.UI.Input.InputSite.WindowClass")', '']
    """

    # importa recursos do módulo io
    import io

    # importa recursos do módulo Path
    from contextlib import redirect_stdout

    if isinstance(caminho_elemento, dict) is False:
        raise ValueError('`caminho_elemento` precisa ser do tipo dict.')

    # localiza o elemento até o final da árvore de parantesco do app
    app_interno = _localizar_elemento(caminho_elemento)
    app_interno.exists()

    conteudoStdOut = io.StringIO()
    with redirect_stdout(conteudoStdOut):
        app_interno.print_control_identifiers()

    valor = conteudoStdOut.getvalue()
    valor_dividido = valor.split('\n')

    # retorna o valor capturado e tratado
    return valor_dividido

---

Coletando valor selecionado de um campo de seleção

Um campo de seleção, elemento do tipo combobox, sempre contém alguma opção selecionada, mesmo que seja um valor vazio ou definido por padrão pela aplicação. Caso queira coletar o valor de um campo de seleção, utilize a função abaixo, que retornará o valor do campo informado no momento de sua execução.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função coletar_dado_selecionado

Coleta a opção atualmente selecionada em um elemento de seleção de um objeto do tipo Application.

Parameters:

Name	Type	Description	Default
caminho_campo	dict	Caminho do elemento na estrutura da aplicação sendo manipulada.	required

Returns:

Type	Description
str	Retorna uma string, sendo o valor capturado do elemento informado.

Raises:

Type	Description
ValueError	caminho_campo precisa ser do tipo dict.

Examples:

>>> coletar_dado_selecionado(
...     caminho_campo={
...         'window': {
...             'title': 'Character Map',
...             'child_window': {
...                 'title': 'Font :',
...                 'control_type': 'ComboBox',
...                 'auto_id': '105',
...             }
...         }
...     },
... )
'Arial'

Source code in py_rpautom\desktop_utils.py

def coletar_dado_selecionado(caminho_campo: dict) -> str:
    """Coleta a opção atualmente selecionada em um elemento de seleção de \
        um objeto do tipo Application.

    Parameters:
        caminho_campo: Caminho do elemento na estrutura da aplicação \
            sendo manipulada.

    Returns:
        Retorna uma string, sendo o valor capturado do elemento informado.

    Raises:
        ValueError: `caminho_campo` precisa ser do tipo dict.

    Examples:
        >>> coletar_dado_selecionado(
        ...     caminho_campo={
        ...         'window': {
        ...             'title': 'Character Map',
        ...             'child_window': {
        ...                 'title': 'Font :',
        ...                 'control_type': 'ComboBox',
        ...                 'auto_id': '105',
        ...             }
        ...         }
        ...     },
        ... )
        'Arial'
    """

    # define estático como falso para trabalhar com elemento dinâmico
    if isinstance(caminho_campo, dict) is False:
        raise ValueError('`caminho_campo` precisa ser do tipo dict.')

    # localiza o elemento até o final da árvore de parantesco do app
    app_interno = _localizar_elemento(caminho_campo)
    app_interno.exists()

    # captura o texto do campo localizado
    valor_capturado: str = app_interno.selected_text()

    # retorna o valor capturado
    return valor_capturado

---

Coletando valores disponíveis de um campo de seleção

Assim como um campo de seleção, elemento do tipo combobox, contém alguma opção selecionada, também contem uma ou mais opções para selecionar. Para coletar todos os valores disponíveis em um campo de seleção, utilize a função abaixo, que retornará, em string, as opções de seleção do elemento solicitado no momento de sua execução.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função coletar_dados_selecao

Coleta todas as opções disponíveis para seleção em um elemento de seleção de um objeto do tipo Application.

Parameters:

Name	Type	Description	Default
caminho_campo	dict	Caminho do elemento na estrutura da aplicação sendo manipulada.	required

Returns:

Type	Description
str	Retorna uma string, sendo o valor capturado do elemento informado.

Raises:

Type	Description
ValueError	caminho_campo precisa ser do tipo dict.

Examples:

...

Source code in py_rpautom\desktop_utils.py

def coletar_dados_selecao(caminho_campo: dict) -> str:
    """Coleta todas as opções disponíveis para seleção em um elemento de \
        seleção de um objeto do tipo Application.

    Parameters:
        caminho_campo: Caminho do elemento na estrutura da aplicação \
            sendo manipulada.

    Returns:
        Retorna uma string, sendo o valor capturado do elemento informado.

    Raises:
        ValueError: `caminho_campo` precisa ser do tipo dict.

    Examples:
        ...
    """

    # define estático como falso para trabalhar com elemento dinâmico
    if isinstance(caminho_campo, dict) is False:
        raise ValueError('`caminho_campo` precisa ser do tipo dict.')

    # localiza o elemento até o final da árvore de parantesco do app
    app_interno = _localizar_elemento(caminho_campo)
    app_interno.exists()

    # captura o texto do campo localizado
    valor_capturado: str = app_interno.item_texts()

    # retorna o valor capturado
    return valor_capturado

---

Coletando o estado atual da janela

As janelas de uma aplicação dentro de um sistema operacional tem estados padrões, como estar minimizado ou em modo normal. Estes e outros estados podem ser capturados utilizando a função coletar_situacao_janela no momento de sua execução.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função coletar_situacao_janela

Coleta a situação do estado atual de uma janela de um objeto do tipo Application.

Parameters:

Name	Type	Description	Default
caminho_janela	dict	Caminho da janela na estrutura da aplicação sendo manipulada.	required

Returns:

Type	Description
str	Retorna uma string, sendo um dos valores a seguir: 'normal', 'minimizado', 'maximizado' e 'não identificado'.

Raises:

Type	Description
ValueError	caminho_janela precisa ser do tipo dict.

Examples:

Validação com a janela restaurada no momento da execução do comando

>>> coletar_situacao_janela(
...     caminho_janela={
...         'window': {
...             'title': 'Untitled - Notepad',
...         }
...     }
... )
'normal'

Validação com a janela maximizada no momento da execução do comando

>>> coletar_situacao_janela(
...     caminho_janela={
...         'window': {
...             'title': 'Untitled - Notepad',
...         }
...     }
... )
'maximizado'

Validação com a janela minimizaa no momento da execução do comando

>>> coletar_situacao_janela(
...     caminho_janela={
...         'window': {
...             'title': 'Untitled - Notepad',
...         }
...     }
... )
'minimizado'

Source code in py_rpautom\desktop_utils.py

def coletar_situacao_janela(caminho_janela: dict) -> str:
    """Coleta a situação do estado atual de uma janela de um objeto do tipo Application.

    Parameters:
        caminho_janela: Caminho da janela na estrutura da aplicação \
            sendo manipulada.

    Returns:
        Retorna uma string, sendo um dos valores a seguir: 'normal', 'minimizado', 'maximizado' e 'não identificado'.

    Raises:
        ValueError: `caminho_janela` precisa ser do tipo dict.

    Examples:
        #### Validação com a janela restaurada no momento da execução do comando
        >>> coletar_situacao_janela(
        ...     caminho_janela={
        ...         'window': {
        ...             'title': 'Untitled - Notepad',
        ...         }
        ...     }
        ... )
        'normal'

        #### Validação com a janela maximizada no momento da execução do comando
        >>> coletar_situacao_janela(
        ...     caminho_janela={
        ...         'window': {
        ...             'title': 'Untitled - Notepad',
        ...         }
        ...     }
        ... )
        'maximizado'

        #### Validação com a janela minimizaa no momento da execução do comando
        >>> coletar_situacao_janela(
        ...     caminho_janela={
        ...         'window': {
        ...             'title': 'Untitled - Notepad',
        ...         }
        ...     }
        ... )
        'minimizado'
    """

    # importa app para o escopo da função
    global APP

    if isinstance(caminho_janela, dict) is False:
        raise ValueError('`caminho_janela` precisa ser do tipo dict.')

    # inicializa APP para uma variável interna
    app_interno = APP

    situacao = ''
    # coleta a situacao atual da janela
    app_interno = _localizar_elemento(caminho_janela)
    app_interno.exists()
    situacao_temp = app_interno.get_show_state()

    # 1 - Normal
    # 2 - Minimizado
    # 3 - Maximizado
    # Caso não encontre as situações normal, ninimizado e
    #   maximizado, define um valor padrão.
    if situacao_temp == 1:
        situacao = 'normal'
    elif situacao_temp == 2:
        situacao = 'minimizado'
    elif situacao_temp == 3:
        situacao = 'maximizado'
    else:
        situacao = 'não identificado'

    # retorna a situação da janela
    return situacao

---

Conectando-se à uma aplicação já em execução

É possível manipular aplicações já em execução. Para isso, utilize a função conectar_app, que adicionará a aplicação ao conjunto de aplicações manipuláveis e retornará o PID da mesma.

função conectar_app

Torna um processo do sistema já existente como um objeto do tipo Application manipulável.

Parameters:

Name	Type	Description	Default
pid	int	PID do processo existente.	required
tempo_espera	int	Tempo limite em segundos para o início do processo.	60
estilo_aplicacao	str	Estilo de aplicação a ser manipulado, sendo 'win32' e 'uia' os valores aceitos.	'win32'

Returns:

Type	Description
int	Retorna int, sendo o PID do processo manipulado.

Examples:

>>> conectar_app(
...     pid=notepad_pid,
...     tempo_espera=10,
...     estilo_aplicacao='win32',
... )
33144

Source code in py_rpautom\desktop_utils.py

def conectar_app(
    pid: int,
    tempo_espera: int = 60,
    estilo_aplicacao: str = 'win32',
) -> int:
    """Torna um processo do sistema já existente como um objeto do tipo \
        Application manipulável.

    Parameters:
        pid: PID do processo existente.
        tempo_espera: Tempo limite em segundos para o início do processo.
        estilo_aplicacao: Estilo de aplicação a ser manipulado, sendo \
            'win32' e 'uia' os valores aceitos.

    Returns:
        Retorna int, sendo o PID do processo manipulado.

    Raises:
        ...

    Examples:
        >>> conectar_app(
        ...     pid=notepad_pid,
        ...     tempo_espera=10,
        ...     estilo_aplicacao='win32',
        ... )
        33144
    """

    # define app como global
    global APP
    global ESTILO_APLICACAO

    ESTILO_APLICACAO = estilo_aplicacao

    # instancia o objeto application
    APP = _aplicacao(estilo_aplicacao=ESTILO_APLICACAO)

    # inicia o processo de execução do aplicativo passado como parâmetro
    app_conectado: Application = _conectar_app(
        pid=pid,
        tempo_espera=tempo_espera,
        estilo_aplicacao=ESTILO_APLICACAO,
    )

    # coleta o PID da aplicação instanciada
    processo_app: int = app_conectado.process

    # retorna o PID coletado
    return processo_app

Escolha o estilo da aplicação, Win32 ou UIA, de acordo com a arquitetura da aplicação que se quer manipular. Aplicações Win32 são aplicações no estilo clássico do Windows, já aplicações UIA são aplicações modernas, em sua maioria disponibilizadas a partir da loja do Windows. Recomendamos que, em caso de dúvidas, teste as possibilidades e escolha o que melhor se adequa ao momento.

---

Digitando em um elemento

Para escrever algum texto ou número em um elemento, utilize a função digitar. Em caso de número, deve ser enviado em formato string.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função digitar

Digita em um elemento dentro de um objeto do tipo Application.

Parameters:

Name	Type	Description	Default
caminho_campo	dict	Caminho do elemento na estrutura da aplicação sendo manipulada.	required
valor	str	O valor a ser digitado.	required

Returns:

Type	Description
str	Retorna str, sendo o valor do campo após a inserção do valor informado.

Raises:

Type	Description
ValueError	caminho_campo precisa ser do tipo dict.

Examples:

>>> digitar(
...     caminho_campo={
...         'window': {
...             'title': 'Character Map',
...             'child_window': {
...                 'control_type': 'Edit',
...                 'auto_id': '104',
...             }
...         }
...     },
...     valor='ABCDE',
... )
"['ABCDE']"

Source code in py_rpautom\desktop_utils.py

def digitar(
    caminho_campo: dict,
    valor: str,
) -> str:
    """Digita em um elemento dentro de um objeto do tipo Application.

    Parameters:
        caminho_campo: Caminho do elemento na estrutura da aplicação \
            sendo manipulada.
        valor: O valor a ser digitado.

    Returns:
        Retorna str, sendo o valor do campo após a inserção do valor \
            informado.

    Raises:
        ValueError: `caminho_campo` precisa ser do tipo dict.


    Examples:
        >>> digitar(
        ...     caminho_campo={
        ...         'window': {
        ...             'title': 'Character Map',
        ...             'child_window': {
        ...                 'control_type': 'Edit',
        ...                 'auto_id': '104',
        ...             }
        ...         }
        ...     },
        ...     valor='ABCDE',
        ... )
        "['ABCDE']"
    """

    if isinstance(caminho_campo, dict) is False:
        raise ValueError('`caminho_campo` precisa ser do tipo dict.')

    # localiza o elemento até o final da árvore de parantesco do app
    app_interno = _localizar_elemento(caminho_campo)
    app_interno.exists()

    # digita o valor no campo localizado
    app_interno.set_edit_text(
        text=valor,
    )

    # trata o valor capturado conforme o tipo do valor de entrada
    valor_retornado = str(capturar_texto(caminho_campo))

    # retorna o valor capturado e tratado
    return valor_retornado

---

Fechando uma aplicação

Para fechar uma aplicação e todas as suas janelas abertas, utilize a função encerrar_app.

função encerrar_app

Encerra um processo do sistema de um objeto do tipo Application sendo manipulado.

Parameters:

Name	Type	Description	Default
pid	int	PID do processo existente.	required
forcar	bool	Força o encerramento do processo.	False
tempo_espera	int	Tempo limite em segundos para a tentativa de encerramento do processo.	60

Returns:

Type	Description
bool	Retorna booleano, True caso o processo seja encerrado com sucesso, False caso o processo não seja encerrado com sucesso

Raises:

Type	Description
ValueError	caminho_campo precisa ser do tipo dict.

Examples:

>>> encerrar_app(
...     pid=39440,
...     forcar=True,
...     tempo_espera=10,
... )
True

Source code in py_rpautom\desktop_utils.py

def encerrar_app(
    pid: int,
    forcar: bool = False,
    tempo_espera: int = 60,
) -> bool:
    """Encerra um processo do sistema de um objeto do tipo Application \
        sendo manipulado.

    Parameters:
        pid: PID do processo existente.
        forcar: Força o encerramento do processo.
        tempo_espera: Tempo limite em segundos para a tentativa de \
            encerramento do processo.

    Returns:
        Retorna booleano, `True` caso o processo seja encerrado \
            com sucesso, `False` caso o processo não seja \
            encerrado com sucesso

    Raises:
        ValueError: `caminho_campo` precisa ser do tipo dict.
        ...


    Examples:
        >>> encerrar_app(
        ...     pid=39440,
        ...     forcar=True,
        ...     tempo_espera=10,
        ... )
        True
    """

    # importa app para o escopo da função
    global APP

    # conecta a aplicação correspondente ao PID informado
    app_interno: Application = _conectar_app(
        pid=pid,
        tempo_espera=tempo_espera,
        estilo_aplicacao=ESTILO_APLICACAO,
    )

    # encerra o aplicativo em execução
    app_interno.kill(soft=not forcar)

    # retorna o objeto application com o processo encerrado
    return True

---

Coletando o estado de foco atual da janela

As janelas de uma aplicação dentro de um sistema operacional tem estados de focos padrões, com foco ou sem foco. Estes estados de foco podem ser capturados utilizando a função esta_com_foco, que retorna a situação do foco da janela no momento de sua execução.

função esta_com_foco

Verifica se a janela de um objeto do tipo Application está com foco.

Parameters:

Name	Type	Description	Default
nome_janela	str	O nome de uma janela já manipulável.	required

Returns:

Type	Description
bool	Retorna booleano, True caso a janela estiver com foco, False caso a janela não estiver com foco.

Examples:

Validação sem foco na janela no momento da execução do comando

>>> esta_com_foco(
...     nome_janela='Untitled - Notepad',
... )
False

Validação com foco na janela no momento da execução do comando

>>> esta_com_foco(
...     nome_janela='Untitled - Notepad',
... )
True

Source code in py_rpautom\desktop_utils.py

def esta_com_foco(nome_janela: str) -> bool:
    """Verifica se a janela de um objeto do tipo Application está com foco.

    Parameters:
        nome_janela: O nome de uma janela já manipulável.

    Returns:
        Retorna booleano, `True` caso a janela estiver com foco, \
        `False` caso a janela não estiver com foco.

    Raises:
        ...

    Examples:
        #### Validação sem foco na janela no momento da execução do comando
        >>> esta_com_foco(
        ...     nome_janela='Untitled - Notepad',
        ... )
        False

        #### Validação com foco na janela no momento da execução do comando
        >>> esta_com_foco(
        ...     nome_janela='Untitled - Notepad',
        ... )
        True
    """

    # importa app para o escopo da função
    global APP

    # inicializa APP para uma variável interna
    app_interno = APP

    # retorna a situacao atual de foco da janela
    return app_interno.window(title=nome_janela).has_focus()

---

Coletando o estado de visibilidade atual de uma janela

As janelas de uma aplicação dentro de um sistema operacional tem estados de visibilidade padrões, como visível ou não visível. Entende-se por visível, a situação da janela onde está em estado 'maximizado' ou 'normal'. E não visível para 'minimizado'. Estes estados de visibilidade podem ser capturados utilizando a função esta_visivel, que retorna a situação de visibilidade da janela no momento de sua execução.

função esta_visivel

Verifica se a janela de um objeto do tipo Application está visível.

Parameters:

Name	Type	Description	Default
nome_janela	dict	Caminho da janela na estrutura da aplicação sendo manipulada.	required

Returns:

Type	Description
str	Retorna uma string, sendo um dos valores a seguir: 'visivel', 'não visível', e 'não identificado'.

Examples:

Validação com a janela restaurada no momento da execução do comando

>>> esta_visivel(
...     nome_janela={
...         'window': {
...             'title': 'Untitled - Notepad',
...         }
...     }
... )
'visivel'

Validação com a janela minimizada no momento da execução do comando

>>> esta_visivel(
...     nome_janela={
...         'window': {
...             'title': 'Untitled - Notepad',
...         }
...     }
... )
'não visível'

Source code in py_rpautom\desktop_utils.py

def esta_visivel(nome_janela: dict) -> str:
    """Verifica se a janela de um objeto do tipo Application está visível.

    Parameters:
        nome_janela: Caminho da janela na estrutura da aplicação \
            sendo manipulada.

    Returns:
        Retorna uma string, sendo um dos valores a seguir: 'visivel', \
            'não visível', e 'não identificado'.

    Raises:
        ...

    Examples:
        #### Validação com a janela restaurada no momento da execução do comando
        >>> esta_visivel(
        ...     nome_janela={
        ...         'window': {
        ...             'title': 'Untitled - Notepad',
        ...         }
        ...     }
        ... )
        'visivel'

        #### Validação com a janela minimizada no momento da execução do comando
        >>> esta_visivel(
        ...     nome_janela={
        ...         'window': {
        ...             'title': 'Untitled - Notepad',
        ...         }
        ...     }
        ... )
        'não visível'
    """

    # coleta a situação atual da janela
    situacao = coletar_situacao_janela(nome_janela)

    # define visível para situação 'maximizado' ou 'normal'
    if situacao == 'maximizado' or situacao == 'normal':
        situacao = 'visivel'
    # define não visível para situação 'minimizado'
    elif situacao == 'minimizado':
        situacao = 'não visível'
    # Caso não encontre as situações normal, ninimizado e maximizado
    else:
        # define um valor padrão
        situacao = 'não identificado'

    # retorna a situação da janela
    return situacao

---

Fechando uma janela de uma aplicação

Para fechar uma janela aberta de uma aplicação, utilize a função fechar_janela.

função fechar_janela

Encerra uma janela de um objeto do tipo Application sendo manipulado.

Parameters:

Name	Type	Description	Default
caminho_janela	dict	Caminho da janela na estrutura da aplicação sendo manipulada.	required

Returns:

Type	Description
bool	Retorna booleano, True.

Raises:

Type	Description
ValueError	caminho_janela precisa ser do tipo dict.

Examples:

>>> fechar_janela(
...     caminho_janela={
...         'window': {
...             'title': 'Untitled - Notepad',
...         }
...     }
... )
True

Source code in py_rpautom\desktop_utils.py

def fechar_janela(caminho_janela: dict) -> bool:
    """Encerra uma janela de um objeto do tipo Application sendo manipulado.

    Parameters:
        caminho_janela: Caminho da janela na estrutura da aplicação \
            sendo manipulada.

    Returns:
        Retorna booleano, `True`.

    Raises:
        ValueError: `caminho_janela` precisa ser do tipo dict.

    Examples:
        >>> fechar_janela(
        ...     caminho_janela={
        ...         'window': {
        ...             'title': 'Untitled - Notepad',
        ...         }
        ...     }
        ... )
        True
    """

    # importa app para o escopo da função
    global APP

    if isinstance(caminho_janela, dict) is False:
        raise ValueError('`caminho_janela` precisa ser do tipo dict.')

    # inicializa APP para uma variável interna
    app_interno = _localizar_elemento(
        caminho_campo=caminho_janela,
    )
    app_interno.exists()

    # fecha a janela informada
    app_interno.close()

    # retorna verdadeiro confirmando a execução da ação
    return True

---

Iniciando uma aplicação

Para iniciar e abrir uma aplicação, utilize a função iniciar_app conforme descrito abaixo.

função iniciar_app

Inicia um processo do sistema de um objeto do tipo Application sendo manipulado.

Parameters:

Name	Type	Description	Default
executavel	str	Caminho da aplicação a ser manipulada.	required
estilo_aplicacao	str	Estilo de aplicação a ser manipulado, sendo 'win32' e 'uia' os valores aceitos.	'win32'
esperar	tuple	Define, em uma tupla, a condição esperada pela aplicação, sendo o primeiro valor a condição esperada nos valores 'exists', 'visible', 'enabled', 'ready', ou 'active', e o segundo valor o tempo limite de espera em segundos.	()
inverter	bool	True Aguarda a inicialização da aplicação ficar na condição informada, False aguarda a inicialização da aplicação ficar diferente da condição informada.	False
ocioso	bool	Define se deve aguardar a inicialização da aplicação sair do ocioso. True para aguardar, False para não aguardar.	False

Returns:

Type	Description
int	Retorna int, sendo o PID do processo manipulado.

Examples:

>>> iniciar_app(
...     executavel= 'C:\Program Files\WindowsApps\Microsoft.WindowsNotepad_11.2410.21.0_x64__8wekyb3d8bbwe\Notepad\Notepad.exe',
...     estilo_aplicacao='uia',
...     esperar=('ready', 10),
...     ocioso=False,
...     inverter=True,
... )
40944

Source code in py_rpautom\desktop_utils.py

def iniciar_app(
    executavel: str,
    estilo_aplicacao: str = 'win32',
    esperar: tuple = (),
    inverter: bool = False,
    ocioso: bool = False,
) -> int:
    """Inicia um processo do sistema de um objeto do tipo Application  sendo manipulado.

    Parameters:
        executavel: Caminho da aplicação a ser manipulada.
        estilo_aplicacao: Estilo de aplicação a ser manipulado, sendo \
            'win32' e 'uia' os valores aceitos.
        esperar: Define, em uma tupla, a condição esperada pela \
            aplicação, sendo o primeiro valor a condição esperada nos \
            valores 'exists', 'visible', 'enabled', 'ready', ou 'active', \
            e o segundo valor o tempo limite de espera em segundos.
        inverter: `True` Aguarda a inicialização da aplicação \
            ficar na condição informada, `False` aguarda a inicialização \
            da aplicação ficar diferente da condição informada.
        ocioso: Define se deve aguardar a inicialização da \
            aplicação sair do ocioso. `True` para aguardar, \
            `False` para não aguardar.

    Returns:
        Retorna int, sendo o PID do processo manipulado.

    Raises:
        ...

    Examples:
        >>> iniciar_app(
        ...     executavel= 'C:\\Program Files\\WindowsApps\\Microsoft.WindowsNotepad_11.2410.21.0_x64__8wekyb3d8bbwe\\Notepad\\Notepad.exe',
        ...     estilo_aplicacao='uia',
        ...     esperar=('ready', 10),
        ...     ocioso=False,
        ...     inverter=True,
        ... )
        40944
    """

    # define app como global
    global APP
    global ESTILO_APLICACAO

    ESTILO_APLICACAO = estilo_aplicacao

    # instancia o objeto application
    APP = _aplicacao(estilo_aplicacao=ESTILO_APLICACAO)

    # inicia o processo de execução do aplicativo passado como parâmetro
    APP.start(
        cmd_line=executavel,
        wait_for_idle=ocioso,
    )

    esperar_por = tempo_espera = None
    # verifica se foi passado algum parâmetro para esperar, caso não:
    if esperar == ():
        # aguarda a inicialização da aplicação ficar pronta em até 10 segundos
        esperar_por = 'ready'
        tempo_espera = 10
    else:
        esperar_por, tempo_espera = esperar

    if inverter is False:
        # aguarda a inicialização da aplicação ficar na condição informada
        APP.window().wait(
            wait_for=esperar_por,
            timeout=tempo_espera,
            retry_interval=None,
        )
    else:
        # aguarda a inicialização da aplicação não ficar na condição informada
        APP.window().wait_not(
            wait_for_not=esperar_por,
            timeout=tempo_espera,
            retry_interval=None,
        )

    # coleta o PID da aplicação instanciada
    processo_app: int = APP.process

    # retorna o PID coletado
    return processo_app

---

Coletando o estado de existência atual de uma janela

Para verificar se uma janela de uma aplicação existe, utilize a função janela_existente.

função janela_existente

Verifica se a janela de um objeto do tipo Application existe.

Parameters:

Name	Type	Description	Default
nome_janela		O nome de uma janela já manipulável.	required
pid		PID do processo existente.	required

Returns:

Type	Description
bool	Retorna booleano, True caso a janela da aplicação exista, False caso a janela da aplicação não exista.

Examples:

>>> janela_existente(
...     pid=39440,
...     nome_janela='Untitled - Notepad',
... )
True

Source code in py_rpautom\desktop_utils.py

def janela_existente(pid, nome_janela) -> bool:
    """Verifica se a janela de um objeto do tipo Application existe.

    Parameters:
        nome_janela: O nome de uma janela já manipulável.
        pid: PID do processo existente.

    Returns:
        Retorna booleano, `True` caso a janela da aplicação exista, \
            `False` caso a janela da aplicação não exista.

    Raises:
        ...

    Examples:
        >>> janela_existente(
        ...     pid=39440,
        ...     nome_janela='Untitled - Notepad',
        ... )
        True
    """

    # coleta a situação atual da janela
    lista_janelas = retornar_janelas_disponiveis(pid)

    # verifica se o nome da janela informada corresponde à alguma janela na lista
    for janela in lista_janelas:
        # caso o nome da janela seja o mesmo da janela atual da lista
        if janela == nome_janela:
            # retorna True
            return True

    # retorna False caso nenhuma janela tenha correspondido
    return False

---

Selecionando um caminho em uma lista de diretórios

Para selecionar um caminho em uma lista hierárquica de diretórios, elemento do tipo treeview, utilize a função localizar_diretorio_em_treeview.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função localizar_diretorio_em_treeview

Localiza um diretório, seguindo a árvore de diretórios informada, dentro de um objeto TreeView do tipo Application.

Parameters:

Name	Type	Description	Default
caminho_janela	dict	Caminho da janela na estrutura da aplicação sendo manipulada.	required
caminho_diretorio	str	Caminho da estrutura de diretórios a ser localizada.	required

Returns:

Type	Description
bool	Retorna booleano, True caso a localização tenha sucesso, False caso a localização não tenha sucesso.

Raises:

Type	Description
ValueError	caminho_janela precisa ser do tipo dict.

Examples:

...

Source code in py_rpautom\desktop_utils.py

def localizar_diretorio_em_treeview(
    caminho_janela: dict,
    caminho_diretorio: str,
) -> bool:
    """Localiza um diretório, seguindo a árvore de diretórios informada, \
        dentro de um objeto TreeView do tipo Application.

    Parameters:
        caminho_janela: Caminho da janela na estrutura da aplicação \
            sendo manipulada.
        caminho_diretorio: Caminho da estrutura de diretórios a ser localizada.

    Returns:
        Retorna booleano, `True` caso a localização tenha sucesso, \
            `False` caso a localização não tenha sucesso.

    Raises:
        ValueError: `caminho_janela` precisa ser do tipo dict.

    Examples:
        ...
    """

    try:
        if isinstance(caminho_janela, dict) is False:
            raise ValueError('`caminho_janela` precisa ser do tipo dict.')

        # localiza e armazena o elemento conforme informado
        app_interno = _localizar_elemento(caminho_janela)
        app_interno.exists()

        # seleciona o caminho informado na janela do tipo TreeView
        app_interno.TreeView.get_item(caminho_diretorio).click()

        # clica em Ok para confirmar
        app_interno.OK.click()

        # retorna verdadeiro caso processo seja feito com sucesso
        return True
    except:
        return False

---

Localizando uma janela ou elemento em uma janela

É possível verificar se uma janela ou um elemento dentro de uma janela na estrutura de elementos da aplicação que está sendo manipulado existe através da função localizar_elemento.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função localizar_elemento

Retorna se o caminho de elementos informado existe no objeto do tipo Application sendo manipulado.

Parameters:

Name	Type	Description	Default
caminho_campo	dict	Caminho do elemento na estrutura da aplicação sendo manipulada.	required
estilo_aplicacao		Estilo de aplicação a ser manipulado, sendo 'win32' e 'uia' os valores aceitos.	'win32'

Returns:

Type	Description
bool	Retorna booleano, True caso o caminho do elemento na aplicação exista, False caso o caminho do elemento na aplicação não exista.

Raises:

Type	Description
ValueError	caminho_campo precisa ser do tipo dict.

Examples:

>>> localizar_elemento(
...     caminho_campo={
...         'window': {
...             'title': 'Untitled - Notepad',
...             'child_window': {
...                 'title': 'DesktopWindowXamlSource',
...                 'best_match': 'Windows.UI.Composition.DesktopWindowContentBridge2',
...                 'child_window': {
...                     'best_match': 'Windows.UI.Input.InputSite.WindowClass2',
...                 }
...             }
...         }
...     },
...     estilo_aplicacao='win32',
... )
True

Source code in py_rpautom\desktop_utils.py

def localizar_elemento(
    caminho_campo: dict,
    estilo_aplicacao='win32',
) -> bool:
    """Retorna se o caminho de elementos informado existe no objeto do \
        tipo Application sendo manipulado.

    Parameters:
        caminho_campo: Caminho do elemento na estrutura da aplicação \
            sendo manipulada.
        estilo_aplicacao: Estilo de aplicação a ser manipulado, sendo \
            'win32' e 'uia' os valores aceitos.

    Returns:
        Retorna booleano, `True` caso o caminho do elemento na aplicação \
            exista, `False` caso o caminho do elemento na aplicação \
            não exista.

    Raises:
        ValueError: `caminho_campo` precisa ser do tipo dict.

    Examples:
        >>> localizar_elemento(
        ...     caminho_campo={
        ...         'window': {
        ...             'title': 'Untitled - Notepad',
        ...             'child_window': {
        ...                 'title': 'DesktopWindowXamlSource',
        ...                 'best_match': 'Windows.UI.Composition.DesktopWindowContentBridge2',
        ...                 'child_window': {
        ...                     'best_match': 'Windows.UI.Input.InputSite.WindowClass2',
        ...                 }
        ...             }
        ...         }
        ...     },
        ...     estilo_aplicacao='win32',
        ... )
        True
    """

    # importa app para o escopo da função
    global APP

    if isinstance(caminho_campo, dict) is False:
        raise ValueError('`caminho_campo` precisa ser do tipo dict.')

    # inicializa APP para uma variável interna
    app_interno = _localizar_elemento(
        caminho_campo=caminho_campo,
    )
    app_interno.exists()

    return app_interno.exists()

---

Maximizando uma janela

As janelas de uma aplicação dentro de um sistema operacional tem estados padrões, como estar maximizado. utilize a função maximizar_janela para, no momento de sua execução, alterar uma janela para maximizado.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função maximizar_janela

Maximiza a janela de um objeto do tipo Application.

Parameters:

Name	Type	Description	Default
caminho_janela	dict	Caminho da janela na estrutura da aplicação sendo manipulada.	required

Returns:

Type	Description
bool	Retorna booleano, True caso a ação de maximizar tenha sucesso, False caso a ação de maximizar não tenha sucesso.

Examples:

>>> maximizar_janela(
...     caminho_janela={
...         'window': {
...             'title': 'Untitled - Notepad',
...         }
...     }
... )
True

Source code in py_rpautom\desktop_utils.py

def maximizar_janela(caminho_janela: dict) -> bool:
    """Maximiza a janela de um objeto do tipo Application.

    Parameters:
        caminho_janela: Caminho da janela na estrutura da aplicação \
            sendo manipulada.

    Returns:
        Retorna booleano, `True` caso a ação de maximizar tenha sucesso, \
        `False` caso a ação de maximizar não tenha sucesso.

    Raises:
        `caminho_janela` precisa ser do tipo dict.

    Examples:
        >>> maximizar_janela(
        ...     caminho_janela={
        ...         'window': {
        ...             'title': 'Untitled - Notepad',
        ...         }
        ...     }
        ... )
        True
    """

    # importa app para o escopo da função
    global APP

    if isinstance(caminho_janela, dict) is False:
        raise ValueError('`caminho_janela` precisa ser do tipo dict.')

    try:
        # localiza o elemento até o final da árvore de parantesco do app
        app_interno = _localizar_elemento(caminho_janela)
        app_interno.exists()

        # maximiza a janela informada
        app_interno.maximize()

        # retorna verdadeiro confirmando a execução da ação
        return True
    except:
        return False

---

Minimizando uma janela

As janelas de uma aplicação dentro de um sistema operacional tem estados padrões, como estar minimizado. utilize a função minimizar_janela para, no momento de sua execução, alterar uma janela para minimizado.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função minimizar_janela

Miniminiza a janela de um objeto do tipo Application.

Parameters:

Name	Type	Description	Default
caminho_janela	dict	Caminho da janela na estrutura da aplicação sendo manipulada.	required

Returns:

Type	Description
bool	Retorna booleano, True caso a ação de miniminizar tenha sucesso, False caso a ação de miniminizar não tenha sucesso.

Examples:

>>> minimizar_janela(
...     caminho_janela={
...         'window': {
...             'title': 'Untitled - Notepad',
...         }
...     }
... )
True

Source code in py_rpautom\desktop_utils.py

def minimizar_janela(caminho_janela: dict) -> bool:
    """Miniminiza a janela de um objeto do tipo Application.

    Parameters:
        caminho_janela: Caminho da janela na estrutura da aplicação \
            sendo manipulada.

    Returns:
        Retorna booleano, `True` caso a ação de miniminizar tenha sucesso, \
        `False` caso a ação de miniminizar não tenha sucesso.

    Raises:
        `caminho_janela` precisa ser do tipo dict.

    Examples:
        >>> minimizar_janela(
        ...     caminho_janela={
        ...         'window': {
        ...             'title': 'Untitled - Notepad',
        ...         }
        ...     }
        ... )
        True
    """

    # importa app para o escopo da função
    global APP

    if isinstance(caminho_janela, dict) is False:
        raise ValueError('`caminho_janela` precisa ser do tipo dict.')

    try:
        # localiza o elemento até o final da árvore de parantesco do app
        app_interno = _localizar_elemento(caminho_janela)
        app_interno.exists()

        # miniminiza a janela informada
        app_interno.minimize()

        # retorna verdadeiro confirmando a execução da ação
        return True
    except:
        return False

---

Movendo o mouse

Há um recurso para movimentação do mouse até um ponto específico da tela, mediante coordenadas de eixo X e Y. As coordenadas precisam ser informadas em pixels e representam o posicionamento de pixels da tela. Para isso, utilize a função mover_mouse.

função mover_mouse

Move o mouse para o ponto das coordenadas X e Y informadas.

Parameters:

Name	Type	Description	Default
eixo_x	int	valor int para a posição de coordenada X.	required
eixo_y	int	valor int para a posição de coordenada Y.	required

Returns:

Type	Description
bool	Retorna booleano, True caso tenha sucesso ao mover o mouse, False caso não tenha sucesso ao mover o mouse.

Raises:

Type	Description
ValueError	Coordenadas precisam ser do tipo inteiro .

Examples:

>>> mover_mouse(eixo_x=961, eixo_y=562,)
True

Source code in py_rpautom\desktop_utils.py

def mover_mouse(eixo_x: int, eixo_y: int) -> bool:
    """Move o mouse para o ponto das coordenadas X e Y informadas.

    Parameters:
        eixo_x: valor int para a posição de coordenada X.
        eixo_y: valor int para a posição de coordenada Y.

    Returns:
        Retorna booleano, `True` caso tenha sucesso ao mover o mouse, \
        `False` caso não tenha sucesso ao mover o mouse.

    Raises:
        ValueError: Coordenadas precisam ser do tipo inteiro .

    Examples:
        >>> mover_mouse(eixo_x=961, eixo_y=562,)
        True
    """

    # importa recursos do módulo mouse
    from pywinauto.mouse import move

    if (not isinstance(eixo_x, int)) or (not isinstance(eixo_y, int)):
        raise ValueError('Coordenadas precisam ser do tipo inteiro .')

    try:
        move(coords=(eixo_x, eixo_y))

        return True
    except:
        return False

---

Restaurando uma janela

As janelas de uma aplicação dentro de um sistema operacional tem estados padrões, como estar restaurado. utilize a função restaurar_janela para, no momento de sua execução, alterar uma janela para restaurado.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função restaurar_janela

Restaura a janela de um objeto do tipo Application.

Parameters:

Name	Type	Description	Default
caminho_janela	dict	Caminho da janela na estrutura da aplicação sendo manipulada.	required

Returns:

Type	Description
bool	Retorna booleano, True caso a ação de restaurar tenha sucesso, False caso a ação de restaurar não tenha sucesso.

Examples:

>>> restaurar_janela(
...     caminho_janela={
...         'window': {
...             'title': 'Untitled - Notepad',
...         }
...     }
... )
True

Source code in py_rpautom\desktop_utils.py

def restaurar_janela(caminho_janela: dict) -> bool:
    """Restaura a janela de um objeto do tipo Application.

    Parameters:
        caminho_janela: Caminho da janela na estrutura da aplicação \
            sendo manipulada.

    Returns:
        Retorna booleano, `True` caso a ação de restaurar tenha sucesso, \
        `False` caso a ação de restaurar não tenha sucesso.

    Raises:
        `caminho_janela` precisa ser do tipo dict.

    Examples:
        >>> restaurar_janela(
        ...     caminho_janela={
        ...         'window': {
        ...             'title': 'Untitled - Notepad',
        ...         }
        ...     }
        ... )
        True
    """

    # importa app para o escopo da função
    global APP

    if isinstance(caminho_janela, dict) is False:
        raise ValueError('`caminho_janela` precisa ser do tipo dict.')

    try:
        # localiza o elemento até o final da árvore de parantesco do app
        app_interno = _localizar_elemento(caminho_janela)
        app_interno.exists()

        # restaura a janela informada
        app_interno.restore()

        # retorna verdadeiro confirmando a execução da ação
        return True
    except:
        return True

---

Verificando janelas disponíveis

Um recurso muito comum é a verificação das janelas existentes de uma aplicação em execução. Para coletar todos os nomes de janelas disponíveis de uma aplicação em execução e que está sendo manipulada, utilize a função abaixo, que retornará, em string, os nomes coletados no momento de sua execução.

função retornar_janelas_disponiveis

Retorna as janelas disponíveis em um objeto do tipo Application manipulável.

Parameters:

Name	Type	Description	Default
pid	int	PID do processo existente.	required
estilo_aplicacao		Estilo de aplicação a ser manipulado, sendo 'win32' e 'uia' os valores aceitos.	'win32'

Returns:

Type	Description
list[str]	Retorna uma lista de strings, sendo o valor capturado do PID informado.

Examples:

>>> retornar_janelas_disponiveis(
...     pid=24728,
...     estilo_aplicacao='uia'
... )

Source code in py_rpautom\desktop_utils.py

def retornar_janelas_disponiveis(
    pid: int,
    estilo_aplicacao='win32',
) -> list[str]:
    """Retorna as janelas disponíveis em um objeto do tipo \
        Application manipulável.

    Parameters:
        pid: PID do processo existente.
        estilo_aplicacao: Estilo de aplicação a ser manipulado, sendo \
            'win32' e 'uia' os valores aceitos.

    Returns:
        Retorna uma lista de strings, sendo o valor capturado do PID \
            informado.

    Raises:
        ...

    Examples:
        >>> retornar_janelas_disponiveis(
        ...     pid=24728,
        ...     estilo_aplicacao='uia'
        ... )
    """

    # importa app para o escopo da função
    global APP
    global ESTILO_APLICACAO

    ESTILO_APLICACAO = estilo_aplicacao

    # instancia o objeto application
    APP = _aplicacao(estilo_aplicacao=ESTILO_APLICACAO)

    # conecta a aplicação correspondente ao PID informado
    tempo_espera = 60
    app_interno: Application = _conectar_app(
        pid=pid,
        tempo_espera=tempo_espera,
        estilo_aplicacao=ESTILO_APLICACAO,
    )

    # coleta as janelas disponíveis
    lista_janelas = app_interno.windows()

    # instancia uma lista vazia
    lista_janelas_str = []
    # para cada janela na lista de janelas
    for janela in lista_janelas:
        # coleta e salva o nome da janela
        lista_janelas_str.append(janela.texts()[0])

    # retorna uma lista das janelas coletadas
    return lista_janelas_str

Escolha o estilo da aplicação, Win32 ou UIA, de acordo com a arquitetura da aplicação que se quer manipular. Aplicações Win32 são aplicações no estilo clássico do Windows, já aplicações UIA são aplicações modernas, em sua maioria disponibilizadas a partir da loja do Windows. Recomendamos que, em caso de dúvidas, teste as possibilidades e escolha o que melhor se adequa ao momento.

---

Selecionando uma aba disponível

Para em um elemento de conjunto de abas, elemento do tipo tab control, selecionar alguma opção das opções de abas disponíveis, utilize a função abaixo, que retornará, em booleano, se a aba foi selecionada no momento de sua execução. É possível selecionar a aba informando o número correspondente da aba, ou seu nome, através do parâmetro item.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função selecionar_aba

Seleciona uma aba em um conjunto de abas de um objeto do tipo Application manipulável.

Parameters:

Name	Type	Description	Default
caminho_campo	dict	Caminho do elemento na estrutura da aplicação sendo manipulada.	required
item	Union[str, int]	Valor em int ou em str da aba a ser selecionada.	required

Returns:

Type	Description
bool	Retorna booleano, True caso a aba seja selecionada com sucesso, False caso a aba não seja selecionada com sucesso.

Raises:

Type	Description
ValueError	caminho_campo precisa ser do tipo dict.
ValueError	item precisa ser do tipo int ou str.

Examples:

...

Source code in py_rpautom\desktop_utils.py

def selecionar_aba(caminho_campo: dict, item: Union[str, int]) -> bool:
    """Seleciona uma aba em um conjunto de abas de um objeto do tipo \
        Application manipulável.

    Parameters:
        caminho_campo: Caminho do elemento na estrutura da aplicação \
            sendo manipulada.
        item: Valor em int ou em str da aba a ser selecionada.

    Returns:
        Retorna booleano, `True` caso a aba seja selecionada com sucesso, \
        `False` caso a aba não seja selecionada com sucesso.

    Raises:
        ValueError: `caminho_campo` precisa ser do tipo dict.
        ValueError: `item` precisa ser do tipo int ou str.
        ...

    Examples:
        ...
    """

    from pywinauto.controls.common_controls import TabControlWrapper

    # define estático como falso para trabalhar com elemento dinâmico
    if isinstance(caminho_campo, dict) is False:
        raise ValueError('`caminho_campo` precisa ser do tipo dict.')

    if isinstance(item, str) is False and isinstance(item, int) is False:
        raise ValueError('`item` precisa ser do tipo int ou str.')

    # localiza o elemento até o final da árvore de parantesco do app
    app_interno = _localizar_elemento(caminho_campo)
    app_interno.exists()

    try:
        # seleciona o item informado
        app_interno = TabControlWrapper(app_interno)
        app_interno.select(item).click_input()

        return True
    except:
        return False

---

Selecionando um valor em um campo de listas

Para em um campo de listas, elemento do tipo listbox, selecionar alguma opção das opções da listagem disponível, utilize a função abaixo, que retornará, em booleano, se a opção foi selecionada no momento de sua execução.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função selecionar_em_campo_lista

Seleciona um dado em um elemento de lista em um objeto do tipo Application.

Parameters:

Name	Type	Description	Default
caminho_campo	dict	Caminho do elemento na estrutura da aplicação sendo manipulada.	required
item	int	Valor em int da opção no campo de seleção a ser selecionada.	required
selecionar	bool	Ativa seleção física direto no elemento informado.	True
performar	bool	Ativa clique físico direto no elemento informado.	False

Returns:

Type	Description
bool	Retorna booleano, True caso a opção no campo de seleção seja selecionada com sucesso, False caso a opção no campo de seleção não seja selecionada com sucesso.

Raises:

Type	Description
ValueError	caminho_campo precisa ser do tipo dict.
ValueError	item precisa ser do tipo int.
ValueError	selecionar precisa ser do tipo bool.
ValueError	performar precisa ser do tipo bool.

Examples:

...

Source code in py_rpautom\desktop_utils.py

def selecionar_em_campo_lista(
    caminho_campo: dict,
    item: int,
    selecionar: bool = True,
    performar: bool = False,
) -> bool:
    """Seleciona um dado em um elemento de lista em um objeto do \
        tipo Application.

    Parameters:
        caminho_campo: Caminho do elemento na estrutura da aplicação \
            sendo manipulada.
        item: Valor em int da opção no campo de seleção \
            a ser selecionada.
        selecionar: Ativa seleção física direto no elemento informado.
        performar: Ativa clique físico direto no elemento informado.

    Returns:
        Retorna booleano, `True` caso a opção no campo de seleção seja \
            selecionada com sucesso, `False` caso a opção no campo de \
            seleção não seja selecionada com sucesso.

    Raises:
        ValueError: `caminho_campo` precisa ser do tipo dict.
        ValueError: `item` precisa ser do tipo int.
        ValueError: `selecionar` precisa ser do tipo bool.
        ValueError: `performar` precisa ser do tipo bool.

    Examples:
        ...
    """

    if isinstance(caminho_campo, dict) is False:
        raise ValueError('`caminho_campo` precisa ser do tipo dict.')

    if isinstance(item, int) is False:
        raise ValueError('`item` precisa ser do tipo int.')

    if isinstance(selecionar, bool) is False:
        raise ValueError('`selecionar` precisa ser do tipo bool.')

    if isinstance(performar, bool) is False:
        raise ValueError('`performar` precisa ser do tipo bool.')

    # localiza o elemento até o final da árvore de parantesco do app
    app_interno = _localizar_elemento(caminho_campo)

    try:
        # seleciona o item informado
        if performar is True:
            app_interno.select(item=item, select=selecionar).click_input()
        else:
            app_interno.select(item=item, select=selecionar)

        return True
    except:
        return False

---

Selecionando um valor em um campo de seleção

Para em um campo de seleção, elemento do tipo combobox, selecionar alguma opção das opções disponíveis, utilize a função abaixo, que retornará, em string, o valor do campo informado alterado no momento de sua execução.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função selecionar_em_campo_selecao

Seleciona uma opção em um elemento de seleção em um objeto do tipo Application.

Parameters:

Name	Type	Description	Default
caminho_campo	dict	Caminho do elemento na estrutura da aplicação sendo manipulada.	required
item	str	Valor em str da opção no campo de seleção a ser selecionada.	required

Returns:

Type	Description
str	Retorna str, sendo o valor capturado do elemento informado após a opção selecionada.

Raises:

Type	Description
ValueError	caminho_campo precisa ser do tipo dict.
ValueError	item precisa ser do tipo int.
ValueError	selecionar precisa ser do tipo bool.
ValueError	performar precisa ser do tipo bool.

Examples:

>>> selecionar_em_campo_selecao(
...     caminho_campo={
...         'window': {
...             'title': 'Character Map',
...             'child_window': {
...                 'title': 'Font :',
...                 'control_type': 'ComboBox',
...                 'auto_id': '105',
...             }
...         }
...     },
...     item='Arial'
... )
'Arial'

Source code in py_rpautom\desktop_utils.py

def selecionar_em_campo_selecao(caminho_campo: dict, item: str) -> str:
    """Seleciona uma opção em um elemento de seleção em um objeto do \
        tipo Application.

    Parameters:
        caminho_campo: Caminho do elemento na estrutura da aplicação \
            sendo manipulada.
        item: Valor em str da opção no campo de seleção \
            a ser selecionada.

    Returns:
        Retorna str, sendo o valor capturado do elemento informado após \
            a opção selecionada.

    Raises:
        ValueError: `caminho_campo` precisa ser do tipo dict.
        ValueError: `item` precisa ser do tipo int.
        ValueError: `selecionar` precisa ser do tipo bool.
        ValueError: `performar` precisa ser do tipo bool.

    Examples:
        >>> selecionar_em_campo_selecao(
        ...     caminho_campo={
        ...         'window': {
        ...             'title': 'Character Map',
        ...             'child_window': {
        ...                 'title': 'Font :',
        ...                 'control_type': 'ComboBox',
        ...                 'auto_id': '105',
        ...             }
        ...         }
        ...     },
        ...     item='Arial'
        ... )
        'Arial'
    """

    # define estático como falso para trabalhar com elemento dinâmico
    if isinstance(caminho_campo, dict) is False:
        raise ValueError('`caminho_campo` precisa ser do tipo dict.')

    # localiza o elemento até o final da árvore de parantesco do app
    app_interno = _localizar_elemento(caminho_campo)
    app_interno.exists()

    # seleciona o item informado
    app_interno.select(item).click_input()

    # captura o texto do campo localizado
    valor_capturado = coletar_dado_selecionado(caminho_campo)

    # retorna o valor capturado
    return valor_capturado

---

Selecionando um item de menu

Para em menu, elemento do tipo MenuBar, selecionar alguma opção dos itens de menu disponíveis, utilize a função abaixo, que retornará, em booleano, se o item de menu foi selecionado no momento de sua execução.

Para informar o caminho do elemento, deve-se seguir a estrutura de elementos conforme apresendado na sessão "Estrutura de hierarquia de um elemento".

função selecionar_menu

Seleciona um item de menu conforme o caminho informado em um objeto do tipo Application.

Parameters:

Name	Type	Description	Default
caminho_janela	dict	Caminho da janela na estrutura da aplicação sendo manipulada.	required
caminho_menu	str	Caminho do menu na estrutura da aplicação sendo manipulada. Deve ser informado no formato 'Menu1->Menu2->Menu3'.	required

Returns:

Type	Description
bool	Retorna booleano, True caso a ação de selecionar o menu tenha sucesso, False caso a ação de selecionar o menu não tenha sucesso.

Raises:

Type	Description
ValueError	caminho_campo precisa ser do tipo dict.
ValueError	item precisa ser do tipo int.
ValueError	selecionar precisa ser do tipo bool.
ValueError	performar precisa ser do tipo bool.

Examples:

...

Source code in py_rpautom\desktop_utils.py

def selecionar_menu(caminho_janela: dict, caminho_menu: str) -> bool:
    """Seleciona um item de menu conforme o caminho informado em um objeto \
        do tipo Application.

    Parameters:
        caminho_janela: Caminho da janela na estrutura da aplicação \
            sendo manipulada.
        caminho_menu: Caminho do menu na estrutura da aplicação \
            sendo manipulada. Deve ser informado no formato \
            'Menu1->Menu2->Menu3'.

    Returns:
        Retorna booleano, `True` caso a ação de selecionar o menu \
            tenha sucesso, `False` caso a ação de selecionar o menu \
            não tenha sucesso.

    Raises:
        `caminho_janela` precisa ser do tipo dict.

    Raises:
        ValueError: `caminho_campo` precisa ser do tipo dict.
        ValueError: `item` precisa ser do tipo int.
        ValueError: `selecionar` precisa ser do tipo bool.
        ValueError: `performar` precisa ser do tipo bool.

    Examples:
        ...
    """

    # importa app para o escopo da função
    if isinstance(caminho_janela, dict) is False:
        raise ValueError('`caminho_janela` precisa ser do tipo dict.')

    try:
        # localiza o elemento até o final da árvore de parantesco do app
        app_interno = _localizar_elemento(caminho_janela)
        app_interno.exists()

        # percorre e clica no menu informado
        app_interno.menu_select(caminho_menu)

        # retorna verdadeiro confirmando a execução da ação
        return True
    except:
        return False

---

Simulando clique do mouse

Há um recurso para disparar eventos de clique do mouse em um ponto específico da tela, mediante coordenadas de eixo X e Y. As coordenadas precisam ser informadas em pixels e representam o posicionamento de pixels da tela. Para isso, utilize a função simular_clique.

função simular_clique

Simula clique físico do mouse conforme coordenadas X e Y informadas.

Parameters:

Name	Type	Description	Default
botao	str	valor str para o lado do botão a ser simulado. Aceita valores 'ESQUERDO' e 'DIREITO'.	required
eixo_x	int	valor int para a posição de coordenada X.	required
eixo_y	int	valor int para a posição de coordenada Y.	required
tipo_clique	str	valor str para o tipo de clique a ser simulado. Aceita valores 'UNICO' e 'DUPLO'.	'unico'

Returns:

Type	Description
bool	Retorna booleano, True caso tenha sucesso ao simular o clique, False caso não tenha sucesso ao simular o clique.

Raises:

Type	Description
ValueError	Informe um botão válido: esquerdo, direito.
ValueError	Tipo de clique inválido, escolha entre único e duplo.
ValueError	Coordenadas precisam ser do tipo inteiro .

Examples:

>>> simular_clique(
...     botao='ESQUERDO',
...     eixo_x=valor_eixo_x,
...     eixo_y=valor_eixo_y,
...     tipo_clique='UNICO',
... )
True

Source code in py_rpautom\desktop_utils.py

def simular_clique(
    botao: str,
    eixo_x: int,
    eixo_y: int,
    tipo_clique: str = 'unico',
) -> bool:
    """Simula clique físico do mouse conforme coordenadas X e Y informadas.

    Parameters:
        botao: valor str para o lado do botão a ser simulado. \
            Aceita valores 'ESQUERDO' e 'DIREITO'.
        eixo_x: valor int para a posição de coordenada X.
        eixo_y: valor int para a posição de coordenada Y.
        tipo_clique: valor str para o tipo de clique a ser simulado. \
            Aceita valores 'UNICO' e 'DUPLO'.

    Returns:
        Retorna booleano, `True` caso tenha sucesso ao simular o clique, \
        `False` caso não tenha sucesso ao simular o clique.

    Raises:
        ValueError: Informe um botão válido: esquerdo, direito.
        ValueError: Tipo de clique inválido, escolha entre único e duplo.
        ValueError: Coordenadas precisam ser do tipo inteiro .

    Examples:
        >>> simular_clique(
        ...     botao='ESQUERDO',
        ...     eixo_x=valor_eixo_x,
        ...     eixo_y=valor_eixo_y,
        ...     tipo_clique='UNICO',
        ... )
        True
    """

    # importa recursos do módulo mouse
    from pywinauto.mouse import click, double_click

    if not botao.upper() in ['ESQUERDO', 'DIREITO']:
        raise ValueError('Informe um botão válido: esquerdo, direito.')

    if not tipo_clique.upper() in ['UNICO', 'DUPLO']:
        raise ValueError(
            'Tipo de clique inválido, escolha entre único e duplo.'
        )

    if (not isinstance(eixo_x, int)) or (not isinstance(eixo_y, int)):
        raise ValueError('Coordenadas precisam ser do tipo inteiro .')

    if botao.upper() == 'ESQUERDO':
        botao = 'left'
    else:
        botao = 'right'

    try:
        if tipo_clique.upper() == 'UNICO':
            click(button=botao, coords=(eixo_x, eixo_y))
        else:
            double_click(button=botao, coords=(eixo_x, eixo_y))

        return True
    except Exception:
        return False

---

Simulando digitação do teclado

Há um recurso para disparar eventos de digitação do teclado em um ponto específico da tela, mediante coordenadas de eixo X e Y. As coordenadas precisam ser informadas em pixels e representam o posicionamento de pixels da tela. Para isso, utilize a função simular_digitacao.

função simular_digitacao

Simula digitação do teclado, performando o teclado real.

Parameters:

Name	Type	Description	Default
texto	str	valor str para o valor do texto a ser digitado. Aceita valores 'ESQUERDO' e 'DIREITO'.	required
com_espaco	bool	valor booleano, True para digitar com espaços, False para remover espaços ao digitar.	True
com_tab	bool	valor booleano, True para digitar tab ao final da digitação, False para não digitar tab ao final da digitação.	False
com_linha_nova	bool	valor booleano, True para digitar linha nova ao final da digitação, False para não digitar linha nova ao final da digitação.	False

Returns:

Type	Description
bool	Retorna booleano, True caso tenha sucesso ao simular a digitação, False caso não tenha sucesso ao simular a digitação.

Raises:

Type	Description
ValueError	Informe os parâmetros com_espaco, com_tab e com_linha_nova com valor boleano.
ValueError	Informe um texto do tipo string.

Examples:

>>> simular_digitacao(
...     texto = 'FGHIJ',
...     com_espaco = True,
...     com_tab = False,
...     com_linha_nova = False,
... )
True

Source code in py_rpautom\desktop_utils.py

def simular_digitacao(
    texto: str,
    com_espaco: bool = True,
    com_tab: bool = False,
    com_linha_nova: bool = False,
) -> bool:
    """Simula digitação do teclado, performando o teclado real.

    Parameters:
        texto: valor str para o valor do texto a ser digitado. \
            Aceita valores 'ESQUERDO' e 'DIREITO'.
        com_espaco: valor booleano, `True` para digitar com espaços, \
            `False` para remover espaços ao digitar.
        com_tab: valor booleano, `True` para digitar tab ao final \
            da digitação, `False` para não digitar tab ao final \
            da digitação.
        com_linha_nova: valor booleano, `True` para digitar linha \
            nova ao final da digitação, `False` para não digitar linha \
            nova ao final da digitação.

    Returns:
        Retorna booleano, `True` caso tenha sucesso ao simular \
            a digitação, `False` caso não tenha sucesso ao simular \
            a digitação.

    Raises:
        ValueError: Informe os parâmetros com_espaco, com_tab e \
            com_linha_nova com valor boleano.
        ValueError: Informe um texto do tipo string.

    Examples:
        >>> simular_digitacao(
        ...     texto = 'FGHIJ',
        ...     com_espaco = True,
        ...     com_tab = False,
        ...     com_linha_nova = False,
        ... )
        True
    """

    # importa recursos do módulo keyboard
    from pywinauto.keyboard import send_keys

    if (
        (not isinstance(com_espaco, bool))
        or (not isinstance(com_tab, bool))
        or (not isinstance(com_linha_nova, bool))
    ):
        raise ValueError(
            """Informe os parâmetros com_espaco,
                com_tab e com_linha_nova com valor boleano"""
        )

    if not isinstance(texto, str):
        raise ValueError('Informe um texto do tipo string.')

    try:
        send_keys(
            keys=texto,
            with_spaces=com_espaco,
            with_tabs=com_tab,
            with_newlines=com_linha_nova,
        )

        return True
    except:
        return False