brown.core.staff

classes

A staff capable of holding StaffObjects

Create a Unit class with a ratio of 1 to a staff unit size

Args: staff_unit_size

Returns: type: A new StaffUnit class specifically for use in this staff.

__init__ (pos, length, flowable, staff_unit=None, line_count=5, music_font=None, default_time_signature_duration=None) permalink view source

overriden from GraphicObject

arguments:

pos (Point): The position of the top-left corner of the staff

length (Unit): The horizontal width of the staff

staff_unit (Unit): The distance between two lines in the staff. If not set, this will default to constants.DEFAULT_STAFF_UNIT

line_count (int): The number of lines in the staff.

music_font (MusicFont): The font to be used in all MusicTextObjects unless otherwise specified.

default_time_signature_duration (tuple or None): The duration tuple of the initial time signature. If none, (4, 4) will be used.

properties

unit: type(Unit) The standard distance between two lines in this staff. permalink view source

This is a generated class with the name StaffUnit. All Staff objects have a unique StaffUnit class such that different sized staves may coexist within a score and StaffObjects placed within them will be able to correctly position and scale themselves accordingly.

This class is generated automatically according to self.height and self.line_count, with the assumption that all staff lines are evenly spaced.

read-only.

height: Unit The height of the staff from top to bottom line. permalink view source

If the staff only has one line, its height is defined as 0.

read-only.

line_count: int The number of lines in the staff permalink view source

read-only.

top_line_y: StaffUnit The position of the top staff line permalink view source

read-only.

center_pos_y: StaffUnit The position of the center staff position permalink view source

read-only.

bottom_line_y: StaffUnit The position of the bottom staff line permalink view source

read-only.

inherited properties

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.

inherited from GraphicObject

current_draw_pos: Point The current drawing position relative to self.pos. permalink view source

This is the location from which operations like line_to() will draw.

To change this without connecting the path to the new position, use move_to().

read-only.

inherited from Path

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

straight_line (start, stop, pen=None, brush=None, parent=None) permalink view source

Path: Constructor for a straight line

arguments:

start (Point or init tuple): Starting position relative to the parent

stop (Point or init tuple): Ending position relative to the parent.

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

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

parent (GraphicObject): The parent object or None

returns:

inherited from Path

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

distance_to_next_of_type (staff_object) permalink view source

Find the x distance until the next occurrence of an object's type.

arguments:

staff_object (StaffObject):

returns:

If the object is the last of its type, this gives the remaining length of the staff after the object.

This is useful for determining rendering behavior of StaffObjects who are active until another of their type occurs, such as KeySignatures, or Clefs.

active_clef_at (pos_x) permalink view source

Find and return the active clef at a given x position.

arguments:

pos_x (Unit): An x-axis position on the staff

returns:

Clef: The active clef at pos_x None: If no clef is active at pos_x

active_transposition_at (pos_x) permalink view source

Find and return the active transposition at a given x position.

arguments:

pos_x (Unit): An x-axis position on the staff

returns:

Transposition: The active transposition at pos_x None: If no transposition was found.

The current implementation simply searches through the staff descendants for any OctaveLines which overlap with pos_x, and returns the transposition of the first found, and None if none are.

middle_c_at (pos_x) permalink view source

Find the vertical staff position of middle-c at a given point.

returns:

StaffUnit: A vertical staff position

Looks for clefs and other transposing modifiers to determine the position of middle-c.

If no clef is present, a NoClefError is raised.

y_inside_staff (pos_y) permalink view source

Determine if a y-axis position is inside the staff.

arguments:

pos_y (StaffUnit): A vertical staff position

returns:

bool

This is true for any position within or on the outer lines.

y_outside_staff (pos_y) permalink view source

Determine if a y-axis position is outside of the staff.

arguments:

pos_y (StaffUnit): A vertical staff position

returns:

bool

This is true for any position not on or between the outer staff lines.

y_on_ledger (pos_y) permalink view source

Determine if a y-axis position is on a ledger line position

arguments:

pos_y (StaffUnit): A vertical staff position

returns:

bool

This is true for any whole-number position outside of the staff

ledgers_needed_for_y (position) permalink view source

Find the y positions of all ledgers needed for a given y position

arguments:

position (StaffUnit): Any y-axis position

returns:

set[StaffUnit]

inherited methods

line_to (x, y, parent=None) permalink view source

Draw a path from the current position to a new point.

arguments:

x (Unit): The end x position

y (Unit): The end y position

parent (GraphicObject or Page): An optional parent, whose position the target coordinate will be relative to.

returns:

None

Connect a path from the current position to a new position specified by x and y, and move self.current_draw_pos to the new point.

A point parent may be passed as well, anchored the target point to a separate GraphicObject. In this case, the coordinates passed will be considered relative to the parent.

inherited from Path

move_to (x, y, parent=None) permalink view source

Close the current sub-path and start a new one.

arguments:

x (Unit): The end x position

y (Unit): The end y position

parent (GraphicObject or Page): An optional parent, whose position the target coordinate will be relative to.

returns:

None

A point parent may be passed as well, anchored the target point to a separate GraphicObject. In this case, the coordinates passed will be considered relative to the parent.

inherited from Path

close_subpath () permalink view source

Close the current sub-path and start a new one at the local origin.

returns:

None

This is equivalent to move_to((Unit(0), Unit(0)))

inherited from Path

cubic_to (self, control_1_x, control_1_y, control_2_x, control_2_y, end_x, end_y, control_1_parent=None, control_2_parent=None, end_parent=None) permalink view source

Draw a cubic bezier curve from the current position to a new point.

arguments:

control_1_x (Unit): The x coordinate of the first control point.

control_1_y (Unit): The y coordinate of the first control point.

control_2_x (Unit): The x coordinate of the second control point.

control_2_y (Unit): The y coordinate of the second control point.

end_x (Unit): The x coordinate of the curve target.

end_y (Unit): The y coordinate of the curve target.

control_1_parent (GraphicObject or Page): An optional parent for the first control point. Defaults to self.

control_2_parent (GraphicObject or Page): An optional parent for the second control point. Defaults to self.

end_parent (GraphicObject or Page): An optional parent for the curve target. Defaults to self.

returns:

None

inherited from Path

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