zooui.objects.mediaobjects.mediaobjectsutils.string.textlayout module

TextLayoutData class for storing pre-calculated text layout information.

This class encapsulates all the information needed to render text efficiently in parallel, including font metrics, bounding rectangles, and layout options.

Thread safety: All data is stored as plain Python types (str, float, int). Qt GUI objects (QFont, QColor) are only constructed on the main thread in render() or via the to_qfont()/to_qcolor() convenience methods. This ensures that TextLayoutData can be safely created and passed between threads without triggering Qt-internal C++ font database races.

class zooui.objects.mediaobjects.mediaobjectsutils.string.textlayout.TextAlignment(*values)

Bases: Enum

Text alignment options.

LEFT = 0

CENTER = 1

RIGHT = 2

JUSTIFY = 3

class zooui.objects.mediaobjects.mediaobjectsutils.string.textlayout.TextLayoutData(text, font_family='Sans Serif', font_pointsize=12.0, font_weight=Weight.Normal, font_italic=False, color_r=0, color_g=0, color_b=0, color_a=255, position=(0.0, 0.0), bounding_rect=<factory>, text_rect=<factory>, line_rects=<factory>, alignment=TextAlignment.LEFT, rotation=0.0, scale=1.0, opacity=1.0, timestamp=<factory>, is_valid=True)

Bases: object

Stores pre-calculated text layout information for efficient parallel rendering.

This class encapsulates all the information needed to render text without recalculating font metrics, bounding rectangles, or layout options during the rendering phase.

Font and color are stored as plain data (not Qt objects) so that TextLayoutData instances can be safely created on any thread. Qt objects are only constructed in render() (called from the main thread).

text

font_family = 'Sans Serif'

font_pointsize = 12.0

font_weight = 400

font_italic = False

color_r = 0

color_g = 0

color_b = 0

color_a = 255

position = (0.0, 0.0)

bounding_rect

text_rect

line_rects

alignment = 0

rotation = 0.0

scale = 1.0

opacity = 1.0

timestamp

is_valid = True

to_qfont()

Construct a QFont from the stored plain font data.

Must be called from the main thread. QFont accesses the global system font database, which is not thread-safe.

Returns:

QtGui.QFont configured with the stored family, size, weight and italic.

to_qcolor()

Construct a QColor from the stored RGBA values.

Safe to call from any thread, but typically called from the main thread during rendering.

Returns:

QtGui.QColor with the stored red, green, blue and alpha.

classmethod from_string_object(string_obj, viewport_rect)

Create TextLayoutData from a StringMediaObject.

Thread-safe: extracts plain data from the string object without constructing Qt GUI objects. All Qt object construction is deferred to render() (main thread).

Parameters:

• string_obj – StringMediaObject instance

• viewport_rect – Current viewport rectangle in scene coordinates

Returns:

TextLayoutData instance with pre-calculated layout

distance_to_viewport_center(viewport_center)

Calculate distance from text position to viewport center.

Parameters:

viewport_center – (x, y) tuple of viewport center

Returns:

Euclidean distance

is_in_viewport(viewport_rect)

Check if this text is visible in the current viewport.

Parameters:

viewport_rect – Current viewport rectangle

Returns:

True if text is visible, False otherwise

render(painter)

Render the text using the pre-calculated layout.

Constructs QFont and QColor on the calling thread (must be the main thread for QFont). Uses to_qfont() and to_qcolor() internally.

Parameters:

painter – QPainter object to render with

invalidate()

Mark this layout data as invalid (e.g., after font change).

is_stale(max_age_ms=1000.0)

Check if this layout data is stale and should be recalculated.

Parameters:

max_age_ms – Maximum age in milliseconds before considered stale

Returns:

True if stale, False otherwise

See Also

• zooui/objects/mediaobjects/stringmediaobject - StringMediaObject class

• zooui/objects/mediaobjects/mediaobjectsutils/string/parallellayout - Parallel layout management