Create text over other apps. Call show() to display it and to apply later changes. Enable press, drag or hold tracking with track(). Read current values with state(); text() and background() are methods.
badge = OverlayText("Running...", Point(320, 160, scale="width", anchor="top"), background=None)
badge.color("#FF00E676").background("#66000000").size(18).track(press=True, move=True, hold=True, hold_ms=700)
badge.show()
state = badge.state()
if state["status"] == 2:
MacroPanel.notify("Badge is moving")
p = badge.get_point()
r = badge.get_region()
if r is not None:
r.highlight("yellow", auto_hide_ms=600)
badge.hide() # hide fast
badge.show() # show again quickly
badge.off() # fully release
Fields
Name
Description
xNumber
Top-left X position in pixels. Writable before show().
Default:0
yNumber
Top-left Y position in pixels. Writable before show().
OverlayText — Returns this overlay so you can call another method on it.
Example
# Configure or inspect a flow-owned overlay
badge = OverlayText("Ready", (24, 120))
badge.position((80, 160))
badge.show()
OverlayText.track
Method
Configure press, drag and hold tracking. If all flags are False, the text stays fixed and touches pass through it. Where a movable highlight overlaps the text, enabled text interaction receives touches first. A gesture that starts outside the text stays with the highlight.
Report PRESSED after a short press is released without dragging or holding.
Optional · Positional or named
Default:False
moveBoolean
Allow dragging the text. Movement within the device touch threshold does not move it; dragging starts after the threshold is exceeded.
Optional · Positional or named
Default:False
holdBoolean
Report HOLDING after hold_ms, then HOLDED when released; dragging takes priority.
Optional · Positional or named
Default:False
hold_msNumber
Time to hold before HOLDING, in milliseconds. Values below 150 use 150.
Optional · Positional or named
Default:600
Returns
OverlayText — Returns this overlay so you can call another method on it.
Example
# Configure or inspect a flow-owned overlay
badge = OverlayText("Ready", (24, 120))
badge.track(press=True, move=True, hold=True, hold_ms=700)
badge.show()
print(badge.state())
OverlayText.get_point
Method
Get current top-left point of this overlay text. This position is updated after drag moves. This does not consume interaction events.
Syntax
overlay.get_point()
Returns
Point — Current overlay position in screen pixels.
Example
# Configure or inspect a flow-owned overlay
badge = OverlayText("Ready", (24, 120))
badge.show()
point = badge.get_point()
print(point.x, point.y)
OverlayText.get_region
Method
Get a region that wraps current overlay text bounds. Returns None when the overlay is not visible or not measured yet. This does not consume interaction events.
Syntax
overlay.get_region()
Returns
Region? — Bounding region for overlay text, or None. Always check for None before using the region.
Example
# Configure or inspect a flow-owned overlay
badge = OverlayText("Ready", (24, 120))
badge.show()
bounds = badge.get_region()
if bounds is not None:
print(bounds.width, bounds.height)
OverlayText.show
Method
Show the text, including after hide(), and apply changes to its content, style, position, tracking or writable fields. Call show() again after each configuration change.
If only the position changes while visible, only the latest position is kept for the next display frame. The call returns before it appears: returned x/y are the accepted position, and overlay_width_px/overlay_height_px are None. Other updates wait until applied.
While visible, show() preserves interaction state and events if tracking is unchanged. Showing after hide() or changing tracking resets to IDLE; changing tracking also cancels the previous gesture.
# Configure or inspect a flow-owned overlay
badge = OverlayText("Ready", (24, 120))
badge.show()
print(badge.off())
OverlayText.state
Method
Read the latest state. With the corresponding tracking enabled:
Press and release → PRESSED (1).
Drag → MOVING (2); release → MOVED (4).
Hold for hold_ms → HOLDING (3); release → HOLDED (7).
Other states: IDLE (0), HIDDEN (5), OFF (6). Pressing down alone creates no event; dragging takes priority over holding.
PRESSED, MOVED and HOLDED are returned once, then reset to IDLE. MOVING and HOLDING remain while active. Only the latest state is kept; a new event replaces an unread one. Cancellation creates no completion event. Pending position changes are applied before reading.
Only state() consumes terminal events. They do not expire, but polling every 100 ms cannot retain every event between reads.
Syntax
overlay.state()
Returns
dict — State dictionary with status/status_label, tracking flags, and optional overlay width/height in pixels.
Example
# Configure or inspect a flow-owned overlay
badge = OverlayText("Ready", (24, 120))
badge.track(press=True, move=True)
badge.show()
state = badge.state()
print(state["status_label"])
