brown.core.graphic_object

classes

permalink view source

GraphicObject (ABC)

An abstract graphic object.

All classes in core which have the ability to be displayed should be subclasses of this.

A single GraphicObject can have multiple graphical representations, calculated 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 GraphicObject has another GraphicObject for a parent, except Page objects, whose parent is always the global 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 brown.document.pages[n]

Render the object and all its children.

Returns: None

Add an object to self.children.

Args: child (GraphicObject): The object to add

Returns: None

Remove an object from self.children.

Args: child (GraphicObject): The object to remove

Returns: None

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

Returns: None

Render the entire object.

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

This method should create a GraphicInterface and store it in self.interfaces.

Args: pos (Point): The rendering position in document space for drawing. dist_to_line_start (Unit): If in a Flowable, the x-axis distance from the active NewLines beginning. Otherwise, this is always None. Subclasses may use this information to perform basic position modifications at render time, though in most cases this field can be ignored. local_start_x (Unit): If this object is in a flowable, the local starting position of this drawing segment.

Returns: None

Note: All GraphicObject subclasses should implement this for correct rendering.

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.

This method should create a GraphicInterface and store it in self.interfaces.

Args: local_start_x (Unit): The local starting position of this drawing segment. start (Point): The starting point in document space for drawing. stop (Point): The stopping point in document space for drawing. dist_to_line_start (Unit): The x-axis distance from the active NewLines beginning. Subclasses may use this information to perform basic position modifications at render time, though in most cases this field can be ignored.

Returns: None

Note: All GraphicObject subclasses whose length can be nonzero must implement this method.

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.

This method should create a GraphicInterface and store it in self.interfaces.

Args: local_start_x (Unit): The local starting position of this drawing segment. start (Point): The starting point in document space for drawing. stop (Point): The stopping point in document space for drawing.

Returns: None

Note: All GraphicObject subclasses whose length can be nonzero must implement this method.

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.

This method should create a GraphicInterface and store it in self.interfaces.

Args: local_start_x (Unit): The local starting position of this drawing segment. start (Point): The starting point in document space for drawing. stop (Point): The stopping point in document space for drawing.

Returns: None

Note: All GraphicObject subclasses whose length can be nonzero must implement this method.

__init__ (pos, length=None, pen=None, brush=None, parent=None) permalink view source

arguments:

pos (Point[Unit] or tuple): The position of the object relative to its parent

length (Unit): The width of the object which can be subject to breaking across lines when in aFlowable. If the object is not inside a Flowable, this has no effect

pen (Pen): The pen to draw outlines with.

brush (Brush): The brush to draw outlines with.

parent (GraphicObject): The parent object or None

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.

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

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

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

length: Unit The breakable length of the object. permalink view source

This is used to determine how and where rendering cuts should be made.

read-only.

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

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.

parent: GraphicObject The parent object. permalink view source

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

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

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.

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.

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

read-only.

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.

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

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

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

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.

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.