Access this quickly in the future: - Graphite

+++ title = "Editor structure"

[extra] order = 1 # Page number after chapter intro css = ["/page/contributor-guide/editor-structure.css"] js = ["/js/page/contributor-guide/editor-structure.js"] +++

The Graphite editor is the application users interact with to create documents. Its code is a single Rust crate that lives below the frontend (web code) and above Graphene (the node-based graphics engine). The main business logic of all visual editing is handled by the editor backend. When running in the browser, it is compiled to WebAssembly and passes messages to the frontend.

Message system

The Graphite editor backend is organized into a hierarchy of subsystems which talk to one another through message passing. Messages are pushed to the front or back of a queue and each one is processed sequentially by the editor's dispatcher.

The dispatcher lives at the root of the editor hierarchy and acts as the owner of all its top-level message handlers. This satisfies Rust's restrictions on mutable borrows because only the dispatcher may mutate its message handlers, one at a time, while each message is processed.

Editor outline

# Access this quickly in the future:
cargo run explore editor

Click to explore the outline of the editor subsystem hierarchy which forms the structure of the editor's subsystems, state, and interactions. Also available as a searchable <a href="/volunteer/guide/codebase-overview/hierarchical-message-system-tree.txt">plain text file</a>.

Parts of the hierarchy

Subsystem components

A *Message enum is the component of an editor subsystem that defines its message interfaces as enum variants. Messages are used for passing a request from anywhere in the application, optionally with some included data, to have a particular block of code be run by its respective message handler.
A *MessageHandler struct is the component of an editor subsystem that has ownership over its persistent editor state and its child message handlers for the lifetime of the application. It also defines the logic for handling each of its messages that it receives from the dispatcher. Those blocks of logic may further enqueue additional messages to be processed by itself or other message handlers during the same dispatch cycle.
A *MessageContext struct is the component of an editor subsystem that defines what data is made available from other subsystems when running the logic to handle a dispatched message. It is a struct that is passed to the message handler when processing a message, and it gets filled in with data (owned, borrowed, or mutably borrowed) from its parent message handler. Intermediate subsystem layers may forward data from their parent to their child contexts to make state available from further up the hierarchy.

Sub-messages

A #[child] * attribute-decorated message enum variant is a special kind of message that encapsulates a nested subsystem. As with all messages, its handler has a manually written code block. But that code must call its corresponding child message handler's process_message method. The child message handler is a field of this parent message handler's state struct.

Messages

A * message enum variant is used throughout the editor to request that a certain subsystem performs some action, potentially given some data. In that sense, it resembles a function call, but a key difference is that messages are queued up and processed sequentially in a flat order, always invoked by the dispatcher.

How messages work

Messages are enum variants that are dispatched to perform some intended activity within their respective message handlers. Here are two message definitions from DocumentMessage:

pub enum DocumentMessage {
	...
	// A message that carries one data field
	DeleteLayer {
		id: NodeId,
	}
	// A message that carries no data
	DeleteSelectedLayers,
	...
}

As shown above, additional data fields can be included with each message. But as a special case denoted by a #[child] attribute, that data can also be a sub-message enum, which enables hierarchical nesting of message handler subsystems.

By convention, regular data must be written as struct-style named fields (shown above), while a sub-message enum must be written as a tuple/newtype-style field (shown below). The DocumentMessage enum of the previous example is defined as a child of PortfolioMessage which wraps it like this:

pub enum PortfolioMessage {
	...
	// A message that carries the `DocumentMessage` child enum as data
	#[child]
	Document(DocumentMessage),
	...
}

Likewise, the PortfolioMessage enum is wrapped by the top-level Message enum. The dispatcher operates on the queue of these base-level Message types.

So for example, the DeleteSelectedLayers message mentioned previously will look like this as a Message data type:

Message::Portfolio(
	PortfolioMessage::Document(
		DocumentMessage::DeleteSelectedLayers
	)
)

Writing out these nested message enum variants would be cumbersome, so that #[child] attribute shown earlier invokes a proc macro that automatically implements the From trait, letting you write this instead to get a Message data type:

DocumentMessage::DeleteSelectedLayers.into()

Most often, this is simplified even further because the .into() is called for you when pushing a message to the queue with .add() or .add_front(). So this becomes as simple as:

responses.add(DocumentMessage::DeleteSelectedLayers);

The responses message queue is composed of Message data types, and thanks to this system, child messages like DocumentMessage::DeleteSelectedLayers are automatically wrapped in their ancestor enum variants to become a Message, saving you from writing the verbose nested form.