WindowsAppEnv

Die Anwendungsfälle für die Klasse WindowsAppEnv sind wie folgt:

• Öffnen eines angegebenen Dokuments.
• Abgleichen von Dokumentfenstern mithilfe verschiedener Strategien (contains, fuzzy und regex).
• Abgleichen der Steuerelemente, die für jeden Schritt im instanziierten Plan erforderlich sind, mithilfe verschiedener Strategien (contains, fuzzy und regex).
• Schließen eines angegebenen Dokuments.

Die folgenden Abschnitte bieten eine detaillierte Erklärung der Abgleichstrategien für Fenster und Steuerelemente sowie ihrer Verwendungsmethoden.

Abgleichstrategien

In der Klasse WindowsAppEnv sind Abgleichstrategien Regeln, die bestimmen, wie window- oder control-Namen mit einem gegebenen Dokumentnamen oder Zieltext übereinstimmen. Basierend auf der Konfigurationsdatei können drei verschiedene Abgleichstrategien ausgewählt werden: contains, fuzzy und regex.

• Der Contains-Abgleich ist die einfachste Strategie und eignet sich, wenn die Fenster- und Dokumentnamen exakt übereinstimmen.
• Der Fuzzy-Abgleich ist flexibler und kann auch bei Tippfehlern oder teilweisen Übereinstimmungen zwischen dem Fenstertitel und dem Dokumentnamen übereinstimmen.
• Der Regex-Abgleich bietet die größte Flexibilität und ist ideal für komplexe Abgleichmuster in Fenstertiteln.

1. Beispiel für Fensterabgleich

Die Methode find_matching_window ist für den Abgleich von Fenstern basierend auf der konfigurierten Abgleichstrategie zuständig. Hier ist, wie Sie sie verwenden können, um ein Fenster zu finden, indem Sie einen Dokumentnamen angeben.

Beispiel

# Initialize your application object (assuming app_object is already defined)
app_env = WindowsAppEnv(app_object)

# Define the document name you're looking for
doc_name = "example_document_name"

# Call find_matching_window to find the window that matches the document name
matching_window = app_env.find_matching_window(doc_name)

if matching_window:
    print(f"Found matching window: {matching_window.element_info.name}")
else:
    print("No matching window found.")

Erklärung

• app_env.find_matching_window(doc_name) durchsucht alle geöffneten Fenster und gleicht den Fenstertitel anhand der in der Konfiguration definierten Strategie (contains, fuzzy oder regex) ab.
• Wenn eine Übereinstimmung gefunden wird, enthält das Objekt matching_window das übereinstimmende Fenster, und Sie können den Namen des Fensters ausgeben.
• Wenn keine Übereinstimmung gefunden wird, wird None zurückgegeben.

2. Beispiel für Steuerelementabgleich

Um ein passendes Steuerelement innerhalb eines Fensters zu finden, können Sie die Methode find_matching_controller verwenden. Diese Methode erfordert ein Wörterbuch mit gefilterten Steuerelementen und einen abzugleichenden Steuerelementtext.

Beispiel

# Initialize your application object (assuming app_object is already defined)
app_env = WindowsAppEnv(app_object)

# Define a filtered annotation dictionary of controls (control_key, control_object)
# Here, we assume you have a dictionary of UIAWrapper controls from a window.
filtered_annotation_dict = {
    1: some_control_1,  # Example control objects
    2: some_control_2,  # Example control objects
}

# Define the control text you're searching for
control_text = "submit_button"

# Call find_matching_controller to find the best match
controller_key, control_selected = app_env.find_matching_controller(filtered_annotation_dict, control_text)

if control_selected:
    print(f"Found matching control with key {controller_key}: {control_selected.window_text()}")
else:
    print("No matching control found.")

Erklärung

• filtered_annotation_dict ist ein Wörterbuch, in dem der Schlüssel die ID des Steuerelements und der Wert das Steuerelementobjekt (UIAWrapper) darstellt.
• control_text ist der Text, nach dem Sie in diesen Steuerelementen suchen.
• app_env.find_matching_controller(filtered_annotation_dict, control_text) berechnet den Übereinstimmungs-Score für jedes Steuerelement basierend auf der definierten Strategie und gibt das Steuerelement mit dem höchsten Übereinstimmungs-Score zurück.
• Wenn eine Übereinstimmung gefunden wird, werden das Steuerelementobjekt (control_selected) und sein Schlüssel (controller_key) zurückgegeben, die für weitere Interaktionen verwendet werden können.

Referenz

29
30
31
32
33
34
35
36
37
38

def __init__(self, app_object: object) -> None:
    """
    Initializes the Windows Application Environment.
    :param app_object: The app object containing information about the application.
    """

    self.app_window = None
    self.app_root_name = app_object.app_root_name
    self.app_name = app_object.description.lower()
    self.win_app = app_object.win_app

57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

def close(self) -> None:
    """
    Tries to gracefully close the application; if it fails or is not closed, forcefully terminates the process.
    """

    try:
        # Gracefully close the application window
        if self.app_window and self.app_window.process_id():
            self.app_window.close()
        sleep(1)
        # Forcefully close the application window
        if self.app_window.element_info.name.lower() != "":
            self._check_and_kill_process()
    except Exception as e:
        logging.warning(
            f"Graceful close failed: {e}. Attempting to forcefully terminate the process."
        )
        self._check_and_kill_process()
        raise e

157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181

def find_matching_controller(
    self, filtered_annotation_dict: Dict[int, UIAWrapper], control_text: str
) -> Tuple[str, UIAWrapper]:
    """ "
    Select the best matched controller.
    :param filtered_annotation_dict: The filtered annotation dictionary.
    :param control_text: The text content of the control for additional context.
    :return: Tuple containing the key of the selected controller and the control object.s
    """
    control_selected = None
    controller_key = None
    highest_score = 0

    # Iterate through the filtered annotation dictionary to find the best match
    for key, control in filtered_annotation_dict.items():
        # Calculate the matching score using the match function
        score = self._calculate_match_score(control, control_text)

        # Update the selected control if the score is higher
        if score > highest_score:
            highest_score = score
            controller_key = key
            control_selected = control

    return controller_key, control_selected

 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105

def find_matching_window(self, doc_name: str) -> Optional[UIAWrapper]:
    """
    Finds a matching window based on the process name and the configured matching strategy.
    :param doc_name: The document name associated with the application.
    :return: The matched window or None if no match is found.
    """

    desktop = Desktop(backend=_BACKEND)
    windows_list = desktop.windows()
    for window in windows_list:
        window_title = window.element_info.name.lower()
        if self._match_window_name(window_title, doc_name):
            self.app_window = window
            return window
    return None

40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

def start(self, copied_template_path: str) -> None:
    """
    Starts the Windows environment.
    :param copied_template_path: The file path to the copied template to start the environment.
    """

    from ufo.automator.ui_control import openfile

    file_controller = openfile.FileController(_BACKEND)
    try:
        file_controller.execute_code(
            {"APP": self.win_app, "file_path": copied_template_path}
        )
    except Exception as e:
        logging.exception(f"Failed to start the application: {e}")
        raise