Metadata-Version: 2.4
Name: movva-tech-library
Version: 0.1.1
Summary: Core library for movva tech aplications.
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: pyautogui>=0.9.53
Requires-Dist: pywinauto>=0.6.8; sys_platform == "win32"
Requires-Dist: numpy>=1.19.0
Requires-Dist: openpyxl>=3.1.2
Requires-Dist: pywin32>=306; sys_platform == "win32"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Provides-Extra: browser
Requires-Dist: selenium>=4.10.0; extra == "browser"
Requires-Dist: playwright>=1.40.0; extra == "browser"
Provides-Extra: browser-selenium
Requires-Dist: selenium>=4.10.0; extra == "browser-selenium"
Provides-Extra: browser-playwright
Requires-Dist: playwright>=1.40.0; extra == "browser-playwright"

# movva-tech-library

Uma biblioteca de automação desktop focada em Windows, encapsulando e simplificando as funcionalidades do `pywinauto` e `pyautogui`.

## Como inicializar

Para utilizar a biblioteca, basta importar e instanciar a classe `DesktopRobot`:

```python
from movva_tech_library import DesktopRobot
from pathlib import Path

# Instanciando o robô
robot = DesktopRobot()

## Referência de Métodos

### Gerenciamento de Aplicações e Janelas

- **Iniciar uma aplicação:**
  ```python
  robot.start_application(path=r"C:\Caminho\Para\App.exe", backend="uia")
  ```

- **Conectar a uma aplicação em execução:**
  ```python
  robot.connect_application(title="Meu App", backend="uia")
  ```

- **Esperar por uma janela específica:**
  ```python
  robot.wait_for_window(title="Janela Principal", timeout=10)
  ```

- **Definir janela ativa:** (Útil para buscar locators apenas dentro dessa janela)
  ```python
  robot.set_active_window(title="Janela Principal")
  ```

- **Encerrar aplicação:**
  ```python
  robot.kill()
  ```

### Interação com Elementos da Interface (Locators pywinauto)

Os métodos abaixo aceitam qualquer critério do `pywinauto` (ex: `title`, `auto_id`, `control_type`).

- **Clicar por locator:**
  ```python
  robot.click_by_locator(title="Botão Confirmar")
  ```

- **Duplo clique por locator:**
  ```python
  robot.double_click_by_locator(auto_id="btnDetalhes")
  ```

- **Obter texto de um elemento:**
  ```python
  texto = robot.get_text(auto_id="labelStatus")
  print(texto)
  ```

### Interação por Imagens na Tela (pyautogui)

> Recomenda-se o uso de caminhos absolutos para as imagens.

- **Clicar em uma imagem:**
  ```python
  # Opcional: usar offset_x e offset_y para clicar deslocado do centro da imagem
  image_path = str(BASE_DIR / "assets" / "botao.png")
  robot.click_by_image(image_path, confidence=0.9, timeout=10)
  ```

- **Esperar por uma imagem aparecer na tela:**
  ```python
  coordenadas = robot.wait_for_image(image_path, confidence=0.9, timeout=10)
  ```

### Teclado e Digitação

- **Digitar texto:**
  Pode focar em um elemento específico antes de digitar caso forneça um `locator`.
  ```python
  # Digita livremente onde o cursor estiver
  robot.type_text("Olá Mundo", interval=0.05)
  
  # Foca no input primeiro e depois digita
  robot.type_text("Meu texto direto no campo", locator={"auto_id": "inputTexto"})
  ```

- **Pressionar teclas isoladas:**
  ```python
  robot.press_key("enter")
  robot.press_key("tab", presses=2)
  ```

- **Pressionar atalhos (hotkeys):**
  ```python
  robot.hotkey("ctrl", "c")
  robot.hotkey("alt", "f4")
  ```

### Esperas (Timeouts e Pausas)

- **Pausa estática (não recomendado, use waits dinâmicos quando possível):**
  ```python
  robot.wait(2.5) # Aguarda 2.5 segundos
  ```
