API reference¶

The API can be separated into a [Model-View-Controller](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) with these three parts:

The Model, including the canvas and items
The View, called view
The Controller, called tools

Canvas and Items¶

Class: `gaphas.canvas.Canvas`¶

The Canvas is a container for items.

Class: `gaphas.item.Item`¶

Base class (or interface) for items on a Canvas.

Properties¶

matrix: The item’s transformation matrix
canvas: The canvas, which owns an item
constraints: list of item constraints, automatically registered when the item is added to a canvas; may be extended in subclasses

Class: `gaphas.connector.Handle`¶

Handles are used to support modifications of Items.

If the handle is connected to an item, the connected_to property should refer to the item. A disconnect handler should be provided that handles the required disconnect behaviour, for example, cleaning up the constraints and connected_to.

pos (gaphas.connector.Position): The position of the item, default value is (0, 0).
strength (int): The strength of the handle to use in the constraint solver; default value is NORMAL, which is 20.
connectable (bool): Makes the handle connectable to other items; default value is False.
movable (bool): Makes the handle moveable; default value is True.

Class: `gaphas.connector.LinePort`¶

The Line Port is part of an item that provides a line between two handles.

start (gaphas.connector.Position): The start position of the line.
end (gaphas.connector.Position): The end position of the line.

Class: `gaphas.connector.PointPort`¶

The Point Port connects the handle to an item using a port at the location of the handle.

Class: `gaphas.solver.Solver`¶

A Solver solves constraints.

Class: `gaphas.constraint.EqualsConstraint`¶

Make ‘a’ and ‘b’ equal.

Class: `gaphas.constraint.LessThanConstraint`¶

Ensure one variable stays smaller than another.

Class: `gaphas.constraint.CenterConstraint`¶

Ensures a Variable is kept between two other variables.

Class: `gaphas.constraint.EquationConstraint`¶

Solve a linear equation.

Class: `gaphas.constraint.BalanceConstraint`¶

Keeps three variables in line, maintaining a specific ratio.

Class: `gaphas.constraint.LineConstraint`¶

Solves the equation where a line is connected to a line or side at a specific point.

### View

Class: `gaphas.view.View`¶

View class for gaphas.canvas.Canvas objects.

Class: `gaphas.view.GtkView`¶

GTK+ widget for rendering a gaphas.canvas.Canvas to a screen.

Class: `gaphas.painter.PainterChain`¶

Chain up a set of painters.

Class: `gaphas.painter.DrawContext`¶

Special context for drawing the item. It contains a cairo context and properties like selected and focused.

**kwargs: Optional cairo properties for a context.

Class: `gaphas.painter.ItemPainter`¶

Painter to draw an item.

Class: `gaphas.painter.CairoBoundingBoxContext`¶

It is used to intercept stroke(), fill(), and other context operations so that the bounding box of the item involved can be calculated.

cairo (cairo.Context): The cairo context to intercept.

Class: `gaphas.painter.BoundingBoxPainter`¶

A type of ItemPainter which is used to calculate the bounding boxes (in canvas coordinates) for the items.

Class: `gaphas.painter.HandlePainter`¶

Draw handles of items that are marked as selected in the view.

Class: `gaphas.painter.ToolPainter`¶

Allows the Tool defined on a view to conduct drawing.

Class: `gaphas.painter.FocusedItemPainter`¶

Used to draw on top of all the other layers for the focused item.

### Tools

Interacting with the Canvas is done through tools. Tools tell _what_ has to be done (like moving). To make an element move aspects are defined. Aspects tell how the behaviour has to be performed.

Class: `gaphas.tools.ToolChain`¶

Used to chain tools together. For example, chain a HoverTool, HandleTool, and SelectionTool in order to combine their functionality in to a new tool.

view (gaphas.view.View): The view to use for the tool chain.

Class: `gaphas.tools.HoverTool`¶

Makes the item under the mouse cursor the hovered item.

view (gaphas.view.View): The view to use for the tool; default is None.

Class: `gaphas.tools.ItemTool`¶

Does selection and dragging of items.

view (gaphas.view.View): The view to use for the tool; default is None.

Class: `gaphas.tools.HandleTool`¶

Tool to move handles around.

view (gaphas.view.View): The view to use for the tool; default is None.

Class: `gaphas.tools.RubberbandTool`¶

Allows the user to drag a “rubber band” for selecting items in an area.

view (gaphas.view.View): The view to use for the tool; default is None.

Class: `gaphas.tools.PanTool`¶

Captures drag events with the middle mouse button and uses them to translate the Canvas within the view.

view (gaphas.view.View): The view to use for the tool; default is None.

Class: `gaphas.tools.ZoomTool`¶

Tool for zooming using two different user inputs:

Ctrl + middle-mouse dragging in the up and down direction
Ctrl + mouse-wheel

view (gaphas.view.View): The view to use for the tool; default is None.

Class: `gaphas.tools.PlacementTool`¶

