Modeling Languages

Since version 2.0, Gaphor supports the concept of Modeling languages. This allows for development of separate modeling languages separate from the Gaphor core application.

The main language was, and will be UML. Gaphor now also supports a subset of SysML.

A ModelingLanguage in Gaphor is defined by a class implementing the abstract base class. The modeling language should be registered as a gaphor.modelinglanguage entry point.

The ModelingLanguage interface is fairly minimal. It allows other services to look up elements and diagram items, as well as a toolbox. However, the responsibilities of a ModelingLanguage do not stop there. Parts of functionality will be implemented by registering handlers to a set of generic functions.

But let’s not get ahead of ourselves. What is the functionality a modeling language implementation can offer?

We expose the first three by methods defined on the ModelingLanguage class. We then expose the others by adding handlers to the respective generic functions.


A model provider is a special service that provides an entrypoint to a model implementation, such as UML, SysML, RAAML.

abstract lookup_element(name: str) type[Element] | None[source]

Look up a model element type (class) by name.

abstract property name: str

Human readable name of the model.

abstract property toolbox_definition: ToolboxDefinition

Get structure for the toolbox.


Connectors are used to connect one element to another.

Connectors should adhere to the ConnectorProtocol. Normally you would inherit from BaseConnector.

class gaphor.diagram.connectors.BaseConnector(element: gaphor.core.modeling.presentation.Presentation[gaphor.core.modeling.element.Element], line: gaphor.core.modeling.presentation.Presentation[gaphor.core.modeling.element.Element])[source]

Connection adapter for Gaphor diagram items.

Line item line connects with a handle to a connectable item element.

  • line (Presentation) – connecting item

  • element (Presentation) – connectable item

The following methods are required to make this work:

  • allow(): is the connection allowed at all (during mouse movement for example).

  • connect(): Establish a connection between element and line. Also takes care of disconnects, if required (e.g. 1:1 relationships)

  • disconnect(): Break connection, called when dropping a handle on a point where it can not connect.

  • reconnect() (Optional): Connect to another item (only used if present)

By convention the adapters are registered by (element, line) – in that order.

allow(handle: gaphas.connector.Handle, port: gaphas.connector.Port) bool[source]

Determine if items can be connected.

Returns True if connection is allowed.

connect(handle: gaphas.connector.Handle, port: gaphas.connector.Port) bool[source]

Connect to an element. Note that at this point the line may be connected to some other, or the same element. Also the connection at model level still exists.

Returns True if a connection is established.

disconnect(handle: gaphas.connector.Handle) None[source]

Disconnect model level connections.

get_connected(handle: Handle) Presentation[Element] | None[source]

Get item connected to a handle.

get_connection(handle: Handle) Connection | None[source]

Get connection information.


Grouping is done by dragging one item on top of another.

Grouping dispatch objects are normally inheriting from AbstractGroup.

class gaphor.diagram.grouping.AbstractGroup(parent: gaphor.core.modeling.presentation.Presentation, item: gaphor.core.modeling.presentation.Presentation)[source]

Base class for grouping model elements, i.e. interactions contain lifelines and components contain classes objects.

  • parent (Presentation) – Parent item, which groups other items.

  • item (Presentation) – Item to be grouped.

can_contain() bool[source]

Determine if parent can contain item.

abstract group() None[source]

Perform grouping of items.

abstract ungroup() None[source]

Perform ungrouping of items.

Editor property pages

The editor page is constructed from snippets. For example: almost each element has a name, so there is a UI snippet that allows you to edit a name.

Each property page (snippet) should inherit from PropertyPageBase.

class gaphor.diagram.propertypages.PropertyPageBase[source]

A property page which can display itself in a notebook.

abstract construct()[source]

Create the page (Gtk.Widget) that belongs to the Property page.

Returns the page’s toplevel widget (Gtk.Widget).

Inline (diagram) editor popups

When you double click on an item in a diagram, a popup can show up so you can easily change the name.

By default this works for any named element. You can register your own inline editor function if you need to.

gaphor.diagram.inlineeditors.InlineEditor(item: Item, view, pos: Optional[Tuple[int, int]] = None) bool

Show a small editor popup in the diagram. Makes for easy editing without resorting to the Element editor.

In case of a mouse press event, the mouse position (relative to the element) are also provided.

Copy and paste

Copy and paste works out of the box for simple items: one diagram item with one model element (the subject). It leveages the load() and save() methods of the elements to ensure all relevant data is copied.

Sometimes items need more than one model element to work. For example an Association: it has two association ends.

In those specific cases you need to implement your own copy and paste functions. To create such a thing you’ll need to create two functions: one for copying and one for pasting.

gaphor.diagram.copypaste.copy(obj: Element) T

Create a copy of an element (or list of elements). The returned type should be distinct, so the paste() function can properly dispatch.

gaphor.diagram.copypaste.paste(copy_data: T, diagram: Diagram, lookup: Callable[[str], Element]) object

Paste previously copied data. Based on the data type created in the copy() function, try to duplicate the copied elements. Returns the newly created item or element

To serialize the copied elements and deserialize them again, there are two functions available:


Return a serialized version of a value. If the value is an element, it’s referenced.

gaphor.diagram.copypaste.deserialize(ser, lookup)

Deserialize a value previously serialized with serialize(). The lookup function is used to resolve references to other elements.