# 【Tutorial】取得應用程式上的畫面內容

## 簡介
Venom 是一款用於擴充應用程式功能的工具。由於其核心目的是操作應用程式的畫面內容，因此需要透過 `host-object-model` API，提供開發者一種方式來準確地取得目標應用程式的畫面元素。

在這篇教學中，我們將深入探討如何利用 `host-object-model` API 的功能來取得應用程式畫面，包括如何取得 Host 與 HomElement，以及如何利用描述檔（Descriptor）達成這些操作。

## Host 與 HomElement 的介紹

### Host 的意義
Host 是應用程式中的容器，代表整個畫面或主要的功能區域。通過描述檔，Host 能夠準確定位並管理其內部的元素。Host 是操作應用程式畫面的核心基礎。

### HomElement 的定義
HomElement 是 Host 中的 UI 元素。例如，按鈕、輸入框或文件夾等。每個 HomElement 都可以是樹狀結構的一部分，並可能包含多層次的子元素。

#### HomElement 的特性
1. **多個元素**:
- 用描述檔抓出的 HomElement 通常不只一個，例如文件管理器中的多個檔案或文件夾。

2. **樹狀結構**:
- 每個 HomElement 都是樹的一部分，可能包含子元素，並構成更大的 UI 結構。

## 可取得的畫面內容

Venom 提供強大的功能來獲取應用程式的多種資訊，以下是主要的內容類型：

1. **位置與尺寸資訊（Bounding Box）**:
- 獲取 UI 元素在畫面上的位置和大小。
- 可用於追蹤元素的移動或調整。

2. **名稱資訊（Name）**:
- 提供 UI 元素的名稱或標籤，用於識別和操作特定元素。

3. **值屬性（Value）**:
- 適用於可輸入或顯示數值的 UI 元素，例如文字框。

4. **滾動狀態（Scrollable）**:
- 確認元素是否支持滾動，並獲取滾動相關屬性。

5. **UI Pattern 支援**:
- 確認元素支持的操作模式，例如 Invoke、Selection 或 Value Pattern（詳見 [透過 Venom 操作應用程式](https://hackmd.io/@oolabsoftwarear/By_VSpVIye)）。

這些內容讓開發者能掌握應用程式的畫面結構與屬性。

## 使用描述檔（Descriptor）取得畫面內容
描述檔是 Venom 的關鍵組件，主要用於判斷需要操作的應用程式畫面或畫面上的特定元素。

### 描述檔的原理
Venom 透過 **UI Automation** 技術與應用程式進行互動。這項技術能夠以樹狀結構組織應用程式中的 UI 元素，讓描述檔能準確定位特定的 UI 元素或整體畫面。

### 描述檔的生成
詳細的描述檔生成方法請參考 [如何生成描述檔](https://hackmd.io/@oolabsoftwarear/HJMTpNs3p)。

## API 使用教學
以下是 `host-object-model` 中的核心 API，這些 API 可用於取得應用程式畫面的內容。

### 1. 取得 Host
#### `Parasite.getHost()`
這個方法用於透過描述檔獲取目標應用程式的 Host（主機）。

#### `Parasite.getSubscribedHost()`
這是 `getHost()` 的進階版本，不僅能取得 Host，還會為 Host 增加事件支持（如監控畫面元素的變化）。

const hostDescriptor = require('./descriptor/host.json') as DescriptorDTO;
const  myVenom = await Venom.create(url, hwnd)

// 取得訂閱的 Host
const host = myVenom.getSubscribedHost(hostDescriptor);

// 監控 Host 的變化
host.onBoundingBoxChanged((updatedHost) => {
    console.log('Host bounding box changed:', updatedHost.boundingBox);
});

### 2. 用描述檔取得 HomElement
Host 內部包含許多 UI 元素，這些元素稱為 HomElement。開發者可以使用描述檔來取得這些元素。

HomElement 位於 UI 樹狀結構中，當調用 API 時，可以指定範圍，例如使用 `UITreeScope.Subtree` 來獲取目標元素及其所有子元素。這種結構化方式能幫助開發者更直觀地操作和管理應用程式中的 UI。

const filesExplorerDescriptor = require('./descriptor/filesExplorer.json') as DescriptorDTO;

// 從 Host 中取得 HomElement
const filesExplorer = await host.getElementsByDescriptor(filesExplorerDescriptor, UITreeScope.Subtree);

// 遍歷取得的 HomElement
filesExplorer.forEach(element => {
    console.log('Element ID:', element.id);
});

## UI Tree 與操作
可參考 [UI Tree](https://hackmd.io/@oolabsoftwarear/ByFompEIke) 的相關文件來深入了解如何操作這些元素，以及如何實現複雜的 UI 自動化功能。