Tool for placing items on the Canvas.

view (gaphas.view.View): The view to use for the tool.
factory (factory object): A Canvas item factory for creating new items.
handle_tool (gaphas.tools.HandleTool): The handle tool to use.
handle_index (int): The index of the handle to be used by the handle tool.

Class: `gaphas.aspects.ItemFinder`¶

Find an item on the Canvas.

view (gaphas.view.View): The view to use in order to search for an item.

Class: `gaphas.aspects.ItemSelection`¶

Manages selection and unselection of items.

item (gaphas.item.Item): The item to set as focused or unfocused.
view (gaphas.view.View): The view to focus or unfocus on.

Class: `gaphas.aspects.ItemInMotion`¶

Manages motion of an item.

item (gaphas.item.Item): The item to move.
view (gaphas.view.View): The view to to use for move coordinates.

Class: `gaphas.aspects.ItemHandleFinder`¶

Finds handles.

item (gaphas.item.Item): The item.
view (gaphas.view.View): The view to get the handle at the position from.

Class: `gaphas.aspects.ElementHandleSelection`¶

Selects the handle of a gaphas.item.Element.

item (gaphas.item.Item): The Element item that the handle belongs to.
handle (gaphas.connector.Handle): The handle to select or unselect.
view (gaphas.view.View): The view that can be used to apply the cursor to.

Class: `gaphas.aspects.ItemHandleInMotion`¶

Move a handle.

item (gaphas.item.Item): The item that the handle belongs to.
handle (gaphas.connector.Handle): The handle to move.
view (gaphas.view.View): The view to use for the coordinate system.

Class: `gaphas.aspects.ItemConnector`¶

Connect or disconnect an item’s handle to another item or port.

item (gaphas.item.Item): The item that the handle belongs to.
handle (gaphas.connector.Handle): The handle to connect.

Class: `gaphas.aspects.ItemConnectionSink`¶

Makes an item a sink, which is another item that an item’s handle is connected to like a connected item or port.

item (gaphas.item.Item): The item to look for ports on.
port (gaphas.connector.Port): The port to use as the sink.

Class: `gaphas.aspects.ItemPaintFocused`¶

Paints on top of all items, just for the focused item and only when it’s hovered (see: gaphas.painter.FocusedItemPainter).

item (gaphas.item.Item): The focused item.
view (gaphas.view.View): The view to paint with.

### Extended Behaviour

By importing the following modules, extra behaviour is added to the default view behaviour.

Class: `gaphas.segment.LineSegment`¶

Split and merge line segments.

item (gaphas.item.Item): The item of the segment.
view (gaphas.view.View): The view to use for the split coordinate system.

Class: `gaphas.segment.SegmentHandleFinder`¶

Extends the gaphas.aspects.ItemHandleFinder to find a handle on a line, and create a new handle if the mouse is located between two handles. The position aligns with the points drawn by the SegmentPainter.

item (gaphas.item.Item): The item.
view (gaphas.view.View): The view to get the handle at the position from.

Class: `gaphas.segment.SegmentHandleSelection`¶

Extends the gaphas.aspects.ItemHandleSelection to merge segments if the handle is released.

item (gaphas.item.Item): The item that the handle belongs to.
handle (gaphas.connector.Handle): The handle to select or unselect.
view (gaphas.view.View): The view to use to apply the cursor to.

Class: `gaphas.segment.LineSegmentPainter`¶

This painter draws pseudo-handles on a gaphas.item.Line by extending gaphas.aspects.ItemPaintFocused. Each line can be split by dragging those points, which will result in a new handle.

ConnectHandleTool takes care of performing the user interaction required for this feature.

item (gaphas.item.Item): The focused item.
view (gaphas.view.View): The view to paint with.

Class: `gaphas.guide.ElementGuide`¶

Provides a guide to align items for gaphas.item.Element.

item (gaphas.item.Item): The item to provide guides for.

Class: `gaphas.guide.LineGuide`¶

Provides a guide to align items for gaphas.item.Line.

item (gaphas.item.Item): The item to provide guides for.

Class: `gaphas.guide.GuidedItemInMotion`¶

Move the item and lock the position of any element that’s located at the same position.

item (gaphas.item.Item): The item to move.
view (gaphas.view.View): The view with guides to use for move coordinates.

Class: `gaphas.guide.GuidedItemHandleInMotion`¶

Move a handle and lock the position of any element that’s located at the same position.

item (gaphas.item.Item): The item that the handle belongs to.
handle (gaphas.connector.Handle): The handle to move.
view (gaphas.view.View): The view with guides to use for the coordinate system.

Class: `gaphas.guide.GuidePainter`¶

Paints on top of all items with guides, just for the focused item and only when it’s hovered.

item (gaphas.item.Item): The focused item.
view (gaphas.view.View): The view with guides to paint with.

Miscellaneous¶

Class: `gaphas.tree.Tree`¶

A Tree structure with the nodes stored in a depth-first order.

