brown.core.flowable

classes

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 the vast majority of objects will be placed inside it.

Generate automatic layout controllers.

The generated controllers are stored in self.layout_controllers in sorted order according to ascending x position

Warning: This overwrites the contents of self.layout_controllers

Returns: None

Find the BreakOpporunity closest to the left a local x position.

Args: local_x(Unit): an x-axis position in the flowable space.

Returns: BreakOpportunity or None: the closest BreakOpporunity to the left of the given point, or None if none exists.

__init__ (pos, width, height, y_padding=Mm(5), break_threshold=Mm(5)) permalink view source

overriden from GraphicObject

arguments:

pos (Point or tuple): Starting position in relative to the top left corner of the live document area of the first page

width (Unit): length of the flowable

height (Unit): height of the flowable

y_padding (Unit): The vertical gap between flowable sections

break_threshold (Unit): The maximum distance the flowable will shorten a line to allow a break to occur on a BreakOpportunity

properties

length: Unit The length (length) of the unwrapped flowable permalink view source

overriden from GraphicObject

read-only.

height: Unit The height of the unwrapped flowable permalink view source

y_padding: Unit The padding between wrapped sections of the flowable permalink view source

break_threshold: Unit The threshold for BreakOpportunity-aware line breaks. permalink view source

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

If set to Unit(0) (or in an equivalent unit), BreakOpportunitys will be entirely ignored during layout.

layout_controllers: list[LayoutController] Controllers affecting flowable layout permalink view source

inherited properties

interfaces: set(GraphicObjectInterface) The interfaces for this object permalink view source

Interface objects are created upon calling GraphicObject.render()

Typically each GraphicObject will have one interface for each flowable line it appears in. Objects which fit completely in one visual line will typically have exactly one interface.

If this is an empty set, the object has not been rendered yet with the render() method.

read-only.

inherited from GraphicObject

pos: Point The position of the object relative to its parent. permalink view source

inherited from GraphicObject

x: Unit The x position of the object relative to its parent. permalink view source

inherited from GraphicObject

y: Unit The x position of the object relative to its parent. permalink view source

inherited from GraphicObject

pen: Pen The pen to draw outlines with permalink view source

inherited from GraphicObject

brush: Brush The brush to draw outlines with permalink view source

As a convenience, this may be set with a hex color string for a solid color brush of that color. For brushes using alpha channels and non-solid-color fill patterns, a fully initialized brush must be passed to this.

inherited from GraphicObject

parent: GraphicObject The parent object. permalink view source

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

inherited from GraphicObject

children: set(GraphicObject) All objects who have self as their parent. permalink view source

inherited from GraphicObject

descendants: iter[GraphicObject] All of the objects in the children subtree. permalink view source

This recursively searches all of 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.

read-only.

inherited from GraphicObject

ancestors: iter[GraphicObject] All ancestors of this object. permalink view source

Follows the chain of parents until a document page is reached. The iterable will not include the document Page.

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

read-only.

inherited from GraphicObject

flowable: Flowable or None The flowable this object belongs in. permalink view source

read-only.

inherited from GraphicObject

page_index: The index of the page this object appears on. permalink view source

>>> from brown.core import brown; brown.setup()
>>> some_object = GraphicObject((Mm(20), Mm(50)),
...                             parent=brown.document.pages[5])
>>> some_object.page_index
5
>>> some_object in brown.document.pages[5].descendants
True

read-only.

inherited from GraphicObject

inherited class methods

map_between_items (source, destination) permalink view source

Find a GraphicObject's position relative to another GraphicObject

arguments:

source (GraphicObject): The object to map from

destination (GraphicObject): The object to map to

returns:

Point: The canvas position of destination relative to source

inherited from GraphicObject

methods

map_to_canvas (local_point) permalink view source

Convert a local point to its position in the canvas.

arguments:

local_point (Point): A position in the flowable's local space.

returns:

Point: The position mapped to the canvas.

dist_to_line_start (local_x) permalink view source

Find the distance of an x-pos to the left edge of its laid-out line.

arguments:

local_x (Unit): An x-axis location in the virtual flowable space.

returns:

dist_to_line_end (local_x) permalink view source

Find the distance of an x-pos to the right edge of its laid-out line.

arguments:

local_x (Unit): An x-axis location in the virtual flowable space.

returns:

last_break_at (local_x) permalink view source

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

arguments:

local_x (Unit): An x-axis location in the virtual flowable space.

returns:

The result of this function will be accurate within Unit(1)

last_break_index_at (local_x) permalink view source

Like last_break_at, but returns an index.

arguments:

local_x (Unit): An x-axis location in the virtual flowable space.

returns:

int

The result of this function will be accurate within Unit(1)

pos_in_flowable_of (graphic_object) permalink view source

Find the position of an object in (unwrapped) flowable space.

arguments:

graphic_object (GraphicObject): An object in the flowable.

returns:

Point: A non-paged point relative to the flowable.

map_between_locally (source, destination) permalink view source

Find the relative position between two objects in this flowable.

arguments:

source (GraphicObject): The object to map from

destination (GraphicObject): The object to map to

returns:

Point: The relative position of destination, relative to source within the local flowable space.

inherited methods

descendants_of_class_or_subclass (graphic_object_class) permalink view source

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

Args: graphic_object_class (type): The type to search for. This should be a subclass of GraphicObject.

Yields: GraphicObject

inherited from GraphicObject

descendants_of_exact_class (graphic_object_class) permalink view source

Yield all child descendants with a given class.

Args: graphic_object_class (type): The type to search for. This should be a subclass of GraphicObject.

Yields: GraphicObject

inherited from GraphicObject

first_ancestor_of_class_or_subclass (graphic_object_class) permalink view source

Get the closest ancestor with a class or its subclasses.

arguments:

graphic_object_class (type): The type to search for. This should be a subclass of GraphicObject.

returns:

GraphicObject or None

If none can be found, returns None.

inherited from GraphicObject

first_ancestor_of_exact_class (graphic_object_class) permalink view source

Get the closest ancestor with a class.

arguments:

graphic_object_class (type or str): The type to search for. This should be a subclass of GraphicObject. A str of a class name may also be used.

returns:

GraphicObject or None

If none can be found, returns None.

inherited from GraphicObject