neoscore.core.flowable

class neoscore.core.flowable.Flowable

Bases: PositionedObject

A flowable coordinate space container.

This provides a virtual horizontal strip of space in which objects can be placed, and at render time be automatically flowed across line breaks and page breaks in the document.

To place an object in a Flowable, simply parent it to one, or to an object already in one.

In typical scores, there will be a single Flowable placed in the first page of the document, and most objects will be placed inside it.

__init__(pos: PointDef, parent: Optional[PositionedObject], length: Unit, height: Unit, y_padding: Unit = Mm(5), break_threshold: Unit = Mm(5))

Parameters

• pos – Starting position in relative to the top left corner of the live document area of the first page

• parent – An optional parent object. Nested flowables are not supported, so this should not be a flowable or in one. This defaults to the document’s first page.

• length – length of the flowable

• height – height of the flowable

• y_padding – The vertical gap between flowable sections

• break_threshold – The maximum distance the flowable will shorten a line to allow a break to occur on a BreakOpportunity

property length: Unit

The length of the unwrapped flowable

property height: Unit

The height of the unwrapped flowable

property y_padding: Unit

The padding between wrapped sections of the flowable

property break_threshold: Unit

The threshold for BreakOpportunity-aware line breaks.

This is the maximum distance the flowable will shorten a line to allow a break to occur on a BreakOpportunity.

If set to ZERO, break opportunities will be entirely ignored during layout. On the other hand, if set to a value larger than the live page width, all break opportunities will be taken.

property lines: List[NewLine]

The generated lines of this flowable.

This property is managed and should not be modified.

property provided_controllers: SortedKeyList[MarginController]

Layout controllers provided by users.

Currently, this only supports margin controllers. Eventually on we may expand this to allow things like explicit user-defined NewLines.

Controllers should not be added directly to this list; use add_margin_controller instead.

add_margin_controller(controller: MarginController)

Add a margin controller if applicable.

If provided_controllers already has a margin controller at the given controller.flowable_x with the same layer_key, the controller is only inserted if its margin is larger than the existing one.

map_to_canvas(local_point: Point) → Point

Convert a local point to its position in the canvas.

Note that this should only be called at render-time, since it depends on layout controllers only generated once the flowable has started rendering.

Parameters

local_point – A position in the flowable’s local space.

last_break_at(flowable_x: Unit) → NewLine

Find the last NewLine that occurred before a given local flowable_x-pos

Parameters

flowable_x – An x-axis location in the virtual flowable space.

last_break_index_at(flowable_x: Unit) → int

Like last_break_at, but returns an index.

Parameters

flowable_x – An x-axis location in the virtual flowable space.

render()

Render the object and all its children.

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

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.