tree = Tree()
tree.add("node1")
tree.add("node2", parent="node1")

Class: `gaphas.matrix.Matrix`¶

Adds @observed messages on state changes to the cairo.Matrix.

xx (float): xx component of the affine transformation
yx (float): yx component of the affine transformation
xy (float): xy component of the affine transformation
yy (float): yy component of the affine transformation
x0 (float): X translation component of the affine transformation
y0 (float): Y translation component of the affine transformation

matrix = Matrix(1, 0, 0, 1, 0, 0)

Class: `gaphas.table.Table`¶

Table is a storage class that can be used to store information, like one would in a database table, with indexes on the desired “columns.” It includes indexing and is optimized for lookups.

columns (tuple): The columns of the table.
index (tuple):

from collections import namedtuple
C = namedtuple('C', "foo bar baz")
s = Table(C, (2,))

Class: `gaphas.quadtree.Quadtree`¶

A quadtree is a tree data structure in which each internal node has up to four children. Quadtrees are most often used to partition a two

bounds (tuple): The boundaries of the quadtree (x, y, width, height).
capacity (int); The number of elements in one tree bucket; default is 10.

qtree = Quadtree((0, 0, 100, 100))

Class: `gaphas.geometry.Rectangle`¶

Rectangle object which can be added (union), substituted (intersection), and points and rectangles can be tested to be in the rectangle.

x (int): X position of the rectangle.
y (int): Y position of the rectangle.
width (int): Width of the rectangle.
height (int): Hiehgt of the rectangle.

rect = Rectangle(1, 1, 5, 5)

Decorator: `@AsyncIO`¶

Schedule an idle handler at a given priority.

single (bool): Schedules the decorated function to be called only a single time.
timeout (int): The time between calls of the decorated function.
priority (int): The GLib.PRIORITY constant to set the event priority.

@AsyncIO(single=True, timeout=60)
def c2(self):
    print('idle-c2', GLib.main_depth())

Decorator: `@nonrecursive`¶

Enforces a function or method to not be executed recursively.: api/decorators

class A(object):
    @nonrecursive
    def a(self, x=1):
        self.a(x+1)

Decorator: `@recursive`¶

Limits the recursion for a specific function.

limit (int): The limit for the number of recursive loops a function can be called; default is 10000.

@recursive(10)
def a(self, x=0):
    self.a()

API reference¶

Canvas and Items¶

Class: gaphas.canvas.Canvas¶

Class: gaphas.item.Item¶

Properties¶

Class: gaphas.connector.Handle¶

Class: gaphas.connector.LinePort¶

Class: gaphas.connector.PointPort¶

Class: gaphas.solver.Solver¶

Class: gaphas.constraint.EqualsConstraint¶

Class: gaphas.constraint.LessThanConstraint¶

Class: gaphas.constraint.CenterConstraint¶

Class: gaphas.constraint.EquationConstraint¶

Class: gaphas.constraint.BalanceConstraint¶

Class: gaphas.constraint.LineConstraint¶

Class: gaphas.view.View¶

Class: gaphas.view.GtkView¶

Class: gaphas.painter.PainterChain¶

Class: gaphas.painter.DrawContext¶

Class: gaphas.painter.ItemPainter¶

Class: gaphas.painter.CairoBoundingBoxContext¶

Class: gaphas.painter.BoundingBoxPainter¶

Class: gaphas.painter.HandlePainter¶

Class: gaphas.painter.ToolPainter¶

Class: gaphas.painter.FocusedItemPainter¶

Class: gaphas.tools.ToolChain¶

Class: gaphas.tools.HoverTool¶

Class: gaphas.tools.ItemTool¶

Class: gaphas.tools.HandleTool¶

Class: gaphas.tools.RubberbandTool¶

Class: gaphas.tools.PanTool¶

Class: gaphas.tools.ZoomTool¶

Class: gaphas.tools.PlacementTool¶

Class: gaphas.aspects.ItemFinder¶

Class: gaphas.aspects.ItemSelection¶

Class: gaphas.aspects.ItemInMotion¶

Class: gaphas.aspects.ItemHandleFinder¶

Class: gaphas.aspects.ElementHandleSelection¶

Class: gaphas.aspects.ItemHandleInMotion¶

Class: gaphas.aspects.ItemConnector¶

Class: gaphas.aspects.ItemConnectionSink¶

Class: gaphas.aspects.ItemPaintFocused¶

Class: gaphas.segment.LineSegment¶

Class: gaphas.segment.SegmentHandleFinder¶

Class: gaphas.segment.SegmentHandleSelection¶

Class: gaphas.segment.LineSegmentPainter¶

Class: gaphas.guide.ElementGuide¶

Class: gaphas.guide.LineGuide¶

Class: gaphas.guide.GuidedItemInMotion¶

Class: gaphas.guide.GuidedItemHandleInMotion¶

Class: gaphas.guide.GuidePainter¶