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, RAAML and the C4 model.

A modeling language in Gaphor is defined by a class implementing the gaphor.abc.ModelingLanguage 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, and diagram types. However, the responsibilities of a modeling language 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?

  • A data model (elements) and diagram items

  • Diagram types

  • A toolbox definition

  • Connectors, allow diagram items to connect

  • Format/parse model elements to and from a textual representation

  • Copy/paste behavior when element copying is not trivial, for example with more than one element is involved

  • Grouping, allow elements to be nested in one another

  • Dropping, allow elements to be dragged from the tree view onto a diagram

  • Automatic cleanup rules to keep the model consistent

The first three by functionalities are exposed by the ModelingLanguage class. The other functionalities can be extended by adding handlers to the respective generic functions.

Modeling languages can also provide new UI components. Those components are not loaded directly when you import a modeling language package. Instead, they should be imported via the gaphor.modules entrypoint.

class gaphor.abc.ModelingLanguage[source]#

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

abstract property diagram_types: Iterable[DiagramType]#

Iterate diagram types.

abstract property element_types: Iterable[ElementCreateInfo]#

Iterate element types.

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

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

abstract property name: str#

Human-readable name of the modeling language.

abstract property toolbox_definition: ToolboxDefinition#

Get structure for the toolbox.

Connectors#

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: Presentation[Element], line: Presentation[Element])[source]#

Connection adapter for Gaphor diagram items.

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

Parameters

  • 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.

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

allow(handle: Handle, port: Port) → bool[source]#

Determine if items can be connected.

Returns True if connection is allowed.

connect(handle: Handle, port: Port) → bool[source]#

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

Returns True if a connection is established.

disconnect(handle: Handle) → None[source]#

Disconnect model level connections.

get_connected(handle: Handle) → Optional[Presentation[Element]][source]#

Get item connected to a handle.

Format and parse#

Model elements can be formatted to a simple text representation. For example, This is used in the Model Browser. It isn’t a full serialization of the model element.

In some cases it’s useful to parse a text back into an object. This is done when you edit attributes and operations on a class.

Not every format() needs to have an equivalent parse() function.

gaphor.core.format.format(element: Element) → str#

Returns a human readable representation of the model element. In most cases this is just the name, however, properties (attributes) and operations are formatted more extensively:

+ attr: str
+ format(element: Element): string
gaphor.core.format.parse(element: Element, text: str) → None#

Parse text and populate element. The element is populated with elements from the text. This may mean that new model elements are created as part of the parse process.

Copy and paste#

Copy and paste works out of the box for simple items: one diagram item with one model element (the subject). It leverages 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) → Iterator[tuple[Id, Opaque]]#

Create a copy of an element (or list of elements). The returned type should be distinct, so the paste() function can properly dispatch. A copy function normally copies only the element and mandatory related elements. E.g. an Association needs two association ends.

gaphor.diagram.copypaste.paste(copy_data: Opaque, diagram: Diagram, lookup: Callable[[str], Element | None]) → Iterator[Element]#

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.

Gaphor provides some convenience functions:

gaphor.diagram.copypaste.copy_full(items: Collection[Element], lookup: Callable[[Id], Element | None] | None = None) → CopyData:#

Copy items. The lookup function is used to look up owned elements (shown as child nodes in the Model Browser).

Paste a copy of the Presentation element to the diagram, but try to link the underlying model element. A shallow copy.

gaphor.diagram.copypaste.paste_full(copy_data: CopyData, diagram: Diagram) → set[~gaphor.core.modeling.Presentation]:#

Paste a copy of both Presentation and model element. A deep copy.

Grouping#

Grouping is done by dragging one item on top of another, in a diagram or in the tree view.

gaphor.diagram.group.group(parent: Element, element: Element) → bool#

Group an element in a parent element. The grouping can be based on ownership, but other types of grouping are also possible.

gaphor.diagram.group.ungroup(parent: Element, element: Element) → bool#

Remove the grouping from an element. The function needs to check if the provided parent node is the right one.

gaphor.diagram.group.can_group(parent_type: type[Element], element_or_type: type[Element] | Element) → bool#

This function tries to determine if grouping is possible, without actually performing a group operation. This is not 100% accurate.

Dropping#

Dropping is performed by dragging an element from the tree view and drop it on a diagram. This is an easy way to extend a diagram with already existing model elements.

gaphor.diagram.drop.drop(element: Element, diagram: Diagram, x: float, y: float) → Presentation | None#

The drop function creates a new presentation for an element on the diagram. For relationships, a drop only works if both connected elements are present in the same diagram.

The big difference with dragging an element from the toolbox, is that dragging from the toolbox will actually place a new Presentation element on the diagram. drop works the other way around: it starts with a model element and creates an accompanying Presentation.

Automated model cleanup#

Gaphor wants to keep the model in sync with the diagrams.

A little dispatch function is used to determine if a model element can be removed.

gaphor.diagram.deletable.deletable(element: Element) → bool#

Determine if a model element can safely be removed.

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() → Gtk.Widget | None[source]#

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

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

Instant (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.instanteditors.instant_editor(item: Item, view, event_manager: EventManager, pos: tuple[int, int] | None = 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.