OverlayText

Class

Draw text on top of the screen with optional interaction tracking (press/move/hold). Setter names such as text/background are methods; read current values through state().

Syntax

OverlayText(text="", position=(0, 0), color="#FFFFFFFF", size=16, background=None)

Constructor parameters

Name	Description
`textString`	Initial text content. Optional · Positional or named Default: `""`
`positionPoint \| tuple[Number, Number]`	Initial position as Point or tuple/list (x, y). Point carries scale/anchor metadata. Optional · Positional or named Default: `(0, 0)`
`colorColor \| String \| Number`	Initial text color. Optional · Positional or named Default: `white`
`sizeNumber`	Initial text size (sp). Optional · Positional or named Default: `16`
`backgroundColor \| String \| Number \| None`	Initial background color. None means transparent/no background. Optional · Positional or named Default: `None`

Returns

OverlayText

Example

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(). Default: `0`
`scaleString`	Coordinate scale copied from Point positions. Default: `fixed`
`anchorString`	Coordinate anchor copied from Point positions. Default: `none`
`argbColor`	Text color. Assign with Color/string/number values. Use overlay.color(value) for method chaining. Default: `white`
`size_spNumber`	Text size in sp. Use overlay.size(sp) for method chaining. Default: `16`

Constructor example

badge = OverlayText("Ready", Point(420, 220, scale="width", anchor="top"), background=None)

Methods

13 methods

OverlayText.off_all

Static Method

Turn off and release every overlay text created by the current flow, without affecting parallel flows.

Syntax

OverlayText.off_all()

Returns

None — No return value.

Example

# Release overlays owned by this flow
a = OverlayText("Running", (24, 120))
a.show()
OverlayText.off_all()

OverlayText.text

Method

Update displayed text content.

Syntax

overlay.text(value)

Parameters

Name	Description
`valueString`	Text content. Required · Positional or named No default

Returns

OverlayText — Returns the same overlay text builder.

Example

# Configure or inspect a flow-owned overlay
badge = OverlayText("Ready", (24, 120))
badge.text("Running")
badge.show()

OverlayText.color

Method

Update text color.

Syntax

overlay.color(value)

Parameters

Name	Description
`valueColor \| String \| Number`	Color value. Required · Positional or named No default

Returns

OverlayText — Returns the same overlay text builder.

Example

# Configure or inspect a flow-owned overlay
badge = OverlayText("Ready", (24, 120))
badge.color("#FF00E676")
badge.show()

OverlayText.background

Method

Update background color. Passing None removes the background.

Syntax

overlay.background(value=None)

Parameters

Name	Description
`valueColor \| String \| Number \| None`	Background color, or None for transparent/no background. Optional · Positional or named Default: `None`

Returns

OverlayText — Returns the same overlay text builder.

Example

# Configure or inspect a flow-owned overlay
badge = OverlayText("Ready", (24, 120))
badge.background("#66000000")
badge.show()
badge.background(None)

OverlayText.size

Method

Update text size (sp).

Syntax

overlay.size(sp)

Parameters

Name	Description
`spNumber`	Text size in sp. Required · Positional or named No default

Returns

OverlayText — Returns the same overlay text builder.

Example

# Configure or inspect a flow-owned overlay
badge = OverlayText("Ready", (24, 120))
badge.size(20)
badge.show()

OverlayText.position

Method

Update draw position with a Point or tuple/list (x, y). Point carries scale/anchor metadata.

Syntax

overlay.position(position)

Parameters

Name	Description
`positionPoint \| tuple[Number, Number]`	New position. Required · Positional or named No default

Returns

OverlayText — Returns the same overlay text builder.

Example

# Configure or inspect a flow-owned overlay
badge = OverlayText("Ready", (24, 120))
badge.position((80, 160))
badge.show()

OverlayText.track

Method

Configure interaction tracking. If all flags are False, the text stays fixed at declared position.

Syntax

overlay.track(press=False, move=False, hold=False, hold_ms=600)

Parameters

Name	Description
`pressBoolean`	Track press/release state. Optional · Positional or named Default: `False`
`moveBoolean`	Allow user drag to move text. Optional · Positional or named Default: `False`
`holdBoolean`	Track hold state. Optional · Positional or named Default: `False`
`hold_msNumber`	Hold threshold to treat interaction as holding, measured in milliseconds. Optional · Positional or named Default: `600`

Returns

OverlayText — Returns the same overlay text builder.

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.

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.

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 text overlay (or show again after hide()).

Syntax

overlay.show()

Returns

dict — Current overlay state dictionary.

Example

# Configure or inspect a flow-owned overlay
badge = OverlayText("Ready", (24, 120))
print(badge.show())

OverlayText.hide

Method

Hide overlay text but keep cached view for faster show().

Syntax

overlay.hide()

Returns

dict — Current overlay state dictionary.

Example

# Configure or inspect a flow-owned overlay
badge = OverlayText("Ready", (24, 120))
badge.show()
badge.hide()
badge.show()

OverlayText.off

Method

Turn off overlay text and release resources.

Syntax

overlay.off()

Returns

dict — Current overlay state dictionary.

Example

# Configure or inspect a flow-owned overlay
badge = OverlayText("Ready", (24, 120))
badge.show()
print(badge.off())

OverlayText.state

Method

Return current interaction state. Status map: 0=IDLE, 1=PRESSED, 2=MOVING, 3=HOLDING, 4=RELEASED, 5=HIDDEN, 6=OFF. Reading state() auto-resets PRESSED and RELEASED back to IDLE for the next poll; MOVING and HOLDING do not auto-reset.

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"])