neoscore.core.positioned_object

class neoscore.core.positioned_object.render_cached_property

Bases: cached_property

A property annotation for fields which can be cached at render time.

You can annotate any PositionedObject property to get this behavior, including on inheriting classes.

class Example(PositionedObject):
    @render_cached_property
    def some_expensive_computed_property(self):
        ...

Such properties must be immutable during rendering. Typical @property setters are not supported.

__init__(func)

class neoscore.core.positioned_object.PositionedObject

Bases: object

An object positioned in the scene

This is the base class of all objects in the neoscore scene tree.

A single PositionedObject can have multiple graphical representations derived at render-time. If the object’s ancestor is a Flowable, it will be rendered as a flowable object, capable of being wrapped around lines.

The position of this object is relative to that of its parent. Each PositionedObject has another PositionedObject for a parent, except Page objects, whose parent is always the global root Document.

For convenience, the parent may be initialized to None to indicate the first page of the document.

To place objects directly in the scene on pages other than the first, simply set the parent to the desired page, accessed through the global document with neoscore.document.pages[n]

__init__(pos: PointDef, parent: Optional[PositionedObject])

Parameters

• pos – The position of the object relative to its parent

• parent – The parent object. Defaults to the document’s first page.

property pos: Point

The position of the object relative to its parent.

property scale: float

A scale factor to be applied to the rendered object.

Outside flowable contexts, scaling is inherited by children.

Scaling occurs relative to self.transform_origin, which is by default the local origin.

property rotation: float

A rotation angle in degrees.

Outside flowable contexts, rotation is inherited by children.

Rotation occurs relative to self.transform_origin, which is by default the local origin.

property transform_origin: Point

The origin point for rotation and scaling transforms

property x: Unit

The x position of the object relative to its parent.

property y: Unit

The y position of the object relative to its parent.

property breakable_length: Unit

The breakable length of the object.

This is used to determine how and where rendering cuts should be made. A length of zero indicates that no rendering cuts will be made.

The default implementation of this method returns ZERO. Subclasses which want to support flowable line breaks should override this method.

property parent: PositionedObject

The parent object.

If this is set to None, it defaults to the first page of the document.

property children: List[PositionedObject]

All direct children of this object.

property descendants: Iterator[PositionedObject]

All the objects in the children subtree.

This recursively searches all the object’s children (and their children, etc.) and provides an iterator over them.

The current implementation performs a simple recursive DFS over the tree, and has the potential to be rather slow.

flowable

The flowable this object belongs in.

property interfaces: List[PositionedObjectInterface]

The graphical backend binding interfaces for this object

Interface objects are created and stored here upon calling render.

Typically each PositionedObject will have at most one interface for each flowable line it appears in.

property interface_for_children: Optional[PositionedObjectInterface]

The low level object interface to be used by children objects.

Outside flowable contexts, interface classes utilize a parenting scheme much like core classes. The interfaces of child objects should use this field as their parent for proper position and transform inheritance.

Users should rarely, if ever, have to deal with this field.

descendants_of_class_or_subclass(graphic_object_class: Type[PositionedObject]) → Iterator[PositionedObject]

Yield all child descendants with a given class or its subclasses.

descendants_of_exact_class(graphic_object_class: Type[PositionedObject]) → Iterator[PositionedObject]

Yield all child descendants of a given class, excluding sublcasses

descendants_with_attribute(attribute: str) → Iterator[PositionedObject]

Yield all child descendants which has a given attribute.

This is useful for searching descendants for duck-typing matches.

property ancestors: Iterator[PositionedObject]

All ancestors of this object.

Follows the chain of parents up to and including the Document root.

The order begins with self.parent and traverses upward in the document tree.

first_ancestor_with_attr(attr: str) → Optional[PositionedObject]

Find this object’s closest ancestor with an attribute

descendant_pos(descendant: PositionedObject) → Point

Find the position of a descendant relative to this object.

Raises

ValueError – If descendant is not a descendant of this object.

