Quick Start

Quick Start#

Installation#

Install PyScreenReader latest release from pip registries.

pip install PyScreenReader

PyScreenReader is still in active development.
If installation via pip fails, it may be due to incompatibility with your system’s OS, architecture, or Python interpreter version. Please kindly help us to file a report here.

Example#

In your Python script,

# Import the reader itself
from PyScreenReader.screen_reader import ScreenReader
# Import the widgets the reader will return
from PyScreenReader.virtual_widgets import VirtualWidget

# Create a screen reader instance
screen_reader = ScreenReader()
# Read the virtual widget tree by your program's PID
root = screen_reader.from_pid(20880)
# Print the location of the root widget extracted
print(f"Position of Root Widget (X: {root.get_x()}, Y: {root.get_y()})")

# Optional: Get all children of the root as a list of VirtualWidgets to traverse the tree!
children = root.get_children()

Virtual widgets (such as VirtualButtonWidget, etc.) are high-level abstractions of native system UI elements. They are organized into a hierarchical structure — a virtual widget tree — where each node represents a single widget on the screen.

In the example above, the root variable refers to the root node of the widget tree of program with PID 20880.
From there, you can navigate through its children and inspect each widget’s properties, including:

  • Control type

  • Bounding rectangle

  • Text content

  • Focus state

  • …

Code snippet below shows an example of BFS that traverses every node.

def print_tree(root: VirtualWidget) -> None:
    """Print a virtual widget tree using DFS.

    :param root: root of the virtual widget tree
    """
    node_stack = [(root, 0)]

    while node_stack:
        curr_node, indent = node_stack.pop()

        if curr_node is None:
            continue

        print(" " * (indent * 2) + str(curr_node))

        for child in reversed(curr_node.get_children()):
            node_stack.append((child, indent + 1))

# Pass in the root created above to print the entire widget tree
print_tree(root)

For more information, please refer to other pages in this documentation.

Contents