descendant_pos_x(descendant: PositionedObject) → Unit

Find the x position of a descendant relative to this object.

This is a specialized version of descendant_pos provided for optimization.

Raises

ValueError – If descendant is not a descendant of this object.

map_to(dst: PositionedObject) → Point

Find an object’s logical position relative to this one

This calculates the position in logical space, which differs from canvas space in that it doesn’t account for repositioning of objects inside Flowable containers. For example, this function will return the same relative position for two objects in a Flowable container whether they are separated by a line break.

map_x_to(dst: PositionedObject) → Unit

Like map_to, but only return the X distance from to dst.

distance_to(obj: PositionedObject, offset: Point = ORIGIN) → Unit

Find the distance to a given object, with an optional extra offset.

Like map_to, this works in logical coordinates.

canvas_pos() → Point

Find the document-space position of this object.

For objects in Flowables, this should only be accessed at render time, when flowable layouts are available.

remove()

Remove this object from the document tree.

pre_render_hook()

Run code once just before document rendering begins.

Implementations must call the superclass function as well.

post_render_hook()

Run code once after document rendering completes.

Implementations must call the superclass function as well.

render()

Render the object and all its children.

This and other render methods should generally not be called directly.

render_in_flowable()

Render the object to the scene, dispatching partial rendering calls when needed if an object flows across a break in the flowable.

This and other render methods should generally not be called directly.

render_complete(pos: Point, flowable_line: Optional[NewLine] = None, flowable_x: Optional[Unit] = None)

Render the entire object.

This is used to render all objects outside flowables, as well as those inside flowables when they fit completely in one line of the flowable.

By default, this is a no-op. Subclasses with rendered appearances should override this.

This method behaves differently inside and outside of flowables. Whether this object is inside a flowable can be determined by whether a flowable_line is given. When inside a flowable, the given position is in global document coordinates, and created interfaces (or higher level classes) must not be assigned a parent. When not inside a flowable, the given position is relative to self.parent and created interfaces (or higher level classes) must be assigned a parent. In this case, created interfaces should use self.parent.interface_for_children as their parent.

This and other render methods should generally not be called directly.

Parameters

• pos – The rendering position. If outside a flowable, this is relative to the parent. Otherwise, it is in document coordinates.

• flowable_line – If in a Flowable, the line in which this object appears

• flowable_x – If in a Flowable, the flowable x position of this render

render_before_break(pos: Point, flowable_line: NewLine, flowable_x: Unit)

Render the beginning of the object up to a stopping point.

For use in flowable containers when rendering an object that crosses a line or page break. This function should render the beginning portion of the object up to the break.

By default, this is a no-op. Subclasses with rendered appearances should override this.

Created interfaces and higher level objects should not be assigned a parent.

This and other render methods should generally not be called directly.

Parameters

• pos – The rendering position in document space for drawing.

• flowable_line – The line in which this object appears

• flowable_x – The flowable x position of this render

render_spanning_continuation(pos: Point, flowable_line: NewLine, object_x: Unit)

Render the continuation of an object after a break and before another.

For use in flowable containers when rendering an object that crosses two breaks. This function should render the portion of the object surrounded by breaks on either side.

By default, this is a no-op. Subclasses with rendered appearances should override this.

Created interfaces and higher level objects should not be assigned a parent.

This and other render methods should generally not be called directly.

Parameters

• pos – The rendering position in document space for drawing.

• flowable_line – The line in which this object appears

• object_x – The local object x position of the line’s start.

render_after_break(pos: Point, flowable_line: NewLine, object_x: Unit)

Render the continuation of an object after a break.

For use in flowable containers when rendering an object that crosses a line or page break. This function should render the ending portion of an object after a break.

By default, this is a no-op. Subclasses with rendered appearances should override this.

Created interfaces and higher level objects should not be assigned a parent.

This and other render methods should generally not be called directly.

Parameters

• pos – The rendering position in document space for drawing.

• flowable_line – The line in which this object appears

• object_x – The local object x position of the line’s start.